Source for the Ubuntu Robotics documentation site, built with Sphinx and bootstrapped from the Canonical sphinx-stack template. This repository documents the Ubuntu Robotics stack; it is not the template itself.
This repository contains the documentation for Canonical's Ubuntu Robotics stack, including packaging and distribution with snaps, observability with COS for Robotics, security hardening, and ROS ESM guidance.
The documentation source lives under docs/.
Key locations:
- docs/index.rst - documentation home page
- docs/tutorials/ - guided, learning-oriented tutorials
- docs/how-to-guides/ - task-focused maintenance and operations guides
- docs/references/ - reference material
- docs/explanations/ - conceptual background
- docs/Makefile - local build, preview, and validation targets
- .github/workflows/ - CI checks that run for documentation changes
Install the core tools used by the local documentation workflow:
sudo apt update
sudo apt install make python3 python3-venv python3-pipThe optional accessibility check requires additional tooling:
sudo apt install npmFrom docs/, create the virtual environment and install dependencies:
cd docs
make installRun a live-reloading preview server:
cd docs
make runThen open http://127.0.0.1:8000 in your browser.
Before opening a pull request, run the checks that match your change.
Build the site cleanly:
cd docs
make clean-doc
make htmlLint Markdown:
cd docs
make lint-mdCheck spelling:
cd docs
make spellingCheck inclusive language:
cd docs
make wokeRun style-guide linting with Vale:
cd docs
make valeCheck links:
cd docs
make linkcheckOptional accessibility check:
cd docs
make pa11y-install
make pa11yGitHub Actions also run documentation checks for pull requests that touch docs/.
Use a git worktree rather than editing directly in your main checkout. A typical maintainer workflow looks like this:
git fetch origin
git worktree add ../robotics_documentation-my-change -b docs/my-change origin/main
cd ../robotics_documentation-my-changeMake your changes, run the relevant checks from docs/, then commit and push your branch:
git status
git add readme.rst docs/
git commit
git push -u origin docs/my-changeOpen a pull request against main and let CI complete before requesting
review or merging. Avoid force-pushing once review is in progress unless there
is a clear need to rewrite history.
- Keep repository-level guidance in this README focused on this documentation project, not on the upstream template.
- If pages move, add redirects in docs/conf.py so existing links keep working.
- Add project-specific spelling exceptions to docs/.custom_wordlist.txt instead of editing shared upstream word lists.
- When adjusting documentation structure, update the relevant index or toctree pages under docs/.