Developing documentation

The documentation in this repository pertains to the Glean SDK. That is, the client-side code for Glean telemetry. Documentation for Glean in general, and the Glean-specific parts of the data pipeline and analysis is documented elsewhere in the firefox-data-docs repository.

The main narrative documentation is written in Markdown and converted to static HTML using mdbook.

API docs are also generated from docstrings for Rust, Kotlin, Swift and Python.

Building documentation

Building the narrative (book) documentation

The mdbook crate is required in order to build the narrative documentation:

cargo install mdbook mdbook-mermaid mdbook-open-on-gh

Then both the narrative and Rust API docs can be built with:

make docs
# ...or...
bin/build-rust-docs.sh
# ...or on Windows...
bin/build-rust-docs.bat

The built narrative documentation is saved in build/docs/book, and the Rust API documentation is saved in build/docs/docs.

Building API documentation

Swift API documentation is generated using jazzy. It can be installed using:

  1. Install the latest Ruby: brew install ruby
  2. Make the installed Ruby available: export PATH=/usr/local/opt/ruby/bin:$PATH (and add that line to your .bashrc)
  3. Install the documentation tool: gem install jazzy

To build the Swift API documentation:

make docs-swift

The generated documentation is saved in build/docs/swift.

The Python API docs are generated using pdoc3. It is installed as part of creating the virtual environment for Python development.

To build the Python API documentation:

make docs-python

The generated documentation is saved in build/docs/python.

Internal links within the documentation can be checked using the link-checker tool. External links are currently not checked, since this takes considerable time and frequently fails in CI due to networking restrictions or issues.

Link checking requires building the narrative documentation as well as all of the API documentation for all languages. It is rare to build all of these locally (and in particular, the Swift API documentation can only be built on macOS), therefore it is reasonable to let CI catch broken link errors for you.

If you do want to run the link-checker locally, it can be installed using npm or your system's package manager. Then, run link-checker with:

make linkcheck

Spell checking

The narrative documentation (but not the API documentation) is spell checked using aspell.

On Unix-like platforms, it can be installed using your system's package manager:

sudo apt install aspell-en
# ...or...
sudo dnf install aspell-en
# ...or...
brew install aspell

Note that aspell 0.60.8 or later is required, as that is the first release with markdown support.

You can the spell check the narrative documentation using the following:

make spellcheck
# ...or...
bin/spellcheck.sh

This will bring up an interactive spell-checking environment in the console. Pressing a to add a word will add it to the project's local .dictionary file, and the changes should be committed to git.