Hi; I'm trying to convert some documentation to Sphinx, and I'm running into an issue where I'd like to have a bit of the input that's only handled when we're producing a manpage, not when doing HTML.
At first glance it looks like the ".. only::' directive ought to work, but it doesn't do the right thing. Specifically, I'd like to emit the 'Synopsis' and 'Description' headings in the manpage, but leave them out of the HTML. Here's the version without only:: (I use ===begin===/===endit=== markers to delimit the .rst in this email): ===begin=== QEMU block drivers reference ============================ Synopsis -------- QEMU block driver reference manual Description ----------- Disk image file formats ^^^^^^^^^^^^^^^^^^^^^^^ Some text here. ===endit=== This works as I expect -- Sphinx's manpage output has the 'SYNOPSIS' and 'DESCRIPTION' top level headings as '.SH' man commands, and the next-level-down 'Disk image file formats' as a '.SS' (and in mixed-case rather than all-caps). Now if I use only:: to put those parts in the manpage but skip the HTML: ===begin=== QEMU block drivers reference ============================ .. only:: man Synopsis -------- QEMU block driver reference manual Description ----------- Disk image file formats ^^^^^^^^^^^^^^^^^^^^^^^ Some text here. ===endit=== the HTML does indeed look better, but the manpage output has changed! The "Disk image file formats" line is no longer .SS mixed-case, but has ended up as .SH and upper-case. This is unexpected to me -- surely an 'only' directive whose condition passes should not change output ? This issue (closed 'wontfix' last May) https://github.com/sphinx-doc/sphinx/issues/1420 is sort of similar in describing a different situation where the 'only' directive fails to act as "just ignore this lump of the input", and a comment says this is because the directive is dealt with as a post-filter rather than early in the handling of the input file. How can I achieve what I'm trying to do? Some sort of facility for the equivalent of #ifdef BUILDER_MAN that really just did do textual substitution at a very early stage would be handy, but it looks like Sphinx doesn't have that? (I'm using sphinx-build 1.7.5.) thanks -- PMM -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/CAFEAcA-Bqv%2BA2ipdvJGQPh_QHO4PTbC-0oSpVXOAFm855EmdbA%40mail.gmail.com.
