[v2,2/2] Documentation/sphinx: link dma-buf rsts
diff mbox

Message ID 1471878705-3963-3-git-send-email-sumit.semwal@linaro.org
State New
Headers show

Commit Message

Sumit Semwal Aug. 22, 2016, 3:11 p.m. UTC
Include dma-buf sphinx documentation into top level index.

Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>
---
 Documentation/index.rst | 2 ++
 1 file changed, 2 insertions(+)

Comments

Mauro Carvalho Chehab Aug. 22, 2016, 3:49 p.m. UTC | #1
Em Mon, 22 Aug 2016 20:41:45 +0530
Sumit Semwal <sumit.semwal@linaro.org> escreveu:

> Include dma-buf sphinx documentation into top level index.
> 
> Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>
> ---
>  Documentation/index.rst | 2 ++
>  1 file changed, 2 insertions(+)
> 
> diff --git a/Documentation/index.rst b/Documentation/index.rst
> index e0fc72963e87..8d05070122c2 100644
> --- a/Documentation/index.rst
> +++ b/Documentation/index.rst
> @@ -14,6 +14,8 @@ Contents:
>     :maxdepth: 2
>  
>     kernel-documentation
> +   dma-buf/intro
> +   dma-buf/guide
>     media/media_uapi
>     media/media_kapi
>     media/dvb-drivers/index

IMHO, the best would be, instead, to add an index with a toctree
with both intro and guide, and add dma-buf/index instead.

We did that for media too (patches not merged upstream yet), together
with a patchset that will allow building just a subset of the books.

Regards,
Mauro

PS.: That's the content of our index.rst file, at
Documentation/media/index.rst:

Linux Media Subsystem Documentation
===================================

Contents:

.. toctree::
   :maxdepth: 2

   media_uapi
   media_kapi
   dvb-drivers/index
   v4l-drivers/index

.. only::  subproject

   Indices
   =======

   * :ref:`genindex`


Thanks,
Mauro
Daniel Vetter Aug. 23, 2016, 6:01 a.m. UTC | #2
On Mon, Aug 22, 2016 at 12:49:30PM -0300, Mauro Carvalho Chehab wrote:
> Em Mon, 22 Aug 2016 20:41:45 +0530
> Sumit Semwal <sumit.semwal@linaro.org> escreveu:
> 
> > Include dma-buf sphinx documentation into top level index.
> > 
> > Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>
> > ---
> >  Documentation/index.rst | 2 ++
> >  1 file changed, 2 insertions(+)
> > 
> > diff --git a/Documentation/index.rst b/Documentation/index.rst
> > index e0fc72963e87..8d05070122c2 100644
> > --- a/Documentation/index.rst
> > +++ b/Documentation/index.rst
> > @@ -14,6 +14,8 @@ Contents:
> >     :maxdepth: 2
> >  
> >     kernel-documentation
> > +   dma-buf/intro
> > +   dma-buf/guide
> >     media/media_uapi
> >     media/media_kapi
> >     media/dvb-drivers/index
> 
> IMHO, the best would be, instead, to add an index with a toctree
> with both intro and guide, and add dma-buf/index instead.
> 
> We did that for media too (patches not merged upstream yet), together
> with a patchset that will allow building just a subset of the books.

I'm also not too sure about whether dma-buf really should be it's own
subdirectory. It's plucked from the device-drivers.tmpl, I think an
overall device-drivers/ for all the misc subsystems and support code would
be better. Then one toc there, which fans out to either kernel-doc and
overview docs.
-Daniel

> 
> Regards,
> Mauro
> 
> PS.: That's the content of our index.rst file, at
> Documentation/media/index.rst:
> 
> Linux Media Subsystem Documentation
> ===================================
> 
> Contents:
> 
> .. toctree::
>    :maxdepth: 2
> 
>    media_uapi
>    media_kapi
>    dvb-drivers/index
>    v4l-drivers/index
> 
> .. only::  subproject
> 
>    Indices
>    =======
> 
>    * :ref:`genindex`
> 
> 
> Thanks,
> Mauro
> _______________________________________________
> dri-devel mailing list
> dri-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/dri-devel
Markus Heiser Aug. 23, 2016, 9:20 a.m. UTC | #3
Am 23.08.2016 um 08:01 schrieb Daniel Vetter <daniel@ffwll.ch>:

