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