Setup reproducible docs builds using pip-tools

[atugushev]

Since the last Sphinx update, the docs build has started failing. It turns out pip-tools doesn't have reproducible builds for docs. Hence, the PR.

Refs: pradyunsg/furo#693.

[webknjaz]

Somebody should start dogfooding pip-tools...

[atugushev]

Somebody should start dogfooding pip-tools...

@webknjaz I'm kinda lost, what do you mean?

[atugushev]

Ah, I wasn't aware of the word "dogfooding". You're right. It would be nice to have docs/requirements.in and perhaps dependabot integration. You're reading my mind.

Found nice docs over here.

[theryanwalker]

I'm wondering if there is a way to use pip-sync here?

[webknjaz]

In fact, I don't like installing from a constraints file.
Here https://github.com/aio-libs/aiohttp/pull/7471/files#diff-cde814ef2f549dc093f5b8fc533b7e8f47e7b32a8081e0760e57d5c25a1139d9R18-R44 I've been playing with a new mechanism for RTD build customization. Try reproducing the same here.

[atugushev]

I'm wondering if there is a way to use pip-sync here?

I guess we can figure it out. I'll try to come up with a solution in a follow-up PR. Thanks for the example, @webknjaz. That's useful.

[webknjaz]

Since we don't already have generic requirements, I wouldn't move this to a separate folder. The location under docs/ is closer to where it's actually being used + this idiom is widely copied over the ecosystem. Let's not reinvent the wheel.

[atugushev]

Indeed, currently we don't have any generic requirements. I propose, if we're looking to fully embrace pip-tools and create reproducible builds, that we should consider compiling dependencies for the tests as well, which are currently declared in pyproject.toml under extra=testing. I'm under the impression that current approach is less favoured based on this and this comments.

So, the next step – to move the test requirements to requirements/test.{in|txt} from extra=testing in pyproject.toml – seems logical. With this in mind, wouldn't it also be logical to relocate preemptively the docs requirements to a common requirements folder to keep runtime requirements close together, thus eliminating the need to open another PR later on? Would that make sense?

[webknjaz]

Yes to no extra. But it's a bit more complicated since different envs have different trees. So it's not just one file pair but a matrix of them.
I think that the idea that works is to have tox-env based collections of lockfiles, like the one I implemented in #826 (comment).

As for the docs, I'm torn. If we were to have a constraints file following the same principle, it'd be tox-specific and would probably need several env-specific incarnations. Whereas, tox is not the only place where we call sphinx — in RTD we do so as well. The common denominator is the docs/ dir, so it kinda makes sense to bundle everything under it. OTOH, even in my cheroot PoC, I experimented with having the lockfiles under requirements/ and I'm not sure how I feel about it. That was my attempt to come up with something generic/reusable, and it seems to need more polishing still. I think I have requirements under docs/ in all (or most) the other projects.

I guess it's hard for me to decide on one way or the other. Having the docs/ dir self-contained ain't bad.

[atugushev]

Thank you for the detailed reply. Your insights certainly provided a lot to consider. Following the principle of "not putting the cart before the horse" let's fix the broken docs build first and then make a decision on how to handle the generic requirements. The commit has been reverted in 9beca35 so that we can progress further.

[webknjaz]

Found nice docs over here.

Yeah, that's a relatively new doc.