EMOD documentation

The EMOD documentation is presented in multiple documentation sets, one for each disease simtype. Because a significant amount of information is the same across all simtypes, we share content across the docsets to avoid duplication and inconsistent/stale content.

Generic folder

The generic folder contains all content that is common to all disease simulations: installation, using EMOD, generic modeling tutorials, etc. When naming files, begin with the name of the section and connect words using hyphens.

Disease/transmission folders

To pull common content from the generic folder into the disease-specific docsets, create a topic with the same name in the disease directory. In that topic, enter:

.. include:: ../generic/topic-name.rst

Similarly, if the content is shared from the intermediate transmission mode, you can use:

.. include:: ../vector/topic-name.rst

The include directive takes a path relative from the topic in which it appears; you cannot provide an external URL, for example. For more information, see the include directive docs. This limitation is why the EMOD docs have a flat file structure: bits of content are reused so extensively that they would end up nested at different levels with more structure. It’s important to remember that any content added to generic must be added to all other EMOD docsets using the include directive.

Content that is entirely specific to the disease or transmission mode can be written in separate RST files stored in the corresponding folder. When naming files, begin with the name of the simtype so it’s easy to differentiate between shared common content and disease-specific content.

Conditional content

In addition to wholesale reuse of topics across docsets, the EMOD docs make extensive use of conditional text. For example, if any of the generic topics contain information specific to a particular disease that should not be a separate topic, conditionalize that content so it only builds into the specified docset.

If the conditional content can appear at the end of the topic, you can add that specific info after the include directive and it will be appended to the end of the shared content. For example:

.. include:: ../generic/topic-name.rst

This is additional information specific to the simtype.

If placing the specific information at the end of the topic does not flow, use the only directive. You can use Boolean operators to use multiple conditions. For example:

.. only:: malaria

    Indented conditional text will be included in the malaria docset only.

.. only:: malaria or vector

    Indented conditional text will be included in the malaria and vector docsets only.

You cannot use the only directive to conditionalize an entire topic because Sphinx runs a check on the presence of all required files before it runs the conditionalization. Likewise, if you link to a topic that does not exist in the current docset, you will get an error, even if you conditionalize the text containing the link using the only directive.

For more information, see the only directive docs. The docset tags that are used with only are defined in SPHINXOPTS in the Makefile/make.bat for local builds and in tags.add() in the conf.py file for Read the Docs builds.

CSV folder

The CSV folder contains CSV files exported from the parameter database. These are used to build parameter tables with the csv-table directive. For example:

.. csv-table::
   :header: Parameter, Data type, Minimum, Maximum, Default, Description, Example
   :widths: 10, 5, 5, 5, 5, 20, 5
   :file: ../csv/config-sampling-typhoid.csv

For more information, see Parameter DB: Store EMOD parameter info.

Ongoing branches

We previously had an agreement to document only parameters and features in the master branch of DtkTrunk, not in unmerged working branches. This has been modified recently to include documenting parameters in the following ongoing branches: malaria-ongoing, hiv-ongoing, and generic-ongoing. However, given that this agreement is new as of spring 2021, the documentation is not yet current with the ongoing branches.

The paramDB currently cannot support ongoing branches. To document ongoing branches in the interim until the paramDB has been updated, manually make changes to the CSV files. These changes will then be ingested by the paramDB. Remember to make changes in all CSV files in which a given parameter appears to avoid merge conflicts later.

Warning

Do not use Excel to manually edit CSV files. Excel hides surrounding quote marks and can introduce errors by changing the encoding from UTF-8 or otherwise making invisible changes. Instead, we recommend editing CSV files in a text editor like Sublime.

When updating content that is not specific to ongoing branch work, such as fixing a typo or expanding upon existing content, you must make these changes in all branches (all three ongoing branches and the master branch). If an ongoing branch changes something that applies to other simtypes, make that change broadly too. For example, if malaria-ongoing updates the InsetChart report, you must make these changes in all simtype docsets in the malaria-ongoing branch because that report is available for all simtypes.

Specs

The spec folder is used for documenting specifications for work in progress in ongoing branches. These records can be used to write the full documentation. There is an RST template available for writing specs. See RST templates. To add a new spec, follow these steps:

  1. Create a new topic in the specs directory of the EMOD-docs repository, using an informative name and version number in the file name.

  2. Make your changes and save the file to a working branch.

  3. Submit a pull request, tagging content team members to review your changes.

  4. They may ask additional clarifying questions before merging the pull request. The information you provided will be added to the appropriate docset by one of the content team writers and the file you committed will remain unmodified in the specs directory.