On Thu, 25 Jul 2019 at 18:26, John Snow <js...@redhat.com> 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
