Docs build requirements

Project Discussions
1

Hi folks! I wanted to start a discussion on our current set of documentation build requirements and when to use each of them. A lot has changed recently, so I’m not really sure when to use the current options.

A bit of history

Previously, we had two sets of requirements:
1 - pinned requirements used for stable builds (released versions of Ansible and ansible-core). This was to ensure our important publishing is always available and stable.
2 - some unpinned requirements - used for the nightly devel docs build and publish - The idea was to have this as the early warning system. If devel docs builds started failing, we’d look and see what the problem is and if a dependency released a new version that our docs build isn’t compatible with.

What we have today

1 - https://github.com/ansible/ansible-documentation/blob/devel/tests/requirements.in This has two options:
a. -c constraints.in - this is our stable, pinned requirements used for publishing latest docs etc - it pins sphinx, rstcheck, and antsibull-docs.
b. -r requirements-relaxed.in - minimal pinning. sphinx is unpinned.
2. https://github.com/ansible/ansible-documentation/blob/devel/tests/constraints-base.in - for known limits (rstcheck < 6, and now possibly sphinx < 7).

And our docs instructions currently advise:

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.

And our jenkins job at the time of this writing was updated to just use the pinned option for now while we figure some things out:

python3 -m pip install setuptools six
                # Clone the relevant parts of the `ansible/ansible` repository to build docs.
                python3 ./docs/bin/clone-core.py
 # install pinned docs build requirements
                python3 -m pip install -r ./tests/requirements.in -c ./tests/requirements.txt

Related areas that might need updating:

General questions

So - It feels like we have three options to choose from:

  • pinned (known good and stable)
  • kinda pinned (keeps sphinx pinned)
  • mostly unpinned (sphinx not pinned)

While the benefit of the third option is it did break builds for devel and let us know sphinx’s latest version doesn’t work for us, it does beg the question of why we need all three options.

2 Likes