Publish API documentation to GitHub Pages via Sphinx

.github/workflows/docs.yml

@@ -0,0 +1,48 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - 'main'
+
+jobs:
+  build:
+    name: "Build Sphinx docs"
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v7
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - name: Install Poetry
+        uses: snok/install-poetry@a783c322200f0519c7926aa6faa857c4e23e9263 # v1
+        with:
+          version: "2.4.0"
+      - name: Install dependencies
+        run: poetry install --no-interaction --with docs
+        env:
+          POETRY_INSTALLER_ONLY_BINARY: ":all:" # only install pre-built wheels, never run a source dist's build/setup scripts
+      - name: Build documentation
+        run: poetry run sphinx-build -b html docs docs/_build/html -W --keep-going
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: docs/_build/html
+
+  deploy:
+    name: "Deploy to GitHub Pages"
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/test.yml

@@ -26,6 +26,8 @@ jobs:
           virtualenvs-in-project: true
       - name: Install dependencies
         run: poetry install --no-interaction
+        env:
+          POETRY_INSTALLER_ONLY_BINARY: ":all:" # only install pre-built wheels, never run a source dist's build/setup scripts
       - name: Lint with flake8
         run: |
           poetry run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics

.gitignore

@@ -188,6 +188,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/_autosummary/
 
 # PyBuilder
 .pybuilder/

README.md

@@ -1,6 +1,7 @@
 [![Status](https://github.com/augustocristian/samples-python-template/actions/workflows/test.yml/badge.svg)](https://github.com/augustocristian/samples-python-template/actions)
 [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=augustocristian_samples-python-template&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=augustocristian_samples-python-template)
 [![PyPI](https://img.shields.io/pypi/v/samples-python-template.svg)](https://pypi.org/project/samples-python-template/)
+[![Docs](https://github.com/augustocristian/samples-python-template/actions/workflows/docs.yml/badge.svg)](https://augustocristian.github.io/samples-python-template/)
 
 # samples-python-template
 
@@ -10,6 +11,7 @@ Template project, includes:
 - Aggregated test reports (pytest style)
 - SonarCloud static test (includes coverage results)
 - Publish the package/lib in PyPI's
+- Publish API documentation, generated from docstrings, to [GitHub Pages](https://augustocristian.github.io/samples-python-template/)
 
 ## Publishing to PyPI
 
@@ -27,6 +29,14 @@ To release a new version:
 One-time setup (repo/PyPI admin only): on [pypi.org](https://pypi.org), add a Trusted Publisher for this project
 pointing at this GitHub repo, workflow file `publish.yml`, and environment `pypi`.
 
+## Documentation
+
+API docs are generated from the code's docstrings with [Sphinx](https://www.sphinx-doc.org/) (autodoc + autosummary)
+and published to [GitHub Pages](https://augustocristian.github.io/samples-python-template/) by
+[.github/workflows/docs.yml](.github/workflows/docs.yml) on every push to `main`. Sources live under
+[docs/](docs/); nothing needs to be regenerated by hand — new modules and docstrings show up automatically on the
+next push.
+
 See the general contribution policies and guidelines for *giis-uniovi* at
 [CONTRIBUTING.md](https://github.com/giis-uniovi/.github/blob/main/profile/CONTRIBUTING.md).
 

docs/conf.py

@@ -0,0 +1,28 @@
+# Configuration file for the Sphinx documentation builder.
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+project = "samples-python-template"
+copyright = "2026, Cristian Augusto"
+author = "Cristian Augusto"
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
+
+autosummary_generate = True
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
+
+templates_path = []
+exclude_patterns = ["_build"]
+
+html_theme = "furo"

docs/index.rst

@@ -0,0 +1,10 @@
+samples-python-template
+========================
+
+API reference generated from the code's docstrings.
+
+.. autosummary::
+   :toctree: _autosummary
+   :recursive:
+
+   sample