Open Stack

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