From 58f26388be7fc20aee8a3f43863c7832eea21fb6 Mon Sep 17 00:00:00 2001
From: Alicia Cozine <879121+acozine@users.noreply.github.com>
Date: Tue, 22 Jun 2021 13:58:54 -0500
Subject: [PATCH] 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              | 17 ++++++++++
 docs/docsite/requirements.txt                 | 15 +++++---
 .../community/documentation_contributions.rst | 34 +++++++++----------
 3 files changed, 44 insertions(+), 22 deletions(-)
 create mode 100644 docs/docsite/known_good_reqs.txt

diff --git a/docs/docsite/known_good_reqs.txt b/docs/docsite/known_good_reqs.txt
new file mode 100644
index 00000000000..347d2d15f78
--- /dev/null
+++ b/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
diff --git a/docs/docsite/requirements.txt b/docs/docsite/requirements.txt
index dd32ac0df53..251503fa7b5 100644
--- a/docs/docsite/requirements.txt
+++ b/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
diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst
index e0f7e560b17..e456876dce5 100644
--- a/docs/docsite/rst/community/documentation_contributions.rst
+++ b/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::