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 and export EMOD parameter info.

Ongoing branches#

ParamDB stores information for multiple documentation branches; ensure updates are made within the correct branch in both paramDB and github:

Simtype/s

Branch

HIV and malaria

malaria-ongoing

Generic and typhoid

generic-ongoing

TBHIV

TBHIV-ongoing

All others

main

When updating content that is NOT specific to a single branch, such as fixing a typo or expanding upon existing content, you must make these changes in all branches (all ongoing branches and main).

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.