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@xxxxxxx> wrote:
> On Thu, 11 Aug 2016 16:17:56 +0530
> Sumit Semwal <sumit.semwal@xxxxxxxxxx> 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.