Re: [PATCH] doc: flat-table directive

[Mauro Carvalho Chehab]

Em Fri, 01 Jul 2016 20:24:48 +0300
Jani Nikula <jani.nikula@xxxxxxxxx> escreveu:

> On Fri, 01 Jul 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
> > 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 ... ;-)  
> 
> 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).

My view is just the reverse of yours: the non-media documentation is
too simple, and has lots of gaps ;)

Anyway, the media documentation actually started out of the tree,
by the time Alan Cox were the V4L2 maintainer, as two separate documents. 
The first one written 1999 (v4l2) and the second one in 2001 (dvb).
They were merged upstream by 2006 or 2007, after several conversions
(the DVB doc were in LaTex, and the V4L2 one, were on a very old 
DocBook version).

We're doing a real hard work to keep it updated over the last 10
years, and we just don't want to throw it away and do a fresh
start. Whatever we do, we should not lost documentation nor lost
the scripts that have been working so well to enforce the docs
to keep updated as we touch on the code.

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

Having the capability of integrating with other documents is a nice
thing. However, the media uAPI book will have *very few* outside
references (right now, I can think on just one reference, at the
introduction that mentions the ALSA project - even so, maybe the
best would be to point to the ALSA project website, but, if we
decide to point to the internal ALSA docs, we could use intersphinx). 
The reason for that is simple: it describes the API from the Kernel
to userspace, and not the Kernel's internal API.

The Media Kernel's internal API is described at the media section of
the device-drivers.xml. There, references to the other Kernel-doc
documented APIs is very welcomed.

Regards,
Mauro