# 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

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

```md
# <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:
```text
docs/projects/index.md
```

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

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

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

```bash
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.