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
pull/75059/head
Alicia Cozine 3 years ago committed by GitHub
parent 50b6d28ee1
commit 58f26388be
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23

@ -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

@ -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

@ -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::

Loading…
Cancel
Save