New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Replace documentation infrastructure #156
Comments
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 |
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:
We should look for replacements that fit the following criteria:
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.
The text was updated successfully, but these errors were encountered: