Hi Andre,
I believe you were asking recently about the format of the output from the new documentation tool (hotdoc), which we’re building to replace gtk-doc.
Mathieu has produced some example output of the documentation for libgrassmoor, and I’ve attached it if you would like to take a look.
Currently, the output resembles gtk-doc’s quite faithfully — except for that it’s generated for C, Python and JavaScript bindings of the API. gtk-doc only supports C output.
For the purposes of this demo, we have not significantly changed the wording of the documentation in libgrassmoor; but we have spent some effort adding GObject Introspection annotations to it so that its APIs can be used from Python and JavaScript. These are what hotdoc uses to generate the binding documentation.
The other new feature you can see in the generated documentation is the ‘Edit’ link by each symbol. This is an early part of the implementation of an online editing system for allowing readers of the documentation to easily contribute fixes and improvements to the documentation. We believe this is a good way to encourage community contributions to the documentation by lowering the barrier to contribution.
This feature is still in development, but should be available in beta form for 15.12.
A third feature which hotdoc already has over gtk-doc is its support for incremental building, where it will only rebuild the output pages affected by the specific input files which have been changed, rather than rebuilding all output pages every time. This gives speed improvements over gtk-doc, which can take 5 minutes to build the documentation for a medium-to-large project.
Mathieu is currently working on implementing an interface for tagging symbols by their stability, private/public, supported/unsupported, and whether they are specific to an OEM (for example). We aim to have that ready for 15.12 as well. However, it does not make an appearance in the attached example.
In terms of our roadmap for after Christmas, we were thinking about the following additional features, which would be useful for Apertis and also highly desired by GNOME. If we can implement features useful to GNOME, that should increase the adoption of hotdoc there as a replacement for gtk-doc, and therefore increase its contributor base. Mathieu has spoken to various key people in the GNOME community about it (including the author of gtk-doc), and his ideas for hotdoc are well received.
• Support for stand-alone Ducktype pages (rather than just Markdown pages), which would be useful for integration with prosaic developer guides (such as the GNOME developer guide, or the Apertis developer guide), to bridge the gap between API reference manuals and developer guides • Ensure linking to Mallard manuals/pages from API documentation work (another facet of the above; this allows API documentation to link to the user manuals for developer tools which are written in Mallard [which is a markup language for documentation; a more modern version of Docbook]) • Improving the Devhelp UI to improve searching, because its current search interface doesn’t return results in relevance order or support full-text search • Improving the Devhelp UI to integrate with the hotdoc online editing system to allow typos fixes to be submitted from within Devhelp • Promoting hotdoc within GNOME by applying it to some upstream modules as a test bed and to increase adoption
The first two features would be useful for integrating API documentation and developer manuals and guides, such as an SDK development guide or the Apertis developer guidelines.
The third feature would be good for use in the SDK to actually access the new documentation. Devhelp can do this already, but sub-optimally. Alternatively, it can be accessed via the web browser — Devhelp simply has some nice features like a side search bar and keyboard shortcuts.
I’d appreciate your thoughts on these features, and how you would prioritise them in the roadmap.
Philip