Use MkDocs to generate static documentation (with GitHub workflows > GitHub Pages)

[SableRaf]

I suggest using MkDocs to generate static documentation for libraries. For library creators, this would make it easier to fullfil the requirement of creating and hosting a documentation website for their library. Hosting on GitHub pages would also make it less likely for those library websites to go 404 in the future (as long as GitHub Pages exists).

See the way @fredegd deploys the doc for their EasyEase library:

• Static site: https://fredegd.github.io/EasyEase/
• Config file: https://github.com/fredegd/EasyEase/blob/main/mkdocs.yml

Same for the FIP library by @prontopablo:

• Static site: https://prontopablo.github.io/FIP/
• Config file: https://github.com/prontopablo/FIP/blob/main/mkdocs.yml

[SableRaf]

Some context for @prontopablo and @fredegd: this repo was created by our pr05 grant recipient @mingness to work on an official Gradle template for Processing libraries. With your recent experience publishing Processing library documentation using MkDocs, your input on this would be greatly appreciated!

[prontopablo]

Hey everyone. I found MkDocs, particularly Material for MkDocs, very handy to use. With MkDocs, you write in Markdown, and it generates static HTML files for you. This is different from other tools like docsify, which don't produce static HTML that you can bundle with your library as offline documentation. Also, you can easily enable or disable great features like code embedding through the configuration file. If you have any specific questions, I'd be happy to help!

[mingness]

Thanks for this issue @SableRaf ! I now understand better the situation. Thanks @prontopablo and @fredegd for seeking a better solution. I will use your repos as models, and will reach out with specific questions if needed. 🙏

[fredegd]

Hello issue group 👋🏻! I agree with @prontopablo about the usability of MkDocs; especially when it comes to create static web pages wich be visited locally aka offline. As workflow would recommend to use MkDocs and let it build the static HTML documentation directly into the /reference folder wich will be added by gradle directly into the Release's reference/

[mingness]

Thanks @prontopablo and @fredegd for the examples of your libraries and mkdocs sites. I referred to them many times while working on this part of the library template. There is now a PR adding more content to the docs for the template.

https://github.com/mingness/processing-library-template/pull/46