Re: [PATCH] doc: flat-table directive

[Jani Nikula <jani.nikula@intel.com>]

On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@darmarit.de> wrote:
> Am 01.07.2016 um 14:58 schrieb Jonathan Corbet <corbet@lwn.net>:
>
>> On Fri, 01 Jul 2016 13:44:17 +0300
>> Jani Nikula <jani.nikula@intel.com> 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 ... ;-)

Hey, the discussions can sometimes be heated, but you should never have
to worry about expressing your opinions.

You know I'm opposed to adding several configs and building things
separately. Some of the reasons are to keep things (especially the
Makefiles and configs) simple and easy for the wider audience to
understand, and to agressively promote finding generic solutions that
work for everyone. Sure, maybe this won't completely work in the end,
but it sure as hell won't work if we don't even try.

The current media DocBook docs are a prime example. There are really
great features there, but IMHO done in a really complicated way and
specifically for media documentation (sorry Mauro). I think we'd be in a
better position now if all of that had been done in a more generic way
for all the DocBook docs. So I just want to avoid that for Sphinx, now
that we have a chance for a fresh start.

>> 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*.

This is another reason why I like the "everything together" approach. I
like the cross-references from kernel-doc comments to work beyond one
subsystem. I like to have the function() and &struct style references
from GPU documentation to the kernel API and device documents just
work. AFAICT intersphinx doesn't solve this because kernel-doc has no
way of knowing where the target exists. For GPU documentation, putting
it into a silo would be giving up on the goals we had.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center