Update docs requirements list (#74956)

* removes upper bound on sphinx version
* updates versions of docs build dependencies, adds known good requirements file
* adds instructions for using known_good_reqs file

docs/docsite/known_good_reqs.txt

@@ -0,0 +1,17 @@
+# pip packages required to build docsite
+# tested June 9 2021
+
+antsibull==0.33.0
+docutils==0.16
+# check unordered lists when testing more recent docutils versions
+# see https://github.com/readthedocs/sphinx_rtd_theme/issues/1115
+jinja2==3.0.1
+Pygments==2.9.0
+PyYAML==5.4.1
+resolvelib==0.5.4
+rstcheck==3.3.1
+sphinx==4.0.2
+sphinx-notfound-page==0.7.1 # must be >= 0.6
+sphinx-intl==2.0.1
+sphinx_ansible_theme===0.6.0
+straight.plugin==1.5.0 # Needed for hacking/build-ansible.py which is the backend build script

docs/docsite/requirements.txt

@@ -1,13 +1,18 @@
-#pip packages required to build docsite
+# pip packages required to build docsite
+# these requirements are as loosely defined as possible
+# if you want known good versions of these dependencies
+# use known_good_reqs.txt instead 
+
+antsibull >= 0.25.0
+docutils == 0.16 # pin for now until the problem with unordered lists is fixed
+# see https://github.com/readthedocs/sphinx_rtd_theme/issues/1115jinja2==3.0.1
 jinja2
+Pygments >= 2.4.0
 PyYAML
 rstcheck
-sphinx==2.1.2
+sphinx
 sphinx-notfound-page >= 0.6
 sphinx-intl
 sphinx_ansible_theme === 0.6.0
 resolvelib
-Pygments >= 2.4.0
 straight.plugin # Needed for hacking/build-ansible.py which is the backend build script
-antsibull >= 0.25.0
-docutils==0.16 # pin for now until sphinx_rtd_theme is compatible with 0.17 or later

docs/docsite/rst/community/documentation_contributions.rst

@@ -74,33 +74,33 @@ Setting up your environment to build documentation locally
 
 To build documentation locally, ensure you have a working :ref:`development environment <environment_setup>`.
 
-To work with documentation on your local machine, you need to have python-3.5 or greater and the
-following packages installed:
+To work with documentation on your local machine, you need to have python-3.5 or greater and install the `Ansible dependencies`_ and `documentation dependencies`_, which are listed in two :file:`requirements.txt` files to make installation easier:
 
-    - ``gcc``
-    - ``jinja2``
-    - ``libyaml``
-    - ``make``
-    - ``Pygments``
-    - ``pyparsing``
-    - ``PyYAML``
-    - ``rstcheck``
-    - ``six``
-    - ``sphinx``
-    - ``sphinx-notfound-page``
-    - ``straight.plugin``
-
-These required packages are listed in two :file:`requirements.txt` files to make installation easier:
+.. _Ansible dependencies: https://github.com/ansible/ansible/blob/devel/requirements.txt
+.. _documentation dependencies: https://github.com/ansible/ansible/blob/devel/docs/docsite/requirements.txt
 
 .. code-block:: bash
 
     pip install --user -r requirements.txt
     pip install --user -r docs/docsite/requirements.txt
 
-You can drop ``--user`` if you have set up a virtual environment (venv/virtenv).
+The :file:`docs/docsite/requirements.txt` file allows a wide range of versions and may install new releases of required packages. New releases of these packages may cause problems with the Ansible docs build. If you want to install tested versions of these dependencies, use :file:`docs/docsite/known_good_reqs.txt` instead:
+
+.. code-block:: bash
+
+    pip install --user -r requirements.txt
+    pip install --user -r docs/docsite/known_good_reqs.txt
+
+You can drop ``--user`` if you have set up a virtual environment (venv/virtenv). 
 
 .. note::
 
+    You may need to install these general pre-requisites separately on some systems:
+    - ``gcc``
+    - ``libyaml``
+    - ``make``
+    - ``pyparsing``
+    - ``six``
     On macOS with Xcode, you may need to install ``six`` and ``pyparsing`` with ``--ignore-installed`` to get versions that work with ``sphinx``.
 
 .. note::