📚 Documentation

“Good documentation is like a good joke: it needs no explanation.” — Unknown

Seedling includes comprehensive documentation tooling with Sphinx and modern documentation practices.

Overview

The template provides:

  • Sphinx: Professional documentation generator

  • Furo theme: Modern, responsive documentation theme

  • MyST parser: Markdown support for Sphinx

  • API documentation: Automatic API documentation

  • Search functionality: Full-text search

Documentation Structure

docs/
├── source/                    # Source files
│   ├── index.md              # Main documentation index
│   ├── contributing.md       # Contributing guide
│   └── _static/              # Static assets
├── build/                    # Built documentation
└── pyproject.toml           # Documentation dependencies

Building Documentation

# Build documentation
just docs
# or
nox -s docs
# or
uv run sphinx-build -W docs/source docs/build

# Serve locally (after building)
cd docs/build/html
python -m http.server 8000

Writing Documentation

Markdown Support

Use MyST Markdown with Sphinx extensions:

# Your Documentation

## Code Examples

```python
def example_function():
    return "Hello, World!"

Cross-References

See ⚙️ Configuration Guide for template configuration options and 📚 Examples for usage examples.


### API Documentation

Automatic API documentation with autodoc:

```markdown
# API Reference

## Core Module

```{eval-rst}
.. automodule:: your_package.core
   :members:
   :undoc-members:
   :show-inheritance:


## Configuration

### Sphinx Configuration

```python
# docs/source/conf.py
extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.napoleon",
    "myst_parser",
]

html_theme = "furo"

MyST Extensions

myst_enable_extensions = [
    "colon_fence",
    "deflist",
    "dollarmath",
    "html_admonition",
    "html_image",
    "replacements",
    "smartquotes",
    "substitution",
    "tasklist",
]

Best Practices

  1. Write clear, concise documentation

  2. Include code examples

  3. Use cross-references

  4. Test all links

  5. Keep documentation up to date

Deployment

GitHub Pages

The template includes automatic documentation deployment:

  • Automatic builds: Documentation is built and deployed on every commit

  • GitHub Pages: Automatically publishes to your project’s GitHub Pages site

  • Branch protection: Only deploys from the main branch

  • Custom domain support: Can be configured to use a custom domain

  • Version history: Maintains documentation history across releases

Next Steps

  • Customize the theme for your brand

  • Add more documentation sections

  • Set up automatic deployment

  • Integrate with your CI/CD pipeline