Re: [Qemu-devel] [PATCH v3 08/12] docs: Provide separate conf.py for each manual we want

[Cleber Rosa]

On Thu, Mar 07, 2019 at 12:29:08PM +0000, Peter Maydell wrote:
> On Thu, 7 Mar 2019 at 12:14, Cleber Rosa <address@hidden> wrote:
> >
> > On Thu, Mar 07, 2019 at 09:49:44AM +0000, Peter Maydell wrote:
> > > On Thu, 7 Mar 2019 at 01:40, Cleber Rosa <address@hidden> wrote:
> > > Thanks for pointing out the tags functionality. That said,
> > > this won't do what we want, will it?
> > >  * building the docs gives all the docs in the build tree
> > >  * but we only install via 'make install' the ones the user wants
> > >
> >
> > It should be doable.  I put a PoC here:
> >
> >   https://github.com/clebergnu/sphinx-conditional-project/tree/master
> >
> > I'm understanding that the `make install` step is nothing but a copy
> > of the produced build.  For this PoC, I used an HTML builder.
> 
> I'm still not clear how this helps. Either the top level
> index file has everything in it (in which case it's no good
> for 'make install'), or we just have separate manuals per

IIRC, it shouldn't matter what the "top level" index file (index.rst)
has, because it's the resulting build (not the source index.rst) that
will be 'make install'ed.  Or am I missing something?

> document (which doesn't seem to me to gain much over what
> we currently have in this patchset, and you end up listing
> everything multiple times in the index.rst).

I don't see the multiple listings you mention here, but I guess you're
referring to the "include" of the individual manual's index (devel.rst
and interop.rst in this example).  I chose to implement the logic for
choosing the content in the rst file, but an alternative would be to
do it in conf.py:

 if tags.has('devel'):
    master_doc = 'devel.rst'
 elif tags.has('interop'):
    master_doc = 'interop.rst'
 else:
    master_doc = 'index.rst'

IMO all options add a bit of poison (pick yours).  I do feel that the
tag approach reuses sphinx functionality, and thus facilitate
maintanance and minimize duplication.

Anyway, if it's not clear to you as it's to me, then I'm probably
biased or missing something.

> 
> thanks
> -- PMM

Best regards,
- Cleber.