docs: Don't document disabled features
cover docs: Don't document disabled features
It was reported that it's confusing that the QEMU man page contains documentation of features that aren't even available in the build because they were disabled during configure.
This series makes documentation for some block drivers conditional so that it is only included in the man page (and other documentation) when the feature is actually available in the build.
Kevin Wolf (5):
docs: Pass disabled configure options to sphinx
docs: Only mention iscsi in the man page when available
docs: Only mention ssh in the man page when available
docs: Only mention curl in the man page when available
docs: Only mention gluster in the man page when available
docs/meson.build | 10 + docs/system/device-url-syntax.rst.inc | 252 +++++++++++++------------- qemu-options.hx | 9 +- 3 files changed, 146 insertions(+), 125 deletions(-)
Signature · 1 line
2.31.1
PATCH 1/5 docs: Pass disabled configure options to sphinx
Man pages and other documentation should only contain things that are actually available in this build. In order to conditionally build documentation depending on the build configuration, pass the configuration to sphinx as tags.
The tags are negative so that building documentation from outside of meson (in particular for things like readthedocs) without any tags set results in the full documentation rather than disabling everything that is optional.
--- docs/meson.build | 10 ++++++++++ 1 file changed, 10 insertions(+)
docs/meson.build +10 -0
@@ -37,6 +37,16 @@ endif if build_docs SPHINX_ARGS += ['-Dversion=' + meson.project_version(), '-Drelease=' + config_host['PKGVERSION']] + foreach key: config_host_data.keys() + if not key.startswith('CONFIG_') + continue + endif + if '@0@'.format(config_host_data.get(key)) in ['0', 'false'] + tag = 'DISABLE_' + key.substring(7) + SPHINX_ARGS += ['-t', tag] + endif + endforeach + have_ga = have_tools and config_host.has_key('CONFIG_GUEST_AGENT') man_pages = {
Signature · 1 line
2.31.1
Re: [PATCH 1/5] docs: Pass disabled configure options to sphinx
Quoted 9 lines · Kevin Wolf
Man pages and other documentation should only contain things that are actually available in this build. In order to conditionally build documentation depending on the build configuration, pass the configuration to sphinx as tags.
The tags are negative so that building documentation from outside of meson (in particular for things like readthedocs) without any tags set results in the full documentation rather than disabling everything that is optional.
IMHO if we're building in upstream CI we should have a way to explicitly force inclusion of /all/ docs, because we don't want docs published from CI to be missing features just because we happen to not have the deps enabled.
Quoted 31 lines
Signed-off-by Kevin Wolf <[email protected]>--- docs/meson.build | 10 ++++++++++ 1 file changed, 10 insertions(+)docs/meson.build +10
-0@@ -37,6 +37,16 @@ endif if build_docs SPHINX_ARGS += ['-Dversion=' + meson.project_version(), '-Drelease=' + config_host['PKGVERSION']] + foreach key: config_host_data.keys() + if not key.startswith('CONFIG_') + continue + endif + if '@0@'.format(config_host_data.get(key)) in ['0', 'false'] + tag = 'DISABLE_' + key.substring(7) + SPHINX_ARGS += ['-t', tag] + endif + endforeach + have_ga = have_tools and config_host.has_key('CONFIG_GUEST_AGENT') man_pages = {Signature · 1 line
2.31.1
Regards,
Daniel
Signature · 3 lines
|: https://berrange.com -o- https://www.flickr.com/photos/dberrange :| |: https://libvirt.org -o- https://fstop138.berrange.com :| |: https://entangle-photo.org -o- https://www.instagram.com/dberrange :|
PATCH 2/5 docs: Only mention iscsi in the man page when available
In reply to Kevin WolfIf libiscsi is disabled in the build, the man page shouldn't contain information on how to construct iscsi URLs etc.
This patch is best viewed with whitespace changes ignored.
--- docs/system/device-url-syntax.rst.inc | 60 ++++++++++++++------------- qemu-options.hx | 9 ++-- 2 files changed, 37 insertions(+), 32 deletions(-)
docs/system/device-url-syntax.rst.inc +31 -29
@@ -1,47 +1,49 @@ In addition to using normal file images for the emulated storage -devices, QEMU can also use networked resources such as iSCSI devices. -These are specified using a special URL syntax. +devices, QEMU can also use networked resources. These are specified using a +special URL syntax. -``iSCSI`` - iSCSI support allows QEMU to access iSCSI resources directly and use - as images for the guest storage. Both disk and cdrom images are - supported. +.. only:: not DISABLE_LIBISCSI - Syntax for specifying iSCSI LUNs is - "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>" + ``iSCSI`` + iSCSI support allows QEMU to access iSCSI resources directly and use + as images for the guest storage. Both disk and cdrom images are + supported. - By default qemu will use the iSCSI initiator-name - 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from - the command line or a configuration file. + Syntax for specifying iSCSI LUNs is + "iscsi://<target-ip>[:<port>]/<target-iqn>/<lun>" - Since version QEMU 2.4 it is possible to specify a iSCSI request - timeout to detect stalled requests and force a reestablishment of the - session. The timeout is specified in seconds. The default is 0 which - means no timeout. Libiscsi 1.15.0 or greater is required for this - feature. + By default qemu will use the iSCSI initiator-name + 'iqn.2008-11.org.linux-kvm[:<name>]' but this can also be set from + the command line or a configuration file. - Example (without authentication): + Since version QEMU 2.4 it is possible to specify a iSCSI request + timeout to detect stalled requests and force a reestablishment of the + session. The timeout is specified in seconds. The default is 0 which + means no timeout. Libiscsi 1.15.0 or greater is required for this + feature. - .. parsed-literal:: + Example (without authentication): - |qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \\ - -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \\ - -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 + .. parsed-literal:: - Example (CHAP username/password via URL): + |qemu_system| -iscsi initiator-name=iqn.2001-04.com.example:my-initiator \\ + -cdrom iscsi://192.0.2.1/iqn.2001-04.com.example/2 \\ + -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 - .. parsed-literal:: + Example (CHAP username/password via URL): - |qemu_system| -drive file=iscsi://user%[email protected]/iqn.2001-04.com.example/1 + .. parsed-literal:: - Example (CHAP username/password via environment variables): + |qemu_system| -drive file=iscsi://user%[email protected]/iqn.2001-04.com.example/1 - .. parsed-literal:: + Example (CHAP username/password via environment variables): + + .. parsed-literal:: - LIBISCSI_CHAP_USERNAME="user" \\ - LIBISCSI_CHAP_PASSWORD="password" \\ - |qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 + LIBISCSI_CHAP_USERNAME="user" \\ + LIBISCSI_CHAP_PASSWORD="password" \\ + |qemu_system| -drive file=iscsi://192.0.2.1/iqn.2001-04.com.example/1 ``NBD`` QEMU supports NBD (Network Block Devices) both using TCP protocol as
qemu-options.hx +6 -3
@@ -1363,7 +1363,7 @@ SRST If the filename contains comma, you must double it (for instance, "file=my,,file" to use file "my,file"). - Special files such as iSCSI devices can be specified using + Special files such as for network protocols can be specified using protocol specific URLs. See the section for "Device URL Syntax" for more information.
@@ -1831,8 +1831,11 @@ DEF("iscsi", HAS_ARG, QEMU_OPTION_iscsi, " iSCSI session parameters\n", QEMU_ARCH_ALL) SRST -``-iscsi`` - Configure iSCSI session parameters. + +.. only:: not DISABLE_LIBISCSI + + ``-iscsi`` + Configure iSCSI session parameters. ERST DEFHEADING()
Signature · 1 line
2.31.1
Re: [PATCH 2/5] docs: Only mention iscsi in the man page when available
Quoted 10 lines · Kevin Wolf
If libiscsi is disabled in the build, the man page shouldn't contain information on how to construct iscsi URLs etc.
This patch is best viewed with whitespace changes ignored.
Signed-off-by Kevin Wolf <[email protected]>---
-``iSCSI``
docs/system/device-url-syntax.rst.inc line 6
Quoted 4 lines
docs/system/device-url-syntax.rst.inc +1
-3- iSCSI support allows QEMU to access iSCSI resources directly and use - as images for the guest storage. Both disk and cdrom images are - supported. +.. only:: not DISABLE_LIBISCSI
Unfortunately the Sphinx "only::" tag is unusably broken by design. It doesn't work the way you might expect (similar to ifdef, making the docs be built as if the markup disabled by only:: was not present in the source rst files). Instead it filters out generated doctree nodes very late. The effect is that documentation that you try to suppress with an 'only' directive will still show up in the table of contents, index and search.
Upstream bug, closed 'wontfix':
https://github.com/sphinx-doc/sphinx/issues/1420
I ran into this when I was looking at whether there were nicer ways to structure how we generate some of our manpages etc. Unfortunately my conclusion was that the only safe approach was to avoid use of the 'only::' directive entirely :-(
thanks
-- PMM
Re: [PATCH 2/5] docs: Only mention iscsi in the man page when available
Am 31.01.2022 um 19:57 hat Peter Maydell geschrieben:
Quoted 24 lines · Kevin Wolf
Quoted 10 lines
If libiscsi is disabled in the build, the man page shouldn't contain information on how to construct iscsi URLs etc.
This patch is best viewed with whitespace changes ignored.
Signed-off-by Kevin Wolf <[email protected]>---
-``iSCSI``
docs/system/device-url-syntax.rst.inc line 6
Quoted 4 lines
docs/system/device-url-syntax.rst.inc +1
-3- iSCSI support allows QEMU to access iSCSI resources directly and use - as images for the guest storage. Both disk and cdrom images are - supported. +.. only:: not DISABLE_LIBISCSIUnfortunately the Sphinx "only::" tag is unusably broken by design. It doesn't work the way you might expect (similar to ifdef, making the docs be built as if the markup disabled by only:: was not present in the source rst files). Instead it filters out generated doctree nodes very late. The effect is that documentation that you try to suppress with an 'only' directive will still show up in the table of contents, index and search.
Quoted 7 lines
Upstream bug, closed 'wontfix':
https://github.com/sphinx-doc/sphinx/issues/1420I ran into this when I was looking at whether there were nicer ways to structure how we generate some of our manpages etc. Unfortunately my conclusion was that the only safe approach was to avoid use of the 'only::' directive entirely :-(
Hm, that's very disappointing. :-(
Does it affect anything that is used in man pages, though? Otherwise I guess we could have something like ::only (not man) or (not DISABLE*) to make things conditional at least in the man pages even if we can't in HTML.
Or I guess the alternative would be manually preprocessing docs (maybe even just with cpp) before feeding them to sphinx...
In fact, a large part of the man pages is already preprocessed by hxtool. But obviously, the changes I make in this patch are outside of it for the most part.
Kevin
PATCH 3/5 docs: Only mention ssh in the man page when available
In reply to Kevin WolfIf libssh is disabled in the build, the man page shouldn't contain information on how to use the ssh block driver.
This patch is best viewed with whitespace changes ignored.
--- docs/system/device-url-syntax.rst.inc | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-)
docs/system/device-url-syntax.rst.inc +10 -8
@@ -74,18 +74,20 @@ special URL syntax. |qemu_system| --drive file=nbd:unix:/tmp/nbd-socket -``SSH`` - QEMU supports SSH (Secure Shell) access to remote disks. +.. only:: not DISABLE_LIBSSH - Examples: + ``SSH`` + QEMU supports SSH (Secure Shell) access to remote disks. - .. parsed-literal:: + Examples: + + .. parsed-literal:: - |qemu_system| -drive file=ssh://user@host/path/to/disk.img - |qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img + |qemu_system| -drive file=ssh://user@host/path/to/disk.img + |qemu_system| -drive file.driver=ssh,file.user=user,file.host=host,file.port=22,file.path=/path/to/disk.img - Currently authentication must be done using ssh-agent. Other - authentication methods may be supported in future. + Currently authentication must be done using ssh-agent. Other + authentication methods may be supported in future. ``GlusterFS`` GlusterFS is a user space distributed file system. QEMU supports the
Signature · 1 line
2.31.1
PATCH 4/5 docs: Only mention curl in the man page when available
In reply to Kevin WolfIf curl is disabled in the build, the man page shouldn't contain information on how to use the curl block drivers.
This patch is best viewed with whitespace changes ignored.
--- docs/system/device-url-syntax.rst.inc | 114 +++++++++++++------------- 1 file changed, 58 insertions(+), 56 deletions(-)
docs/system/device-url-syntax.rst.inc +58 -56
@@ -128,87 +128,89 @@ special URL syntax. See also http://www.gluster.org. -``HTTP/HTTPS/FTP/FTPS`` - QEMU supports read-only access to files accessed over http(s) and - ftp(s). +.. only:: not DISABLE_CURL - Syntax using a single filename: + ``HTTP/HTTPS/FTP/FTPS`` + QEMU supports read-only access to files accessed over http(s) and + ftp(s). - :: + Syntax using a single filename: - <protocol>://[<username>[:<password>]@]<host>/<path> + :: - where: + <protocol>://[<username>[:<password>]@]<host>/<path> - ``protocol`` - 'http', 'https', 'ftp', or 'ftps'. + where: - ``username`` - Optional username for authentication to the remote server. + ``protocol`` + 'http', 'https', 'ftp', or 'ftps'. - ``password`` - Optional password for authentication to the remote server. + ``username`` + Optional username for authentication to the remote server. - ``host`` - Address of the remote server. + ``password`` + Optional password for authentication to the remote server. - ``path`` - Path on the remote server, including any query string. + ``host`` + Address of the remote server. - The following options are also supported: + ``path`` + Path on the remote server, including any query string. - ``url`` - The full URL when passing options to the driver explicitly. + The following options are also supported: - ``readahead`` - The amount of data to read ahead with each range request to the - remote server. This value may optionally have the suffix 'T', 'G', - 'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be - assumed to be in bytes. The value must be a multiple of 512 bytes. - It defaults to 256k. + ``url`` + The full URL when passing options to the driver explicitly. - ``sslverify`` - Whether to verify the remote server's certificate when connecting - over SSL. It can have the value 'on' or 'off'. It defaults to - 'on'. + ``readahead`` + The amount of data to read ahead with each range request to the + remote server. This value may optionally have the suffix 'T', 'G', + 'M', 'K', 'k' or 'b'. If it does not have a suffix, it will be + assumed to be in bytes. The value must be a multiple of 512 bytes. + It defaults to 256k. - ``cookie`` - Send this cookie (it can also be a list of cookies separated by - ';') with each outgoing request. Only supported when using - protocols such as HTTP which support cookies, otherwise ignored. + ``sslverify`` + Whether to verify the remote server's certificate when connecting + over SSL. It can have the value 'on' or 'off'. It defaults to + 'on'. - ``timeout`` - Set the timeout in seconds of the CURL connection. This timeout is - the time that CURL waits for a response from the remote server to - get the size of the image to be downloaded. If not set, the - default timeout of 5 seconds is used. + ``cookie`` + Send this cookie (it can also be a list of cookies separated by + ';') with each outgoing request. Only supported when using + protocols such as HTTP which support cookies, otherwise ignored. - Note that when passing options to qemu explicitly, ``driver`` is the - value of <protocol>. + ``timeout`` + Set the timeout in seconds of the CURL connection. This timeout is + the time that CURL waits for a response from the remote server to + get the size of the image to be downloaded. If not set, the + default timeout of 5 seconds is used. - Example: boot from a remote Fedora 20 live ISO image + Note that when passing options to qemu explicitly, ``driver`` is the + value of <protocol>. - .. parsed-literal:: + Example: boot from a remote Fedora 20 live ISO image - |qemu_system_x86| --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly + .. parsed-literal:: - |qemu_system_x86| --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly + |qemu_system_x86| --drive media=cdrom,file=https://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly - Example: boot from a remote Fedora 20 cloud image using a local - overlay for writes, copy-on-read, and a readahead of 64k + |qemu_system_x86| --drive media=cdrom,file.driver=http,file.url=http://archives.fedoraproject.org/pub/fedora/linux/releases/20/Live/x86_64/Fedora-Live-Desktop-x86_64-20-1.iso,readonly - .. parsed-literal:: + Example: boot from a remote Fedora 20 cloud image using a local + overlay for writes, copy-on-read, and a readahead of 64k - qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 + .. parsed-literal:: - |qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on + qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"http",, "file.url":"http://archives.fedoraproject.org/pub/archive/fedora/linux/releases/20/Images/x86_64/Fedora-x86_64-20-20131211.1-sda.qcow2",, "file.readahead":"64k"}' /tmp/Fedora-x86_64-20-20131211.1-sda.qcow2 - Example: boot from an image stored on a VMware vSphere server with a - self-signed certificate using a local overlay for writes, a readahead - of 64k and a timeout of 10 seconds. + |qemu_system_x86| -drive file=/tmp/Fedora-x86_64-20-20131211.1-sda.qcow2,copy-on-read=on - .. parsed-literal:: + Example: boot from an image stored on a VMware vSphere server with a + self-signed certificate using a local overlay for writes, a readahead + of 64k and a timeout of 10 seconds. + + .. parsed-literal:: - qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:[email protected]/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2 + qemu-img create -f qcow2 -o backing_file='json:{"file.driver":"https",, "file.url":"https://user:[email protected]/folder/test/test-flat.vmdk?dcPath=Datacenter&dsName=datastore1",, "file.sslverify":"off",, "file.readahead":"64k",, "file.timeout":10}' /tmp/test.qcow2 - |qemu_system_x86| -drive file=/tmp/test.qcow2 + |qemu_system_x86| -drive file=/tmp/test.qcow2
Signature · 1 line
2.31.1
PATCH 5/5 docs: Only mention gluster in the man page when available
In reply to Kevin WolfIf gluster is disabled in the build, the man page shouldn't contain information on how to use the gluster block driver.
This patch is best viewed with whitespace changes ignored.
--- docs/system/device-url-syntax.rst.inc | 64 ++++++++++++++------------- 1 file changed, 33 insertions(+), 31 deletions(-)
docs/system/device-url-syntax.rst.inc +33 -31
@@ -89,44 +89,46 @@ special URL syntax. Currently authentication must be done using ssh-agent. Other authentication methods may be supported in future. -``GlusterFS`` - GlusterFS is a user space distributed file system. QEMU supports the - use of GlusterFS volumes for hosting VM disk images using TCP, Unix - Domain Sockets and RDMA transport protocols. +.. only:: not DISABLE_GLUSTERFS - Syntax for specifying a VM disk image on GlusterFS volume is + ``GlusterFS`` + GlusterFS is a user space distributed file system. QEMU supports the + use of GlusterFS volumes for hosting VM disk images using TCP, Unix + Domain Sockets and RDMA transport protocols. - .. parsed-literal:: + Syntax for specifying a VM disk image on GlusterFS volume is - URI: - gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...] + .. parsed-literal:: - JSON: - 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...", - "server":[{"type":"tcp","host":"...","port":"..."}, - {"type":"unix","socket":"..."}]}}' + URI: + gluster[+type]://[host[:port]]/volume/path[?socket=...][,debug=N][,logfile=...] - Example + JSON: + 'json:{"driver":"qcow2","file":{"driver":"gluster","volume":"testvol","path":"a.img","debug":N,"logfile":"...", + "server":[{"type":"tcp","host":"...","port":"..."}, + {"type":"unix","socket":"..."}]}}' - .. parsed-literal:: + Example + + .. parsed-literal:: - URI: - |qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img, - file.debug=9,file.logfile=/var/log/qemu-gluster.log - - JSON: - |qemu_system| 'json:{"driver":"qcow2", - "file":{"driver":"gluster", - "volume":"testvol","path":"a.img", - "debug":9,"logfile":"/var/log/qemu-gluster.log", - "server":[{"type":"tcp","host":"1.2.3.4","port":24007}, - {"type":"unix","socket":"/var/run/glusterd.socket"}]}}' - |qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, - file.debug=9,file.logfile=/var/log/qemu-gluster.log, - file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, - file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket - - See also http://www.gluster.org. + URI: + |qemu_system| --drive file=gluster://192.0.2.1/testvol/a.img, + file.debug=9,file.logfile=/var/log/qemu-gluster.log + + JSON: + |qemu_system| 'json:{"driver":"qcow2", + "file":{"driver":"gluster", + "volume":"testvol","path":"a.img", + "debug":9,"logfile":"/var/log/qemu-gluster.log", + "server":[{"type":"tcp","host":"1.2.3.4","port":24007}, + {"type":"unix","socket":"/var/run/glusterd.socket"}]}}' + |qemu_system| -drive driver=qcow2,file.driver=gluster,file.volume=testvol,file.path=/path/a.img, + file.debug=9,file.logfile=/var/log/qemu-gluster.log, + file.server.0.type=tcp,file.server.0.host=1.2.3.4,file.server.0.port=24007, + file.server.1.type=unix,file.server.1.socket=/var/run/glusterd.socket + + See also http://www.gluster.org. .. only:: not DISABLE_CURL
Signature · 1 line
2.31.1