Generate reference docs, build Sphinx documentation, and review all screenshots
Generate all reference documentation from code, build Sphinx docs, capture tutorial screenshots, and review everything for issues.
uv sync)SLICER_PATH in .env# Generate mouse profiles reference
python MouseMaster/Testing/Python/test_generate_mouse_profiles.py
# Build docs (will have placeholder for actions)
pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html
# Set Slicer path
export SLICER_PATH=/path/to/Slicer
# Generate all reference docs
python MouseMaster/Testing/Python/test_generate_mouse_profiles.py
$SLICER_PATH --no-splash \
--python-script MouseMaster/Testing/Python/test_generate_actions_reference.py \
--additional-module-paths $(pwd)/MouseMaster
# Generate tutorial screenshots
$SLICER_PATH --no-splash \
--python-script MouseMaster/Testing/Python/test_tutorial_workflow.py \
--additional-module-paths $(pwd)/MouseMaster
# Build docs
sphinx-build -b html docs docs/_build/html
This can run standalone without Slicer:
python MouseMaster/Testing/Python/test_generate_mouse_profiles.py
Output: docs/reference/_generated/mouse-profiles.rst
Verify:
cat docs/reference/_generated/mouse-profiles.rst | head -50
Should show all mouse profiles with button tables.
$SLICER_PATH --no-splash \
--python-script MouseMaster/Testing/Python/test_generate_actions_reference.py \
--additional-module-paths $(pwd)/MouseMaster
Output: docs/reference/_generated/actions.rst
Verify:
cat docs/reference/_generated/actions.rst | head -50
Should show action categories with tables.
mkdir -p docs/user-guide/_generated
$SLICER_PATH --no-splash \
--python-script MouseMaster/Testing/Python/test_tutorial_workflow.py \
--additional-module-paths $(pwd)/MouseMaster
Output:
docs/user-guide/_generated/*.png - Tutorial screenshotsdocs/user-guide/_generated/manifest.json - Screenshot metadatadocs/user-guide/tutorial.rst - Generated tutorial RSTVerify:
ls -la docs/user-guide/_generated/
cat docs/user-guide/_generated/manifest.json
pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html 2>&1 | tee sphinx-build.log
Check for errors:
grep -i "error\|warning" sphinx-build.log
Preview (if browser available):
python -m http.server 8000 -d docs/_build/html
# Open http://localhost:8000
Review each screenshot for issues:
# List all screenshots
find docs -name "*.png" -o -name "manifest.json"
# Read manifest for descriptions
cat docs/user-guide/_generated/manifest.json
For each screenshot, check:
If screenshots have problems:
MouseMaster/MouseMaster.py widget codetest_tutorial_workflow.py capture sequenceAfter fixes, re-run from Step 3.
| File | Source | Requires Slicer |
|---|---|---|
docs/reference/_generated/mouse-profiles.rst | JSON files | No |
docs/reference/_generated/actions.rst | ActionRegistry | Yes |
docs/user-guide/_generated/*.png | Tutorial test | Yes |
docs/user-guide/_generated/manifest.json | Tutorial test | Yes |
docs/user-guide/tutorial.rst | Tutorial test | Yes |
# Check path
which Slicer || echo "Not in PATH"
# Set explicitly
export SLICER_PATH=/opt/Slicer/Slicer
# Verify module path
ls MouseMaster/MouseMaster.py
# Check for syntax errors
python -m py_compile MouseMaster/MouseMaster.py
Check if virtual display is needed (CI/headless):
# Start Xvfb
Xvfb :99 -screen 0 1920x1080x24 &
export DISPLAY=:99
# Then run Slicer
$SLICER_PATH --no-splash ...
# Check for missing files
grep "include" docs/reference/*.rst
ls docs/reference/_generated/
# Create placeholder if needed
echo ".. note:: Auto-generated content not available" > docs/reference/_generated/actions.rst
The CI workflow runs these steps automatically:
# From .github/workflows/tests.yml
- name: Generate reference documentation
run: |
python MouseMaster/Testing/Python/test_generate_mouse_profiles.py
$SLICER_HOME/Slicer --python-script MouseMaster/Testing/Python/test_generate_actions_reference.py ...
/generate-screenshots - Capture Extension Index screenshots/review-ui-screenshots - Detailed UI review/run-tests - Run all tests including doc generatorsAfter building docs:
docs/reference/_generated/mouse-profiles.rst exists and has contentdocs/reference/_generated/actions.rst exists (or placeholder)docs/user-guide/_generated/ has PNG filessphinx-build completed without errors