Re: [PATCH] doc: flat-table directive

[Markus Heiser]

Am 01.07.2016 um 14:58 schrieb Jonathan Corbet <corbet@xxxxxxx>:

> On Fri, 01 Jul 2016 13:44:17 +0300
> Jani Nikula <jani.nikula@xxxxxxxxx> wrote:
> 
>> This is also one of the reasons why I so much want to keep everything
>> behind one configuration file, and build everything in the Sphinx
>> toolchain. To keep it all more uniform, to not duplicate stuff, and not
>> deviate to some silos like we've done in the past. I think when we have
>> things working, we can add dedicated config files for the select few
>> things that have additional special needs. Media is probably one of
>> them. But that said, I think we should be able to keep including that to
>> the main documentation build too.
> 
> So this is mostly how I see things too.  But it might still be worth
> thinking about whether media, in particular, is special and should be
> buildable as a standalone document.  I can see there may be settings
> where only that is wanted.
> 

I dare hardly say it, but I come back to the sphinx-sub-project
solution ... don't hurt me ... listen, it is conceptual a bit 
different to what I have done first, but hopefully it is a solution
we can all live with:

* media is "special", so let's build it separate.
 
We have this Documentation/index.rst file, where we can place
all "books" in, except those which are specifically.

.. toctree::
   :maxdepth: 2

   kernel-documentation
   gpu
   ...

Folders matching Documentation/*/conf.py are build separate,
media is the one. This is exactly what my sphinx-sub-project
solution does, building books from folders with a conf.py in.
This conf.py inherits all settings from the top config in
Documentation/conf.py and overwrites only those configurations
which are different.

... could this be a solution?

... I'm a bit afraid to press the send button ... ;-)

> Some sort of "only build xxx.rst and see what explodes" makefile option
> also seems like a useful thing to have, just as a time saver for
> developers and maintainers.
> 
> jon

IMHO it is a conceptual problem:

If we assemble "books" into one project, the context of each
node in the doctree is the union. E.g. cross references from
one "book" to another will only work if the context is the union. 

No matter how we do it, but if we are building parts, the context
is reduced to this part and this will always be different to build
the union, so it could never be a entire *lint*.

-- Markus --