Getting Sphinx to ignore manpage-only files when generating HTML, and vice-versa

[Peter Maydell]

Hi; we use Sphinx in QEMU to produce both:
* one big HTML manual (starting from the index.rst master_doc)
* some manpages (starting from the rst files listed in man_pages)

The manpages are generated from manpage-specific .rst files,
so that they can (a) include only a specific subset of the info
in the full HTML manual and (b) include manpage-only text (like
a "see also: our HTML documentation" section).

This generally works, but the HTML manual builder seems to produce
html files for the manpage-specific .rst files, even though those
.rst files are only referenced in the man_pages config file and are
not accessible from the master_doc index.rst.

How can I get Sphinx to ignore the manpage documents when producing
HTML, and vice-versa? Ideally I would like:

(a) when building HTML, Sphinx should only process rst files
reachable from index.rst
(b) when building manpages, Sphinx should only process rst files
reachable from the documents listed in man_pages
(c) ideally, Sphinx should warn about rst files not reachable from
either of the above two places

As well as having bogus extra .html files, it's also possible to
get warnings about "duplicate labels" if an HTML-only rst file
and a manpage-only rst file happen to use the same label, even though
no output should ever use both rst files.

(I tried putting the manpages rst files into exclude_patterns. This
makes the HTML generation ignore them, but Sphinx panics when you
ask it to build the manpages.)

thanks
-- PMM