HotDoc
Contents
HotDoc is a micro framework for generating documentation. This is a proposal page for using HotDoc instead of GTK-Doc to generate GNOME API documentation.
This page is currently work in progress.
HotDoc Features
- Generates HTML documentation from:
- Source file comments written in the standard GTK-Doc format, which are used to generate API documentation for introspected languages.
Hand-written, standalone CommonMark documentation
- Output documentation comes with search and navigation
- Output HTML docs can be themed
- Some support for online editing of docs
Migration Plan
Draft plan for migrating away from existing documentation tools (GTK-Doc, library-web) to HotDoc.
GNOME Libraries
Migrating libraries from GTK-Doc to Hotdoc is fairly straightforward. API comments need to be in standard GTK-Doc format and docbook needs to have been completely removed.
TODO: more details and examples needed
gnome-devel-docs
HotDoc only supports CommonMark and Google style Python docstrings. It would therefore need to be possible to convert the content we want to keep from gnome-devel-docs into CommonMark.
developer.gnome.org
Porting to HotDoc would require that we switch away from the existing developer.gnome.org to a new site. This isn't necessarily a bad thing - the current site isn't great. GNOME needs a new, modern developer portal.
A new prototype developer site has been designed and built. This could serve as the basis for a new developer.gnome.org.
For now, the plan is to continue using library-web to generate the release notes and user documentation. However, it might be worth considering alternatives.
DevHelp
HotDoc documentation can be used locally. It also supports outputting DevHelp indexes.
FAQ
Who develops HotDoc?
MathieuDuponchelle is the principal author; he works on HotDoc for Collabora.
How can I hack on HotDoc?
See the HotDoc Github repository.
What's HotDoc's development status?
HotDoc is actively being developed, particularly in response to the needs of early adopters.
Have any other projects adopted HotDoc?
It is being used by GStreamer and Apertis. The documentation for both these projects is expected to improve in the near future, as HotDoc itself improves.
Can HotDoc provide translated documentation?
Translations aren't supported at the moment, but they should be possible - the basic plumbing is in place.