> On Mon, Aug 22, 2016 at 12:49:30PM -0300, Mauro Carvalho Chehab wrote:
>> Em Mon, 22 Aug 2016 20:41:45 +0530
>> Sumit Semwal <sumit.semwal@linaro.org> escreveu:
>> 
>>> Include dma-buf sphinx documentation into top level index.
>>> 
>>> Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org>
>>> ---
>>> Documentation/index.rst | 2 ++
>>> 1 file changed, 2 insertions(+)
>>> 
>>> diff --git a/Documentation/index.rst b/Documentation/index.rst
>>> index e0fc72963e87..8d05070122c2 100644
>>> --- a/Documentation/index.rst
>>> +++ b/Documentation/index.rst
>>> @@ -14,6 +14,8 @@ Contents:
>>>    :maxdepth: 2
>>> 
>>>    kernel-documentation
>>> +   dma-buf/intro
>>> +   dma-buf/guide
>>>    media/media_uapi
>>>    media/media_kapi
>>>    media/dvb-drivers/index
>> 
>> IMHO, the best would be, instead, to add an index with a toctree
>> with both intro and guide, and add dma-buf/index instead.
>> 
>> We did that for media too (patches not merged upstream yet), together
>> with a patchset that will allow building just a subset of the books.

Since 606b9ac, one more *pro* of a index.rst file in a sub-folder is,
that you can reduce your roundtrips. Add a conf.py to your subfolder
and compile only your sub-folder with e.g.

  make SPHINXDIRS="dma-buf" htmldocs

* http://git.kernel.org/cgit/linux/kernel/git/next/linux-next.git/commit/?id=606b9ac81a63ab3adb7e61206b9ae34ee186a89d

One / the example (Mauro mentioned) is media commit b32feba

* http://git.kernel.org/cgit/linux/kernel/git/next/linux-next.git/commit/?id=b32febad77068b4a28daf7b7e063438d0cca8a42

> I'm also not too sure about whether dma-buf really should be it's own
> subdirectory. It's plucked from the device-drivers.tmpl, I think an
> overall device-drivers/ for all the misc subsystems and support code would
> be better.

If the sub-folder named 'device-drivers' use:
 
  make SPHINXDIRS="device-drivers" htmldocs

-- Markus --


> Then one toc there, which fans out to either kernel-doc and
> overview docs.
> -Daniel
> 
>> 
>> Regards,
>> Mauro
>> 
>> PS.: That's the content of our index.rst file, at
>> Documentation/media/index.rst:
>> 
>> Linux Media Subsystem Documentation
>> ===================================
>> 
>> Contents:
>> 
>> .. toctree::
>>   :maxdepth: 2
>> 
>>   media_uapi
>>   media_kapi
>>   dvb-drivers/index
>>   v4l-drivers/index
>> 
>> .. only::  subproject
>> 
>>   Indices
>>   =======
>> 
>>   * :ref:`genindex`
>> 
>> 
>> Thanks,
>> Mauro
>> _______________________________________________
>> dri-devel mailing list
>> dri-devel@lists.freedesktop.org
>> https://lists.freedesktop.org/mailman/listinfo/dri-devel
> 
> -- 
> Daniel Vetter
> Software Engineer, Intel Corporation
> http://blog.ffwll.ch
Jonathan Corbet Aug. 23, 2016, 1:08 p.m. UTC | #4
On Tue, 23 Aug 2016 08:01:35 +0200
Daniel Vetter <daniel@ffwll.ch> wrote:

> I'm also not too sure about whether dma-buf really should be it's own
> subdirectory. It's plucked from the device-drivers.tmpl, I think an
> overall device-drivers/ for all the misc subsystems and support code would
> be better. Then one toc there, which fans out to either kernel-doc and
> overview docs.

I'm quite convinced it shouldn't be.

If you get a chance, could you have a look at the "RFC: The beginning of
a proper driver-api book" series I posted yesterday (yes, I should have
copied more of you, sorry)?  It shows the direction I would like to go
with driver API documentation, and, assuming we go that way, I'd like the
dma-buf documentation to fit into that.

Thanks,

