| Message ID | 1471878705-3963-3-git-send-email-sumit.semwal@linaro.org (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
Em Mon, 22 Aug 2016 20:41:45 +0530 Sumit Semwal <sumit.semwal@linaro.org> escreveu: > Include dma-buf sphinx documentation into top level index. > > Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org> > --- > Documentation/index.rst | 2 ++ > 1 file changed, 2 insertions(+) > > diff --git a/Documentation/index.rst b/Documentation/index.rst > index e0fc72963e87..8d05070122c2 100644 > --- a/Documentation/index.rst > +++ b/Documentation/index.rst > @@ -14,6 +14,8 @@ Contents: > :maxdepth: 2 > > kernel-documentation > + dma-buf/intro > + dma-buf/guide > media/media_uapi > media/media_kapi > media/dvb-drivers/index IMHO, the best would be, instead, to add an index with a toctree with both intro and guide, and add dma-buf/index instead. We did that for media too (patches not merged upstream yet), together with a patchset that will allow building just a subset of the books. Regards, Mauro PS.: That's the content of our index.rst file, at Documentation/media/index.rst: Linux Media Subsystem Documentation =================================== Contents: .. toctree:: :maxdepth: 2 media_uapi media_kapi dvb-drivers/index v4l-drivers/index .. only:: subproject Indices ======= * :ref:`genindex` Thanks, Mauro
On Mon, Aug 22, 2016 at 12:49:30PM -0300, Mauro Carvalho Chehab wrote: > Em Mon, 22 Aug 2016 20:41:45 +0530 > Sumit Semwal <sumit.semwal@linaro.org> escreveu: > > > Include dma-buf sphinx documentation into top level index. > > > > Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org> > > --- > > Documentation/index.rst | 2 ++ > > 1 file changed, 2 insertions(+) > > > > diff --git a/Documentation/index.rst b/Documentation/index.rst > > index e0fc72963e87..8d05070122c2 100644 > > --- a/Documentation/index.rst > > +++ b/Documentation/index.rst > > @@ -14,6 +14,8 @@ Contents: > > :maxdepth: 2 > > > > kernel-documentation > > + dma-buf/intro > > + dma-buf/guide > > media/media_uapi > > media/media_kapi > > media/dvb-drivers/index > > IMHO, the best would be, instead, to add an index with a toctree > with both intro and guide, and add dma-buf/index instead. > > We did that for media too (patches not merged upstream yet), together > with a patchset that will allow building just a subset of the books. I'm also not too sure about whether dma-buf really should be it's own subdirectory. It's plucked from the device-drivers.tmpl, I think an overall device-drivers/ for all the misc subsystems and support code would be better. Then one toc there, which fans out to either kernel-doc and overview docs. -Daniel > > Regards, > Mauro > > PS.: That's the content of our index.rst file, at > Documentation/media/index.rst: > > Linux Media Subsystem Documentation > =================================== > > Contents: > > .. toctree:: > :maxdepth: 2 > > media_uapi > media_kapi > dvb-drivers/index > v4l-drivers/index > > .. only:: subproject > > Indices > ======= > > * :ref:`genindex` > > > Thanks, > Mauro > _______________________________________________ > dri-devel mailing list > dri-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/dri-devel
Am 23.08.2016 um 08:01 schrieb Daniel Vetter <daniel@ffwll.ch>: > On Mon, Aug 22, 2016 at 12:49:30PM -0300, Mauro Carvalho Chehab wrote: >> Em Mon, 22 Aug 2016 20:41:45 +0530 >> Sumit Semwal <sumit.semwal@linaro.org> escreveu: >> >>> Include dma-buf sphinx documentation into top level index. >>> >>> Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org> >>> --- >>> Documentation/index.rst | 2 ++ >>> 1 file changed, 2 insertions(+) >>> >>> diff --git a/Documentation/index.rst b/Documentation/index.rst >>> index e0fc72963e87..8d05070122c2 100644 >>> --- a/Documentation/index.rst >>> +++ b/Documentation/index.rst >>> @@ -14,6 +14,8 @@ Contents: >>> :maxdepth: 2 >>> >>> kernel-documentation >>> + dma-buf/intro >>> + dma-buf/guide >>> media/media_uapi >>> media/media_kapi >>> media/dvb-drivers/index >> >> IMHO, the best would be, instead, to add an index with a toctree >> with both intro and guide, and add dma-buf/index instead. >> >> We did that for media too (patches not merged upstream yet), together >> with a patchset that will allow building just a subset of the books. Since 606b9ac, one more *pro* of a index.rst file in a sub-folder is, that you can reduce your roundtrips. Add a conf.py to your subfolder and compile only your sub-folder with e.g. make SPHINXDIRS="dma-buf" htmldocs * http://git.kernel.org/cgit/linux/kernel/git/next/linux-next.git/commit/?id=606b9ac81a63ab3adb7e61206b9ae34ee186a89d One / the example (Mauro mentioned) is media commit b32feba * http://git.kernel.org/cgit/linux/kernel/git/next/linux-next.git/commit/?id=b32febad77068b4a28daf7b7e063438d0cca8a42 > I'm also not too sure about whether dma-buf really should be it's own > subdirectory. It's plucked from the device-drivers.tmpl, I think an > overall device-drivers/ for all the misc subsystems and support code would > be better. If the sub-folder named 'device-drivers' use: make SPHINXDIRS="device-drivers" htmldocs -- Markus -- > Then one toc there, which fans out to either kernel-doc and > overview docs. > -Daniel > >> >> Regards, >> Mauro >> >> PS.: That's the content of our index.rst file, at >> Documentation/media/index.rst: >> >> Linux Media Subsystem Documentation >> =================================== >> >> Contents: >> >> .. toctree:: >> :maxdepth: 2 >> >> media_uapi >> media_kapi >> dvb-drivers/index >> v4l-drivers/index >> >> .. only:: subproject >> >> Indices >> ======= >> >> * :ref:`genindex` >> >> >> Thanks, >> Mauro >> _______________________________________________ >> 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
On Tue, 23 Aug 2016 08:01:35 +0200 Daniel Vetter <daniel@ffwll.ch> wrote: > I'm also not too sure about whether dma-buf really should be it's own > subdirectory. It's plucked from the device-drivers.tmpl, I think an > overall device-drivers/ for all the misc subsystems and support code would > be better. Then one toc there, which fans out to either kernel-doc and > overview docs. I'm quite convinced it shouldn't be. If you get a chance, could you have a look at the "RFC: The beginning of a proper driver-api book" series I posted yesterday (yes, I should have copied more of you, sorry)? It shows the direction I would like to go with driver API documentation, and, assuming we go that way, I'd like the dma-buf documentation to fit into that. Thanks, jon
On Tue, Aug 23, 2016 at 3:08 PM, Jonathan Corbet <corbet@lwn.net> wrote: > On Tue, 23 Aug 2016 08:01:35 +0200 > Daniel Vetter <daniel@ffwll.ch> wrote: > >> I'm also not too sure about whether dma-buf really should be it's own >> subdirectory. It's plucked from the device-drivers.tmpl, I think an >> overall device-drivers/ for all the misc subsystems and support code would >> be better. Then one toc there, which fans out to either kernel-doc and >> overview docs. > > I'm quite convinced it shouldn't be. > > If you get a chance, could you have a look at the "RFC: The beginning of > a proper driver-api book" series I posted yesterday (yes, I should have > copied more of you, sorry)? It shows the direction I would like to go > with driver API documentation, and, assuming we go that way, I'd like the > dma-buf documentation to fit into that. Looks real pretty, ack on that. And we can always split up more, e.g. by extracting dma-buf.rst (and merg the current dma-buffer-sharing.txt into that one). I think the more interesting story is, what's your plan with all the other driver related subsystem? Especially the ones which already have full directories of their own, like e.g. Documentation/gpio/. I think those should be really part of the infrastructure section (or something equally high-level), together with other awesome servies like pwm, regman, irqchip, ... And then there's also the large-scale subsystems like media or gpu. What's the plan to tie them all together? Personally I'm leaning towards keeping the existing directories (where they exist already), but inserting links into the overall driver-api section. -Daniel
Hi Jon, On 23 August 2016 at 18:38, Jonathan Corbet <corbet@lwn.net> wrote: > On Tue, 23 Aug 2016 08:01:35 +0200 > Daniel Vetter <daniel@ffwll.ch> wrote: > >> I'm also not too sure about whether dma-buf really should be it's own >> subdirectory. It's plucked from the device-drivers.tmpl, I think an >> overall device-drivers/ for all the misc subsystems and support code would >> be better. Then one toc there, which fans out to either kernel-doc and >> overview docs. > > I'm quite convinced it shouldn't be. > > If you get a chance, could you have a look at the "RFC: The beginning of > a proper driver-api book" series I posted yesterday (yes, I should have > copied more of you, sorry)? It shows the direction I would like to go > with driver API documentation, and, assuming we go that way, I'd like the > dma-buf documentation to fit into that. > Thanks for your comments, and direction. I'll rework the patches on top of yours then. I'll have a look at your patches to think about how do we handle API guides / detailed documentation as well. > Thanks, > > jon Best, Sumit.
On Tue, 23 Aug 2016 15:28:55 +0200 Daniel Vetter <daniel@ffwll.ch> wrote: > I think the more interesting story is, what's your plan with all the > other driver related subsystem? Especially the ones which already have > full directories of their own, like e.g. Documentation/gpio/. I think > those should be really part of the infrastructure section (or > something equally high-level), together with other awesome servies > like pwm, regman, irqchip, ... And then there's also the large-scale > subsystems like media or gpu. What's the plan to tie them all > together? Personally I'm leaning towards keeping the existing > directories (where they exist already), but inserting links into the > overall driver-api section. To say I have a plan is to overstate things somewhat... One objective I do have, though, is to declutter Documentation/. Presenting people looking for docs with a 270-file directory is unfriendly to say the least. We don't organize the code that way; the average in the kernel is <... find | wc -l ... > about 15 files/directory, which is rather more manageable. Someday I'd like Documentation/ to look a lot more like the top-level directory. It seems to me that we have a few basic types of stuff here: - Driver API documentation, obviously, is a lot of it, and I would like to organize it better and to move it out of the top-level directory. - Hardware usage information - module parameters, sysfs files, supported hardware information, graphic descriptions of the ancestry of hardware engineers, etc. The readership for this stuff is quite different, and I think it should be separate; often it's intertwined with API information at the moment. - Other usage information - a lot of what's under filesystems/ for example, and more. - Core API documentation. - Kernel development tools - the stuff I started pulling together into the dev-tools/ subdirectory. - How to deal with this unruly mob - SubmittingPatches, CodingStyle, development-process, etc. There's process stuff, and general development documents like volatile-considered-harmful.txt or memory-barriers.txt We can go a long way by organizing this stuff within the formatted documentation, but I really think we need to organize the directory structure as well. I see that as a slow-moving process that will take years, but I do think it's a direction we should go. jon
On Tue, Aug 23, 2016 at 08:16:33AM -0600, Jonathan Corbet wrote: > On Tue, 23 Aug 2016 15:28:55 +0200 > Daniel Vetter <daniel@ffwll.ch> wrote: > > > I think the more interesting story is, what's your plan with all the > > other driver related subsystem? Especially the ones which already have > > full directories of their own, like e.g. Documentation/gpio/. I think > > those should be really part of the infrastructure section (or > > something equally high-level), together with other awesome servies > > like pwm, regman, irqchip, ... And then there's also the large-scale > > subsystems like media or gpu. What's the plan to tie them all > > together? Personally I'm leaning towards keeping the existing > > directories (where they exist already), but inserting links into the > > overall driver-api section. > > To say I have a plan is to overstate things somewhat... > > One objective I do have, though, is to declutter Documentation/. > Presenting people looking for docs with a 270-file directory is > unfriendly to say the least. We don't organize the code that way; the > average in the kernel is <... find | wc -l ... > about 15 > files/directory, which is rather more manageable. Someday I'd like > Documentation/ to look a lot more like the top-level directory. > > It seems to me that we have a few basic types of stuff here: > > - Driver API documentation, obviously, is a lot of it, and I would like > to organize it better and to move it out of the top-level directory. > > - Hardware usage information - module parameters, sysfs files, supported > hardware information, graphic descriptions of the ancestry of hardware > engineers, etc. The readership for this stuff is quite different, and > I think it should be separate; often it's intertwined with API > information at the moment. > > - Other usage information - a lot of what's under filesystems/ for > example, and more. Hm yeah, I don't have a plan really for what to do with usage docs for users (as opposed to api docs for kernel developers). With DRM comparatively few people end up writing userspace for our apis, hence I think this is a lower priority issue for us. Definitely something I'd like to address eventually. I think for drivers a big part here is documenting the ioctls and all the other uapi bits&pieces. > - Core API documentation. Personally I'm very much interesting in dragging all the locking primitives into the rst/sphinx world. We already make heavy use fo ww_mutex, and we started to make rather heavy use of rcu in drm and drm/i915. I'd like to be able to directly reference these underlying primitives. For KS I'll try to convince Paul that this is an awesome idea ;-) > - Kernel development tools - the stuff I started pulling together into > the dev-tools/ subdirectory. > > - How to deal with this unruly mob - SubmittingPatches, CodingStyle, > development-process, etc. There's process stuff, and general > development documents like volatile-considered-harmful.txt or > memory-barriers.txt tbh I think the process stuff is important enough that we should imo leave it in the top-level Documentation/ directory. Maybe collated together into a contributing.rst index file (besides the top-level index.rst ofc). > We can go a long way by organizing this stuff within the formatted > documentation, but I really think we need to organize the directory > structure as well. I see that as a slow-moving process that will take > years, but I do think it's a direction we should go. Fully agreed on the larger-scale picture, and I think what I've seen thus far from you looks great. Was simply wondering whether you have a more concrete plane for drivers specifically already. I'm wondering whether we should have Documentation/drivers/(gpu|media|...) too, but otoh nesting things too deeply isn't great either. Starting out with a proper driver directory in there is definitely the right step forward though. We can shuffle the other bits into that later on anytime we like really. -Daniel
Em Tue, 23 Aug 2016 08:16:33 -0600 Jonathan Corbet <corbet@lwn.net> escreveu: > On Tue, 23 Aug 2016 15:28:55 +0200 > Daniel Vetter <daniel@ffwll.ch> wrote: > > > I think the more interesting story is, what's your plan with all the > > other driver related subsystem? Especially the ones which already have > > full directories of their own, like e.g. Documentation/gpio/. I think > > those should be really part of the infrastructure section (or > > something equally high-level), together with other awesome servies > > like pwm, regman, irqchip, ... And then there's also the large-scale > > subsystems like media or gpu. What's the plan to tie them all > > together? Personally I'm leaning towards keeping the existing > > directories (where they exist already), but inserting links into the > > overall driver-api section. > > To say I have a plan is to overstate things somewhat... > > One objective I do have, though, is to declutter Documentation/. > Presenting people looking for docs with a 270-file directory is > unfriendly to say the least. We don't organize the code that way; the > average in the kernel is <... find | wc -l ... > about 15 > files/directory, which is rather more manageable. Someday I'd like > Documentation/ to look a lot more like the top-level directory. Makes sense, although 15 files/dir doesn't seem feasible... I actually grouped the media documentation on a more logical arrangement, grouping things per API type. Yet, just the V4L userspace docs (Documentation/media/uapi/v4l/) has ~200 files :) And I think that a few of them, like the extended-controls.rst one are too big and should likely be split in some future. > > It seems to me that we have a few basic types of stuff here: > > - Driver API documentation, obviously, is a lot of it, and I would like > to organize it better and to move it out of the top-level directory. > > - Hardware usage information - module parameters, sysfs files, supported > hardware information, graphic descriptions of the ancestry of hardware > engineers, etc. The readership for this stuff is quite different, and > I think it should be separate; often it's intertwined with API > information at the moment. In the case or media, I ended by merging those into one subdir for V4L2 and another one for DVB (currently, we don't have hardware usage documents for Remote Controllers or CEC devices). I wouldn't mind moving them to some other place, although a few rst files there are actually linked to kAPI documentation. Btw, we have, at the media subsystem, several drivers using the kernel-doc syntax to describe functions that are internal to a driver, and even some alien markups using some Doxygen syntax out there. Maybe some day we'll end by adding such documentation on some driver-specific rst file, probably at a hardware section of the documentation. > > - Other usage information - a lot of what's under filesystems/ for > example, and more. > > - Core API documentation. > > - Kernel development tools - the stuff I started pulling together into > the dev-tools/ subdirectory. > > - How to deal with this unruly mob - SubmittingPatches, CodingStyle, > development-process, etc. There's process stuff, and general > development documents like volatile-considered-harmful.txt or > memory-barriers.txt I would actually keep at the top-level directory only the build system main conf.py, makefiles & similar stuff), moving everything else to subdirs. IMHO, there are a few advantages on that: 1) the Sphinx build system is oriented per subdir. We can't ask it to build just the stuff at the top dir without building the subdirs; 2) it makes easier to identify what was ported and what wasn't; 3) it makes things more organized, as the subdir will be an alias to the group of documents that will be part of the subdir. > > We can go a long way by organizing this stuff within the formatted > documentation, but I really think we need to organize the directory > structure as well. I see that as a slow-moving process that will take > years, but I do think it's a direction we should go. My suggestion is to create a directory structure for the things that are currently under the top /Documentation dir and at /Documentation/DocBook. Then, create an index.rst file for each of them, initially with an "empty" content like: TODO: add stuff here And then move stuff there as we finish the conversion. I actually did something like that for the stuff that used to be at /Documentation/video4linux and Documentation/dvb and worked fine, IMHO. Ah, btw, on my experience, converting a .txt file into a .rst one is a way easier than converting the DocBooks, as there's just one place to touch, while on DocBooks, you'll also need to touch at the included files, to fix format issues at the kernel-doc macros that won't work anymore with ReST. If you want, I may get some of those non-subsystem specific documentation (like the documents describing the submission process) and convert into a book, in order to add some conversion examples. Regards, Mauro
diff --git a/Documentation/index.rst b/Documentation/index.rst index e0fc72963e87..8d05070122c2 100644 --- a/Documentation/index.rst +++ b/Documentation/index.rst @@ -14,6 +14,8 @@ Contents: :maxdepth: 2 kernel-documentation + dma-buf/intro + dma-buf/guide media/media_uapi media/media_kapi media/dvb-drivers/index
Include dma-buf sphinx documentation into top level index. Signed-off-by: Sumit Semwal <sumit.semwal@linaro.org> --- Documentation/index.rst | 2 ++ 1 file changed, 2 insertions(+)