Re: [Qemu-devel] Sphinx and docs/index.rst: dead code?

[Peter Maydell]

On Thu, 25 Jul 2019 at 18:26, John Snow <address@hidden> wrote:
> On 7/25/19 12:42 PM, Peter Maydell wrote:
> > This means you'll end up building 90% of our documentation twice,
> > which is something I was trying to avoid with the current setup.
> >
>
> Why? Wouldn't it suffice to build just one of the top-level docs just once?
>
> (I guess if you later decided to build the other top-level doc later it
> would duplicate the work, but is that the usual case?)

"make" needs to build the including-for-developers set so
you can refer to it in tree. But what we want for "make install"
is the only-for-users set. We don't want to build stuff during
"make install"; so "make" needs to have already built that set too.

The underlying problem here is that Sphinx doesn't really like
the idea of building documentation but only installing a subset.
So you get to pick which downsides you dislike least when
choosing the workaround. The current setup isn't necessarily
ideal but it seemed good-enough and to more or less match
the five-manuals approach Paolo originally outlined. We can
certainly change it if there's a less-awkward way to do things.

thanks
-- PMM