Constraints and docs requirements
Hello, The Designate project recently discovered that Wallaby docs builds were failing. This started happening because jinja2 newer than is specified in the constraints file was being installed, and there was a non backward compatible change that broke the doc builds. After some debugging we have determined the reason for this is that `tox -e docs` has two steps in its installation process. The first is the dependency installation which respects constraints and then after that is the installation of the package itself (in this case Designate). This second step does not supply constraints info, and it is expected that all dependencies of the package have been preinstalled by the first step. Where we get in trouble is that the docs requirements for projects like Designate (and we suspect others) are a subset of the package requirements necessary to install the packages. This means the second step in this install process discovers that many dependencies need to be installed and this happens without constraints allowing unexpected versions to be pulled in. To resolve this issue, make sure you are including the project requirements along with the doc requirements in your tox environment dependencies section[1]. This will allow pip to install all of the required dependencies, those required for the documentation generation and those for the project, to be all installed using the upper constraints. Thanks to clarkb and fungi for helping track down this issue and composing this email. [1] https://review.opendev.org/c/openstack/designate/+/836410/1/tox.ini
On 2022-04-04 16:01:08 -0700 (-0700), Michael Johnson wrote:
After some debugging we have determined the reason for this is that `tox -e docs` has two steps in its installation process. The first is the dependency installation which respects constraints and then after that is the installation of the package itself (in this case Designate). This second step does not supply constraints info, and it is expected that all dependencies of the package have been preinstalled by the first step. [...]
Do note that the second pip install is occurring because usedevelop is set to True in the tox.ini. If a project doesn't set usedevelop (which defaults to false), or explicitly sets it to false, the project is not installed unless included in the testenv's deps.
To resolve this issue, make sure you are including the project requirements along with the doc requirements in your tox environment dependencies section[1]. This will allow pip to install all of the required dependencies, those required for the documentation generation and those for the project, to be all installed using the upper constraints. [...]
An alternative would be to turn off usedevelop and add something like {toxinidir} or "." to the deps list in the testenv:docs entry, making sure that the -c option to apply constraints is also included in that deps list. This also avoids the second pip install phase, so may shave a few seconds off the run. -- Jeremy Stanley
participants (2)
-
Jeremy Stanley
-
Michael Johnson