About

A minimal, production-ready documentation template for Python projects that need API documentation via Sphinx autodoc. Built with Sphinx, Poetry, and deploys to Read the Docs with an optional GitHub Pages mirror.

Why Provide This Template

What This Template Is For

• Python packages that need API documentation
• Projects with docstrings that should be auto-extracted
• Libraries, CLIs, and tools that ship installable code
• Projects where autodoc, napoleon, or viewcode are needed

What This Template Is NOT For

• Documentation-only projects with no Python code (use Read-the-Docs-Template)
• Projects where documentation is entirely hand-written with no code coupling

Setting up Sphinx + Read the Docs from scratch involves a surprising number of interconnected decisions. This template is focused on documenting Python projects — when you have a package and want its docstrings auto-extracted into clean API docs. These tools are powerful and the way I have it set up is not the only way to do it, but it prevents at least some of the hurdles I faced trying to set up the basic tools. More can always be added as you need them.

The Problems This Solves

1. Poetry extras vs. PEP 621 extras: Poetry's [tool.poetry.extras] and PEP 621's [project.optional-dependencies] look similar but are not interchangeable. pip install .[docs] (used by Read the Docs) only reads PEP 621 extras; Poetry extras are invisible to pip. This template uses [project.optional-dependencies] as the single source of truth, readable by both pip and Poetry.

2. No requirements.txt needed: Since RTD reads from PEP 621 extras via pip install .[docs], there's no separate requirements.txt that can drift out of sync. Simpler.

3. Autodoc wired correctly: The sys.path.insert() in conf.py points to the src/ directory so autodoc can find your package. Extensions (autodoc, napoleon, viewcode) are pre-configured with sensible defaults.

4. Linting and testing built in: Ruff and pytest configurations are included — a package project needs them.

5. Sphinx version pinned: >=8.0,<9.0 prevents breaking changes from major Sphinx updates.

---

Which template do I need?

Your project	Use this template
Python package + documentation	You're in the right place
Documentation only (no Python package)	Read-the-Docs-Template

Not sure? If your repo has a src/ folder with Python code that needs to be pip-installable, you want this template.

---

Quick Start

There are two ways to use this template, depending on whether you're starting a brand new project or adding docs to an existing one.

Path A: New Project (Clone as Starting Point)

Use this if you're creating a new Python package with documentation from scratch.

0. Prerequisites

• Python 3.11+ minimum, 3.12+ preferred
• Git — GitHub Desktop works if you prefer a GUI (Linux users: sudo apt update && sudo apt install git -y)
• Poetry — required (the package must be installed for autodoc to work)
• A text editor — VSCodium recommended if you have no previous preference

If you are not sure, the setup script will inform you which are missing and safely exit. It can also install Poetry for you automatically.

1. Clone the repository

git clone https://github.com/Danweel/Read-the-Docs-Template-Package.git my-project
cd my-project

Or use GitHub Desktop to clone via the on-screen directions.

2. Rename the package placeholder

mv src/[PACKAGENAME] src/your_actual_package_name

Also update the package name in:

• pyproject.toml (the name and packages fields)
• docs/source/conf.py (the sys.path and autodoc module names)
• docs/source/api.rst (replace [PACKAGENAME] with your module name)

3. Fill in placeholders

See the Find-and-Replace Checklist below. Replace all placeholders in pyproject.toml and docs/source/conf.py before running setup — poetry lock will fail if placeholders remain.

4. Run setup

./setup.sh

The script will:

• Check for prerequisites (Python, Git, Poetry)
• Install Poetry if missing
• Run poetry lock and poetry install to set up dependencies
• Ask for or set up your Git credentials (if needed)
• Offer two setup paths:
  • Option A: Contributors (minimal tools for just docs)
  • Option B: Developers (includes linting & extra tools)
• Build the documentation for the first time

Important: If you see an error like project.name must match pattern..., it means you haven't updated pyproject.toml yet. Stop here and complete the find-and-replace checklist, then run ./setup.sh again.

Path B: Existing Project (Install Into It)

Use this if you already have a Python repository and want to add documentation infrastructure to it.

1. Get the template

git clone https://github.com/Danweel/Read-the-Docs-Template-Package.git /tmp/rtd-template

2. Install docs files into your project

cd /path/to/your-project
/tmp/rtd-template/copy-to-project.sh .

This copies docs/, src/[PACKAGENAME]/, pyproject.toml (as pyproject.template.toml if you already have one), .readthedocs.yaml, setup.sh, and live_preview.sh into your project.

