Documentation Contribution Guidelines#

Documentation Overview#

Most development starts with a GitHub Issue. See more about issues on the Development page. The documentation consists of the documentation pages (like this one) and inline code documentation to generate the code reference. The documentation pages can be found in science_jubilee/docs/source. We use Sphinx to generate the documentation, which in turn uses the Markedly Structured Text (MyST) Parser. MyST provides flexibility in that you can use standard Markdown files while exposing the more advanced features of the ReStructuredText (RST) format. The inline code can be found immediately after all functions in the science-jubilee package.

See below for information on how the documentation is organized and how it can be modified. For simple edits (e.g., fixing typos or adding clarification), simply click the “Edit on Github” button at the upper-right of the corresponding page. To make and submit more involved changes to the documentation, please follow the same steps outlined in the Code Contribution Guidelines.

Building the Docs#

If you install the science-jubilee conda environment, all of the packages necessary to build the documentation should be installed automatically (make sure to conda activate science-jubilee). Otherwise, you will need to run pip install -r docs/requirements.txt in your environment first. Then, run the following lines:

cd docs
make html

You can preview the changes in the _build/html folder, which is untracked by git, as specified in .gitignore. Within VS Code for example, you can install the Live Server extension, right-click on docs/_build/html/index.html, and select “Open with Live Server” to dynamically view the documentation. Run make html within the docs folder each time you’d like to view the changes.

Adding New Pages#

If you are adding new documentation pages, make sure to add a target header at the top of your new .md file, just before the top-level heading:

(my-target-header)=
# My Top-level Heading

Click the “Show Source” button on the upper-right of this page to see a real example in this project. Refer to https://myst-parser.readthedocs.io/ for more information.

Adding Inline Documentation#

‘Docstrings’ are specifically formatted comments in code which can be used to generate documentation. We use the Sphinx docstring format to generate our API reference. Please see the description here, and/or take a look at existing docstrings in the repository!