documentation

## Overview Firefox documentation is built using **Sphinx** through the `./mach doc` command. Documentation sources are distributed throughout the repository and are written in **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 `.md` file in the appropriate directory. 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. ## Cross-references between documents Link to the **source file**, not to the generated URL: - Good: `[mots](/mots/index.md)`, `[Coding style](/code-quality/coding-style/index.rst)` - Bad: `[mots](/mots/index.html)` -- produces `WARNING: 'myst' cross-reference target not found: '/mots/index.html' [myst.xref_missing]` - Bad: a full `https://firefox-source-docs.mozilla.org/...` URL for in-tree documentation -- it bypasses link validation and breaks when pages move. The path is rooted at the documentation tree (leading `/`), and the extension must match the actual source file (`.md` or `.rst`). To link to a section, append the anchor: `/mots/index.md#desktop-theme`. ## 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`.