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

[Daniel Vetter <daniel@ffwll.ch>]

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