Better documentation

[KaruroChori]

One of the main issues of the current docs, is that they only cover what is reasonable to directly attach to typescript code.
A proper docs subfolder with information about the internal architecture, how to embed it etc would be great for adoption.

I recently had to bite the bullet, and handle it on several of my projects.
For example:

• vs.fltk has hybrid docs generated via doxygen and mkdocs (for any explicit markdown content).
• comfybun has hybrid docs generated via typedoc for the ts/js things, and mkdocs for the rest of the markdown entries.

For txiki, I think doxygen, mkdocs and typedoc (which is already covered) would be needed to offer full coverage.
As I already got it sorted out for the most part, if you are interested I can put together a PR with the basic configuration & extend the CI to cover the additional generation.

[saghul]

Hey there! Thanks for bringing this up!

I started a similar effort, but got a bit sidetracked... Let's get into it.

My first candidate was Docusaurus, since I am quite familiar with it, and there is a typedoc plugin, so we could integrate it right in. I am, however, not a huge fan of how it's rendered inside Docusaurus, specially the code blocks.

I suppose you mentioned Doxygen for the C API? I suppose we could do that yes.

So it looks like we have a combination of 3 things:

• typedoc for the TS API
• doxygen for the C API
• some documentation side to link the 2 above and have some "Getting started" and such

I'm biased towards Docusaurus because it's the one I introduced in QuickJS-NG (and unrelated, but we also use it successfully with Jitsi Meet) and seems flexible enough. We could just deploy typedoc and doxygen to subdirectories and that should do it.

Thoughts?

[KaruroChori]

Just a quick reply, so I will be brutally honest :D: I think docusaurus is one of the worst offenders out there.
It deploys the documentation as a single page application in place of a static site generation (so unlike typedoc, doxygen and virtually everything else).
This means that:

• One is basically forced to read it through a modern browser with JS enabled.
• Searching in the generated docs via command line tools would be a nightmare as the granularity of files is lost.

Sure, one would still have the source markdown files, but it is a much downgraded experience when reading them.

The added value of docusaurus is to enable using react in the docs... which I think is a very bad idea 😓

By the way, I agree that style is quite bad looking compared to typedoc. Too much whitespace, data looks very sparse.

[KaruroChori]

Aside for my personal grudge against docusaurus, the combination you described is what I was also thinking.

[saghul]

Agree to disagree on Docusaurus :-) Since no documentation other than TypeDoc exists currently, and whichevere system we choose will be markdown files. Let's give mkdocs a try, I'm open to being impressed by it!

Do you want to get the ball rolling since you're more familiar with it?

[KaruroChori]

Ok, I will prepare a demo over the weekend.

[saghul]

Thank you!