Get started#
We encourage anyone outside the content team who notices inaccurate or incomplete documentation to make direct updates to the documentation source. The process to make updates to the source is simple and, in many cases, may take less time than describing the problem. You don’t need to purchase any software licenses and, if you are making small changes, you don’t even need to install anything on your computer. You can make changes directly in the GitHub UI if you like.
Most software projects have the documentation source files under a /docs folder and automatically generate API reference content from Python docstrings. The structure of the EMOD documentation sets is more complicated than other documentation due to the amount of reuse across the docsets for each simtype. For more information, see EMOD documentation.
Install doc tools#
Install the package you will be documenting. See instructions in the GitHub README or corresponding documentation. See the list of IDM docs.
Install Sphinx and other packages required for documentation:
Clone the GitHub repo.
Open a command prompt window and navigate to the repo folder.
Enter the following:
cd docs pip install -r requirements.txt
If desired, configure the text editor of your choice. See Text editors: Write the source.
Small changes to existing docs#
If you notice a typo, inaccuracy, missing information, or other minor error in the existing documentation, you can easily make the fix yourself without installing anything. We recommend this over emailing the team or filing a documentation ticket because it is more efficient.
On Read the Docs, which are found here: https://docs.idmod.org/index.html, click the Edit on GitHub link in the upper-right.
This will open the source RST file for the HTML topic. For EMOD, many topics are shared from the generic docset or from transmission-layer docsets. If you see only a
.. include:: path/to/sourcestatement, this is a pointer to the shared source file. Open this file instead. If you need to add disease-specific information to a topic shared from generic, see EMOD documentation for more information on the sharing infrastructure.Edit the file directly in the GitHub UI and file a pull request, tagging one or more members of the content team to review and merge.
Large changes#
For larger changes to the documentation, such as writing complete RST topics, you can file a documentation ticket or make the changes yourself. For information, see Documentation workflow. To make changes yourself, you will want to clone the repo and write locally in a text editor. Most editors have RST syntax highlighting and other tools to make this easier; see Text editors: Write the source for info on how to configure some of the more common editors. See reStructuredText primer for an introduction to reStructuredText (RST) syntax. This includes information on headings, font styling, diagrams, tables, and other content.
Test the documentation build locally before submitting a pull request with your changes. For more information, see Sphinx: Build the HTML output and Sphinx build troubleshooting.
Python docstrings#
Developers are responsible for writing docstrings in their Python code. Sphinx is configured to automatically create API reference topics from these docstrings. For more information, see Google style Python docstrings. Test the documentation build locally before submitting a pull request with your changes. For more information, see Sphinx: Build the HTML output and Sphinx build troubleshooting.
Set up new documentation set#
To create a new documentation set for a new software library or package, you may create the Sphinx project yourself or contact the documentation team to set it up. As a starting point, you can copy an existing project, modifying the files indicated in Configure the build to customize the configuration. If you are working on a Python library, you can also use a cookiecutter project to automatically configure a skeleton Sphinx project.
If you set the Sphinx project up yourself, you must still contact someone from the documentation team to set up the corresponding project in Read the Docs to build and host the documentation. See Read the Docs: Host the docs for more information.
