Need for tests and documentation on build dependencies for the starter pack

[fnordahl]

The Makefile populates a virtualenv with PIP for the tooling required to build the docs. PIP will by default download binary wheels from PyPI when available, however not all architectures have pre-built wheels available.

This is problematic because at present a build may pass in the gate only to fail further down in the post-merge pipeline, which is currently the case for the riscv64 architecture.

To mitigate this we change the docs Makefile downstream to instruct PIP to avoid using binary wheels so that any missing build dependencies can be detected in the gate.

Building the virtualenv from source is time consuming and I wonder if it's really fair that downstream projects spend time detecting any missing build dependencies for the the docs starter pack.

Would it make sense for the sphinx-docs-starter-pack repository to have a test that ensures all build dependencies are in fact available and as a result document what those build dependencies are?

[ru-fu]

Sorry for "ignoring" this issue until now - I'm not familiar enough with the venv to fully understand. ;)

So, is the request to document the Python requirements? That should be easy to do. We have the (automatically generated) requirements.txt file, so we can add the requirements for the default setup to the docs.

Regarding tests, I'm not quite sure what to do. Would it help to add a --prefer-binary to the installation to use the wheel where available and build from source otherwise?

[fnordahl]

Sorry for "ignoring" this issue until now - I'm not familiar enough with the venv to fully understand. ;)

No issue at all.

So, is the request to document the Python requirements? That should be easy to do. We have the (automatically generated) requirements.txt file, so we can add the requirements for the default setup to the docs.

Regarding tests, I'm not quite sure what to do. Would it help to add a --prefer-binary to the installation to use the wheel where available and build from source otherwise?

The requirements.txt is one thing, and as you point out that does indeed serve as documentation of the runtime dependencies. The issue we are facing is that we need to build these from source code because there are no binary wheels available for some architectures. When doing that there are additional development packages that needs to be installed in the build environment for the build to succeed.

This would also be living material, because these build dependencies change over time as the direct and indirect dependencies of the packages listed in requirements.txt change.

I'd be happy to contribute a test for this repository, I guess raising the issue was mostly to check whether it would be accepted. The list of dependencies in that test would serve as documentation for build dependencies.

Since the workflow file is used by other repositories, I'm thinking along the lines of using conditional execution so that they only run for changes to this specific repository. For example:

  sphinx-build-dependencies-check:
    if: github.repository == 'canonical/sphinx-docs-starter-pack'
    ...

[ru-fu]

I'd be happy to contribute a test for this repository, I guess raising the issue was mostly to check whether it would be accepted. The list of dependencies in that test would serve as documentation for build dependencies.

Yes, that makes sense to me. There will be a significant change to this repo soon-ish when we move the styling and custom processing to an extension. If I understand correctly, this will still work the same way then though, because we'll have the extension as the requirement for the starter pack, and it will have additional dependencies.

Any thoughts @tigarmo?

Since the workflow file is used by other repositories, I'm thinking along the lines of using conditional execution so that they only run for changes to this specific repository.

Good idea, yes. We should also have it in a separate workflow file (and update the init.sh script and our installation instructions to remove it).

[fnordahl]

Good idea, yes. We should also have it in a separate workflow file (and update the init.sh script and our installation instructions to remove it).

Ah, if there is such a script that would do the trick then. Adding conditional execution has the side effect of contributors finding it difficult to test their changes before proposing a PR, so if we can drop that and use init.sh to remove the workflow file, that would be even better.