Skip to content

Make qubes-doc installable with pyproject.toml - #1734

Open
parulin wants to merge 2 commits into
QubesOS:mainfrom
parulin:installable-pyproject-toml
Open

parulin wants to merge 2 commits into
QubesOS:mainfrom
parulin:installable-pyproject-toml

Conversation

@parulin

@parulin parulin commented Jul 16, 2026

Copy link
Copy Markdown
Contributor
  • Move extensions as part of the qubes_doc package
  • Update conf.py
  • Update pyproject.toml:
    • Convert qubes_doc to a real package
    • Move some packages to optional dependencies groups
    • Bump sphinx version
  • Remove requirements.txt
  • Update .readthedocs.yaml to use the new install method
  • Update installation instructions accordingly
  • Add basic instructions to build the docs in README

After all this, the PDF would still not build on Read The Docs, so a workaround is to remove (almost) unused sphinxnotes-* extensions

Fix QubesOS/qubes-issues#10738
Fix QubesOS/qubes-issues#10737

Thanks to @hippalectryon-0 for some parts. See also: #1642

@parulin
parulin force-pushed the installable-pyproject-toml branch from 3cdcb70 to b94ad58 Compare July 16, 2026 07:02
@parulin
parulin marked this pull request as ready for review July 16, 2026 07:03
@parulin
parulin marked this pull request as draft July 16, 2026 07:03
@parulin

parulin commented Jul 16, 2026

Copy link
Copy Markdown
Contributor Author

Tested:

  • html build, with the pull request build
  • html build, locally with pip
  • html build, locally with poetry
  • html build, locally with uv
  • html build, locally with uv without optional dependencies
  • epub and pdf on read the docs

@parulin
parulin force-pushed the installable-pyproject-toml branch 9 times, most recently from 3928f68 to e5ff20d Compare July 16, 2026 12:20
@parulin
parulin marked this pull request as ready for review July 16, 2026 12:27
@parulin
parulin force-pushed the installable-pyproject-toml branch from e5ff20d to 61dc170 Compare July 17, 2026 07:57
parulin added 2 commits July 17, 2026 08:20
* Move extensions as part of the `qubes_doc` package
* Update `pyproject.toml`:
  * Convert `qubes_doc` to a real package
  * Move some packages to optional dependencies groups
  * Bump sphinx version
* Remove `requirements.txt`
* Update `conf.py`:
  * Remove path manipulations
  * Update qubes_doc.ext extensions
  * Create optional extensions (to support installation without `dev`
    dependencies)
  * Conditional use of sphinx-rtd-theme (same reason)
* Update `.readthedocs.yaml` to use the new install method
* Update installation instructions accordingly
* Add basic instructions to build the docs in README
By removing those almost unused extensions, the pdf build works again in
Read The Docs.
@parulin
parulin force-pushed the installable-pyproject-toml branch from 61dc170 to 9772ac2 Compare July 17, 2026 08:21
@unman

unman commented Jul 20, 2026

Copy link
Copy Markdown
Member

I think there is too much being done here, which could be spread across separate PR.
Looking at 10737, I dont think I want to introduce another level of complexity to the build. I've though carefully about this and I do not want to do it - the benefit to users is minimal.

@parulin

parulin commented Jul 20, 2026

Copy link
Copy Markdown
Contributor Author

Okay, what changes do you want to keep? The one allowing us to move to Sphinx >9.1?

Note that this PR doesn't change anything to most users. The only difference is that someone who want to create a perfect copy of the official doc website have to install an extra group of dependencies.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove duplicated dependencies in qubes-doc Make some build dependencies optional in qubes-doc

2 participants