Sphinx Project Docs Implementation Plan¶
For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (
- [ ]) syntax for tracking.
Goal: Add a lightweight Sphinx documentation site for the repository with a home page, quickstart page, and API reference for the core project modules.
Architecture: Create a dedicated docs-src/ Sphinx source tree that uses Markdown pages through myst-parser and autodoc for Python API rendering. Keep authored project docs separate from the existing docs/ library notes, build output under docs-build/, and use uv-based commands with import mocking to keep docs builds stable.
Tech Stack: Python, Sphinx, MyST Parser, sphinx-autodoc-typehints, Markdown, uv
Task 1: Add Sphinx Tooling And Build Entry Points¶
Files:
Modify:
pyproject.tomlModify:
README.md[ ] Step 1: Add a failing documentation build command expectation to the README
Add a short Documentation section near the existing install/test usage so the repository documents the intended build command before the implementation exists.
## Documentation
Build the Sphinx docs locally with:
```bash
UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv run sphinx-build -M html docs-src docs-build
- [ ] **Step 2: Run the docs build command to verify it fails before Sphinx is configured**
Run: `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv run sphinx-build -M html docs-src docs-build`
Expected: FAIL with an error indicating `sphinx-build` is unavailable or `docs-src` does not exist yet.
- [ ] **Step 3: Add documentation dependencies to `pyproject.toml`**
Extend the project dependencies so the repository-local environment can build docs.
```toml
[project]
name = "simkit"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
"mani-skill>=3.0.0b22",
"mujoco>=3.4.0",
"pillow>=11.0.0",
"sapien>=3.0.2",
"sphinx>=8.0.0",
"sphinx-autodoc-typehints>=2.3.0",
"trimesh>=4.11.1",
"myst-parser>=4.0.0",
]
[ ] Step 4: Update the README with the final docs build command and site scope
Replace the temporary section with a concise repository-facing docs section.
## Documentation
This repository includes a lightweight Sphinx documentation site for project docs and API
reference.
Build it locally with:
```bash
UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv run sphinx-build -M html docs-src docs-build
The generated HTML site will be written to docs-build/html.
- [ ] **Step 5: Sync the environment so the docs tooling exists**
Run: `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv sync`
Expected: PASS with Sphinx, MyST, and sphinx-autodoc-typehints installed into `.venv`.
- [ ] **Step 6: Commit the tooling setup**
```bash
git add pyproject.toml README.md uv.lock
git commit -m "build: add sphinx documentation tooling"
Run Tests¶
cd test && python run_tests.py
Run The Scene Composer¶
python scene_composer.py --help
Import The Package¶
from simkit import HssdSceneEnv
from simkit.scene import SceneReader
```md
# API Reference
The API reference covers the repository's main public modules and package exports.
```{toctree}
:maxdepth: 2
simkit
scene_composer
- [ ] **Step 5: Add placeholder static/template directories**
Create empty placeholder files so the directories exist in git.
```text
docs-src/_static/.gitkeep
docs-src/_templates/.gitkeep
[ ] Step 6: Run the docs build to verify the scaffolding passes
Run: UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv run sphinx-build -M html docs-src docs-build
Expected: PASS, with HTML generated under docs-build/html, even though API pages are not yet added.
[ ] Step 7: Commit the Sphinx scaffold
git add docs-src README.md
git commit -m "docs: scaffold sphinx project docs"
Task 3: Add API Reference Pages For Core Modules¶
Files:
Create:
docs-src/api/simkit.mdCreate:
docs-src/api/scene_composer.mdModify:
docs-src/api/index.md[ ] Step 1: Add the failing API module references to the API index
Ensure the API index references both intended module pages before the pages exist.
# API Reference
The API reference covers the repository's main public modules and package exports.
```{toctree}
:maxdepth: 2
simkit
scene_composer
- [ ] **Step 2: Run the docs build to verify it fails on missing API pages**
Run: `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv run sphinx-build -M html docs-src docs-build`
Expected: FAIL with missing document errors for `api/simkit` and `api/scene_composer`.
- [ ] **Step 3: Create `docs-src/api/simkit.md`**
```md
# `simkit` API
The `simkit` package exposes the repository's main environment entrypoint and the scene
definition subpackage.
## Package Exports
```{eval-rst}
.. automodule:: simkit
:members:
:undoc-members:
:show-inheritance:
Scene Subpackage¶
Scene Types¶
Scene Reader¶
HSSD Environment¶
- [ ] **Step 4: Create `docs-src/api/scene_composer.md`**
```md
# `scene_composer` API
`scene_composer.py` provides the repository's MuJoCo scene composition entrypoint and
its main adapter classes.
```{eval-rst}
.. automodule:: scene_composer
:members:
:undoc-members:
:show-inheritance:
- [ ] **Step 5: Run the docs build to verify the API pages render**
Run: `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv run sphinx-build -M html docs-src docs-build`
Expected: PASS, with generated API pages for `simkit` and `scene_composer`.
- [ ] **Step 6: Commit the API pages**
```bash
git add docs-src/api
git commit -m "docs: add sphinx api reference pages"
Task 4: Fix Documentation Quality Gaps And Verify End-To-End Build¶
Files:
Modify:
README.mdModify:
scene_composer.pyModify:
simkit/__init__.pyModify:
simkit/scene/__init__.pyModify:
simkit/scene/scene_types.pyModify:
simkit/scene/scene_reader.py[ ] Step 1: Identify the most visible documentation gaps in generated output
Run: UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv run sphinx-build -M html docs-src docs-build
Expected: PASS, but note warnings or visibly poor module/class headings that come from stale or weak docstrings.
[ ] Step 2: Normalize the top-level module docstrings that feed the API pages
Update module docstrings to describe current responsibility without historical drift.
"""Repository entrypoints for MuJoCo scene composition."""
"""Public package exports for SimKit."""
"""Public scene-definition types and YAML I/O exports."""
"""Dataclasses and helper types for structured scene definitions."""
"""YAML readers and writers for structured scene definitions."""
[ ] Step 3: Add or tighten public docstrings where generated output is unclear
Limit changes to public classes and methods surfaced by the docs.
class SceneComposer:
"""Compose MuJoCo scenes from repository assets and optional Menagerie models."""
def create_scene(self, robot_positions=None):
"""Create and compile a scene with a ground plane and one or more robots.
Args:
robot_positions: Optional list of `[x, y, z]` robot base positions.
Returns:
A compiled `mujoco.MjModel`.
"""
class SceneWriter:
"""Write `Scene` instances to YAML files."""
[ ] Step 4: Run the docs build with warnings treated as failures
Run: UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple uv run sphinx-build -W -M html docs-src docs-build
Expected: PASS with no warnings promoted to errors.
[ ] Step 5: Run the repository tests to ensure doc-focused edits did not break code
Run: cd test && python run_tests.py
Expected: PASS for the current unit test suite.
[ ] Step 6: Inspect the generated site output paths
Run: rg --files docs-build/html | rg 'index\\.html|quickstart|api'
Expected: PASS with matches for docs-build/html/index.html, docs-build/html/quickstart.html, and API output pages.
[ ] Step 7: Commit the final documentation polish
git add README.md scene_composer.py simkit/__init__.py simkit/scene/__init__.py simkit/scene/scene_types.py simkit/scene/scene_reader.py docs-build
git commit -m "docs: finalize sphinx project documentation"