ci: doc: pin Python dependencies to specific versions/hashes

[kartben]

Use secure install for Python documentation dependencies.

[pdgendt]

Yes please!

[pdgendt]

The job doc-build-pdf also has a install-pip step:

    - name: install-pip
      run: |
        pip install -r doc/requirements.txt
        pip install west==${WEST_VERSION}
        pip install cmake==${CMAKE_VERSION}

Which has a different construct for the package versions, what's the rationale here, and why can't we simply add these in doc/requirements.in?

[nashif]

what version are we using in CI? Should this match the same version used in CI?

[pdgendt]

I'm not fluent in ruby, but AFAICS dependabot parses this line to match the python version.

Version parsing:
https://github.com/dependabot/dependabot-core/blob/0405a99f095c792385a61be4f0f11911b81a86e8/python/lib/dependabot/python/file_parser/python_requirement_parser.rb#L92
Matching:
https://github.com/dependabot/dependabot-core/blob/0405a99f095c792385a61be4f0f11911b81a86e8/python/lib/dependabot/python/language_version_manager.rb#L90

This kind of information lacks in the documentation it seems.

[nashif]

the question is unrelated to dependabot , wondering if this would be a problem to generate hashes using one version and to be using a different version when installing the packages, i.e. there might be incompatibilities.

[kartben]

I think we're good. The version is there to help dependabot generate requirements.txt files that are "consistent" (i.e. no unnecessary diffs). The actual hashes have nothing to do with it AFAICT and any pip 8+ version will be happy with the format of the file (https://pip.pypa.io/en/stable/topics/secure-installs/#hash-checking-mode)

[kartben]

re-gen'd the requirements.txt with python 3.12 (Python version used in our docker image)

[kartben]

The job doc-build-pdf also has a install-pip step:

    - name: install-pip
      run: |
        pip install -r doc/requirements.txt
        pip install west==${WEST_VERSION}
        pip install cmake==${CMAKE_VERSION}

Which has a different construct for the package versions, what's the rationale here,

Yeah I need to look into this as it seems to actually be failing anyway
https://github.com/kartben/zephyr/actions/runs/13961212510/job/39082783857

and why can't we simply add these in doc/requirements.in?

Yeah this needs some cleanup. Adding cmake to the requirements file would likely be problematic for folks install dependencies locally and already having CMake? I will install it as a Linux package

[kartben]

Ended up doing lots of houskeeping on the PDF job so as to get rid of the texlive docker container we were using so that we actually install the required packages and therefore cross-check that our documentation has up-to-date instructions w.r.t what people might need to install to build the PDF locally

[kartben]

Just added one more extra flag that makes extra sure hashes are mandatory (and makes scorecard happy as well)