Documentation build refactoring

[alex-key]

This is a discussion to investigate and define how documentation build process could be refactored to make it closer to modern stack. Update is needed, because it is based on outdated libraries, which are not maintained anymore. And as a result final website is looking quite outdated and UX could be much improved.

To start the discussion I will copy a message by @limzykenneth from processing/p5.js#6006 (comment)

The documentation system is definitely not great and is something I want to work on for a long time now. The underlying system is a system called YUIDoc and the static page generation is using Assemble, both of which are abandoned by their original authors.

We have specific requirements that basically precludes us from switching to other stacks.

We want to keep inline documentation as that is an important aspect of p5.js' codebase
We want to be able to run interactive examples on individual pages
We want to have control over the exact layout and design of the individual pages
We want the ability to do internationalization easily (which is my main focus at the moment)
For inline documentation, YUIDoc is the only one currently (that I know of) that uses the JSDoc format and generate a JSON file that we can use for rendering (JSDoc last I checked does not generate a JSON file containing the documentation in a structured format). For static pages, I'm open to moving away from Assemble but we have the internationalization bits built alongside it so any new system will need to integrate our existing system without needing us to rebuild/reformat all our existing translations.

A new website is currently in discussion in the very early stages so that is also another reason to not go all in on a redesign/rebuild if the new website eventually goes with something completely different.

That's all a bit long and should really be another issue as mentioned 😅

I checked the code and based on the explanation above I understand the needs. As an initial effort I'll try to create a POC, where some alternative to YuiDoc and Assemble are used.
There are several packages which could analize JSDoc comments and produce json/alternative format output. I'll start playing with it to understand challenges better.

[limzykenneth]

@alex-key I have something pretty rudimentary done a few years ago for documentation generation using JSDoc style comments: https://github.com/limzykenneth/DynamicRecord/tree/master/gendocs. You can have a look so you're not starting complete from scratch.

[alex-key]

Thank you, @limzykenneth. I'll check this

[limzykenneth]

This could be useful to look at as well: https://github.com/processing/processing-doclet