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

[Kevin Wolf <kwolf@redhat.com>]

Am 31.01.2022 um 19:57 hat Peter Maydell geschrieben:
> 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 :-(

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