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 primary implementation of the documentation system.
Note
Because Sphinx does not have a plug-in for documenting R code, we use a different toolchain for producing documentation for R packages. It still follows a “docs as code” philosophy but uses different tools. See R package toolchain instead.
- 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
ParamDB contains all EMOD parameters for all simtypes and branches. CSVs exported from the DB are used to generate the parameter information tables in the EMOD documentation. See Parameter DB: Store and export EMOD parameter info for additional information.
- 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.