jon
Daniel Vetter Aug. 23, 2016, 1:28 p.m. UTC | #5
On Tue, Aug 23, 2016 at 3:08 PM, Jonathan Corbet <corbet@lwn.net> wrote:
> On Tue, 23 Aug 2016 08:01:35 +0200
> Daniel Vetter <daniel@ffwll.ch> wrote:
>
>> I'm also not too sure about whether dma-buf really should be it's own
>> subdirectory. It's plucked from the device-drivers.tmpl, I think an
>> overall device-drivers/ for all the misc subsystems and support code would
>> be better. Then one toc there, which fans out to either kernel-doc and
>> overview docs.
>
> I'm quite convinced it shouldn't be.
>
> If you get a chance, could you have a look at the "RFC: The beginning of
> a proper driver-api book" series I posted yesterday (yes, I should have
> copied more of you, sorry)?  It shows the direction I would like to go
> with driver API documentation, and, assuming we go that way, I'd like the
> dma-buf documentation to fit into that.

Looks real pretty, ack on that. And we can always split up more, e.g.
by extracting dma-buf.rst (and merg the current dma-buffer-sharing.txt
into that one).

I think the more interesting story is, what's your plan with all the
other driver related subsystem? Especially the ones which already have
full directories of their own, like e.g. Documentation/gpio/. I think
those should be really part of the infrastructure section (or
something equally high-level), together with other awesome servies
like pwm, regman, irqchip, ... And then there's also the large-scale
subsystems like media or gpu. What's the plan to tie them all
together? Personally I'm leaning towards keeping the existing
directories (where they exist already), but inserting links into the
overall driver-api section.
-Daniel
Sumit Semwal Aug. 23, 2016, 1:33 p.m. UTC | #6
Hi Jon,

On 23 August 2016 at 18:38, Jonathan Corbet <corbet@lwn.net> wrote:
> On Tue, 23 Aug 2016 08:01:35 +0200
> Daniel Vetter <daniel@ffwll.ch> wrote:
>
>> I'm also not too sure about whether dma-buf really should be it's own
>> subdirectory. It's plucked from the device-drivers.tmpl, I think an
>> overall device-drivers/ for all the misc subsystems and support code would
>> be better. Then one toc there, which fans out to either kernel-doc and
>> overview docs.
>
> I'm quite convinced it shouldn't be.
>
> If you get a chance, could you have a look at the "RFC: The beginning of
> a proper driver-api book" series I posted yesterday (yes, I should have
> copied more of you, sorry)?  It shows the direction I would like to go
> with driver API documentation, and, assuming we go that way, I'd like the
> dma-buf documentation to fit into that.
>

Thanks for your comments, and direction. I'll rework the patches on
top of yours then.
I'll have a look at your patches to think about how do we handle API
guides / detailed documentation as well.

> Thanks,
>
> jon

Best,
Sumit.
Jonathan Corbet Aug. 23, 2016, 2:16 p.m. UTC | #7
On Tue, 23 Aug 2016 15:28:55 +0200
Daniel Vetter <daniel@ffwll.ch> wrote:

> I think the more interesting story is, what's your plan with all the
> other driver related subsystem? Especially the ones which already have
> full directories of their own, like e.g. Documentation/gpio/. I think
> those should be really part of the infrastructure section (or
> something equally high-level), together with other awesome servies
> like pwm, regman, irqchip, ... And then there's also the large-scale
> subsystems like media or gpu. What's the plan to tie them all
> together? Personally I'm leaning towards keeping the existing
> directories (where they exist already), but inserting links into the
> overall driver-api section.

To say I have a plan is to overstate things somewhat...

One objective I do have, though, is to declutter Documentation/.
Presenting people looking for docs with a 270-file directory is
unfriendly to say the least.  We don't organize the code that way; the
average in the kernel is <... find | wc -l ... > about 15
files/directory, which is rather more manageable.  Someday I'd like
Documentation/ to look a lot more like the top-level directory.

It seems to me that we have a few basic types of stuff here:

 - Driver API documentation, obviously, is a lot of it, and I would like
   to organize it better and to move it out of the top-level directory.

 - Hardware usage information - module parameters, sysfs files, supported
   hardware information, graphic descriptions of the ancestry of hardware
   engineers, etc.  The readership for this stuff is quite different, and
   I think it should be separate; often it's intertwined with API
   information at the moment.

 - Other usage information - a lot of what's under filesystems/ for
   example, and more.

 - Core API documentation.

 - Kernel development tools - the stuff I started pulling together into
   the dev-tools/ subdirectory.

 - How to deal with this unruly mob - SubmittingPatches, CodingStyle,
   development-process, etc.  There's process stuff, and general
   development documents like volatile-considered-harmful.txt or
   memory-barriers.txt

