README sphinx website generation

.github/workflows/sphinx-build.yml

@@ -0,0 +1,32 @@
+name: Sphinx build
+
+on:  # yamllint disable-line rule:truthy
+  push:
+    paths:
+      - "docs/**"
+  workflow_dispatch:
+
+jobs:
+  sphinx-build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version: '3.13'
+          enable-cache: true
+
+      - name: Sync UV
+        run: uv sync --extra docs
+
+      - name: Build HTML
+        run: uv run sphinx-build -b html docs docs/_build/html
+
+      - name: Deploy
+        if: ${{ github.ref == 'refs/heads/master' }}
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/_build/html

.gitignore

@@ -8,3 +8,4 @@ __pycache__/
 /build
 /venv
 uv.lock
+/docs/_build/

.pre-commit-config.yaml

@@ -20,4 +20,5 @@ repos:
     rev: v1.0.1
     hooks:
       - id: rst-linter
+        exclude: ^docs/
         args: [--allow-raw]

CHANGES.rst

@@ -6,6 +6,8 @@ These features will be included in the next release:
 Added
 -----
 - Drop python 3.8, add python 3.13 official support
+- CI workflow, enable caching of packages via uv across all actions
+- Add readthedocs site
 - New exit codes 2 for file not found, 3 for invalid command line arguments, 4 for
   missing dependencies and 123 for unknown failures.
 - Display exit code in parentheses after error message.

docs/conf.py

@@ -0,0 +1,30 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+project = "darker-docs"
+copyright = "2025, akaihola,csteiner"
+author = "akaihola,csteiner"
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]

docs/index.rst

@@ -0,0 +1,5 @@
+.. contents::
+   :local:
+
+.. include:: ../README.rst
+   :parser: rst

pyproject.toml

@@ -90,6 +90,12 @@ none = "darker.formatters.none_formatter:NoneFormatter"
 [project.scripts]
 darker = "darker.__main__:main_with_error_handling"
 
+[project.optional-dependencies]
+docs = [
+    "sphinx>=7.4.7",
+    "sphinx-rtd-theme>=3.0.2",
+]
+
 [tool.black]
 # Darker makes Black read its configuration from the file indicated by the `--config`
 # option, so we need to mirror the same configuration here and in `check-darker.toml`.