Hi there
Even after reading our packaging doc I'm wondering what's the proper way to handle sphinx doc autogenerated from built sources.
The issue is that %build is the section where all building should be done, followed by %install and %check. Building the documentation (e.g. using sphinx autodoc) is clearly a build step, but often requires the build products, and often *installed* build products.
[I came across an upstream which even calls "pip install" from sphinx's docs/conf.py ... ]
So, what do you guys do? Build docs in %install and point py/sphinx to the installed sources? Build docs after the wheel and point py to %{pyproject_whichone_please}? I somehow cannot find a solution without failed imports being reported by sphinx.
[Yes, partly py-specific, but not totally.]
Michael
On 18. 06. 26 15:00, Michael J Gruber wrote:
Hi there
Even after reading our packaging doc I'm wondering what's the proper way to handle sphinx doc autogenerated from built sources.
The issue is that %build is the section where all building should be done, followed by %install and %check. Building the documentation (e.g. using sphinx autodoc) is clearly a build step, but often requires the build products, and often *installed* build products.
[I came across an upstream which even calls "pip install" from sphinx's docs/conf.py ... ]
So, what do you guys do? Build docs in %install and point py/sphinx to the installed sources? Build docs after the wheel and point py to %{pyproject_whichone_please}? I somehow cannot find a solution without failed imports being reported by sphinx.
I usually try to do PYTHONPATH=%{buildroot}%{_pyproject_wheeldir}/...whl -- it should work. If we need to make %{_pyproject_wheeldir} a public macro, we can.
Am Do., 18. Juni 2026 um 15:20 Uhr schrieb Miro Hrončok mhroncok@redhat.com:
On 18. 06. 26 15:00, Michael J Gruber wrote:
Hi there
Even after reading our packaging doc I'm wondering what's the proper way to handle sphinx doc autogenerated from built sources.
The issue is that %build is the section where all building should be done, followed by %install and %check. Building the documentation (e.g. using sphinx autodoc) is clearly a build step, but often requires the build products, and often *installed* build products.
[I came across an upstream which even calls "pip install" from sphinx's docs/conf.py ... ]
So, what do you guys do? Build docs in %install and point py/sphinx to the installed sources? Build docs after the wheel and point py to %{pyproject_whichone_please}? I somehow cannot find a solution without failed imports being reported by sphinx.
I usually try to do PYTHONPATH=%{buildroot}%{_pyproject_wheeldir}/...whl -- it should work. If we need to make %{_pyproject_wheeldir} a public macro, we can.
Cool, I didn't know that one can put a wheel on PYTHONPATH. Works! [FTR: %{_pyproject_wheeldir} contains %{buildroot} already.]
I'm still wondering how "bad" (policy, side-effects) building doc in %install would be, but I don't need to in this case any more.
Thanks a lot!
Michael
Michael J Gruber venit, vidit, dixit 2026-06-18 15:46:42:
Am Do., 18. Juni 2026 um 15:20 Uhr schrieb Miro Hrončok mhroncok@redhat.com:
On 18. 06. 26 15:00, Michael J Gruber wrote:
Hi there
Even after reading our packaging doc I'm wondering what's the proper way to handle sphinx doc autogenerated from built sources.
The issue is that %build is the section where all building should be done, followed by %install and %check. Building the documentation (e.g. using sphinx autodoc) is clearly a build step, but often requires the build products, and often *installed* build products.
[I came across an upstream which even calls "pip install" from sphinx's docs/conf.py ... ]
So, what do you guys do? Build docs in %install and point py/sphinx to the installed sources? Build docs after the wheel and point py to %{pyproject_whichone_please}? I somehow cannot find a solution without failed imports being reported by sphinx.
I usually try to do PYTHONPATH=%{buildroot}%{_pyproject_wheeldir}/...whl -- it should work. If we need to make %{_pyproject_wheeldir} a public macro, we can.
Cool, I didn't know that one can put a wheel on PYTHONPATH. Works! [FTR: %{_pyproject_wheeldir} contains %{buildroot} already.]
I'm still wondering how "bad" (policy, side-effects) building doc in %install would be, but I don't need to in this case any more.
Update: Works as reported for pure python wheels.
Now, with a wheel that has swig bindings and some so in it (_capi.abi3.so for notmuch2), there's a problem:
ImportError: cannot import name '_capi' from partially initialized module 'notmuch2' (most likely due to a circular import)
No, it's not circular. Oh well. But things are a bit messy for that mixed package anyways.
Michael
On 23. 06. 26 18:04, Michael J Gruber wrote:
Michael J Gruber venit, vidit, dixit 2026-06-18 15:46:42:
Am Do., 18. Juni 2026 um 15:20 Uhr schrieb Miro Hrončok mhroncok@redhat.com:
On 18. 06. 26 15:00, Michael J Gruber wrote:
Hi there
Even after reading our packaging doc I'm wondering what's the proper way to handle sphinx doc autogenerated from built sources.
The issue is that %build is the section where all building should be done, followed by %install and %check. Building the documentation (e.g. using sphinx autodoc) is clearly a build step, but often requires the build products, and often *installed* build products.
[I came across an upstream which even calls "pip install" from sphinx's docs/conf.py ... ]
So, what do you guys do? Build docs in %install and point py/sphinx to the installed sources? Build docs after the wheel and point py to %{pyproject_whichone_please}? I somehow cannot find a solution without failed imports being reported by sphinx.
I usually try to do PYTHONPATH=%{buildroot}%{_pyproject_wheeldir}/...whl -- it should work. If we need to make %{_pyproject_wheeldir} a public macro, we can.
Cool, I didn't know that one can put a wheel on PYTHONPATH. Works! [FTR: %{_pyproject_wheeldir} contains %{buildroot} already.]
I'm still wondering how "bad" (policy, side-effects) building doc in %install would be, but I don't need to in this case any more.
Update: Works as reported for pure python wheels.
Oh, I forgot to mention that. Pure Python only. And packages that access data files on runtime by direct file access rather than importlib.resourecs also tend to blow up.
-
Michael J Gruber -
Miro Hrončok