Documentation toolchain

Many technical documentation teams use a single end-to-end program that handles all aspects of the process: writing, source control, compilation, hosting, etc. These are often XML-based and require expensive licenses to write or review docs. They are great at enforcing standards, but can create silo’d doc teams because getting content reviews often requires exporting Word or PDF files, which tend to multiply and diverge, making the review process very inefficient.

Instead, we follow a “docs as code” philosophy in which the process and tools used for writing documentation align closely with those used for writing code. This enables greater collaboration across the organization and more ownership of documentation by people in all roles. For more information on this philosophy and its implementation, see https://www.writethedocs.org/guide/docs-as-code/. The following tools are used in our implementation of the documentation system:

_images/Toolchain.png
Text editor

One of the biggest benefits of a “docs as code” toolchain is that you can work in the text editor or IDE you are already using, with no need to purchase or learn a new piece of software. The documentation team likes Sublime Text, but any text editor will work.

Parameter database

The paramDB contains all EMOD parameters for all simtypes and versions. You can run various queries to export CSV files for each simtype. Sphinx uses these CSV files to compile HTML tables in the documentation.

GitHub

All software documentation source files are stored in GitHub. EMOD documentation is in its own repository and all other documentation is in the associated code repo under a /docs directory. Anyone at IDM can directly edit the documentation and submit a pull request to make changes. Please request a review from someone on the documentation team and any other subject matter experts.

Sphinx

Sphinx takes the documentation source files, which include the CSV files exported from the paramDB, manually written reStructuredText (RST) files, and docstrings within Python files, and compiles them into HTML or PDF format. You should install Sphinx locally and test the documentation build before submitting significant changes to the documentation.

Read the Docs

We have a paid account with Read the Docs to automatically rebuild documentation when changes are committed to GitHub and host the documentation for us. This enables functionality like hosting multiple versions, password-protected documentation, improved search, and more.

The topics in this section describe how to work with each of these documentation tools in our workflow.

For installation instructions for working on the docs, see Install doc tools.