[RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

[RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

[Sumit Semwal]

Convert dma-buf documentation over to sphinx; also cleanup to
address sphinx warnings.

While at that, convert dma-buf-sharing.txt as well, and make it the
dma-buf API guide.

There is no content change yet; only format conversion and creation of
some hyperlinks.

Sumit Semwal (4):
  dma-buf/fence: kerneldoc: remove unused struct members
  dma-buf/fence: kerneldoc: remove spurious section header
  Documentation: move dma-buf documentation to rst
  Documentation/sphinx: link dma-buf rsts

 Documentation/DocBook/device-drivers.tmpl |  37 ---
 Documentation/dma-buf/guide.rst           | 503 ++++++++++++++++++++++++++++++
 Documentation/dma-buf/intro.rst           |  76 +++++
 Documentation/index.rst                   |   2 +
 MAINTAINERS                               |   2 +-
 include/linux/fence.h                     |   4 +-
 6 files changed, 583 insertions(+), 41 deletions(-)
 create mode 100644 Documentation/dma-buf/guide.rst
 create mode 100644 Documentation/dma-buf/intro.rst

-- 
2.7.4

[RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

[Sumit Semwal]

Convert dma-buf documentation over to sphinx; also cleanup to
address sphinx warnings.

While at that, convert dma-buf-sharing.txt as well, and make it the
dma-buf API guide.

There is no content change yet; only format conversion and creation of
some hyperlinks.

Sumit Semwal (4):
  dma-buf/fence: kerneldoc: remove unused struct members
  dma-buf/fence: kerneldoc: remove spurious section header
  Documentation: move dma-buf documentation to rst
  Documentation/sphinx: link dma-buf rsts

 Documentation/DocBook/device-drivers.tmpl |  37 ---
 Documentation/dma-buf/guide.rst           | 503 ++++++++++++++++++++++++++++++
 Documentation/dma-buf/intro.rst           |  76 +++++
 Documentation/index.rst                   |   2 +
 MAINTAINERS                               |   2 +-
 include/linux/fence.h                     |   4 +-
 6 files changed, 583 insertions(+), 41 deletions(-)
 create mode 100644 Documentation/dma-buf/guide.rst
 create mode 100644 Documentation/dma-buf/intro.rst

-- 
2.7.4

Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

[Jonathan Corbet]

On Thu, 11 Aug 2016 16:17:56 +0530
Sumit Semwal <sumit.semwal@linaro.org> wrote:

> Convert dma-buf documentation over to sphinx; also cleanup to
> address sphinx warnings.
> 
> While at that, convert dma-buf-sharing.txt as well, and make it the
> dma-buf API guide.

Thanks for working to improve the documentation!  I do have a few overall
comments...

 - The two comment fixes are a separate thing that should go straight to
   the dma-buf maintainer, who is ... <looks> ... evidently somebody
   familiar to you :)  I assume you'll merge those two directly?

 - It looks like you create a new RST document but leave the old one in
   place.  Having two copies of the document around can only lead to
   confusion, so I think the old one should go.

 - I really wonder if we want to start carving pieces out of
   device-drivers.tmpl in this way.  I guess I would rather see the
   conversion of that book and the better integration of the other docs
   *into* it.  One of the goals of this whole thing is to unify our
   documentation, not to reinforce the silos.

Does that make sense?

Thanks,

jon

Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

[Sumit Semwal]

Hi Jon!

On 11 August 2016 at 20:06, Jonathan Corbet <corbet@lwn.net> wrote:
> On Thu, 11 Aug 2016 16:17:56 +0530
> Sumit Semwal <sumit.semwal@linaro.org> wrote:
>
>> Convert dma-buf documentation over to sphinx; also cleanup to
>> address sphinx warnings.
>>
>> While at that, convert dma-buf-sharing.txt as well, and make it the
>> dma-buf API guide.
>
> Thanks for working to improve the documentation!  I do have a few overall
> comments...
>
Thank you for your review, and comments; my responses are inline.

>  - The two comment fixes are a separate thing that should go straight to
>    the dma-buf maintainer, who is ... <looks> ... evidently somebody
>    familiar to you :)  I assume you'll merge those two directly?
>
Yes, of course :) - I will merge them directly, and will remove them
from v2 of this series.

