Adding Documentation

To add new documentation, define the SPHINX_TREES and SPHINX_PYTHON_PACKAGE_DIRS variables in moz.build files in the tree and documentation will automatically get picked up.

Say you have a directory featureX you would like to write some documentation for. Here are the steps to create Sphinx documentation for it:

  1. Create a directory for the docs. This is typically docs. e.g. featureX/docs.

  2. Create an index.md file in this directory. The index.md file is the root documentation for that section. See build/docs/index.md for an example file.

  3. In a moz.build file (typically the one in the parent directory of the docs directory), define SPHINX_TREES to hook up the plumbing. e.g. SPHINX_TREES["/featureX"] = "docs". This says the ``docs`` directory under the current directory should be installed into the Sphinx documentation tree under ``/featureX``.

  4. If you have Python packages you would like to generate Python API documentation for, you can use SPHINX_PYTHON_PACKAGE_DIRS to declare directories containing Python packages. e.g. SPHINX_PYTHON_PACKAGE_DIRS += ["mozpackage"].

  5. In docs/config.yml, defines in which category the doc should go.

  6. Run the linter with ./mach lint -l md

Markdown files are parsed with MyST, a CommonMark-compatible parser that supports Sphinx roles and directives. To use a Sphinx directive in Markdown, use a fenced code block with the {directive-name} info string, for example:

```{toctree}
:maxdepth: 1

page-one
page-two
```