Am 31.01.2022 um 19:57 hat Peter Maydell geschrieben: > On Mon, 31 Jan 2022 at 17:33, Kevin Wolf <kw...@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 <kw...@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
