How to Work With the Container Documentation Site

This document explains how to use, extend, and maintain the Final State Press Container Documentation Site.

The container site is a Sphinx-based documentation hub. Its job is to:

• Build a stable, human-authored documentation site

• Host links to independently generated documentation

• Document the processes used to generate those docs

It does not build or manage subproject documentation directly.

Conceptual Model

Before touching files, understand the model.

Two Layers

1. Container Site (this repository)

   • Hand-authored Markdown

   • Built by Sphinx

   • Defines navigation and context

2. Subproject Documentation

   • Autogenerated HTML

   • Built in separate repositories

   • Copied into this repo as static artifacts

These layers are intentionally decoupled.

Repository Structure

final-state-press-docs/
├── docs/                   # Sphinx source (author-written)
│   ├── index.md             # Root landing page
│   ├── projects/            # Project catalog pages
│   ├── process/             # Documentation methodology
│   ├── _static/             # Site-level assets
│   └── _templates/          # Optional theme overrides
├── subprojects/             # Published HTML artifacts
│   └── <project>_docs/
│       └── build/
│           └── index.html
├── requirements.txt
└── README.md

What Goes Where

docs/

Put only hand-written content here.

Examples:

• Index pages

• Process documentation

• Project descriptions

• Links to generated docs

Do not put generated files here.

subprojects/

Put only generated HTML artifacts here.

Each subproject gets its own folder:

subprojects/my_project_docs/build/

This folder should contain:

• index.html

• _static/

• _images/

• Any other Sphinx-generated files

Never edit these files by hand.

Building the Container Site

Prerequisites

• Python 3.11+

• Virtual environment activated

• Dependencies installed

python -m pip install -r requirements.txt

Build Command

From the docs/ directory:

python -m sphinx -b html . _build/html

Output is written to:

docs/_build/html/

This directory is disposable and should not be committed.

Navigation and Indexing Rules

How Sphinx Decides What to Build

A file is included only if:

• It lives under docs/

• It is reachable from index.md via a toctree

Sphinx does not scan folders automatically.

Top-Level Navigation (docs/index.md)

The root index defines the site’s primary sections.

Example:

## Projects

```{toctree}
:maxdepth: 2

projects/index

Processes

This creates two visible sections:
- Projects
- Processes



## Managing Projects

### Adding a New Project Page

1. Create a page:
   ```text
   docs/projects/my-project.md

2. Add content:

   # My Project
   
   Short description of the project.
   
   ## Documentation
   
   - [HTML documentation](../../subprojects/my_project_docs/build/index.html)
   

3. Register it in the project index:

   ```{toctree}
   :maxdepth: 1
   
   my-project
   

4. Rebuild the site.

Adding Generated Project Documentation

1. Build docs in the project’s own repository:

   python -m sphinx -b html . _build/html
   

2. Copy output into the container:

   rsync -av \
     ../my_project/docs/_build/html/ \
     subprojects/my_project_docs/build/
   

3. Verify index.html exists:

   subprojects/my_project_docs/build/index.html
   

4. Ensure the link in the project page points to this path.

Managing Process Documentation

Process documentation explains how documentation is produced.

Adding a New Process Doc

1. Create the file:

   docs/process/new-process.md
   

2. Add it to:

   docs/process/index.md
   

3. Rebuild the container site.

Process docs should describe:

• Pipelines

• Conventions

• Templates

• Rules and constraints

They are authoritative.

What the Container Site Does Not Do

The container site does not:

• Build subproject docs

• Import subproject Python code

• Include external HTML in a toctree

• Validate subproject documentation

• Scan the filesystem for content

All inclusion is explicit.

Common Mistakes to Avoid

• Putting generated HTML under docs/

• Copying files into docs/_build/

• Expecting Sphinx to discover folders

• Sharing conf.py between projects

• Importing subproject code into the container

If you do any of the above, the architecture breaks down.

Recommended Workflow

1. Write or update container content in docs/

2. Build container site locally

3. Build subproject docs in their own repos

4. Copy generated HTML into subprojects/

5. Link to them from project pages

6. Rebuild container site

Repeat as needed.

Philosophy

This site treats documentation as a generated artifact supported by a stable narrative frame.

• The frame is curated

• The artifacts are replaceable

• The process is documented

That separation is intentional and should be preserved.