Re: [PATCH 2/5] docs: Only mention iscsi in the man page when available

[Peter Maydell <peter.maydell@linaro.org>]

On Mon, 31 Jan 2022 at 17:33, Kevin Wolf <kwolf@redhat.com> wrote:
>
> 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 <kwolf@redhat.com>
> ---

> -``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

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