Skip to content

Support Versioned User Guide Publication

Historically, software often has a User Guide in addition to the auto-generated API docs.

It's assumed for simplicity we want to simply keep this user guide document in the main branch along with the code such that it is implicitly tied to the tagged version (versioned along side the code).

There are a few ways we could support publication of this versioned User Guide.

  1. Require users to navigate to it manually via GitLab web-based file browser (with tag/branch selector) or use git command line to download (i.e. do nothing in the CI/CD Pipeline)
  2. Add option to configure a file path or paths on the generate-pages job to copy doc to the pages branch and expose in the index as an additional link per version.
  3. Ask users to simply incorporate it into their auto generated docs. Doxygen, Sphinx, and javadoc (the auto-doc tools) all support this to various degrees. For example, the initial "landing" page for the docs is fully customizable, and might as well be the user guide.

Aside: We should be writing all docs in Markdown. The auto-doc tools correctly recognized that browsing API docs from a web browser (HTML) is a very powerful and convenient way to provide docs. They've also all recognized that writing and reading (i.e. maintaining) docs by asking devs to read and write HTML is not ideal. It turns out the winner at the moment for easy markup language that can be translated to HTML automatically is Markdown. And it seems all auto-doc tools now support Markdown. You can edit Markdown directly in GitLab so that makes it easier than, say requiring users to have Office 365 / Desktop Word, or even worse, requiring translation to a PDF (ouch!)

See:

Note 1: We may want to support all three of these. The first one is basically "do nothing", so we already support that. Only the second one requires us to do something here. The third one is also "do nothing" in this project as the onus is then on the workflow users to ensure their auto-doc tool is incorporating their user guide.

Note 2: The GitLab website project pages don't render .html files when browsed (you see the source), and users are encouraged to use the Pages site to have .html files served for browser rendering. Interestingly, many auto-doc tools allow output as Markdown, which if browsed on the GitLab project page IS rendered as HTML automatically. So option 1 above actually would work especially well for Markdown user guides, and could also work reasonably well for auto-docs, as long as you output Markdown!

Edited by Slominski, Ryan