Pin doc build requirements (#60) (#247)

docs/docsite/requirements.txt

@@ -1,7 +1,7 @@
-# pip packages required to build docsite
-# these requirements are as loosely defined as possible
-# if you want known good versions of these dependencies
-# use tests/requirements.txt instead
+# pip packages required to build the documentation.
+# These requirements are as loosely defined as possible.
+# For known good versions of doc build dependencies use the following command:
+# pip install -r tests/requirements.in -c tests/requirements.txt
 
 antsibull-docs >= 2.0.0, < 3.0.0
 docutils

docs/docsite/rst/community/documentation_contributions.rst

@@ -109,8 +109,8 @@ Drop the ``--user`` option in the following commands if you use a virtual enviro
 
    .. code-block:: bash
 
-    pip install --user -r docs/docsite/requirements.txt # This file installs the unpinned dependency versions.
-    pip install --user -r tests/requirements.txt # This file installs tested dependency versions.
+    pip install --user -r tests/requirements.in -c tests/requirements.txt # Installs tested dependency versions.
+    pip install --user -r tests/requirements.in # Installs the unpinned dependency versions.
 
 .. note::
 

tests/constraints.in

@@ -0,0 +1,5 @@
+# Known limitations for indirect/transitive dependencies.
+resolvelib < 1.1.0
+sphinx == 5.3.0
+rstcheck < 6  # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3
+antsibull-docs == 2.3.1  # currently approved version

tests/requirements.in

@@ -0,0 +1,10 @@
+-c constraints.in # <-- contains known limitations
+
+jinja2 >= 3.0.0 # used by hacking/build_library/build_ansible/command_plugins/generate_man.py and dump_keywords.py
+pyyaml >= 5.1 # used by ansible-core
+resolvelib # used by ansible-core
+sphinx
+sphinx-notfound-page
+sphinx-ansible-theme
+rstcheck
+antsibull-docs

tests/requirements.txt

@@ -1,8 +1,162 @@
-jinja2
-pyyaml
-resolvelib < 1.1.0
-sphinx == 5.3.0
-sphinx-notfound-page
-sphinx-ansible-theme
-rstcheck < 6  # rstcheck 6.x has problem with rstcheck.core triggered by include files w/ sphinx directives https://github.com/rstcheck/rstcheck-core/issues/3
-antsibull-docs == 2.3.1  # currently approved version
+#
+# This file is autogenerated by pip-compile with Python 3.10
+# by the following command:
+#
+#    pip-compile --allow-unsafe --output-file=requirements.txt --strip-extras requirements.in
+#
+aiofiles==23.1.0
+    # via antsibull-core
+aiohttp==3.8.5
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+aiosignal==1.3.1
+    # via aiohttp
+alabaster==0.7.13
+    # via sphinx
+ansible-pygments==0.1.1
+    # via
+    #   antsibull-docs
+    #   sphinx-ansible-theme
+antsibull-core==2.0.0
+    # via antsibull-docs
+antsibull-docs==2.3.1
+    # via
+    #   -c constraints.in
+    #   -r requirements.in
+antsibull-docs-parser==1.0.0
+    # via antsibull-docs
+async-timeout==4.0.2
+    # via aiohttp
+asyncio-pool==0.6.0
+    # via antsibull-docs
+attrs==23.1.0
+    # via aiohttp
+babel==2.12.1
+    # via sphinx
+build==0.10.0
+    # via antsibull-core
+certifi==2023.7.22
+    # via requests
+charset-normalizer==3.2.0
+    # via
+    #   aiohttp
+    #   requests
+docutils==0.18.1
+    # via
+    #   antsibull-docs
+    #   rstcheck
+    #   sphinx
+    #   sphinx-rtd-theme
+frozenlist==1.4.0
+    # via
+    #   aiohttp
+    #   aiosignal
+idna==3.4
+    # via
+    #   requests
+    #   yarl
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via
+    #   -r requirements.in
+    #   antsibull-docs
+    #   sphinx
+markupsafe==2.1.3
+    # via jinja2
+multidict==6.0.4
+    # via
+    #   aiohttp
+    #   yarl
+packaging==23.1
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+    #   build
+    #   sphinx
+perky==0.9.2
+    # via antsibull-core
+pydantic==1.10.12
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+pygments==2.15.1
+    # via
+    #   ansible-pygments
+    #   sphinx
+pyproject-hooks==1.0.0
+    # via build
+pyyaml==6.0.1
+    # via
+    #   -r requirements.in
+    #   antsibull-core
+    #   antsibull-docs
+requests==2.31.0
+    # via sphinx
+resolvelib==1.0.1
+    # via
+    #   -c constraints.in
+    #   -r requirements.in
+rstcheck==5.0.0
+    # via
+    #   -c constraints.in
+    #   -r requirements.in
+    #   antsibull-docs
+semantic-version==2.10.0
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+sh==1.14.3
+    # via antsibull-core
+six==1.16.0
+    # via twiggy
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==5.3.0
+    # via
+    #   -c constraints.in
+    #   -r requirements.in
+    #   antsibull-docs
+    #   sphinx-ansible-theme
+    #   sphinx-notfound-page
+    #   sphinx-rtd-theme
+    #   sphinxcontrib-jquery
+sphinx-ansible-theme==0.10.2
+    # via -r requirements.in
+sphinx-notfound-page==0.8.3
+    # via -r requirements.in
+sphinx-rtd-theme==1.2.2
+    # via sphinx-ansible-theme
+sphinxcontrib-applehelp==1.0.4
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.1
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.5
+    # via sphinx
+tomli==2.0.1
+    # via
+    #   build
+    #   pyproject-hooks
+twiggy==0.5.1
+    # via
+    #   antsibull-core
+    #   antsibull-docs
+types-docutils==0.18.3
+    # via rstcheck
+typing-extensions==4.7.1
+    # via
+    #   pydantic
+    #   rstcheck
+urllib3==2.0.4
+    # via requests
+yarl==1.9.2
+    # via aiohttp