Add a documentation site on GitHub Pages and shorten the README

.github/workflows/ci.yml

@@ -66,6 +66,26 @@ jobs:
       - name: Run tests
         run: uv run pytest --cov --cov-report=term-missing
 
+  docs:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --no-dev --group docs --python 3.14
+
+      # Warnings, such as a broken cross-reference, fail the build.
+      - name: Build the site
+        run: uv run --no-sync sphinx-build -M html docs docs/_build -W --keep-going -n
+
   build:
     name: Build and verify distributions
     runs-on: ubuntu-latest
@@ -125,7 +145,7 @@ jobs:
   ci-passed:
     name: CI passed
     if: always()
-    needs: [lint, test, build]
+    needs: [lint, test, docs, build]
     runs-on: ubuntu-latest
     steps:
       - name: Fail if any job did not succeed

.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+# One deployment at a time, and never cancel one halfway through.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      # No dependency cache: what gets published should not depend on a cache that other
+      # workflows can write to.
+      - name: Install uv
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
+
+      - name: Install dependencies
+        run: uv sync --locked --no-dev --group docs --python 3.14
+
+      - name: Build the site
+        run: uv run --no-sync sphinx-build -M html docs docs/_build -W --keep-going -n
+
+      - name: Upload the site
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
+        with:
+          path: docs/_build/html
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

.gitignore

@@ -17,3 +17,4 @@ dist/
 .DS_Store
 .coverage
 htmlcov/
+docs/_build/

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Documentation
+
+- A documentation site at <https://seba2390.github.io/ExecutionTimer/>, with a getting
+  started guide, a user guide and an API reference generated from the docstrings. It is
+  built with Sphinx and deployed to GitHub Pages whenever `main` changes. The package's
+  `Documentation` link points to it from the next release on.
+- The README is shorter and links to the site for details.
+- Public functions and types have full docstrings, with parameters, return values and
+  exceptions.
+- The Python examples in the README and the documentation run as part of the test suite,
+  and CI builds the site on every pull request, failing on any warning.
+
 ## [1.0.2] - 2026-09-30
 
 ### Fixed

CONTRIBUTING.md

@@ -41,16 +41,32 @@ machine and Python version, without coverage instrumentation:
 uv run python benchmarks/overhead.py --number 100000 --repeat 9
 ```
 
-See [benchmarks/README.md](benchmarks/README.md) for methodology and reference results.
+See [benchmarks/README.md](https://github.com/seba2390/ExecutionTimer/blob/main/benchmarks/README.md) for methodology and reference results.
 Timing results are advisory rather than CI pass/fail thresholds.
 
+## Documentation
+
+The documentation site is built with [Sphinx](https://www.sphinx-doc.org/) from the
+Markdown pages in `docs/` and the docstrings in `src/`. To build and preview it:
+
+```bash
+uv run --group docs sphinx-build -M html docs docs/_build -W --keep-going -n
+```
+
+Then open `docs/_build/html/index.html`. CI builds the site on every pull request and fails
+on any warning, such as a broken cross-reference. Changes merged into `main` are published
+to [GitHub Pages](https://seba2390.github.io/ExecutionTimer/) automatically.
+
+The Python examples in `docs/` and `README.md` run as part of the test suite, so keep them
+self-contained and runnable.
+
 ## Guidelines
 
 - Tests exercise the **public API** only — import from `execution_timer`, not
   `execution_timer._timer`. This keeps internals free to change.
 - Every behaviour change needs a test that fails before the fix and passes after it.
 - Public functions carry type annotations and a one-line docstring.
-- Add an entry under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md).
+- Add an entry under `## [Unreleased]` in [CHANGELOG.md](https://github.com/seba2390/ExecutionTimer/blob/main/CHANGELOG.md).
 
 ## Releasing
 
@@ -68,7 +84,7 @@ Maintainers only:
 5. Publish a GitHub release tagged `vX.Y.Z`, targeting the merged commit on `main`.
    Use that version's changelog entries as release notes.
 
-The [Publish to PyPI workflow](.github/workflows/publish.yml) runs when a GitHub release
+The [Publish to PyPI workflow](https://github.com/seba2390/ExecutionTimer/blob/main/.github/workflows/publish.yml) runs when a GitHub release
 is **published**. Pushing to `main`, pushing a tag alone, or saving a draft release does
 not trigger it. The workflow builds and validates the distributions, checks that the tag
 matches `__version__`, and uploads them to PyPI via Trusted Publishing. No manual