Build documentation on Read the Docs

.github/dependabot.yml

@@ -1,5 +1,13 @@
 version: 2
 updates:
+  - package-ecosystem: uv
+    directory: /
+    schedule:
+      interval: weekly
+    groups:
+      docs:
+        patterns:
+          - "*"
   - package-ecosystem: github-actions
     directory: /
     schedule:

.github/workflows/ci.yml

@@ -16,6 +16,32 @@ defaults:
     shell: bash
 
 jobs:
+  docs:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Check out documentation and version tags
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Set up Python
+        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@1c37ad07a6a961277cf70c0d37d6f313000f5884 # v10.3.0
+        with:
+          version: "0.13.1"
+
+      - name: Install documentation dependencies
+        run: uv sync --locked --group docs
+
+      - name: Build documentation with warnings as errors
+        run: uv run --locked --group docs sphinx-build --fail-on-warning --keep-going --builder=html docs docs/_build/html
+
   build:
     runs-on: ubuntu-latest
     steps:

.gitignore

@@ -0,0 +1,4 @@
+.venv/
+__pycache__/
+*.egg-info/
+docs/_build/

.readthedocs.yaml

@@ -0,0 +1,17 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - method: uv
+      command: sync
+      groups:
+        - docs
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true

README.rst

@@ -1,4 +1,4 @@
-|PyPI| |Build Status| |Coverage Report|
+|PyPI| |Build Status| |Coverage Report| |Documentation|
 
 jsonstore
 =========
@@ -8,6 +8,9 @@ load and save configuration containing nested dictionaries and lists.
 
 Requires Python 3.9 or newer. Tests run on CPython 3.9–3.15 and PyPy 3.11.
 
+`Documentation <https://python-jsonstore.readthedocs.io/en/latest/>`__
+includes the API reference and build instructions.
+
 Examples
 --------
 
@@ -94,3 +97,6 @@ across a power failure.
    :target: https://pypi.org/project/python-jsonstore/
 .. |Coverage Report| image:: https://codecov.io/gh/Code0x58/python-jsonstore/branch/master/graph/badge.svg
    :target: https://codecov.io/gh/Code0x58/python-jsonstore
+.. |Documentation| image:: https://readthedocs.org/projects/python-jsonstore/badge/?version=latest
+   :target: https://python-jsonstore.readthedocs.io/en/latest/
+   :alt: Documentation status

docs/api.rst

@@ -0,0 +1,48 @@
+API Reference
+=============
+
+.. autoclass:: jsonstore.JsonStore
+
+   :param path: Path to a JSON file, as a string or :class:`os.PathLike`.
+      A missing file is created as an empty JSON object. Its parent directory
+      must already exist.
+   :param indent: Indentation passed to :func:`json.dumps`; defaults to 2.
+      Use ``None`` for compact output.
+   :param bool auto_commit: Save after each assignment or deletion, unless
+      inside a transaction. Defaults to ``True``. With ``False``, use a
+      context manager to commit changes.
+   :raises ValueError: The file contains invalid JSON or its root is not an
+      object. An empty file is treated as an empty object.
+   :raises OSError: The file cannot be read or created.
+
+Keys and values
+---------------
+
+Use attribute access for ordinary top-level keys. Item access also supports
+dot-separated dictionary paths and tuple or list paths containing dictionary
+keys, list indices, and slices. A one-element tuple addresses a literal key
+containing a dot. Dictionary keys must be strings.
+
+Values may be strings, booleans, integers, floats, ``None``, dictionaries,
+lists, or tuples containing these types. Tuples are saved as JSON arrays and
+become lists when the file is reopened. Non-finite floats use Python's JSON
+extensions and are not portable to strict JSON readers.
+
+Reads and assignments use deep copies. Assign a changed collection back to
+the store to persist it. Unsupported values and non-string dictionary keys
+raise :class:`TypeError`; reference cycles raise :class:`ValueError`.
+Shared containers without cycles are accepted.
+
+Transactions and saving
+-----------------------
+
+``with store:`` defers writes until the outermost transaction exits
+successfully, regardless of ``auto_commit``. Exceptions restore the previous
+state, including when the commit fails. Nested transactions provide nested
+rollback scopes.
+
+Saves use a unique temporary file beside the destination, preserve existing
+permission bits, and atomically replace the destination. The containing
+directory must be writable. This does not provide locking, coordination
+between writers, or durability across power failures. Use one writer per file;
+separate stores retain their own snapshots.

docs/conf.py

@@ -0,0 +1,18 @@
+import os
+from importlib import metadata
+
+project = "jsonstore"
+author = "Oliver Bristow"
+copyright = "2016, Oliver Bristow"
+release = metadata.version("python-jsonstore")
+version = release
+
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.intersphinx"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+html_theme = "sphinx_rtd_theme"
+html_title = "jsonstore"
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+html_theme_options = {"collapse_navigation": False, "navigation_depth": 3}
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}

docs/contributing.rst

@@ -0,0 +1,25 @@
+Building the Documentation
+==========================
+
+The documentation uses Sphinx and the Read the Docs theme, like the
+``alternative`` package. The examples are included directly from
+``README.rst`` so they have one source.
+
+Use uv 0.13.1 or newer and Python 3.12 or newer for documentation work.
+The package itself continues to support Python 3.9 and newer.
+
+.. code-block:: console
+
+   $ uv sync --locked --group docs --python 3.12
+   $ uv run --locked --group docs sphinx-build --fail-on-warning --keep-going --builder=html docs docs/_build/html
+
+Open ``docs/_build/html/index.html`` to preview the result. CI runs the same
+warning-free HTML build, and ``.readthedocs.yaml`` configures Read the Docs
+to build ``docs/conf.py`` on Python 3.12.
+
+The committed ``uv.lock`` records documentation dependencies. After changing
+them, run ``uv lock --upgrade`` and commit the updated lockfile. Dependabot
+also proposes weekly dependency updates.
+
+Read the Docs builds the ``latest`` documentation from ``master``. New
+version tags can be enabled after they include the documentation configuration.

docs/index.rst

@@ -0,0 +1,13 @@
+.. include:: ../README.rst
+
+Contents
+--------
+
+.. toctree::
+   :maxdepth: 2
+
+   api
+   contributing
+
+* :ref:`genindex`
+* :ref:`search`

pyproject.toml

@@ -35,6 +35,19 @@ dynamic = ["version"]
 
 [project.urls]
 Homepage = "https://github.com/Code0x58/python-jsonstore/"
+Documentation = "https://python-jsonstore.readthedocs.io/"
+
+[dependency-groups]
+docs = [
+    "sphinx>=8.1.3",
+    "sphinx-rtd-theme>=3.0.2",
+]
+
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
+
+[tool.uv.dependency-groups]
+docs = { requires-python = ">=3.12" }
 
 [tool.setuptools]
 py-modules = ["jsonstore"]