>  - It looks like you create a new RST document but leave the old one in
>    place.  Having two copies of the document around can only lead to
>    confusion, so I think the old one should go.
>
Agreed on this as well; will correct it.

>  - I really wonder if we want to start carving pieces out of
>    device-drivers.tmpl in this way.  I guess I would rather see the
>    conversion of that book and the better integration of the other docs
>    *into* it.  One of the goals of this whole thing is to unify our
>    documentation, not to reinforce the silos.
>
I should've mentioned it in the cover letter - my intention of taking
the dma-buf pieces out was to focus on these first while moving to
sphinx.

My proposal would be, if all the device driver section owners could
take the relevant pieces, convert them to sphinx (ironing out warnings
etc in the process), then we can again 'bind' them together into the
device drivers book in rst format.
This breaks the documentation conversion task into manageable pieces
that can be handled independently, and gives everyone flexibility to
work on their schedules.

This should also help in a good technical re-look at the content by
subsystem developers, and make any documentation updates as required.
The beauty of sphinx should allow us this, I think? Just my 2 cents.

> Does that make sense?
>
I do hope that my proposal above finds some merit with everyone.

> Thanks,
>
> jon

BR,
Sumit.

Re: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup

[Daniel Vetter]

On Fri, Aug 12, 2016 at 12:05:04PM +0530, Sumit Semwal wrote:
> Hi Jon!
> 
> On 11 August 2016 at 20:06, Jonathan Corbet <corbet@lwn.net> wrote:
> > On Thu, 11 Aug 2016 16:17:56 +0530
> > Sumit Semwal <sumit.semwal@linaro.org> wrote:
> >
> >> Convert dma-buf documentation over to sphinx; also cleanup to
> >> address sphinx warnings.
> >>
> >> While at that, convert dma-buf-sharing.txt as well, and make it the
> >> dma-buf API guide.
> >
> > Thanks for working to improve the documentation!  I do have a few overall
> > comments...
> >
> Thank you for your review, and comments; my responses are inline.
> 
> >  - The two comment fixes are a separate thing that should go straight to
> >    the dma-buf maintainer, who is ... <looks> ... evidently somebody
> >    familiar to you :)  I assume you'll merge those two directly?
> >
> Yes, of course :) - I will merge them directly, and will remove them
> from v2 of this series.
> 
> >  - It looks like you create a new RST document but leave the old one in
> >    place.  Having two copies of the document around can only lead to
> >    confusion, so I think the old one should go.
> >
> Agreed on this as well; will correct it.
> 
> >  - I really wonder if we want to start carving pieces out of
> >    device-drivers.tmpl in this way.  I guess I would rather see the
> >    conversion of that book and the better integration of the other docs
> >    *into* it.  One of the goals of this whole thing is to unify our
> >    documentation, not to reinforce the silos.
> >
> I should've mentioned it in the cover letter - my intention of taking
> the dma-buf pieces out was to focus on these first while moving to
> sphinx.
> 
> My proposal would be, if all the device driver section owners could
> take the relevant pieces, convert them to sphinx (ironing out warnings
> etc in the process), then we can again 'bind' them together into the
> device drivers book in rst format.
> This breaks the documentation conversion task into manageable pieces
> that can be handled independently, and gives everyone flexibility to
> work on their schedules.
> 
> This should also help in a good technical re-look at the content by
> subsystem developers, and make any documentation updates as required.
> The beauty of sphinx should allow us this, I think? Just my 2 cents.

I already tried to trick Sumit into converting the entire
device-drivers.tmpl, but he didn't take the bait ;-)

I think just extracting dma-buf stuff (dma_buf, fence, reservation and all
that) is ok though, it is a fairly stand-alone topic.
-Daniel

> 
> > Does that make sense?
> >
> I do hope that my proposal above finds some merit with everyone.
> 
> > Thanks,
> >
> > jon
> 
> BR,
> Sumit.
> _______________________________________________
> 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