Documentation Engine

Meta-documentation for Babylon’s documentation system itself.

This document explains how the documentation you’re reading is built, themed, and organized. It serves as both reference and maintenance guide.

Architecture Overview

The documentation system is built on three pillars:

Sphinx: Python documentation generator that transforms source files into multiple output formats (HTML, PDF, EPUB).
Diataxis: Information architecture framework organizing content into four distinct quadrants: tutorials, how-to guides, concepts, reference.
Bunker Constructivism: Visual identity applied to both HTML and PDF outputs, derived from Visual Design Guidelines.

docs/
├── tutorials/          # Learning-oriented (Diataxis)
├── how-to/             # Goal-oriented (Diataxis)
├── concepts/           # Understanding-oriented (Diataxis)
├── reference/          # Information-oriented (Diataxis)
├── api/                # Auto-generated API docs
├── commentary/         # Meta-level (outside Diataxis)
├── conf.py             # Sphinx configuration
└── index.rst           # Root document

Source Formats

reStructuredText (RST)

The primary format for structured documentation. Native Sphinx format with full feature support.

Section Title
=============

Subsection
----------

.. note::

   Admonitions use directive syntax.

Cross-references: :doc:`/concepts/architecture`, :func:`calculate_rent`

MyST Markdown

Extended Markdown with RST-equivalent features. Enabled via myst-parser. Used for narrative content like the Vibe Coding Manifesto.

Enabled extensions:

dollarmath: LaTeX math ( $E=mc^2$ )
colon_fence: Directive syntax (::: note)
tasklist: GitHub-style checkboxes
strikethrough: ~~deleted text~~
linkify: Auto-link URLs
deflist: Definition lists
fieldlist: Field lists
attrs_inline: Inline attributes {#id .class}

# MyST Section

:::{note}
Admonitions use colon-fence syntax.
:::

Math: $P(S|R) = \frac{O}{R}$

PDF Generation

Two-Book Output

The build produces two PDF books:

Book	Contents
`babylon-docs.pdf`	Main documentation: tutorials, how-to, concepts, reference, API
`babylon-commentary.pdf`	Meta-level: design philosophy, theoretical foundations

LaTeX Engine

We use XeLaTeX for PDF generation:

Native Unicode support (Greek letters Φ, σ, arrows →, em dashes —)
OpenType font support via fontspec
Required for the Bunker Constructivism color definitions

The pdflatex engine cannot handle the Unicode characters used throughout the documentation.

Build Commands

# Full PDF build (both books)
mise run docs-pdf

# Build single PDF
mise run docs-pdf-single babylon-docs
mise run docs-pdf-single babylon-commentary

# HTML build
mise run docs

# Live-reload development server
mise run docs-live

Bunker Constructivism Theme

The PDF output applies the “Damp Basement Cyberinsurgency” aesthetic defined in Visual Design Guidelines.

Color Palette (LaTeX)

Name	Hex	Usage
Phosphor Burn	`#D40000`	Chapter headings, alerts, active elements
Thermal Warning	`#8B0000`	Section headings, internal links
Wet Concrete	`#1A1A1A`	Code block backgrounds
Terminal Glare	`#F5F5F5`	Code block text
The Chassis	`#404040`	Subsection headings, citations
Exposed Circuitry	`#FFD700`	Not yet implemented (reserved for highlights)
The Dust	`#C0C0C0`	Secondary text, prompts

Typography

Main text: TeX Gyre Termes (Times-like serif)
Headings: TeX Gyre Heros (Helvetica-like sans)
Code: TeX Gyre Cursor (Courier-like mono)
Chapter style: Sonny (bold industrial aesthetic)

These TeX Gyre fonts are included in TeX Live and provide consistent cross-platform rendering.

Configuration Reference

Key settings from docs/conf.py:

# LaTeX engine for Unicode support
latex_engine = "xelatex"

# Two-book output
latex_documents = [
    ("docs-pdf-index", "babylon-docs.tex", ...),
    ("commentary/index", "babylon-commentary.tex", ...),
]

# Eliminate blank pages before chapters
latex_elements = {
    "extraclassoptions": "openany",
    "preamble": r"""
\usepackage{fontspec}
\usepackage{xcolor}
\definecolor{PhosphorBurn}{HTML}{D40000}
% ... color definitions
\usepackage{sectsty}
\chapterfont{\color{PhosphorBurn}}
\sectionfont{\color{ThermalWarning}}
""",
}

API Documentation

Autodoc System

API documentation is auto-generated from Python docstrings using:

sphinx.ext.autodoc: Extract docstrings from modules
sphinx.ext.autosummary: Generate stub pages for modules
sphinx.ext.napoleon: Parse Google/NumPy style docstrings
sphinx_autodoc_typehints: Include type hints in docs

Docstring Format

All public APIs use RST-format docstrings compatible with Sphinx:

def calculate_imperial_rent(wages: Currency, value: Currency) -> Currency:
    """Calculate imperial rent extracted via unequal exchange.

    Args:
        wages: Currency amount paid to workers in core.
        value: Currency amount of value actually produced.

    Returns:
        Imperial rent (Phi) extracted from periphery workers.

    Raises:
        ValueError: If wages or value are negative.

    Example:
        >>> calculate_imperial_rent(Currency(100.0), Currency(80.0))
        Currency(20.0)

    See Also:
        :func:`calculate_exploitation_rate`: Related metric.
    """

Intersphinx

Cross-references to external documentation:

Python standard library: :py:class:`list`
Pydantic: :class:`pydantic.BaseModel`
NetworkX: :func:`networkx.algorithms.centrality.betweenness_centrality`

Mermaid Diagrams

Diagrams are written in Mermaid syntax and rendered via sphinxcontrib-mermaid.

In RST files:

.. mermaid::

   graph LR
       A[Source] --> B[Sphinx] --> C[HTML/PDF]

In MyST Markdown files:

```{mermaid}
graph LR
    A[Source] --> B[Sphinx] --> C[HTML/PDF]
```

Note

Mermaid diagrams render in HTML but appear as placeholders in PDF. For critical diagrams in print, use ASCII art or static images.

Maintenance

Adding New Documents

Create .rst or .md file in appropriate Diataxis quadrant
Add to parent index.rst toctree
Build and verify: mise run docs-live

Updating PDF Theme

Edit the latex_elements["preamble"] in docs/conf.py. Key packages:

xcolor: Color definitions
sectsty: Section heading colors
fontspec: Font selection (XeLaTeX only)
fncychap: Chapter title styling

Testing Documentation

# Run doctest examples in code
mise run doctest

# Check documentation coverage
poetry run sphinx-build -b coverage docs docs/_build/coverage

# Check for broken links
poetry run sphinx-build -b linkcheck docs docs/_build/linkcheck