Get started writing

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

  1. Install the package you will be documenting. See instructions in the GitHub README or corresponding documentation. See the list of IDM docs.

  2. Install Sphinx and other packages required for documentation:

    1. Clone the GitHub repo.

    2. Open a command prompt window and navigate to the repo folder.

    3. Enter the following:

      cd docs
      pip install -r requirements.txt
      
  3. 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.

  1. On Read the Docs, click the Edit on GitHub link in the upper-right.

  2. 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/source statement, 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.

  3. 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.

_images/a12b066ace0fd18c911e96078e39e8cf3ba5ee1026c499bb93d273e71fdd25e9.svg

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.

_images/0af3cfe073d89750c39dff538f0b5de3c116d4440e3118712afaedabe6194b47.svg

Pull README files into docs

Sometimes you want to include information in a README for those browsing the GitHub repo and information in the documentation for those browsing the HTML docs. To avoid duplicating the same information in two locations, you can pull README files into the docs as described below. We encourage you to use this judiciously as the README files must be readable in their raw format, preventing usage of Sphinx-specific content that enables better manageability of HTML docs.

  1. Write the README in reStructuredText (.rst), not Markdown (.md). If you like, use the converter at https://cloudconvert.com/md-to-rst to easily convert Markdown to RST.

  2. Create a new RST file in the /docs folder and add the following line to it:

    .. include:: ../path_to_README.rst
    
  3. To include additional information in the HTML docs but not the README file, add that content to the RST file in the /docs folder after the include directive.

  4. To include information in the README but not the HTML docs, use the start_line, end_line, start_after, or end_before options with the include directive to select what content from the README should be included in the HTML. For more information, see https://docutils.sourceforge.io/docs/ref/rst/directives.html#include.

    Use this cautiously! The connection between the README and HTML docs isn’t apparent from the README, so when content changes in the README, the content in the HTML can be changed in inadvertant ways.

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.

_images/a2e9c9ecdf886f6ca54e2fd89435bf5fcb0f490acdcbd9d0dccbd544adbd8fad.svg

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.

_images/3890485a81c5c1ee4509b2fecde3c35770a56b4bae777de2f1bf4190101e9bda.svg