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.
GitHub Pages¶
The public site is https://gt732.github.io/nautobot-app-agent/.
The Documentation workflow in .github/workflows/docs.yml builds and
deploys it on pushes to main, or through Actions → Documentation → Run workflow.
Repository Settings → Pages → Source must be GitHub Actions.
The workflow installs only the locked documentation dependency group and
statically renders code references; it does not start Nautobot or use provider
credentials. Its strict build uses directory-style URLs and writes to site/:
python -m mkdocs build --strict --site-dir site
The hosted build is separate from the file-linked in-app build above.
Both output directories are ignored by Git. Source-edit links continue to
target docs/ on main.
The full Docker CI workflow skips pushes and pull requests that change only
docs/, README.md, mkdocs.yml, .readthedocs.yaml, or the documentation
deployment workflow. Mixed code/documentation changes still run full CI, as do
changes to dependencies, CI itself, and runtime skill Markdown. Manual CI runs
remain available through Actions → CI → Run workflow. Documentation
deployment still runs on pushes to main.
If branch protection requires the Docker CI check, GitHub path filtering can leave a docs-only pull request waiting for that skipped check. Account for this when configuring required checks.
Nautobot branding¶
The site uses the official Nautobot app cookiecutter's logo, favicon, stylesheet,
and adapted footer, with this app's banner and guide content. Theme settings live
in mkdocs.yml; the assets and footer override live under docs/assets/.
The upstream assets retain their Apache-2.0 license in docs/assets/LICENSE;
the app itself remains MIT-licensed. Community links do not imply sponsorship.
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.