On 9/30/24 19:16, John Snow wrote:
The current reality is that Sphinx 3.4.3 is our minimum because RHEL 9
offers that as the distro package and I have not dared bump our version
beyond that for fear of disrupting our ability to build docs on RHEL 9
without internet.
What I'd like to ask is: How adamant are we that we can build docs on
older platforms? Do we consider it part of our platform promise? Can we
bump Sphinx to a slightly newer version at the expense of offline doc
builds for RHEL 9?
Could we stop building QMP docs, if Sphinx is too old? While at the
same time keeping the same 3.x version and the ability to build man
pages, which is the really important part.
It should be as easy as adding a -D option to SPHINX_ARGS based on
sphinx_version in docs/meson.build; bonus points for adding a docs-qmp
feature option, like
enable_docs_qmp = get_option('docs-qmp') \
.disable_auto_if(sphinx_version.version_compare('<4')) \
.allowed()
if enable_docs_qmp
SPHINX_ARGS += ['-Ddocs_qmp=1']
endif
and for adding enable_docs_qmp to the summary. Unfortunately I don't
think -D is accessible from rST, so you'd have to check it from the
extension and put a "QMP documentation not included in this manual"
placeholder. Not great, I admit.
The current check on sphinx being 1.7 or newer is obsolute, but I won't
remove it for now so that you already have the code to compute
sphinx_version.
Paolo
To reiterate: interactive developer builds from git or source tarballs
would continue to work (and be able to build docs just fine) so long as
--enable-docs is passed, but will require an internet connection to set
up the python environment with a new-enough sphinx. RHEL 9 rpm builds of
bleeding edge QEMU may be cut off from building docs in isolated
RPMBUILD environments unless that repository backports a newer sphinx
that can be identified as a dependency in the specfile.
How much of a problem do we consider that to be?
CCing the usual suspects.
--js
