Inline API reference

[KnorpelSenf]

Work in progress.

Pending tasks:

• [x] replace links to inlined API reference
• [x] create TOC for each path, such as /api/core
• [x] complete info for classes
  • [x] include all class members
  • [x] include links to source definitions
• [x] add pages for all other types of exports (see commented out parts)
• [x] decide how to handle clashes
• [x] support /types.ts
• [x] run deno fmt in order to make the doc styles more consistent (blocked by https://github.com/denoland/deno/issues/16730)
• [ ] fix loads of details in the docs, such as link highlighting, cross-references between API objects, and likely a lot more

[github-actions[bot]]

🚀 Deployed on https://65f76187c26572cafaaa2235--grammy.netlify.app

[KnorpelSenf]

https://635855ed09e68c00648923df--grammy.netlify.app/api/core/Bot.html

[KnorpelSenf]

https://6372cc78d06d6331bdcaae80--grammy.netlify.app/ref/api/File.html

[quadratz]

@KnorpelSenf Is there any reason for us to replace the existing docs with this ones? The present documentation from deno.land, in my opinion, is fairly decent. For instance, https://deno.land/x/[email protected]/convenience/session.ts?s=session is much better than ours, https://637e8d4948c6554ad0f7926e--grammy.netlify.app/ref/core/session.html.

[KnorpelSenf]

The goal of this is to deliver quality that's at least on par with Deno. We won't merge this before we're satisfied. We're trying to solve the following problems:

• the search on our page doesn't index the API reference of the core lib or the plugins
• navigating to the API reference leaves the page
• following a docs link inside the reference leaves the page again
• the API reference is hard to find because it's on a different origin
• the docs bot cannot send links to the API reference
• it's not obvious where the methods on https://core.telegram.org/bots/api are reflected in our docs so they're hard to find

It just helps to deliver an integrated experience.

[KnorpelSenf]

If I'm honest, it is quite convenient that the Deno docs pages are getting better and better over time. I don't enjoy replicating their work here. Markdown is pretty constrained, and by now they also finally added a great search feature. Also, if we were to land this, we'd have to constantly work on this code and improve it. There are more downsides to this approach (in addition to it being a lot of work):

• cannot be translated, which is inconsistent
• worse/missing integration with the actual code
• hard to view docs of old versions (so the Deno docs would never be completely dispensable)
• constrained by the features of markdown (Deno docs can choose an arbitrary layout)
• must be adjusted when new TS features are released, in contrast to Deno docs which receive this feature automatically as soon as Deno is updated

I just feel like there are way cooler things to spend my time on (such as actual library innovation). Hence, I will close this. If anyone finds good reasons for picking this up again (and wants to invest the time), feel free to drop a comment so we restore the branch and let you continue.

[KnorpelSenf]

by now they also finally added a great search feature

The search was removed by them in https://github.com/denoland/dotland/pull/2635.

• worse/missing integration with the actual code

This is not correct. Instead of pulling the API reference from Deno, we can do it from GitHub. This will give us links to the source on GitHub, which is even better than links to the code at /x.

• hard to view docs of old versions (so the Deno docs would never be completely dispensable)

This is a good point, but let's be honest: how often are people interested in outdated docs? Basically only when using outdated major versions. This can be fixed by including docs for all latest versions of each major version. This sounds feasible to me.

• must be adjusted when new TS features are released, in contrast to Deno docs which receive this feature automatically as soon as Deno is updated

In fact, this is only true when we use new TS features. In the past two years, this has happened maybe once or twice. So while this point still stands, it's scope is very limited.

I just feel like there are way cooler things to spend my time on (such as actual library innovation).

It turns out that by not working on this, I will instead spend my time explaining to people in the chat that the API reference exists, which I enjoy even less.

[KnorpelSenf]

There's another reason to pick this up again. Some people who do not use Deno are confused if they have to visit a Deno website in order to read docs. It's not intuitive that these docs work for Node, too. We fix this by integrating the docs into our website.

[KnorpelSenf]

Will do

[KnorpelSenf]

Do you think it's feasible to implement this solely with markdown? If we want to be as good as /x then we either have to become markdown design wizards, or start creating a few Vue components to properly layout the API reference pages.

[roziscoding]

Do you think it's feasible to implement this solely with markdown? If we want to be as good as /x then we either have to become markdown design wizards, or start creating a few Vue components to properly layout the API reference pages.

What are some limitations you are currently feeling with markdown? I'm okay with having Vue components for this, and I can help create them.

[KnorpelSenf]

There are many things to display:

• doc string and params docs
• name, params, return type, generics
• optionally, an overview for classes and methods etc
• link to the source code on GitHub
• how to import
• type of the symbol

I'm not sure how to organise this.

[roziscoding]

This might be relevant: https://deno.land/x/[email protected]

[KnorpelSenf]

We could see if it's possible to infer all properties of other types, so we can get an exhaustive option list per method.

[quadratz]

https://t.me/grammyjs/184378

Following direct links like this one will break the page layout upon navigation.

@KnorpelSenf, PQ https://github.com/grammyjs/website/pull/959 will fix the issue

[KnorpelSenf]

t.me/grammyjs/184378

Following direct links like this one will break the page layout upon navigation.

@KnorpelSenf, PQ #959 will fix the issue

That is very interesting … why does it fix that? Can you provide a link to the changes that affect this?

[quadratz]

That is very interesting … why does it fix that? Can you provide a link to the changes that affect this?

I'm not certain, though. After updating VitePress and running the debug, the issue disappeared. The package hasn't been updated for 5 months, so there might have been many improvements during that time.

[KnorpelSenf]

Fair enough, I'll take that. It did seem a bit like a vitepress bug anyway. So let's just get #959 merged and then we can check if that took care of problem 5 in https://t.me/grammyjs/184378 for us.

[KnorpelSenf]

@roj1512 this makes no sense, we have to do a larger restructuring. It should be:

API ref
 - core
 - types
 - plugin0
 - plugin1
 - plugin2

Path structure can remain the same.

Main difference being that:

1. the UI lets us navigate from grammy.dev to API ref to plugin reference
2. we don't generate 20+ independent refs, one for each module, because they constantly link to each other, so we have to build a global index of symbols first and then we can insert cross-references.

I see this as the only way to address

[ ] cross-package references such as RawApi in files/hydrateFiles currently 404

and also it will improve the discoverability of the plugin refs and the types ref.

[KnorpelSenf]

As a side-effect, it will enable us to de-dupe function overloads. This will fix

• [ ] function overloads such as for webhookCallback are broken

[KnorpelSenf]

This needs some more effort. Damn.

[roziscoding]

Can we deploy this again?

[KnorpelSenf]

Not easily. I'm currently working on the auto-retry plugin. Once it has a proper Deno build, we can generate docs for it again.

However, the autoquote plugin recently broke things because it uses an npm: import. Since it's a third-party plugin, we might as well skip generating the docs for it. I do not see a way how we could support it, unless we remove the npm: import from it again.

Once these two plugins are fixed, we can commence work on the remaining tasks.

Until then, you can just look at the most recent deployment.

[KnorpelSenf]

@roziscoding we can deploy again

[KnorpelSenf]

LGTM