diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..5561315 --- /dev/null +++ b/.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 diff --git a/CHANGELOG.md b/CHANGELOG.md index f5ef237..c93dfc9 100644 --- a/CHANGELOG.md +++ b/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. diff --git a/README.rst b/README.rst index c67d624..8235370 100644 --- a/README.rst +++ b/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 ----------- diff --git a/docs/development.rst b/docs/development.rst index 8f971e0..f4f1638 100644 --- a/docs/development.rst +++ b/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 `_ 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. diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..0b7ef2a --- /dev/null +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index f04f9dd..207371f 100644 --- a/pyproject.toml +++ b/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"