lkml.org 
[lkml]   [2016]   [Aug]   [12]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [RFC 0/4] doc: dma-buf: sphinx conversion and cleanup
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

\
 
 \ /
  Last update: 2016-09-17 09:56    [W:0.084 / U:1.016 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site