From 6c105eea5ed867ea6a4c481c341720300adc7e61 Mon Sep 17 00:00:00 2001 From: samccann Date: Fri, 22 Apr 2022 13:36:56 -0400 Subject: [PATCH 1/6] trim down to use sanity test docs requirements file --- docs/docsite/known_good_reqs.txt | 19 ------------------- docs/docsite/requirements.txt | 17 ----------------- .../community/documentation_contributions.rst | 12 ++++-------- 3 files changed, 4 insertions(+), 44 deletions(-) delete mode 100644 docs/docsite/known_good_reqs.txt delete mode 100644 docs/docsite/requirements.txt diff --git a/docs/docsite/known_good_reqs.txt b/docs/docsite/known_good_reqs.txt deleted file mode 100644 index 52a3214101c70b..00000000000000 --- a/docs/docsite/known_good_reqs.txt +++ /dev/null @@ -1,19 +0,0 @@ -# pip packages required to build docsite -# tested Nov 11 2021 -# NOTE - this file must align with CI test for docs-build at -# test/sanity/code-smell/docs-build.requirements.txt -# test/sanity/code-smell/rstcheck.requirements.txt - -antsibull-docs == 1.0.0 -# sphinx 4.2.0 requires docutils < 0.18 -docutils == 0.17.1 -jinja2 == 3.0.3 -pygments == 2.10.0 -pyyaml == 6.0 -resolvelib == 0.5.4 -rstcheck == 3.3.1 -sphinx == 4.2.0 -sphinx-notfound-page == 0.8 # must be >= 0.6 -sphinx-intl == 2.0.1 -sphinx-ansible-theme === 0.9.1 -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 deleted file mode 100644 index d0362f36874cc0..00000000000000 --- a/docs/docsite/requirements.txt +++ /dev/null @@ -1,17 +0,0 @@ -# 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-docs >= 1.0.0, < 2.0.0 -docutils -jinja2 -pygments >= 2.10.0 -pyyaml -rstcheck -sphinx -sphinx-notfound-page >= 0.6 -sphinx-intl -sphinx-ansible-theme >= 0.9.1 -resolvelib -straight.plugin # Needed for hacking/build-ansible.py which is the backend build script diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 12cc0d5811b426..302e7c1150b9e0 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -74,22 +74,18 @@ Setting up your environment to build documentation locally To build documentation locally, ensure you have a working :ref:`development environment `. -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: +To work with documentation on your local machine, you need to have python-3.9 or greater and install the `Ansible dependencies`_ and `documentation dependencies`_, which are listed in two 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 +.. _documentation dependencies: https://github.com/ansible/ansible/blob/devel/test/sanity/code-smell/docs-build.requirements.txt .. code-block:: bash pip install --user -r requirements.txt - pip install --user -r docs/docsite/requirements.txt + pip install --user -r test/sanity/code-smell/docs-build.requirements.txt -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: +The :file:`test/sanity/code-smell/docs-build.requirements.txt` file installs tested versions of the documentation dependencies and matches the tests run in CI. -.. 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). From 31f2b6c0fa4400a5c7a25499b74b3d6769e24200 Mon Sep 17 00:00:00 2001 From: samccann Date: Fri, 22 Apr 2022 14:24:53 -0400 Subject: [PATCH 2/6] add requrements back --- docs/docsite/requirements.txt | 17 +++++++++++++++++ .../community/documentation_contributions.rst | 9 +++++++-- 2 files changed, 24 insertions(+), 2 deletions(-) create mode 100644 docs/docsite/requirements.txt diff --git a/docs/docsite/requirements.txt b/docs/docsite/requirements.txt new file mode 100644 index 00000000000000..d0362f36874cc0 --- /dev/null +++ b/docs/docsite/requirements.txt @@ -0,0 +1,17 @@ +# 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-docs >= 1.0.0, < 2.0.0 +docutils +jinja2 +pygments >= 2.10.0 +pyyaml +rstcheck +sphinx +sphinx-notfound-page >= 0.6 +sphinx-intl +sphinx-ansible-theme >= 0.9.1 +resolvelib +straight.plugin # Needed for hacking/build-ansible.py which is the backend build script diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 302e7c1150b9e0..8251d4bac2905e 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -77,14 +77,19 @@ To build documentation locally, ensure you have a working :ref:`development envi To work with documentation on your local machine, you need to have python-3.9 or greater and install the `Ansible dependencies`_ and `documentation dependencies`_, which are listed in two 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/test/sanity/code-smell/docs-build.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 + +If you want to install tested versions of these dependencies, use :file:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI: + +. code-block:: bash pip install --user -r requirements.txt pip install --user -r test/sanity/code-smell/docs-build.requirements.txt -The :file:`test/sanity/code-smell/docs-build.requirements.txt` file installs tested versions of the documentation dependencies and matches the tests run in CI. You can drop ``--user`` if you have set up a virtual environment (venv/virtenv). From b1daa3b71e4d30e13f4e066ff0213cfe755511c9 Mon Sep 17 00:00:00 2001 From: samccann Date: Fri, 22 Apr 2022 14:27:11 -0400 Subject: [PATCH 3/6] add back missing sentence --- docs/docsite/rst/community/documentation_contributions.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 8251d4bac2905e..d6a5dfb28d6ff0 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -84,7 +84,7 @@ To work with documentation on your local machine, you need to have python-3.9 or pip install --user -r requirements.txt pip install --user -r docs/docsite/requirements.txt -If you want to install tested versions of these dependencies, use :file:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI: +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:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI: . code-block:: bash pip install --user -r requirements.txt From 7ebdba66d36044387d987a3914bc88f596f04598 Mon Sep 17 00:00:00 2001 From: samccann Date: Fri, 22 Apr 2022 15:28:48 -0400 Subject: [PATCH 4/6] fix codeblock --- docs/docsite/rst/community/documentation_contributions.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index d6a5dfb28d6ff0..73d0df46679008 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -86,7 +86,8 @@ To work with documentation on your local machine, you need to have python-3.9 or 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:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI: -. code-block:: bash +.. code-block:: bash + pip install --user -r requirements.txt pip install --user -r test/sanity/code-smell/docs-build.requirements.txt From 5a1545e528cb6834a6423f71e2850c2e09bb889c Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 25 Apr 2022 11:10:14 -0400 Subject: [PATCH 5/6] Update docs/docsite/rst/community/documentation_contributions.rst Co-authored-by: Felix Fontein --- docs/docsite/rst/community/documentation_contributions.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index 73d0df46679008..ebfeb50deae90b 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -87,7 +87,6 @@ To work with documentation on your local machine, you need to have python-3.9 or 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:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI: .. code-block:: bash - pip install --user -r requirements.txt pip install --user -r test/sanity/code-smell/docs-build.requirements.txt From f38362919a660f1377eebf50f5e1a91ef67c8601 Mon Sep 17 00:00:00 2001 From: Sandra McCann Date: Mon, 25 Apr 2022 15:51:51 -0400 Subject: [PATCH 6/6] Update docs/docsite/rst/community/documentation_contributions.rst --- docs/docsite/rst/community/documentation_contributions.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/docsite/rst/community/documentation_contributions.rst b/docs/docsite/rst/community/documentation_contributions.rst index ebfeb50deae90b..51f30b7c3b2213 100644 --- a/docs/docsite/rst/community/documentation_contributions.rst +++ b/docs/docsite/rst/community/documentation_contributions.rst @@ -87,6 +87,7 @@ To work with documentation on your local machine, you need to have python-3.9 or 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:`test/sanity/code-smell/docs-build.requirements.txt` instead, which matches the dependencies used by CI: .. code-block:: bash + pip install --user -r requirements.txt pip install --user -r test/sanity/code-smell/docs-build.requirements.txt