Replace documentation infrastructure

[hpjansson]

We're currently using DocBook and gtk-doc. These have served fine, but they're complex dependencies that get little maintenance anymore. Additionally, even though gtk-doc produces well-structured documentation, it isn't the prettiest to look at.

Our documentation comes from three sources:

• The man page, hand-written in DocBook XML.
• Docstrings in source code. Support for extracting these is a hard requirement for any replacement infra.
• Hand-written developer documentation, e.g. the "Building" and "Using" sections. These are combined with the docstrings into a unified manual.

We should look for replacements that fit the following criteria:

• Well-maintained and widely used.
• Universally available as packages for BSD, Linux, MacOS and Windows environments (MSYS etc).
• Easy to understand and run. Few dependencies.
• Beautiful output (e.g. code syntax coloring is a high priority).
• Simple input syntax to elevate documentation authorship from the status of chore to one of unbridled joy.

E.g. AsciiDoc looks attractive, but I don't think it covers all the bases (what about docstring extraction?). Candidate suggestions are welcome.

This is a long-term issue. The change is on the horizon, but there's plenty of time to discuss things.

[AnonymouX47]

I'm not sure how easy it'll be to port the docs but I would suggest the combination of Python + Sphinx (using reST or Markdown) + Hawkmoth [+ hawkmoth.ext.napoleon], which are all still actively maintained.

Sphinx supports themes, with many freely available and support for further customization like @GuardKenzie did with chafa.py.

There's also MkDocs (not be be confused with MkDoc) + found little/undocumented/unmaintained support for C/C++ docstring extraction (e.g cxxdox) [+ Material for MkDocs] but I'm personally unfamiliar with any of these.

NB: With either of these, the docs will require python3 to build but that's available by default on most linux distros at least. Yes, I know other platforms exist 🙄 but Python and the required python packages are very much available for all major platforms.