Generating end user and developer documentation

Requirements

We were looking for ways to generate documentation for the Ingenii SaaS application we are building. Some of the requirements that came up were:

• We wanted to write using Markdown, which also helps when viewing documentation in GitHub
• Keep the final deployment completely serverless to help costs and management overheads
• Generate both client facing and internal documentation
• Keep the docs integrated as much as possible with our code

Architecture

What we’ve evolved to so far is to use Sphinx as the backend, and the generated files are stored in an Azure storage account with a static website frontend.

Sphinx gives us a great translation tool from Markdown into HTML. It also helps with handling things like table of contents, search and indexing, relative links and also reading our Python and JavaScript code to generate our internal developer docs.

The Azure storage static website is deployed with Pulumi. We were initially also uploading the Sphinx generated files through Pulumi, however the downside was that it was generating a resource for each uploaded file. Using the Pulumi Cloud backend, this was too costly. So we switched to using azcopy to sync the files to the Azure storage account, with the only slight downside that it runs as a post-Pulumi step.

We wrap this whole workflow with our GitHub actions which manages the our infrastructure as code and the regular app release processes. This gives us control to synchronise the app releases with the documentation.

We then added some branding and layout which uses Jinja templating and CSS, for a great end result.