Choosing a new documentation generator
Looking into bundling fe and be docs together it seems like the least hacky way to do that is to create a separate project that has a pipeline for fetching fe and be docs and trigger it on commits to be and fe repos. Which means that we no longer have to use ex_doc
for our documentation. I think that while ex_doc is great for inline code docs, it was never intended and not really suited for using it exclusively for extra docs, like we do.
Thus I think we should choose a new documentation generator, the following section describes some of the most popular ones, I am currently leaning towards MkDocs, but if you want to propose a different one or add more advantages/disadvantages to existing ones, please do.
ExDoc
Example: https://docs-develop.pleroma.social/alpine_linux_en.html
Advantages
- Inline documentation, I guess? We don't really use it though
Disadvantages
- Navigation sucks (The menu has a very low max width and titles of some of the pages often occupy 3 lines as a result, also navigation panel shows only
h2
sections, making it useless on most of the docs) - No i18 support
- No theme support
- Links to Google fonts without an ability to disable it
- Impossible to navigate without JS
- No versioning support
MkDocs
Example: https://docs.loki.network/Lokinet/Guides/ExitNode/
Advantages
- Theme support
- Navigation doesn't suck
- Almost everything works without JS
- A bunch of plugins for both MkDocs and Python Markdown
Disadvantages
- No versioning support
- No i18 support
Docusaurus
Example: https://docusaurus.io/docs/en/site-creation
Advantages
- Navigation doesn't suck
- Versioning support
- i18 support
- Theme support
Disadvantages
- Search requires a proprietary API