[RFC 0/4] doc: dma-buf: sphinx conversion and cleanup
Hi Jon! On 11 August 2016 at 20:06, Jonathan Corbet wrote: > On Thu, 11 Aug 2016 16:17:56 +0530 > Sumit Semwal 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 ... ... 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.
[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 wrote: > > On Thu, 11 Aug 2016 16:17:56 +0530 > > Sumit Semwal 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 ... ... 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 at lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dri-devel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch
[RFC 0/4] doc: dma-buf: sphinx conversion and cleanup
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
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
On Thu, 11 Aug 2016 16:17:56 +0530 Sumit Semwal 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 ... ... 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
