Documentation Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• dev/guidelines/documentation.md
• AGENTS.md
• dev/guidelines/python.md
• tasks.py
• pyproject.toml
• dev/adr/0001-adopt-canonical-agentic-structure.md
• dev/guidelines/git-workflow.md

Documentation guidelines define the standards for authoring, structure, and quality control of published and internal documentation in the nornir-infrahub repository. The project follows the Diataxis framework to organize content by user intent and utilizes both hand-written and automatically generated pages.

Documentation is divided into two main layers: the published documentation site located in docs/ and the internal developer reference layer located in dev/. The published site is built using Docusaurus and synchronized to a central documentation repository upon updates to the stable branch.
Sources: dev/guidelines/documentation.md:3-11, dev/adr/0001-adopt-canonical-agentic-structure.md:33-35

Documentation Structure and Organization

The documentation follows the Diataxis framework, which categorizes content into four distinct types. Pages reside in specific subdirectories within docs/docs/ based on these categories.

Category	Intent	Directory
Tutorials	Learning-oriented	(Currently none)
How-to Guides	Task-oriented	docs/docs/guides/
Explanation	Understanding-oriented	docs/docs/topics/
Reference	Information-oriented	docs/docs/references/

Navigation for these pages is manually defined in docs/sidebars.ts. New pages must be added to the nornirSidebar to appear in the website navigation.
Sources: dev/guidelines/documentation.md:13-24, AGENTS.md:139-144

Internal Reference Layer (dev/)

The dev/ directory serves as an internal knowledge base for contributors and is not published to the external documentation site. It contains:

• ADRs: Architectural Decision Records (e.g., dev/adr/0001-...).
• Guides: Internal task-oriented walkthroughs.
• Guidelines: Coding, testing, and documentation standards.
• Knowledge: Technical deep-dives into architecture and data models.
  Sources: dev/guidelines/documentation.md:10-11, dev/adr/0001-adopt-canonical-agentic-structure.md:33-35

Hand-written vs. Generated Reference

The project distinguishes between content maintained by hand and content generated from source code.

Hand-written Pages

General guides, explanations, and top-level README files (like getting-started.mdx) are written manually in MDX format.
Sources: dev/guidelines/documentation.md:28-29

Auto-generated Plugin Reference

Reference pages for plugins located under docs/docs/references/plugins/ are generated from Python docstrings. The invoke generate-docs task performs the following actions:

1. Scans nornir_infrahub/plugins/inventory/ and nornir_infrahub/plugins/tasks/.
2. Parses docstrings for classes and functions using docstring_parser.
3. Renders the information into MDX files using Jinja2 templates (docs/_templates/plugin.mdx.j2).
4. Updates the plugin index (_plugin_index.mdx).

Contributors must not hand-edit generated .mdx files. Instead, update the docstring in the Python source file.
Sources: dev/guidelines/documentation.md:31-41, tasks.py:126-193

This diagram illustrates the automated pipeline for generating plugin reference documentation from code docstrings.
Sources: tasks.py:157-193, dev/guidelines/documentation.md:31-36

Style and Tone

Technical documentation must be direct, concise, and professional.

Content Guidelines

• Guides: Use imperative verbs and address the user directly ("Configure...", "Create..."). Focus on practical tasks.
• Topics: Use a discursive tone to explain "why" and provide design rationale.
• General: Define new terms on first use and maintain consistency with Infrahub's data model and UI naming conventions.
  Sources: dev/guidelines/documentation.md:65-71, AGENTS.md:154-162

Writing for Non-Native Speakers

• Use short, common words and sentences under 25 words.
• Put conditions before actions or results.
• Use active voice and present tense.
  Sources: [dev/guidelines/documentation.md:76-85] (Note: Content derived from the generic technical writing guidelines applied to this project context).

Quality Gates and Linting

All Markdown (.md) and MDX (.mdx) files must pass two automated quality checks. These are enforced via invoke tasks and pre-commit hooks.

Linting Tools

• Vale: Checks prose style and spelling based on the Infrahub style defined in .vale/styles/Infrahub/. Configured in .vale.ini.
• rumdl: Validates and formats Markdown structure. Configuration is found in the [tool.rumdl] section of pyproject.toml.

Task	Command	Description
Lint Markdown	invoke lint-markdown	Runs rumdl check .
Format Markdown	invoke format	Includes rumdl fmt .
Run Vale	vale <file>	Checks prose and spelling (run directly on files)
Sources: dev/guidelines/documentation.md:52-61, AGENTS.md:167-170, pyproject.toml:139-166

Linting Configuration (rumdl)

The project disables certain rumdl rules to accommodate MDX and generated content:

• MD033: Allows Inline HTML required by Docusaurus.
• MD041: Permits files not starting with a top-level heading (for MDX frontmatter).
• MD012: Allows multiple blank lines often found in generated reference docs.
  Sources: pyproject.toml:142-152

Publication and Development Workflow

Local Preview

The documentation site is managed via npm within the docs/ directory.

invoke docs-install    # Install npm dependencies
invoke docs-serve      # Start local server at http://localhost:3000
invoke docs-build      # Perform production build

Sources: tasks.py:75-104, dev/guidelines/documentation.md:44-49

Publishing Process

Documentation is published via a GitHub Actions workflow (.github/workflows/sync-docs.yml).

1. A push occurs to the stable branch.
2. The workflow detects changes in docs/docs/** or docs/sidebars.ts.
3. Changes are copied into the opsmill/infrahub-docs repository.
4. Files are placed into docs-nornir/ and sidebars-nornir.ts in the destination repo.
   Sources: dev/guidelines/documentation.md:73-81, dev/guidelines/git-workflow.md:37-43

Summary

The nornir-infrahub documentation system prioritizes consistency through the Diataxis framework and automated reference generation. By enforcing strict linting with Vale and rumdl, and utilizing a distinct internal reference layer in dev/, the project ensures that both user-facing and contributor-facing documentation remain accurate and accessible.
Sources: dev/guidelines/documentation.md, AGENTS.md