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.
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.
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
what CI uses for the
docs-buildCI test - https://github.com/ansible/ansible-documentation/blob/4ec04d6f12d3d1011b62c8dacc67f35c265c7949/.github/workflows/ci.yaml#L26
issue to pin sphinx while we figure out what’s breaking - Docs builds are failing with sphinx v7 · Issue #327 · ansible/ansible-documentation · GitHub
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.