Building Documentation - Complete Guide¶

🤖 AI-Generated Content

This documentation was generated with AI assistance and is still being audited. Some, or potentially a lot, of this information may be inaccurate. Learn more.

Quick Start (30 seconds)¶

make docs-serve    # or: we docs serve

Open: http://127.0.0.1:11000 (for provide-foundry)

That's it! The first run will automatically: - Extract theme and configuration - Install dependencies - Start the development server

Available Commands¶

# Development
make docs-serve     # Serve with live reload
make docs-build     # Build static site
make docs-clean     # Clean artifacts

# Validation
python scripts/docs_validate.py verify-config      # Validate mkdocs.yml files
python scripts/validate_partials.py                # Validate partial references
python scripts/validate_standardization.py         # Check standardization

# Maintenance
make docs-setup     # Re-extract theme/config (rarely needed)

Port Registry¶

Each project uses a unique port to avoid conflicts when running multiple documentation servers simultaneously. Ports are organized by project layer:

Foundation Layer (11001-11003)¶

11001 - provide-foundation
11002 - provide-testkit
11003 - provide-workspace

Pyvider Framework (11010-11014)¶

11010 - pyvider
11011 - pyvider-cty
11012 - pyvider-hcl
11013 - pyvider-rpcplugin
11014 - pyvider-components

Tools Layer (11020-11027)¶

11020 - ci-tooling
11021 - flavorpack
11022 - plating
11023 - wrknv
11024 - supsrc
11025 - tofusoup
11026 - messometer
11027 - bfiles

Terraform Providers (11030-11031)¶

11030 - terraform-provider-pyvider
11031 - terraform-provider-tofusoup

Documentation Hub (11000)¶

11000 - provide-foundry (monorepo aggregator)

First-Time Setup¶

Normally automatic, but if needed manually:

# Install dependencies
uv sync

# Extract documentation assets
make docs-setup

Troubleshooting¶

Build fails with "cannot find base-mkdocs.yml"¶

Fix: make docs-setup

Explanation: Documentation theme and configuration need to be extracted from the provide-foundry package to .provide/foundry/ before building.

Port already in use¶

Fix: Each project has a unique port (see Port Registry above). If you see a port conflict, check what's running on that port:

lsof -ti:11000  # Replace 11000 with your project's port

Kill the process if needed:

lsof -ti:11000 | xargs kill

Link checker shows many "errors"¶

Expected behavior: When running lychee in offline mode, you may see warnings about: - Extensionless links (e.g., docs/guides instead of docs/guides.md) - Monorepo package directories (created at build time) - Anchor links in markdown files

These are not real errors - MkDocs handles these correctly when building. The .lychee.toml config filters most false positives.

For accurate link validation, run after building:

mkdocs build
lychee site/

Still having issues?¶

Run diagnostics:

python scripts/validate_standardization.py

Architecture¶

All projects inherit from shared base configuration: - Base config: .provide/foundry/base-mkdocs.yml - Theme: .provide/foundry/theme/ (CSS, JS, custom Material theme) - Shared partials: .provide/foundry/docs/_partials/ (reusable documentation snippets) - API generator: .provide/foundry/gen_ref_pages.py

When you run make docs-setup, these are extracted from the provide-foundry package.

How Documentation Builds Work¶

Extraction (make docs-setup):
Copies theme assets from installed provide-foundry package
Creates .provide/foundry/ directory structure
Extracts base configuration, partials, and scripts
Configuration Inheritance:
Each project's mkdocs.yml starts with: INHERIT: .provide/foundry/base-mkdocs.yml
Projects override only: site_name, site_url, repo_url, dev_addr, navigation
All theme, plugins, and markdown extensions come from base config
Building (make docs-build):
MkDocs loads base config + project overrides
Processes markdown with extensions (code highlighting, admonitions, etc.)
Generates API docs using mkdocstrings
Applies theme and custom CSS/JS
Outputs static HTML to site/
Serving (make docs-serve):
Starts development server on project's assigned port
Watches files for changes and auto-rebuilds
Provides live reload in browser

Monorepo Documentation (provide-foundry only)¶

The provide-foundry project aggregates documentation from all 18 projects using the mkdocs-monorepo-plugin:

nav:
  - Home: index.md
  - '!include ./pyvider/mkdocs.yml'
  - '!include ./flavorpack/mkdocs.yml'
  # ... all projects included

This creates one unified documentation site at http://127.0.0.1:11000 with: - Cross-project search - Unified navigation - Consistent theme across all projects - API docs from all packages

Advanced Usage¶

See: - Contributing to Documentation - Standards and best practices - Link Checking Reference - Understanding lychee and link validation

Quick Reference¶

Command	Purpose
`make docs-serve`	Start dev server with live reload
`make docs-build`	Build static HTML site
`make docs-clean`	Remove build artifacts
`make docs-setup`	Extract theme/config (rarely needed)
`python scripts/docs_validate.py verify-config`	Validate configurations
`python scripts/validate_standardization.py`	Check project compliance

Need Help?¶

Check this guide first
Run python scripts/validate_standardization.py to diagnose issues
See CONTRIBUTING-DOCS.md for detailed documentation standards
Ask in #documentation channel