Yesterday we had the second meeting about the Developer Center Initiative. We had 14 attendees with participation from HotDoc, GJS, Purism, Builder and more.
The primary topic for this week was to let developers review and demonstrate website prototypes based on different technologies. This is where we would like your opinion too! We are particularly interested in choosing the solution which..
- ..can unify our documentation and API reference.
- ..is maintainable.
- ..is easy to contribute to for writers/developers.
I would like to thank everyone for working on the presented solutions! The test instances are not fully functional of course, but they prove that it’s a possible direction we can go if we choose to.
Django
The Django instance is based on the software stack used previously for the Ubuntu Phone developer portal (An example can be seen from the Wayback Machine). It is a dynamic CMS which uses minimal Bootstrap CSS with possibility to extend its functionality using plug-ins. Users registered in the Django instance can edit documentatioGNOME documentationn using the built-in WYSIWYG editor and the documentation can be searched in all programming languages through a unified search. It can be setup for multiple human languages with possibility to set fallback languages. It is also possible to create redirects and stage changes before they are published.
The Ubuntu Portal used language-specific scripts to import API documentation by reading documents generated for each language. For GObject documentation, an importer would be needed to be written. One possibility could be to modify HotDoc to generate the documentation into Django’s database.
One of the things discussed in relation to Django was whether a dynamic website would be necessary (versus static). It creates a heavier load but could offer some extor HTMLra possibilities like comments/code attachments or generated code packages.
HotDoc
HotDoc generates a static website which can become a replacement for the whole Developer Center. It can generate API reference itself from GObject and has unified search. It links languages together so you can easily switch from one programming language to another. HotDoc allows us to specify subprojects meaning that library maintainers can generate documentation on their own and the documentation can then be positioned in HotDocs sitemap. It is meant to replace GtkDoc this way. Documentation is written in Markdown and is editable through “Edit in Gitlab” links.
The project has not been developed further so much lately since there are not so many users and the current users of HotDoc have most of the features they want. Mathieu and Thiblahute gave examples such as the PiTiVi documentation and the GStreamer documentation (work in progress). Mathieu assessed that to use HotDoc as developer center, the existing documentation would need to be ported to MarkDown. He has implemented a PanDoc reader which could be usable for this purpose. Furthermore, libraries would need to be ported from GtkDoc to HotDoc.
VuePress
Evan has built a GJS Guide for his internship based on VuePress which is used by VueJS. It supports multiple human languages via directory overrides and has search. Documentation is written in MarkDown which VuePress compiles into tutorials with table of contents, editable through “Edit in Gitlab” links. This could also be usable for API reference since GObject-introspection now can generate MarkDown and HTML from GtkDoc and make links in-between documentation.
Currently there is no example of API reference ported to VuePress – the test instance currently has it in DevDocs. To generate the API documentation, a CI runner would need to have GObject-introspection generate each language into a directory and create a dropdown component in VuePress to switch between directories. Some extra CSS styling would need to be done to make it conform to Allan’s theme. It currently does not live in GNOME’s Gitlab due to slow CI for Gitlab Pages.
Sphinx
Sphinx was also on the radar, but we did not have time to discuss it in detail. Currently no test instance exists either, except for the PyGObject documentation which is written in ReadTheDocs. Christoph Reiter who is one of the documentation maintainers has shared his thoughts on using Sphinx for the Developer Center in the Gitlab discussion linked above.
Next Steps
With the demonstrated instances and detailed discussion we hope to make a decision on a specific technology at the next meeting. If you have questions or comments on the presented technologies, please let your voice be heard in the linked Gitlab discussion threads! It will help inform the final decision-making.
Finally, check out the framadate we have running for arranging the next meeting in 2 weeks. See you there!
