Release-0.1.2

.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: Docs
+
+on:
+  push:
+    branches:
+      - main
+      - dev
+    paths:
+      - "docs/**"
+      - "src/**"
+      - pyproject.toml
+      - .github/workflows/docs.yml
+  pull_request:
+    branches:
+      - main
+      - dev
+    paths:
+      - "docs/**"
+      - "src/**"
+      - pyproject.toml
+      - .github/workflows/docs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # required so setuptools_scm can derive the version from tags
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: "pip"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[docs]
+
+      - name: Build Sphinx documentation
+        run: sphinx-build -b html -W docs/source docs/build/html
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/build/html
+
+  deploy:
+    if: github.event_name != 'pull_request' && github.ref == 'refs/heads/main'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -9,3 +9,5 @@ tests/test.ipynb
 **_.*.py
 .coverage
 **/__version__.py
+docs/build/
+docs/source/api/generated/

AGENTS.md

@@ -20,3 +20,13 @@ This rule applies to:
 - Refactors
 - Documentation changes
 - Any automated or suggested pull request creation
+
+## Documentation
+
+The project's Sphinx documentation lives under `docs/source` and is built with the `docs` extra (`pip install -e ".[docs]"`).
+
+- The API reference under `docs/source/api/` is generated automatically via `autosummary --recursive` from docstrings (NumPy style, per `ruff.toml`'s `pydocstyle` convention) — new/removed modules require no manual edits there.
+- The version shown on the docs landing page is pulled automatically from the installed package's metadata (`setuptools_scm`), so it never needs to be updated by hand.
+- Explanatory guide pages go under `docs/source/sections/`.
+- Build locally with `sphinx-build -b html -W docs/source docs/build/html`; treat any warning as a build failure, matching CI.
+- `.github/workflows/docs.yml` builds the docs on push/PR to `main`/`dev` and deploys to GitHub Pages on push to `main`.

CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to this project will be documented in this file.
 
 ## Next Release
 
+### Features
+
+#### Documentation
+
+- Add Sphinx documentation site (`sphinx-rtd-theme`) with an automatically generated API reference from docstrings and an automatically displayed package version
+- Add placeholder user guide section for future explanatory documentation pages
+
+### Deployment
+
+#### CI/CD
+
+- Add GitHub Actions workflow to build the documentation and deploy it to GitHub Pages on merges to `main`
+
 <!-- insertion marker -->
 ## [0.1.1](https://github.com/repo/owner/releases/tag/0.1.1) - 2026-02-20
 

docs/Makefile

@@ -0,0 +1,17 @@
+# Minimal makefile for Sphinx documentation
+
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+.PHONY: help clean Makefile
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	rm -rf "$(BUILDDIR)"
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,33 @@
+@ECHO OFF
+
+pushd %~dp0
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/api/index.rst

@@ -0,0 +1,12 @@
+Code Documentation
+===================
+
+The reference below is generated automatically from the ``devops`` source
+code and its docstrings; new modules picked up by the package show up here
+without any manual edits.
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   devops

docs/source/conf.py

@@ -0,0 +1,86 @@
+"""Sphinx configuration for the devops documentation."""
+
+from __future__ import annotations
+
+import os
+import sys
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as get_version
+
+# -- Path setup --------------------------------------------------------------
+# Allow Sphinx to find the package when it is not installed (e.g. local
+# ``sphinx-build`` runs against a checkout without ``pip install -e .``).
+sys.path.insert(0, os.path.abspath("../../src"))
+
+# -- Project information ------------------------------------------------------
+
+project = "devops"
+copyright = "2026, Jakob Gamper"  # noqa: A001
+author = "Jakob Gamper"
+
+# The full version, including alpha/beta/rc tags, is pulled automatically
+# from the installed package metadata (set by setuptools_scm from Git tags),
+# so this file never needs to be touched when a new version is released.
+try:
+    release = get_version("devops")
+except PackageNotFoundError:
+    release = "0.0.0"
+version = ".".join(release.split(".")[:2])
+
+# -- General configuration ----------------------------------------------------
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.intersphinx",
+    "myst_parser",
+]
+
+templates_path = ["_templates"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+# devops re-exports many classes in package __init__ modules for convenience
+# (e.g. CppConfig lives in both devops.config and devops.config.config_cpp),
+# which makes autodoc's type-hint cross-references ambiguous. That's a
+# harmless naming collision, not a doc error, so silence it specifically.
+suppress_warnings = ["ref.python"]
+
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".md": "markdown",
+}
+
+# -- Autodoc / Autosummary -----------------------------------------------------
+
+autosummary_generate = True
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+autodoc_typehints = "description"
+autodoc_member_order = "bysource"
+
+# -- Napoleon (NumPy-style docstrings, matching the project's convention) -----
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = True
+napoleon_use_rtype = False
+
+# -- Intersphinx ---------------------------------------------------------------
+
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+}
+
+# -- HTML output ----------------------------------------------------------------
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+html_theme_options = {
+    "navigation_depth": 4,
+    "collapse_navigation": False,
+}

docs/source/index.rst

@@ -0,0 +1,18 @@
+devops
+======
+
+A collection of DevOps related tools and scripts.
+
+Version |release|
+
+.. toctree::
+   :maxdepth: 2
+   :caption: User Guide
+
+   sections/index
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Code Documentation
+
+   api/index

docs/source/sections/index.rst

@@ -0,0 +1,7 @@
+User Guide
+==========
+
+.. note::
+
+   This section is a placeholder. Explanatory guide pages (installation,
+   configuration, usage walkthroughs, ...) will be added here.

pyproject.toml

@@ -12,6 +12,7 @@ dependencies = ["typer>=0.20.0"]
 
 [project.optional-dependencies]
 test = ["pytest>=9.0.1", "pytest-cov", "coverage", "docstr-coverage"]
+docs = ["sphinx>=8.1", "sphinx-rtd-theme>=3.0", "myst-parser>=4.0"]
 
 [project.scripts]
 cpp_checks = "devops.scripts.cpp_checks:app"

ruff.toml

@@ -1,3 +1,5 @@
+extend-exclude = ["docs"]
+
 [lint]
 select = ["ALL"]
 ignore = [