Building documentation¶
The site uses MkDocs, Material, and mkdocstrings. README.md is the concise public overview; detailed user and administrator guidance belongs in docs/user/ and docs/admin/.
Install documentation dependencies¶
From the repository root, using your existing development environment:
poetry install --only docs --no-root
This installs only the optional documentation dependency group. Building the site does not require Nautobot, Django setup, Redis, a database, provider credentials, or a running Nautobot server. Source references use static analysis rather than importing the app.
The Invoke commands additionally require Invoke from the development environment. Without Invoke, use the equivalent MkDocs commands below.
Preview¶
invoke docs
Open http://127.0.0.1:8001. Stop the documentation server with Ctrl+C. This is a documentation-only server, not a Nautobot server.
Equivalent command:
python -m mkdocs serve --livereload
Build and validate¶
invoke build-and-check-docs
Equivalent command:
python -m mkdocs build --no-directory-urls --strict
Warnings fail the build. Generated HTML goes into nautobot_agent/static/nautobot_agent/docs/, which is ignored by Git. File-style links allow the documentation to be served through Nautobot's static-file handling.
The packaging configuration includes this generated directory in wheels and source distributions when it exists. Build the documentation before packaging when the distribution should include in-app documentation; package builds do not generate it automatically. Do not commit generated HTML.
Edit the site¶
- Keep
README.mdconcise: summarize capabilities and trust boundaries, then link to guide pages rather than reproducing detailed setup or behavior references. - Keep detailed user workflows and data handling under
docs/user/, and administrator installation, configuration, permissions, integrations, operations/recovery, compatibility, upgrade, and removal guidance underdocs/admin/. - Add supplementary Markdown under
docs/and register completed pages inmkdocs.ymlnavigation. - Use admonitions, fenced code, and images where they help readers.
- Keep code-reference directives pointed at existing Python modules; mkdocstrings renders their docstrings from source.
Screenshots¶
Before adding or replacing a screenshot, check it for credentials, private inventory, usernames, endpoints, and other sensitive details. Trace screenshots need particular care because trace and span data is unredacted. Prefer one readable image per topic. Use paths relative to the Markdown file in docs/; README image paths are relative to the repository root.