Use --full to also include .github/ workflows, .gitignore, README_template.md, CONTRIBUTING_template.md, and CODE_OF_CONDUCT.md.

Use --dry-run first to preview what gets copied: /tmp/rtd-template/copy-to-project.sh . --dry-run

3. Rename the package placeholder

mv src/[PACKAGENAME] src/your_actual_package_name

Update the name in pyproject.toml (or merge with your existing one) and docs/source/conf.py.

4. Set up the environment

./setup.sh

Building Documentation Manually

After initial setup, you can rebuild docs anytime: poetry run sphinx-build -b html docs/source docs/_build/html

Or from inside the docs/ directory:

cd docs
poetry run make html

Live Preview

While writing, you can get an auto-reloading preview server: ./live_preview.sh

If sphinx-autobuild isn't installed yet: poetry add sphinx-autobuild --group dev

Writing Content

Open the docs/source/ folder in your text editor and start editing:

• .rst files for reStructuredText (recommended for index.rst)
• .md files for Markdown (enabled via included MyST parser)

The index.rst file is more robust using reStructuredText, but can be done in Markdown.

For API documentation, use autodoc directives in your .rst files:

.. automodule:: your_package_name
   :members:
   :undoc-members:
   :show-inheritance:

Hosting Your Documentation

This template supports dual hosting: Read the Docs as primary, GitHub Pages as a backup mirror.

Primary: Read the Docs

Read the Docs provides automatic builds on every commit, version management, and professional hosting. It is completely free, with one small ad on the left sidebar provided by ethicalads.io. You can pay $5/month to remove ads from all your projects and support Read the Docs.

Why RTD is worth the setup:

• Automatic builds: Every push triggers a new build
• Version management: Each Git tag becomes a separate documentation version (e.g., v1.0, v1.1)
• Professional hosting: Clean URLs like yourproject.readthedocs.io
• Built-in search: Full-text search across all pages
• Free tier: Open-source projects hosted for free

Setup Steps:

1. Go to readthedocs.org and sign in with your GitHub account
2. Click Import a Project → Connect GitHub
3. Find your repository and click Import
4. The .readthedocs.yaml file configures the build automatically
5. First build may take 2–5 minutes

Troubleshooting RTD Builds:

Issue	Solution
"Build failed" with no error	Check Build Logs → expand the "Install" section
Missing dependencies	Ensure pyproject.toml lists all Sphinx extensions
Python version mismatch	Set Python version to 3.11+ in RTD Advanced Settings
Configuration file not found	Verify .readthedocs.yaml is in repository root

Backup Mirror: GitHub Pages

GitHub Pages provides a fast mirror for quick access and diagnostics. It is less powerful than RTD but serves as a fallback if RTD goes down.

Why use GitHub Pages as a mirror:

• Diagnostic value: If GitHub Pages builds but RTD doesn't, you know the problem is RTD-side, not in your docs
• No external dependency: Documentation stays within GitHub
• Faster load times: Served from the GitHub CDN

Limitations:

• Only the latest version is published (no version history)
• No built-in full-text search
• Some Sphinx features may behave differently

Setup Steps:

1. Ensure .github/workflows/pages-deploy.yml is in your repo (included with copy-to-project.sh --full, or already present if cloned)
2. Go to Settings → Pages in your repository
3. Under Source, select Deploy from a branch
4. The workflow handles deployment automatically on push to main
5. Your docs will be live at <username>.github.io/<repository-name>/

Why Both?

Feature	Read the Docs	GitHub Pages
Automatic builds	On every commit	Via workflow on push
Version history	All tags	Latest only
Custom domains	Yes	Yes
Analytics	Built-in	Limited
Search	Full-text	None
Speed	Normal	GitHub CDN
Diagnostic value	Primary deployment	Cross-check if RTD fails

Use Read the Docs as your primary host, and GitHub Pages as a backup mirror for quick access and diagnostics.

Reference

Starting Project Structure

my-project/
├── docs/
│   ├── source/           # Documentation source files (.rst, .md)
│   │   ├── conf.py       # Sphinx config with sys.path for autodoc
│   │   ├── index.rst     # Main documentation page
│   │   └── api.rst       # API reference (autodoc directives)
│   └── _build/           # Generated HTML (ignored by Git)
├── src/
│   └── your_package/     # Your Python package (renamed from [PACKAGENAME])
│       └── __init__.py
├── pyproject.toml        # Poetry deps (package + docs + dev)
├── .readthedocs.yaml     # Read the Docs build config
├── setup.sh              # Environment setup script
├── live_preview.sh       # Live-reload dev server
└── README.md             # Replace with your own

