[PATCH] docs-rst: add input docs at main index and use kernel-figure

[PATCH] docs-rst: add input docs at main index and use kernel-figure

[Mauro Carvalho Chehab]

The input subsystem documentation got converted into ReST.

Add it to the main documentation index and use kernel-figure
for the two svg images there.

Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---

Jon/Dmitry,

This patch contains the final bits of the input documentation
conversion. The linux-input tree has already the ReST conversion
patches, but it doesn't have the
Documentation/sphinx/load_config.py script with implements
the kernel-figure directive, as it got merged via docs tree.

So, either one of you should merge from the other tree or this
patch should be sent in separate upstream after both trees
gets merged. What do you prefer?

Thanks!
Mauro


 Documentation/index.rst    | 1 +
 Documentation/input/ff.rst | 4 ++--
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/Documentation/index.rst b/Documentation/index.rst
index 61306a22888d..bc67dbf76eb0 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -67,6 +67,7 @@ needed).
    driver-api/index
    core-api/index
    media/index
+   input/index
    gpu/index
    security/index
    sound/index
diff --git a/Documentation/input/ff.rst b/Documentation/input/ff.rst
index c30f185216a0..0ea123c64dd2 100644
--- a/Documentation/input/ff.rst
+++ b/Documentation/input/ff.rst
@@ -129,11 +129,11 @@ Effects are file descriptor specific.
 See <linux/input.h> for a description of the ff_effect struct. You should also
 find help in a few sketches, contained in files shape.svg and interactive.svg:
 
-.. figure:: shape.svg
+.. kernel-figure:: shape.svg
 
     Shape
 
-.. figure:: interactive.svg
+.. kernel-figure:: interactive.svg
 
     Interactive
 
-- 
2.9.3

Re: [PATCH] docs-rst: add input docs at main index and use kernel-figure

[Jonathan Corbet]

On Tue, 11 Apr 2017 07:01:19 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> This patch contains the final bits of the input documentation
> conversion. The linux-input tree has already the ReST conversion
> patches, but it doesn't have the
> Documentation/sphinx/load_config.py script with implements
> the kernel-figure directive, as it got merged via docs tree.
> 
> So, either one of you should merge from the other tree or this
> patch should be sent in separate upstream after both trees
> gets merged. What do you prefer?

How about if I send it Linusward toward the end of the merge window?

FWIW, while I think the conversion is great, I'm not fully pleased with
having it as a separate top-level document.  Probably what needs to be
done here is to split it up into two pieces, one for driver-api and one
for userspace-api.  But that can happen later, I guess.

Thanks,

jon

Re: [PATCH] docs-rst: add input docs at main index and use kernel-figure

[Mauro Carvalho Chehab]

Em Tue, 11 Apr 2017 14:54:16 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 11 Apr 2017 07:01:19 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > This patch contains the final bits of the input documentation
> > conversion. The linux-input tree has already the ReST conversion
> > patches, but it doesn't have the
> > Documentation/sphinx/load_config.py script with implements
> > the kernel-figure directive, as it got merged via docs tree.
> > 
> > So, either one of you should merge from the other tree or this
> > patch should be sent in separate upstream after both trees
> > gets merged. What do you prefer?  
> 
> How about if I send it Linusward toward the end of the merge window?

Sounds fine.

> FWIW, while I think the conversion is great, I'm not fully pleased with
> having it as a separate top-level document.  Probably what needs to be
> done here is to split it up into two pieces, one for driver-api and one
> for userspace-api.  But that can happen later, I guess.

Yeah, separating uAPI from driver documentation makes sense to me.

IMHO, there are other type of documents there that aren't neither
uAPI or kAPI.

This one, for example, seems to be a good candidate for the admin
guide (except for the last item, with briefs uAPI events):
	https://mchehab.fedorapeople.org/kernel_docs/input/input.html

There are a number of docs there that describe driver-specific
internals, with, IMHO, won't fit on any of the "main" document
categories:
	https://mchehab.fedorapeople.org/kernel_docs/input/alps.html
	https://mchehab.fedorapeople.org/kernel_docs/input/appletouch.html
	https://mchehab.fedorapeople.org/kernel_docs/input/joystick-parport.html

Some describe messages used to communicate with devices, others
describe user-facing stuff, like modprobe parameters or X11 settings.
Some even have pinups for several device models. So, classifying
them require some thinking.

Btw, that's not that different from what I found on media after
converting all documents that were under Documentation/video4linux
and Documentation/dvb.

Thanks,
Mauro

Re: [PATCH] docs-rst: add input docs at main index and use kernel-figure

[Jonathan Corbet]

On Tue, 11 Apr 2017 07:01:19 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> The input subsystem documentation got converted into ReST.
> 
> Add it to the main documentation index and use kernel-figure
> for the two svg images there.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> ---
> 
> Jon/Dmitry,
> 
> This patch contains the final bits of the input documentation
> conversion. The linux-input tree has already the ReST conversion
> patches, but it doesn't have the
> Documentation/sphinx/load_config.py script with implements
> the kernel-figure directive, as it got merged via docs tree.
> 
> So, either one of you should merge from the other tree or this
> patch should be sent in separate upstream after both trees
> gets merged. What do you prefer?

This is now applied.

I do reserve the right to break apart and reorganize this documentation,
a bit; it's got the classic problem of jumbling stuff for different
audiences into one big document.  But that's for another day when I have
some time...2022 or so...

Thanks,

jon

Re: [PATCH] docs-rst: add input docs at main index and use kernel-figure

[Mauro Carvalho Chehab]

Em Tue, 9 May 2017 13:41:53 -0600
Jonathan Corbet <corbet@lwn.net> escreveu:

> On Tue, 11 Apr 2017 07:01:19 -0300
> Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:
> 
> > The input subsystem documentation got converted into ReST.
> > 
> > Add it to the main documentation index and use kernel-figure
> > for the two svg images there.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> > ---
> > 
> > Jon/Dmitry,
> > 
> > This patch contains the final bits of the input documentation
> > conversion. The linux-input tree has already the ReST conversion
> > patches, but it doesn't have the
> > Documentation/sphinx/load_config.py script with implements
> > the kernel-figure directive, as it got merged via docs tree.
> > 
> > So, either one of you should merge from the other tree or this
> > patch should be sent in separate upstream after both trees
> > gets merged. What do you prefer?  
> 
> This is now applied.

Thanks!

> I do reserve the right to break apart and reorganize this documentation,
> a bit; it's got the classic problem of jumbling stuff for different
> audiences into one big document.  But that's for another day when I have
> some time...2022 or so...

Yeah, it makes sense to better organize things, but I suspect that,
if we do that after converting everything to ReST, it would be easier
to identify what would be the best way to group the documentation
per audience.

Thanks,
Mauro

Re: [PATCH] docs-rst: add input docs at main index and use kernel-figure

[Jonathan Corbet]

On Thu, 11 May 2017 07:44:24 -0300
Mauro Carvalho Chehab <mchehab@s-opensource.com> wrote:

> > I do reserve the right to break apart and reorganize this documentation,
> > a bit; it's got the classic problem of jumbling stuff for different
> > audiences into one big document.  But that's for another day when I have
> > some time...2022 or so...  
> 
> Yeah, it makes sense to better organize things, but I suspect that,
> if we do that after converting everything to ReST, it would be easier
> to identify what would be the best way to group the documentation
> per audience.

Well, it would be nice, when possible, to put things where we want them
sooner and avoid yet another move; some people get grumpy when you move
the docs around too much :)  That said, I know better than to believe
we're going to get all of this right on the first try.  Progress is a good
thing.

jon