diff --git a/.readthedocs.yaml b/.readthedocs.yaml index 32ddc418..7e676ea8 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -13,7 +13,7 @@ formats: build: os: ubuntu-22.04 tools: - python: "3.11" + python: "3.12" jobs: post_checkout: # Cancel building pull requests when there aren't changed in the docs directory or YAML file. @@ -22,6 +22,20 @@ build: then exit 183; fi + pre_install: + # pip-compile was used to generate the requirements.txt file to enable + # reproducible builds. + # + # If adding or updating top-level dependencies, update requirements.in and + # then overwrite existing requirements.txt with results of `pip-compile`. + # + # If simply wanting to update transitive dependencies to pin a new + # reproducible build, then overwrite existing requirements.txt with + # results of `pip-compile`. + # + # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html#pin-your-transitive-dependencies + - python -m pip install pip-tools + - pip-compile --strip-extras -o docs/new_requirements.txt docs/requirements.in --upgrade # Build documentation in the docs/ directory with Sphinx sphinx: @@ -30,6 +44,8 @@ sphinx: # We recommend specifying your dependencies to enable reproducible builds: # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html -# python: -# install: -# - requirements: docs/requirements.txt +python: + install: + # If needing to update for pinning a new reproducible build, then overwrite with + # results of `pip-compile` command above. + - requirements: docs/requirements.txt diff --git a/docs/conf.py b/docs/conf.py index e3b40523..ed1a1f33 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -28,7 +28,7 @@ # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. -#extensions = [] +extensions = ['sphinx.ext.todo'] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -63,7 +63,7 @@ # # This is also used if you do content translation via gettext catalogs. # Usually you set "language" from the command line for these cases. -language = None +language = 'en' # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -139,7 +139,7 @@ # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -def setup(app): app.add_stylesheet("theme_overrides.css" ) +html_css_files = ['theme_overrides.css'] # Add any extra paths that contain custom files (such as robots.txt or # .htaccess) here, relative to this directory. These files are copied diff --git a/docs/requirements.in b/docs/requirements.in new file mode 100644 index 00000000..82133027 --- /dev/null +++ b/docs/requirements.in @@ -0,0 +1,2 @@ +sphinx +sphinx_rtd_theme diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..1fd20802 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,65 @@ +# +# This file is autogenerated by pip-compile with Python 3.12 +# by the following command: +# +# pip-compile --output-file=docs/requirements.txt --strip-extras docs/requirements.in +# +alabaster==0.7.13 + # via sphinx +babel==2.13.1 + # via sphinx +certifi==2023.7.22 + # via requests +charset-normalizer==3.3.1 + # via requests +docutils==0.18.1 + # via + # sphinx + # sphinx-rtd-theme +idna==3.4 + # via requests +imagesize==1.4.1 + # via sphinx +jinja2==3.1.2 + # via sphinx +markupsafe==2.1.3 + # via jinja2 +packaging==23.2 + # via sphinx +pygments==2.16.1 + # via sphinx +requests==2.31.0 + # via sphinx +snowballstemmer==2.2.0 + # via sphinx +sphinx==7.2.6 + # via + # -r docs/requirements.in + # sphinx-rtd-theme + # sphinxcontrib-applehelp + # sphinxcontrib-devhelp + # sphinxcontrib-htmlhelp + # sphinxcontrib-jquery + # sphinxcontrib-qthelp + # sphinxcontrib-serializinghtml +sphinx-rtd-theme==1.3.0 + # via -r docs/requirements.in +sphinxcontrib-applehelp==1.0.7 + # via sphinx +sphinxcontrib-devhelp==1.0.5 + # via sphinx +sphinxcontrib-htmlhelp==2.0.4 + # via sphinx +sphinxcontrib-jquery==4.1 + # via sphinx-rtd-theme +sphinxcontrib-jsmath==1.0.1 + # via sphinx +sphinxcontrib-qthelp==1.0.6 + # via sphinx +sphinxcontrib-serializinghtml==1.1.9 + # via sphinx +urllib3==2.0.7 + # via requests + +# The following packages are considered to be unsafe in a requirements file: +# setuptools