Configure Read the Docs and point the README and project URLs at the hosted documentation

.readthedocs.yaml

@@ -0,0 +1,16 @@
+# Read the Docs builds the Sphinx site in docs/ from this configuration.
+# https://docs.readthedocs.io/en/stable/config-file/v2.html
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true
+
+python:
+  install:
+    - requirements: docs/requirements.txt

CHANGELOG.md

@@ -2,6 +2,12 @@
 
 diskcache-community forked from DiskCache at upstream commit ebfa37c (3 March 2024), two commits after the 5.6.3 release. Each entry names the pull request in this repository. Imported upstream pull requests are referenced by number, and their commits keep their original authors in the git history.
 
+## Unreleased
+
+### Docs
+
+- The documentation is published on Read the Docs at https://diskcache-community.readthedocs.io/, built from `master` on every push; the README links point there instead of at the `.rst` sources (PR #18).
+
 ## 5.7.0 (2026-10-11)
 
 First release under the `diskcache-community` name: upstream commit ebfa37c plus the changes below. The import name stays `diskcache`; the `cache.db` schema, the file layout, the serialization modes, the memoize key format and the persisted settings are unchanged, so a 5.6.3 process opens a directory written by 5.7.0 and the reverse.

README.rst

@@ -187,13 +187,13 @@ prevention, cross-process locking, and cross-process throttling are available::
 Python's docstrings are a quick way to get started but not intended as a
 replacement for the `DiskCache Tutorial`_ and `DiskCache API Reference`_.
 
-.. _`Cache`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/tutorial.rst#cache
-.. _`FanoutCache`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/tutorial.rst#fanoutcache
-.. _`DjangoCache`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/tutorial.rst#djangocache
+.. _`Cache`: https://diskcache-community.readthedocs.io/en/latest/tutorial.html#cache
+.. _`FanoutCache`: https://diskcache-community.readthedocs.io/en/latest/tutorial.html#fanoutcache
+.. _`DjangoCache`: https://diskcache-community.readthedocs.io/en/latest/tutorial.html#djangocache
 .. _`Django`: https://www.djangoproject.com/
-.. _`Deque`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/tutorial.rst#deque
-.. _`Index`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/tutorial.rst#index
-.. _`recipes`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/tutorial.rst#recipes
+.. _`Deque`: https://diskcache-community.readthedocs.io/en/latest/tutorial.html#deque
+.. _`Index`: https://diskcache-community.readthedocs.io/en/latest/tutorial.html#index
+.. _`recipes`: https://diskcache-community.readthedocs.io/en/latest/tutorial.html#recipes
 
 User Guide
 ----------
@@ -210,14 +210,14 @@ tutorial, benchmarks, API, and development.
 * `DiskCache API Reference`_
 * `DiskCache Development`_
 
-.. _`DiskCache Tutorial`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/tutorial.rst
-.. _`DiskCache Cache Benchmarks`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/cache-benchmarks.rst
-.. _`DiskCache DjangoCache Benchmarks`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/djangocache-benchmarks.rst
-.. _`Talk: All Things Cached - SF Python 2017 Meetup`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/sf-python-2017-meetup-talk.rst
-.. _`Case Study: Web Crawler`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/case-study-web-crawler.rst
-.. _`Case Study: Landing Page Caching`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/case-study-landing-page-caching.rst
-.. _`DiskCache API Reference`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/api.rst
-.. _`DiskCache Development`: https://github.com/secondwindoss/diskcache-community/blob/master/docs/development.rst
+.. _`DiskCache Tutorial`: https://diskcache-community.readthedocs.io/en/latest/tutorial.html
+.. _`DiskCache Cache Benchmarks`: https://diskcache-community.readthedocs.io/en/latest/cache-benchmarks.html
+.. _`DiskCache DjangoCache Benchmarks`: https://diskcache-community.readthedocs.io/en/latest/djangocache-benchmarks.html
+.. _`Talk: All Things Cached - SF Python 2017 Meetup`: https://diskcache-community.readthedocs.io/en/latest/sf-python-2017-meetup-talk.html
+.. _`Case Study: Web Crawler`: https://diskcache-community.readthedocs.io/en/latest/case-study-web-crawler.html
+.. _`Case Study: Landing Page Caching`: https://diskcache-community.readthedocs.io/en/latest/case-study-landing-page-caching.html
+.. _`DiskCache API Reference`: https://diskcache-community.readthedocs.io/en/latest/api.html
+.. _`DiskCache Development`: https://diskcache-community.readthedocs.io/en/latest/development.html
 
 Comparisons
 -----------

docs/development.rst

@@ -89,6 +89,11 @@ below 98%. The lint checks are tox environments as well::
 
     $ tox -e bluecheck,isortcheck,flake8,mypy,pylint,doc8,rstcheck,docs
 
+`Read the Docs <https://diskcache-community.readthedocs.io/>`_ builds the
+``docs`` directory from ``master`` on every push, configured by
+``.readthedocs.yaml`` with the build dependencies in
+``docs/requirements.txt``.
+
 Stress tests can be run independently as a module. They are kept in the
 tests directory and prefixed with ``stress_test_``. Stress tests accept many
 arguments. Read the help for details.

docs/requirements.txt

@@ -0,0 +1,5 @@
+# Dependencies of the documentation build on Read the Docs. docs/conf.py puts
+# the repository root on sys.path, so the package itself is not installed;
+# Django is needed to document DjangoCache.
+django==5.2.*
+sphinx>=8,<10

pyproject.toml

@@ -30,6 +30,7 @@ dependencies = []
 
 [project.urls]
 Homepage = "https://github.com/secondwindoss/diskcache-community"
+Documentation = "https://diskcache-community.readthedocs.io/"
 Source = "https://github.com/secondwindoss/diskcache-community"
 Tracker = "https://github.com/secondwindoss/diskcache-community/issues"
 Upstream = "https://github.com/grantjenks/python-diskcache"