Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix documentation build on ReadTheDocs #116

Closed
2 tasks done
roskakori opened this issue Jun 27, 2023 · 0 comments · Fixed by #117
Closed
2 tasks done

Fix documentation build on ReadTheDocs #116

roskakori opened this issue Jun 27, 2023 · 0 comments · Fixed by #117
Labels
Milestone

Comments

@roskakori
Copy link
Owner

roskakori commented Jun 27, 2023

Currently the build on ReadTheDocs fails with the following error:

INFO: pip is looking at multiple versions of sphinx-rtd-theme to determine which version is compatible with other requirements. This could take a while.
ERROR: Cannot install -r docs/requirements.txt (line 2) and Sphinx==7.0.1 because these package versions have conflicting dependencies.

The conflict is caused by:
    The user requested Sphinx==7.0.1
    sphinx-rtd-theme 1.2.2 depends on sphinx<7 and >=1.6

To fix this you could try to:
1. loosen the range of package versions you've specified
2. remove package versions to allow pip attempt to solve the dependency conflict

ERROR: ResolutionImpossible: for help visit https://pip.pypa.io/en/latest/topics/dependency-resolution/#dealing-with-dependency-conflicts

This has already been reported two months ago but not addressed yet: readthedocs/sphinx_rtd_theme#1463. A comment at this issue suggests to switch to the furo theme.

Expected state:

  • The CI catches build error before ReadTheDocs. ℹ️ Not sure why it doesn't already. It does build the documentation using make, which if I understand correctly creates its own virtualenv, which should fail because of the dependency conflict above. However, for some reason however it does not. Spank me. CI did not build the docs.
  • The documentation on ReadTheDocs builds again. ℹ️ Possibly by switching the theme to furo or by reverting to the Spinx default theme.
@roskakori roskakori added the bug label Jun 27, 2023
@roskakori roskakori added this to the v1.6.1 milestone Jun 27, 2023
@roskakori roskakori changed the title Fix documentation build on readthedocs Fix documentation build on ReadTheDocs Jun 27, 2023
roskakori added a commit that referenced this issue Jun 27, 2023
roskakori added a commit that referenced this issue Jun 27, 2023
This enables the local build, the CI build and the ReadTheDocs build to have the same potential dependency conflicts and consequently detect the early on.
roskakori added a commit that referenced this issue Jun 27, 2023
roskakori added a commit that referenced this issue Jun 27, 2023
Sadly it seems very hard to locally mix a docs/requirements.txt with poetry when building both locally and on ReadTheDocs. So for the time being, they use different build methods.

But unlike before, the Sphinx version in poetry.toml and docs/requirements.txt are the same. This should allow to detect possible documentation build error before they make it to ReadTheDocs.
roskakori added a commit that referenced this issue Jun 27, 2023
Rationale: The maintenance of sphinx_rtd_theme is sub par. For details see <readthedocs/sphinx_rtd_theme#1463>.
roskakori added a commit that referenced this issue Jun 27, 2023
…-readthedocs

#116 Fix documentation build on ReadTheDocs
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
Status: Done
Development

Successfully merging a pull request may close this issue.

1 participant