panurus

Documentation Guide

This guide outlines how to contribute to, test, build, and deploy the static documentation site for Panurus.

Documentation is built using MkDocs with the premium, responsive Material for MkDocs theme.


πŸ› οΈ Local Development Setup

To preview changes locally, you will need Python 3 installed on your system.

1. Install Dependencies

Install the pinned documentation tools (including MkDocs and the Material theme) using the requirements file:

make docs-install

This target runs:

pip install -r requirements.txt

2. Live Preview During Editing

You can start a local development server that watches for file changes and automatically refreshes your browser:

make docs-serve

Once started, open your browser and navigate to: πŸ‘‰ http://127.0.0.1:8000

3. Build Static Site Locally

To verify that all links are resolved and the site builds cleanly without any warnings:

make docs-build

This runs the strict compiler command:

mkdocs build --strict

[!IMPORTANT] The --strict flag ensures that the build will fail if there are any warnings (such as orphaned files or broken internal links). Always verify your build with make docs-build before committing changes!

The Check Markdown links workflow (.github/workflows/md_links.yml) runs three checks:

[!NOTE] Anchors follow GitHub’s heading slugs (e.g. ### 3. Finality Tracking becomes #3--finality-tracking), which differ from the slugs MkDocs generates.


πŸš€ GitHub Pages Deployment Setup

The static documentation site is automatically built and deployed to GitHub Pages whenever changes are merged into the main branch.

If this is being set up on a new fork or repository for the first time, follow these steps to configure GitHub Pages:

  1. Navigate to Repository Settings: Go to your repository page on GitHub, click on the Settings tab.
  2. Access Pages Settings: In the left sidebar under the β€œCode and automation” section, click on Pages.
  3. Configure Build and Deployment:
    • Under Build and deployment -> Source, select β€œDeploy from a branch”.
    • Under Branch, select gh-pages and set the folder to / (root).
    • Click Save.

The GitHub Actions workflow .github/workflows/docs.yml will automatically create and update the gh-pages branch on every merge.


πŸ“‚ Documentation Directory Structure

All documentation source markdown files are located in the docs/ directory of the project:

docs/
β”œβ”€β”€ README.md               # Home page
β”œβ”€β”€ configuration.md         # Configuration guide
β”œβ”€β”€ development/            # Developer guidelines and guides
β”‚   β”œβ”€β”€ ai_agents.md        # AI Agent context
β”‚   β”œβ”€β”€ documentation.md    # This guide
β”‚   └── ...                 # Other development guidelines
β”œβ”€β”€ drivers/                # Fabric and ZK driver specs
β”œβ”€β”€ services/               # Core services (auditor, storage, ttx, etc.)
└── imgs/                   # Images and static assets

Adding New Documentation Pages

  1. Write your markdown file and place it in the appropriate subdirectory of docs/.
  2. Add your page to the navigation hierarchy in mkdocs.yml located at the root of the project.
  3. Validate your changes locally using make docs-serve or make docs-build.