Source code
Revision control
Copy as Markdown
Other Tools
# 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:
````markdown
```{toctree}
:maxdepth: 1
page-one
page-two
```
````