Projects Folder: How to Add and Document a Project

This document explains how to add a project to the container documentation site and provides a copy-and-paste template for project pages.

The projects/ folder is a catalog, not a documentation generator.

It answers:

What projects exist?
What do they do?
Where is their documentation?

What Belongs in `docs/projects/`

Each project gets:

One Markdown page
A short human description
Links to generated documentation living in subprojects/

This folder does not contain:

Generated API docs
Sphinx autosummary output
HTML files
Source code

Required Files

docs/projects/
├── index.md          # Project index (toctree)
├── my-project.md     # One page per project
└── another-project.md

Step 1: Create a New Project Page

Create a new Markdown file in docs/projects/.

Example:

docs/projects/my-project.md

Step 2: Copy-Paste the Project Template

Paste the following template into the new file and fill it in.

Project Page Template (Copy & Paste)

# <Project Name>

## Overview

One or two sentences describing:
- what this project is
- why it exists
- who it is for

Keep this short and factual.

## Documentation

- **HTML Documentation**  
  [View documentation](../../subprojects/<project>_docs/build/index.html)

Replace `<project>` with the actual subproject folder name.

## Source

- Repository: <link to source repo>
- Primary language: Python
- Documentation system: Sphinx autodoc + Markdown

## Notes

Optional. Use this section for:
- build requirements
- versioning notes
- warnings
- stability status

Step 3: Register the Project in the Index

Open:

docs/projects/index.md

Add the new file name without .md to the toctree:

# Projects

/``{toctree}
:maxdepth: 1

my-project
another-project
/``

If it is not listed here, Sphinx will not build it.

Step 4: Add the Generated Documentation

Generated HTML must live under subprojects/.

Expected structure:

subprojects/
└── my_project_docs/
    └── build/
        ├── index.html
        ├── _static/
        └── _images/

The container site does not build this content.
It only links to it.

Step 5: Rebuild the Container Site

From the docs/ directory:

python -m sphinx -b html . _build/html

Verify:

The project appears under Projects
The link opens index.html from subprojects/

Naming Conventions (Recommended)

Use predictable names.

Item	Convention
Project page	`my-project.md`
Subproject folder	`my_project_docs/`
Build folder	`build/`

Consistency matters more than aesthetics.

Common Mistakes to Avoid

Putting generated HTML under docs/
Forgetting to add the file to projects/index.md
Linking to _build/html instead of subprojects/
Trying to include HTML in a toctree

If Sphinx didn’t build it, it doesn’t exist.

Mental Model

projects/ = catalog
subprojects/ = artifacts
Markdown = context
HTML = output

One page per project. One link per artifact.