We can go a long way by organizing this stuff within the formatted
documentation, but I really think we need to organize the directory
structure as well.  I see that as a slow-moving process that will take
years, but I do think it's a direction we should go.

jon
Daniel Vetter Aug. 23, 2016, 3:15 p.m. UTC | #8
On Tue, Aug 23, 2016 at 08:16:33AM -0600, Jonathan Corbet wrote:
> On Tue, 23 Aug 2016 15:28:55 +0200
> Daniel Vetter <daniel@ffwll.ch> wrote:
> 
> > I think the more interesting story is, what's your plan with all the
> > other driver related subsystem? Especially the ones which already have
> > full directories of their own, like e.g. Documentation/gpio/. I think
> > those should be really part of the infrastructure section (or
> > something equally high-level), together with other awesome servies
> > like pwm, regman, irqchip, ... And then there's also the large-scale
> > subsystems like media or gpu. What's the plan to tie them all
> > together? Personally I'm leaning towards keeping the existing
> > directories (where they exist already), but inserting links into the
> > overall driver-api section.
> 
> To say I have a plan is to overstate things somewhat...
> 
> One objective I do have, though, is to declutter Documentation/.
> Presenting people looking for docs with a 270-file directory is
> unfriendly to say the least.  We don't organize the code that way; the
> average in the kernel is <... find | wc -l ... > about 15
> files/directory, which is rather more manageable.  Someday I'd like
> Documentation/ to look a lot more like the top-level directory.
> 
> It seems to me that we have a few basic types of stuff here:
> 
>  - Driver API documentation, obviously, is a lot of it, and I would like
>    to organize it better and to move it out of the top-level directory.
> 
>  - Hardware usage information - module parameters, sysfs files, supported
>    hardware information, graphic descriptions of the ancestry of hardware
>    engineers, etc.  The readership for this stuff is quite different, and
>    I think it should be separate; often it's intertwined with API
>    information at the moment.
> 
>  - Other usage information - a lot of what's under filesystems/ for
>    example, and more.

Hm yeah, I don't have a plan really for what to do with usage docs for
users (as opposed to api docs for kernel developers). With DRM
comparatively few people end up writing userspace for our apis, hence I
think this is a lower priority issue for us. Definitely something I'd like
to address eventually. I think for drivers a big part here is documenting
the ioctls and all the other uapi bits&pieces.

>  - Core API documentation.

Personally I'm very much interesting in dragging all the locking
primitives into the rst/sphinx world. We already make heavy use fo
ww_mutex, and we started to make rather heavy use of rcu in drm and
drm/i915. I'd like to be able to directly reference these underlying
primitives. For KS I'll try to convince Paul that this is an awesome idea
;-)

>  - Kernel development tools - the stuff I started pulling together into
>    the dev-tools/ subdirectory.
> 
>  - How to deal with this unruly mob - SubmittingPatches, CodingStyle,
>    development-process, etc.  There's process stuff, and general
>    development documents like volatile-considered-harmful.txt or
>    memory-barriers.txt

tbh I think the process stuff is important enough that we should imo leave
it in the top-level Documentation/ directory. Maybe collated together into
a contributing.rst index file (besides the top-level index.rst ofc).

> We can go a long way by organizing this stuff within the formatted
> documentation, but I really think we need to organize the directory
> structure as well.  I see that as a slow-moving process that will take
> years, but I do think it's a direction we should go.

Fully agreed on the larger-scale picture, and I think what I've seen thus
far from you looks great. Was simply wondering whether you have a more
concrete plane for drivers specifically already. I'm wondering whether we
should have Documentation/drivers/(gpu|media|...) too, but otoh nesting
things too deeply isn't great either. Starting out with a proper driver
directory in there is definitely the right step forward though. We can
shuffle the other bits into that later on anytime we like really.
-Daniel
Mauro Carvalho Chehab Aug. 23, 2016, 4:40 p.m. UTC | #9
Em Tue, 23 Aug 2016 08:16:33 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 23 Aug 2016 15:28:55 +0200
> Daniel Vetter <daniel@ffwll.ch> wrote:
> 
> > I think the more interesting story is, what's your plan with all the
> > other driver related subsystem? Especially the ones which already have
> > full directories of their own, like e.g. Documentation/gpio/. I think
> > those should be really part of the infrastructure section (or
> > something equally high-level), together with other awesome servies
> > like pwm, regman, irqchip, ... And then there's also the large-scale
> > subsystems like media or gpu. What's the plan to tie them all
> > together? Personally I'm leaning towards keeping the existing
> > directories (where they exist already), but inserting links into the
> > overall driver-api section.  
> 
> To say I have a plan is to overstate things somewhat...
> 
> One objective I do have, though, is to declutter Documentation/.
> Presenting people looking for docs with a 270-file directory is
> unfriendly to say the least.  We don't organize the code that way; the
> average in the kernel is <... find | wc -l ... > about 15
> files/directory, which is rather more manageable.  Someday I'd like
> Documentation/ to look a lot more like the top-level directory.

