Documentation Maintenance Guide

This guide explains how to build, maintain, and deploy the KINTSUGI documentation.

Documentation Structure

docs/
├── conf.py              # Sphinx configuration
├── index.rst            # Main documentation page
├── Makefile             # Unix build script
├── make.bat             # Windows build script
├── requirements.txt     # Documentation dependencies
├── _static/             # Static files (CSS, images)
├── _templates/          # Custom templates
├── _build/              # Build output (gitignored)
├── installation.md      # Installation guide
├── quickstart.md        # Quick start guide
├── workflows.md         # Processing workflows
├── cli.md               # CLI reference
├── api.md               # API reference
├── contributing.md      # Contribution guide
├── TROUBLESHOOTING.md   # Troubleshooting guide
├── DEPENDENCY_ANALYSIS.md # Dependency analysis
├── DOCS_MAINTENANCE.md  # This file
├── CD3e.gif             # Demo animation
└── CD31_curtain.gif     # Demo animation

Building Documentation Locally

Prerequisites

Install documentation dependencies:

cd docs
pip install -r requirements.txt

On Windows

Option 1: Using make.bat

cd docs
.\make.bat html

Option 2: Direct sphinx-build command

If make is not available (common on Windows), use sphinx-build directly:

cd docs
sphinx-build -M html . _build

Option 3: Using Python module

cd docs
python -m sphinx -M html . _build

On Linux/macOS

cd docs
make html

Viewing the Built Documentation

After building, open docs/_build/html/index.html in your web browser.

Live Preview During Development

For live-reloading during documentation development:

cd docs
sphinx-autobuild . _build/html

Then open http://127.0.0.1:8000 in your browser. Changes will auto-reload.

Deploying to GitHub Pages

Automatic Deployment

Documentation is automatically deployed to GitHub Pages when changes are pushed to the main branch. The deployment is handled by the .github/workflows/docs.yml workflow.

Manual Deployment

If needed, you can manually trigger deployment:

Go to the repository on GitHub
Navigate to Actions > Deploy Documentation
Click “Run workflow”

Accessing the Live Site

Once deployed, the documentation is available at:

https://smith6jt-cop.github.io/KINTSUGI/

Enabling GitHub Pages (First Time Setup)

Go to repository Settings > Pages
Under “Build and deployment”, select:
- Source: “GitHub Actions”
The workflow will handle the rest

Adding New Documentation

Adding a New Page

Create a new .md or .rst file in the docs/ directory
Add the file to the appropriate toctree in index.rst

Example for docs/new-page.md:

.. toctree::
   :maxdepth: 2
   :caption: User Guide

   workflows
   new-page    # Add your new page here

Adding API Documentation

For automatic API documentation from docstrings:

Ensure modules have proper docstrings (Google or NumPy style)
Use autodoc directives in .rst files:

.. automodule:: kintsugi.kreg
   :members:
   :undoc-members:

Adding Images

Place images in docs/_static/ or the docs/ directory
Reference in Markdown:

![Alt text](image.png)

Or in reStructuredText:

.. image:: image.png
   :alt: Alt text

Writing Style Guidelines

Use clear, concise language
Include code examples where helpful
Keep paragraphs short
Use headers to organize content
Link to related documentation sections
Test all code examples before committing

Common Tasks

Clean Build

To force a complete rebuild:

# Unix
make clean && make html

# Windows
.\make.bat clean
.\make.bat html

Check for Broken Links

make linkcheck

Generate PDF (requires LaTeX)

make latexpdf

Troubleshooting Documentation Builds

“sphinx-build not found”

Install Sphinx:

pip install sphinx sphinx-rtd-theme myst-parser

“make is not recognized” (Windows)

Use the direct sphinx-build command:

sphinx-build -M html . _build

Or install GNU Make via:

Chocolatey: choco install make
Git for Windows (includes make in Git Bash)

Import errors during build

Ensure you’re in the KINTSUGI conda environment:

conda activate KINTSUGI
cd docs
make html

Theme not found

pip install sphinx-rtd-theme

MyST parser errors

pip install myst-parser

Version Updates

When releasing a new version:

Update release in docs/conf.py
Update __version__ in src/kintsugi/__init__.py
Add release notes to documentation if applicable

Contact

For documentation issues, open an issue at: https://github.com/smith6jt-cop/KINTSUGI/issues