Incorrect Sphinx version used during RTD build

[sethfischer]

Details

• Read the Docs project URL: https://readthedocs.org/projects/sphinxcontrib-cadquery/
• Build URL: https://readthedocs.org/projects/sphinxcontrib-cadquery/builds/19088114/
• Read the Docs username: https://readthedocs.org/profiles/sethfischer/

Expected Result

Build 19088114 is expected to use Sphinx 5.3.0.

Actual Result

Build 19088114 uses Sphinx 6.1.1.

Further information

rtd-build-19088114.txt

Build 19088114 uses Poetry to install dependencies with a build.jobs.post_create_environment user-defined job, in a manner recommended by RTD.

As expected poetry install installs Sphinx 5.3.0. This is confirmed with poetry show sphinx in build.jobs.post_create_environment.

However, when the following is run by RTD:

/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-cadquery/envs/1/bin/python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html

The output shows that Sphinx 6.1.1 is being used:

Running Sphinx v6.1.1
WARNING: html_static_path entry '_static' does not exist
building [mo]: targets for 0 po files that are out of date
writing output...
⋮

.readthedocs.yaml:

version: 2

build:
  os: ubuntu-20.04
  tools:
    nodejs: "19"
    python: "3.9"
  jobs:
    post_create_environment:
      # install Poetry
      - pip install poetry
      - poetry config virtualenvs.create false
      # install Python dependencies
      - poetry install
      - poetry show sphinx
    post_install:
      # install Node.js dependencies
      - npm clean-install
      # build
      - npm run build

sphinx:
  configuration: docs/conf.py

[benjaoming]

Hi @sethfischer

It seems there is a built-in pip install which installs the latest sphinx after post_create_environment is run.

What happens if you move these to post_install?

    post_install:
      # These two are moved from post_create_environment
      - poetry install
      - poetry show sphinx
      # install Node.js dependencies
      - npm clean-install
      # build
      - npm run build

(I think we should upgrade the guide if this is indeed the case)

[sethfischer]

Thanks @benjaoming. Moving poetry install from build.jobs.post_create_environment to post_install resolved the issue.

Build #19097755

version: 2

build:
  os: ubuntu-20.04
  tools:
    nodejs: "19"
    python: "3.9"
  jobs:
    post_create_environment:
      - pip install poetry
      - poetry config virtualenvs.create false
    post_install:
      - poetry install
      - npm clean-install
      - make npm-build

sphinx:
  configuration: docs/conf.py

[benjaoming]

@sethfischer thanks so much for sharing the configuration!

@humitos can you confirm that this is also a good setup and if we should use this approach in the example from the documentation?

[humitos]

I don't have too much experience with Poetry, but it seems that using post_install covers more scenarios, so 👍🏼 . I think it makes sense to use the combination of post_create_environment (install poetry) and post_install (install packages with poetry) as shown in the previous comment.

[benjaoming]

Great! Thanks for looking @humitos 👍

@sethfischer if you are interested in contributing to the docs, you are most welcome 👍 Otherwise, I'll give it a look during the week.

[sethfischer]

@benjaoming Sure! I'll submit a pull request.