Revision control
Copy as Markdown
Other Tools
---
description: Use this skill when working with Firefox documentation,
including building documentation with `./mach doc`,
fixing Sphinx build errors or warnings, modifying existing
documentation, or adding new docs.
---
## Overview
Firefox documentation is built using **Sphinx**
through the `./mach doc` command. Documentation sources are distributed
throughout the repository and can be written in **reStructuredText
(`.rst`)** or **Markdown (`.md`)**.
The documentation system integrates:
- Sphinx
- MyST parser (for Markdown support, with colon fences, definition lists, field lists, and HTML admonitions enabled)
- custom Mozilla tooling in `tools/moztreedocs/` and `docs/`
Documentation builds into static HTML that is published to **Firefox
Source Docs**.
## Core Principles
- Always reproduce documentation issues **locally first** using
`./mach doc --no-serve --no-open`.
- Treat warnings seriously; they often indicate real navigation or
reference problems.
- Prefer **small targeted builds** while debugging.
- Ensure new documentation is **reachable through a toctree**.
- Keep documentation **close to the code it describes** when possible.
## Recommended Workflow
### 1. Reproduce the issue locally
Start by building the documentation locally. Redirect output to a file
rather than piping through `tail`/`grep`, since builds can be slow:
./mach doc --no-serve --no-open > /tmp/doc_build.txt 2>&1
Common commands:
- `./mach doc --no-serve --no-open` -- build entire tree
- `./mach doc <path> --no-serve --no-open` -- build a specific component (much faster)
- `./mach doc <path>` -- build and serve with livereload for iterative writing
Useful flags:
- `--no-autodoc` -- skip Python/JS API generation for faster builds
- `--verbose` -- run Sphinx in verbose mode for debugging
- `--disable-warnings-check` -- ignore unexpected warnings during local development
- `--linkcheck` -- validate all links in the documentation
- `-j JOBS` -- control parallel build jobs (defaults to CPU count)
Documentation output is generated under:
obj-*/docs/html/
When debugging, prefer building only the relevant component instead of
rebuilding everything.
### 2. Identify the type of Sphinx problem
Most documentation build issues fall into these categories:
- navigation problems (toctree)
- broken references
- duplicate labels
- include directive errors
- autodoc import failures
- uncategorized documentation (missing from `docs/config.yml`)
- configuration issues
The build output from `./mach doc` will normally indicate the failing
file and line. If the build crashes, Sphinx writes backtraces to
`/tmp/sphinx-err-*` files.
Always start by inspecting the referenced file and directive.
## Documentation Layout
Key locations:
Main documentation root:
docs/
Component documentation often lives near the code, for example:
devtools/docs/
toolkit/docs/
browser/docs/
Important configuration files:
- `docs/config.yml` -- categories, allowed warnings, redirects, JS source paths
- `docs/conf.py` -- Sphinx configuration (extensions, theme, MyST settings)
Custom Mozilla Sphinx integration:
tools/moztreedocs/
### How documentation is discovered
The build system discovers documentation directories via `SPHINX_TREES`
variables in `moz.build` files. When adding documentation in a new
location, you must add a `SPHINX_TREES` entry in the relevant `moz.build`.
## Configuration: `docs/config.yml`
This file controls several critical aspects of the documentation build:
- **`categories`**: Every documentation path must be assigned to a
category. If a new doc path is not categorized here, the build fails
with an "Uncategorized documentation" error.
- **`allowed_warnings`**: Regex patterns for known/acceptable Sphinx
warnings. Warnings matching these patterns are logged as "KNOWN"
instead of causing build failures.
- **`redirects`**: URL redirects for backward compatibility when
documentation moves. Format: `old/path: new/path`.
- **`js_source_paths`**: Directories where JSDoc generation is enabled
(tree-wide JSDoc does not work).
## Adding New Documentation
Typical process:
1. Create a `.rst` or `.md` file in the appropriate directory. Prefer Markdown.
2. Add the document to a parent `toctree`.
3. Add the documentation path to the appropriate category in `docs/config.yml`.
4. If adding docs in a new directory, ensure `SPHINX_TREES` is set in the
relevant `moz.build` file.
5. Follow the structure used by neighboring documentation.
6. Build locally with:
./mach doc <path> --no-serve --no-open
7. Resolve warnings before landing the change.
If the page does not appear in the generated navigation, verify that it
is included in a toctree.
When moving documentation to a new URL, add an entry to the `redirects`
section of `docs/config.yml` so old links continue to work.
## Best Practices
- Always build documentation locally before pushing.
- Resolve warnings before landing documentation changes.
- Keep documentation near the code it describes when appropriate.
- Prefer `literalinclude` for code examples instead of copying code.
- When debugging large documentation changes, build only the affected
component.
- Use `--no-autodoc` for faster iteration when not working on API docs.
- If a new warning appears that is expected/acceptable, add a pattern
to `allowed_warnings` in `docs/config.yml`.