# 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

```text
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:

```text
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

```bash
python -m pip install -r requirements.txt
```



### Build Command

From the `docs/` directory:

```bash
python -m sphinx -b html . _build/html
```

Output is written to:

```text
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:

```md
## Projects

```{toctree}
:maxdepth: 2

projects/index
```

## Processes

```{toctree}
:maxdepth: 2

process/index
```
```

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:
   ```md
   # My Project

   Short description of the project.

   ## Documentation

   - [HTML documentation](../../subprojects/my_project_docs/build/index.html)
   ```

3. Register it in the project index:
   ```md
   ```{toctree}
   :maxdepth: 1

   my-project
   ```
   ```

4. Rebuild the site.



### Adding Generated Project Documentation

1. Build docs in the project’s own repository:
   ```bash
   python -m sphinx -b html . _build/html
   ```

2. Copy output into the container:
   ```bash
   rsync -av \
     ../my_project/docs/_build/html/ \
     subprojects/my_project_docs/build/
   ```

3. Verify `index.html` exists:
   ```text
   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:
   ```text
   docs/process/new-process.md
   ```

2. Add it to:
   ```text
   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.