We use reStructuredText/sphinx for Builder’s documentation because, quite frankly, I found it the easiest for writing massive amounts of documentation in short order. I’m not sure if it’s what I want to stick with long term, but it’s doing the job short term.
However, one thing we don’t get (and I really want) out of any documentation system is support for cross-referencing the user documentation and API docs. This would be useful for us in Builder because we are the use-case for turning users into contributors. Reading our documentation on writing plugins and then locating the API docs should be seamless.
So last week I put together a prototype to generate reStructuredText/Sphinx API docs from .gir files. It will use the provided .gir, including any located dependencies, and generate API docs for them. It can’t be 100% complete for C because the .gir is missing some information that are only found in the sgml files. But it does an okay job.
Mostly, this was just a prototype to see what the state of the documentation systems are. I’m still fairly dissatisfied and am leaning towards the path of “more prototyping necessary”. For example, some things I still want from a modern documentation platform:
- Cross-referencing among user and API docs
- Switch between C, Python, GJS, etc
- Jump to function/class source code
- Find example usage of API in GNOME git
- Partial gettext/i18n support so we don’t have to translate API docs, but can still cross-reference them.
- Fast lookup indexes for use in IDE auto-completion docs using only read-only
mmap()‘d files. - We might want surrogate links to API docs when cross-referencing so end-user documentation stays small.
Anyway, if you’re bored, play around with it here and give me constructive feedback.