Makes sense, although 15 files/dir doesn't seem feasible...

I actually grouped the media documentation on a more logical arrangement,
grouping things per API type.

Yet, just the V4L userspace docs (Documentation/media/uapi/v4l/)
has ~200 files :) 

And I think that a few of them, like the extended-controls.rst one
are too big and should likely be split in some future.

> 
> It seems to me that we have a few basic types of stuff here:
> 
>  - Driver API documentation, obviously, is a lot of it, and I would like
>    to organize it better and to move it out of the top-level directory.
> 
>  - Hardware usage information - module parameters, sysfs files, supported
>    hardware information, graphic descriptions of the ancestry of hardware
>    engineers, etc.  The readership for this stuff is quite different, and
>    I think it should be separate; often it's intertwined with API
>    information at the moment.

In the case or media, I ended by merging those into one subdir for V4L2
and another one for DVB (currently, we don't have hardware usage documents
for Remote Controllers or CEC devices).

I wouldn't mind moving them to some other place, although a few rst files
there are actually linked to kAPI documentation.

Btw, we have, at the media subsystem, several drivers using the
kernel-doc syntax to describe functions that are internal to a driver,
and even some alien markups using some Doxygen syntax out there.
Maybe some day we'll end by adding such documentation on some
driver-specific rst file, probably at a hardware section of the
documentation.

> 
>  - Other usage information - a lot of what's under filesystems/ for
>    example, and more.
> 
>  - Core API documentation.
> 
>  - Kernel development tools - the stuff I started pulling together into
>    the dev-tools/ subdirectory.
> 
>  - How to deal with this unruly mob - SubmittingPatches, CodingStyle,
>    development-process, etc.  There's process stuff, and general
>    development documents like volatile-considered-harmful.txt or
>    memory-barriers.txt

I would actually keep at the top-level directory only the build system 
main conf.py, makefiles & similar stuff), moving everything else to subdirs.

IMHO, there are a few advantages on that:

1) the Sphinx build system is oriented per subdir. We can't ask it to
   build just the stuff at the top dir without building the subdirs;

2) it makes easier to identify what was ported and what wasn't;

3) it makes things more organized, as the subdir will be an
   alias to the group of documents that will be part of the subdir.
> 
> We can go a long way by organizing this stuff within the formatted
> documentation, but I really think we need to organize the directory
> structure as well.  I see that as a slow-moving process that will take
> years, but I do think it's a direction we should go.

My suggestion is to create a directory structure for the
things that are currently under the top /Documentation dir
and at /Documentation/DocBook. Then, create an index.rst file for
each of them, initially with an "empty" content like:

	TODO: add stuff here

And then move stuff there as we finish the conversion.

I actually did something like that for the stuff that used to be at
/Documentation/video4linux and Documentation/dvb and worked fine,
IMHO.

Ah, btw, on my experience, converting a .txt file into a .rst one
is a way easier than converting the DocBooks, as there's just one
place to touch, while on DocBooks, you'll also need to touch at
the included files, to fix format issues at the kernel-doc macros
that won't work anymore with ReST.

If you want, I may get some of those non-subsystem specific
documentation (like the documents describing the submission
process) and convert into a book, in order to add some conversion
examples.

Regards,
Mauro

Patch
diff mbox

diff --git a/Documentation/index.rst b/Documentation/index.rst
index e0fc72963e87..8d05070122c2 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -14,6 +14,8 @@  Contents:
    :maxdepth: 2
 
    kernel-documentation
+   dma-buf/intro
+   dma-buf/guide
    media/media_uapi
    media/media_kapi
    media/dvb-drivers/index