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.
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.
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
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.
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
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
For more information, see the only directive docs.
The docset tags that are used with
only are defined in
the Makefile/make.bat for local builds and in
tags.add() in the conf.py
file for Read the Docs builds.
The CSV folder contains CSV files exported from the parameter database. These
are used to build parameter tables with the
csv-table directive. For
.. 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.
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.
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.
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:
Create a new topic in the specs directory of the EMOD-docs repository, using an informative name and version number in the file name.
Make your changes and save the file to a working branch.
Submit a pull request, tagging content team members to review your changes.
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.