Documentation Survey

The goal is to understand what our current documentation does and survey what other systems are doing. Additionally, we would like to come up with a set of features to implement and potential design.

Problem Statement

• The current state of developer.gnome.org and help.gnome.org leave a lot to be desired. On the surface the site provides integration with the "GNOME style" but it is mostly skin deep. It is difficult to determine where you are with the documentation sites as well as how to navigate between separate, but related projects.
• Furthermore, moving within a piece of documentation is haphazard and lacks strong navigational presence.
• Individual project documentation often lacks cross-referencing, exacerbating the "disconnected feel" of developer documentation. Tutorials also cannot cross-reference API documentation and the API documentation cannot cross-reference between consumer languages.
• An important part of documentation is the ability to search for a particular topic. Search is not unified across the web property and is trivial in quality.
• Keeping the documentation web properties up to date often requires manually uploading documentation and fixing cross-references (when supported, such as with gtk-doc). This often results in out of date or missing documentation.
• Incorrect our outdated documentation is an inevitability. Today, when a developer comes across such documentation, locating the documentation to fix it and submit a patch is non-trivial. It requires cloning the repository, creating a patch (in some cases also building the project), uploading to bugzilla, and then waiting for the next release. This iteration cycle needs to be shortened so that we can use our numbers to improve things faster.
• It's unclear to maintainers how to add their projects documentation to the developer site. Especially if you want tutorials that can exist outside your projects specific documentation (for example, platform tutorials/demos).

Desired Features

• Meson and autotools integration
• Accurate documentation for C libraries and programs (.gir alone is not sufficient)
• Support for extended GLib and Gtk features such as child and style properties
• Integration with supplemental documentation when source-only documentation is insufficient
• Cross-referencing user docs, API docs, supplemental, guides, howtos
• Versioned SDK suites for comprehensive docs with tagged versions
• Fully static html/css/js with options for search similar to Sphinx .doctree files
• Support for additional languages such as Python, GJS, Rust, C++, and Vala (including cross-referencing)
• Fast generation (sphinx for example is very slow as the size increases)
• De-deduplicate docs that are dependencies of multiple projects (no need to embed Gtk docs multiple times on d.gnome.org)
• Small file-size for local docs install (possibly generate search indexes locally)
• Must compress well
• Should be translatable in the project source tree (gettext preferred for GNOME)
• Links to source code to "read more"
• Links to code examples from git.gnome.org
• "Edit Source" by to open doc source in gitlab code editor.
• Ability to supply meta-data about projects that may not be available from source input (project descriptions, url bases, project links, etc)
• Support for various input formats (mallard, rst, gtk-doc, long form howtos, etc)
• Support for cross-reference links through external systems (specify URL base, ensure links are updated)
• Generate output suitable for use by devhelp
• Support for downloading full sdk doc suite as zip/tarball
• Integration with ftp-admin on master.gnome.org to extract docs and update the sdk/suite
• Inheritance graphs using graphviz (I don't actually find this useful, but people seem to like it)
• Locate documentation by pkg-config name so IDEs can automatically fetch docs
• Ability to add meta-navigation templates to "glue" things together (developer.gnome.org landing page for example)
• Documentation can live both "stand-alone" and part of a "suite" and needs to be usable in both cases
• developer.gnome.org has a huge amount of documentation, so incremental updates is probably important. additionally help.gnome.org is part of the same logical property, so it probably makes sense to unify the build pipeline for all of this.
• We need documentation to continue working as it stands today, where the integration points with the "documentation engine" happens either with push or pull/poll semantics.

Existing Tools

gtk-doc

Sphinx

Mallard

PyGObject GI Docs

See https://lazka.github.io/pgi-docs/

Valadoc

See https://valadoc.org/

Proposed Solution

• Daemon or stateful pipeline which can ingest updated documentation and spit out a full developer site with projects/tutorials/howtos/help merged into cohesive site.
• Ability to ingest gtk-doc and retheme html/css to fit into larger web property (see library-web project)
• Ability to ingest mallard and retheme html/css to fit into larger web property
• Ability to map individual documentation into specific subdirectory/location
• Use sidebar style for navigation, even with gtk-doc. Use back-arrow style rather than tree-dive as mockups call for.
• gnome-continuous and sdk.gnome.org build integration so that they can deliver build artifacts (compiled gtk-doc files, etc)
• Full-text extraction for Xapian-style full-text search index (server required)
• Keyword extraction for static-keyword-only search (using trie.js, devhelp2, or similar)
• We will need a series of overlays to bridge between various project documentation.
• Some documentation will need fixups when a dependent project is updated.
• Generate documentation for G-I languages (Python, GJS, Vala, etc)
• When generating API documentation, we need to insert selectors for version and programming language (part of generated theme likely)
• Snapshot output for future zip/tarball recreation
• We might need to index all of the link endpoints for the generated projects into an index to speed up cross-references.
• TODO: plenty more