docs/source/ is where you edit files. docs/_build/ is generated output — don't edit or commit it.

First-Time Setup Checklist

After cloning or installing the template:

• Rename src/[PACKAGENAME] to your actual package name
• Fill in placeholders (see below)
• Run ./setup.sh to install dependencies and build docs
• Update docs/source/index.rst with your project introduction
• Set up Read the Docs (see Hosting section above)
• Optionally enable GitHub Pages
• Replace this README with your own (use README_template.md as a starting point)
• Commit initial setup with: git commit -m "SETUP: Initial template configuration"

Find-and-Replace Checklist

Search for and replace these placeholders before your first real commit:

Placeholder	Replace With	Example
[PROJECTNAME]	Your project display name	My Awesome Lib
[PACKAGENAME]	Your Python package name (snake_case)	my_awesome_lib
[DESCRIPTION]	Short project description	A library for doing things
[NAME]	Your actual name	Jane Doe
[EMAIL]	Your email address	jane@example.com
[USERNAME]	Your GitHub username	janedoe

Look through all the files by hand too. Many contain extra notes I've left that explain certain entries more, and have blanks I may have missed — these files have changed a lot over time!

Recommended VSCode/VSCodium Extensions

Extension	Purpose	Install Link
SimpleRST	Simple syntax highlighting for reStructuredText	Install
Esbonio	Live preview for Sphinx docs	Install
Prettier	Code formatting	Install
GitLens	Enhanced Git blame & history	Install
Auto Open Preview	Opens the preview pane	Install
Highlight Trailing Whitespace	Good for keeping docs clean	Install
Markdown Editor	Useful if intending to use Markdown	Install

Use reStructuredText (formerly Tweag) vscode:extension/lextudio.restructuredtext if you need advanced RST syntax highlighting.

Common Issues & Solutions

Sphinx Build Errors:

Problem: poetry run sphinx-build fails.

Solution:

1. Ensure all dependencies are installed: poetry install --extras docs
2. Check docs/source/conf.py for missing extensions
3. Ensure src/[PACKAGENAME] has been renamed to your actual package name
4. Clear build cache: rm -rf docs/_build/

Autodoc Cannot Find Module:

Problem: ModuleNotFoundError during build.

Solution:

1. Ensure src/your_package_name/__init__.py exists
2. Check docs/source/conf.py has the correct sys.path.insert pointing to ../../src
3. Run poetry install to ensure the package is installed in the venv

Read the Docs Build Fails:

Problem: RTD shows "Build failed" without clear error.

Solution:

1. Check Build Logs in RTD dashboard
2. Ensure pyproject.toml is in the repository root
3. Verify Python version matches your local environment (3.11+)

Virtual Environment Conflicts:

Problem: Poetry creates a new venv every time.

Solution: Pin the Python version: poetry env use `python3.12

Recommended GitHub Settings

For production repositories, enable these protections:

1. Branch Protection Rules: (Settings → Branches):

   • Require pull request reviews before merging
   • Require status checks to pass before merging
   • Include administrators

2. Required Status Checks:

   • Sphinx build check (via GitHub Actions workflow)
   • Ruff linting (if using dev dependencies)

3. Deploy Keys (if using RTD):

   • Add Read the Docs as a collaborator with read access

Windows Users (Windows 10/11)

This template uses Bash scripts for setup and make for building documentation. Both are Unix-native tools, but they work on Windows with the right setup.

Prerequisites

1. Install Git for Windows (if you haven't already):

   • Download from https://git-scm.com/download/win
   • This installs Git Bash, which provides a Bash-compatible terminal
   • During installation, select "Git from the command line" option

2. Install Python 3.12+:

   • Download from https://www.python.org/downloads/
   • Important: During installation, check "Add Python to PATH"
   • If you forget this, add Python's install path manually:
     1. Press Win + S, type "Environment Variables"
     2. Click "Edit environment variables for your account"
     3. Under "Path", click "New" and add your Python install path
     4. Restart your terminal

3. Verify installation (in Git Bash):

   python --version    # Should show 3.12.x or higher
   git --version       # Should show a git version

License

What the license means:

• Attribution (BY): Users must give credit to the original author
• NonCommercial (NC): Users cannot use the template itself for commercial purposes
• ShareAlike (SA): If users modify the template, they must distribute their changes under the same license

See the LICENSE file for legal details. Please keep the sharing going!