canonical / sphinx-docs-starter-pack

A documentation starter-pack
https://canonical-starter-pack.readthedocs-hosted.com/
Other
13 stars 35 forks source link

change build job for build_requirements.py #201

Closed ru-fu closed 2 months ago

ru-fu commented 5 months ago

Changing the build job to pre_install for the build_requirements.py script means that the build machine will already be fully set up, so that you can use pip to install any packages that are required in custom_conf.py and will otherwise give errors.

This is required to work around #197.

dviererbe commented 5 months ago

question: Can you explain how this solves #197?

note: My understanding of the problem is:

flowchart
  style dependency fill:red,color:white
  style requirements.txt stroke-dasharray: 2 2, fill: lightgrey
  style invisible stroke-width:0,fill:#00000000

  subgraph build_requirements.py
    direction TB
    invisible[" "] -->|"import"| custom_conf.py
    custom_conf.py -->|"import"| dependency["not yet installed module"]
  end

  build_requirements.py ---x|build fails| requirements.txt
  pip_install["pip install -r requirements.txt"] --x|"can not find"| requirements.txt

I do not understand how calling build_requirements.py at pre_install changes the situation.

ru-fu commented 5 months ago

It doesn't solve the problem, but it makes it possible to work around it.

See here for an example. The workaround is to "manually" install the required modules before running build_requirements.py. However, if I try to do that at post_checkout, pip isn't installed yet, so it fails. Also if I try to explicitly install pip (as a command or with apt_packages), it isn't available at that stage. It took me a lot of experimenting to figure out that pip IS available at pre_install. So if we change when build_requirements.py runs, we can easily pip-install packages before it runs.