[Devel] Preview of new documentation tool output

[Philip Withnall]

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: grassmoor-doc.tar.gz
Type: application/x-compressed-tar
Size: 67952 bytes
Desc: not available
URL: <http://lists.apertis.org/pipermail/devel/attachments/20151117/9415b176/attachment-0002.bin>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 213 bytes
Desc: This is a digitally signed message part
URL: <http://lists.apertis.org/pipermail/devel/attachments/20151117/9415b176/attachment-0001.sig>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/x-pkcs7-signature
Size: 5445 bytes
Desc: not available
URL: <http://lists.apertis.org/pipermail/devel/attachments/20151117/9415b176/attachment-0003.bin>