mbox series

[0/8] Move most GPIO documentation to driver-api/gpio/ and ReST

Message ID 20180308234024.24145-1-j.neuschaefer@gmx.net
Headers show
Series Move most GPIO documentation to driver-api/gpio/ and ReST | expand

Message

J. Neuschäfer March 8, 2018, 11:40 p.m. UTC
The aim of this patchset is to move the GPIO subsystem's documentation
under Documentation/driver-api/gpio/ such that it is picked up by Sphinx
and compiled into HTML. I moved everything except for sysfs.txt, because
this file describes the legacy sysfs ABI, and doesn't seem to serve much
(non-historical) purpose anymore.

There are still some rough edges:

* I think the API documentation (kernel-doc) should be moved out of
  index.rst into more appropriate files.
* The headings are arguably wrong, because driver.rst, consumer.rst,
  etc. use the "document title" style, even though they are part of the
  GPIO chapter. But the resulting TOC tree is consistent, and I did not
  want to change almost all headings.
* Some of the files could use more :c:func:`...` references and general
  ReST polish.

But I don't want to make this patchset too large.

Jonathan Neuschäfer (8):
  MAINTAINERS: GPIO: Add Documentation/driver-api/gpio/
  Documentation: driver-api: Move gpio.rst to gpio/index.rst
  Documentation: gpio: Move introduction to driver-api
  Documentation: gpio: Move driver documentation to driver-api
  Documentation: gpio: Move legacy documentation to driver-api
  Documentation: gpio: Move gpiod_* consumer documentation to driver-api
  Documentation: gpio: Move GPIO mapping documentation to driver-api
  Documentation: gpio: Move drivers-on-gpio.txt to driver-api

 .../{gpio/board.txt => driver-api/gpio/board.rst}  | 39 +++++-----
 .../consumer.txt => driver-api/gpio/consumer.rst}  | 85 +++++++++++-----------
 .../driver.txt => driver-api/gpio/driver.rst}      | 80 ++++++++++----------
 .../gpio/drivers-on-gpio.rst}                      |  1 +
 .../driver-api/{gpio.rst => gpio/index.rst}        | 21 +++---
 .../{gpio/gpio.txt => driver-api/gpio/intro.rst}   |  9 ++-
 .../gpio-legacy.txt => driver-api/gpio/legacy.rst} | 68 ++++++++++-------
 Documentation/driver-api/index.rst                 |  2 +-
 Documentation/gpio/00-INDEX                        | 13 ----
 Documentation/gpio/sysfs.txt                       |  5 +-
 MAINTAINERS                                        |  1 +
 11 files changed, 169 insertions(+), 155 deletions(-)
 rename Documentation/{gpio/board.txt => driver-api/gpio/board.rst} (88%)
 rename Documentation/{gpio/consumer.txt => driver-api/gpio/consumer.rst} (89%)
 rename Documentation/{gpio/driver.txt => driver-api/gpio/driver.rst} (93%)
 rename Documentation/{gpio/drivers-on-gpio.txt => driver-api/gpio/drivers-on-gpio.rst} (99%)
 rename Documentation/driver-api/{gpio.rst => gpio/index.rst} (74%)
 rename Documentation/{gpio/gpio.txt => driver-api/gpio/intro.rst} (96%)
 rename Documentation/{gpio/gpio-legacy.txt => driver-api/gpio/legacy.rst} (96%)

Comments

Jonathan Corbet March 9, 2018, 5:41 p.m. UTC | #1
On Fri,  9 Mar 2018 00:40:16 +0100
Jonathan Neuschäfer <j.neuschaefer@gmx.net> wrote:

> The aim of this patchset is to move the GPIO subsystem's documentation
> under Documentation/driver-api/gpio/ such that it is picked up by Sphinx
> and compiled into HTML. I moved everything except for sysfs.txt, because
> this file describes the legacy sysfs ABI, and doesn't seem to serve much
> (non-historical) purpose anymore.
> 
> There are still some rough edges:
> 
> * I think the API documentation (kernel-doc) should be moved out of
>   index.rst into more appropriate files.
> * The headings are arguably wrong, because driver.rst, consumer.rst,
>   etc. use the "document title" style, even though they are part of the
>   GPIO chapter. But the resulting TOC tree is consistent, and I did not
>   want to change almost all headings.
> * Some of the files could use more :c:func:`...` references and general
>   ReST polish.
> 
> But I don't want to make this patchset too large.

[For future reference, if you're going to CC me on most of a patch series,
I'd really rather get the whole thing so I don't have to go looking for
it.]

From a quick look, it seems like a reasonable RST conversion to me.  I do
wonder if sysfs.txt should just be removed, since it documents something
we don't want people to use at this point?  Historical purposes are well
served by the repository history.

I'd say changing the headings is worthwhile if it produces a better
result.  OTOH I'd be wary of adding too much "polish"; we really want to
retain the readability of the plain-text files.

Anyway, I'm happy to take these through the docs tree or see them go via
GPIO; Linus, what's your preference?

Thanks,

jon
--
To unsubscribe from this list: send the line "unsubscribe linux-gpio" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
J. Neuschäfer March 10, 2018, 11:18 a.m. UTC | #2
On Fri, Mar 09, 2018 at 10:41:20AM -0700, Jonathan Corbet wrote:
> On Fri,  9 Mar 2018 00:40:16 +0100
> Jonathan Neuschäfer <j.neuschaefer@gmx.net> wrote:
> 
> > The aim of this patchset is to move the GPIO subsystem's documentation
> > under Documentation/driver-api/gpio/ such that it is picked up by Sphinx
> > and compiled into HTML. I moved everything except for sysfs.txt, because
> > this file describes the legacy sysfs ABI, and doesn't seem to serve much
> > (non-historical) purpose anymore.
> > 
> > There are still some rough edges:
> > 
> > * I think the API documentation (kernel-doc) should be moved out of
> >   index.rst into more appropriate files.
> > * The headings are arguably wrong, because driver.rst, consumer.rst,
> >   etc. use the "document title" style, even though they are part of the
> >   GPIO chapter. But the resulting TOC tree is consistent, and I did not
> >   want to change almost all headings.
> > * Some of the files could use more :c:func:`...` references and general
> >   ReST polish.
> > 
> > But I don't want to make this patchset too large.
> 
> [For future reference, if you're going to CC me on most of a patch series,
> I'd really rather get the whole thing so I don't have to go looking for
> it.]

Noted.

> From a quick look, it seems like a reasonable RST conversion to me.  I do
> wonder if sysfs.txt should just be removed, since it documents something
> we don't want people to use at this point?  Historical purposes are well
> served by the repository history.
> 
> I'd say changing the headings is worthwhile if it produces a better
> result.

I just tried this on one file (driver.rst) and it made no difference in
the output (neither in the TOC in index.html nor in driver.html).

Thanks,
Jonathan Neuschäfer


> OTOH I'd be wary of adding too much "polish"; we really want to
> retain the readability of the plain-text files.
> 
> Anyway, I'm happy to take these through the docs tree or see them go via
> GPIO; Linus, what's your preference?
> 
> Thanks,
> 
> jon


----

diff --git a/Documentation/driver-api/gpio/driver.rst b/Documentation/driver-api/gpio/driver.rst
index 505ee906d7d9..8eb08005be55 100644
--- a/Documentation/driver-api/gpio/driver.rst
+++ b/Documentation/driver-api/gpio/driver.rst
@@ -1,4 +1,3 @@
-================================
 GPIO Descriptor Driver Interface
 ================================
 
@@ -13,7 +12,7 @@ the structures used to define a GPIO driver:
 
 
 Internal Representation of GPIOs
-================================
+--------------------------------
 
 Inside a GPIO driver, individual GPIOs are identified by their hardware number,
 which is a unique number between 0 and n, n being the number of GPIOs managed by
@@ -36,7 +35,7 @@ identify GPIOs in a bank of I2C GPIO expanders.
 
 
 Controller Drivers: gpio_chip
-=============================
+-----------------------------
 
 In the gpiolib framework each GPIO controller is packaged as a "struct
 gpio_chip" (see linux/gpio/driver.h for its complete definition) with members
@@ -74,7 +73,7 @@ not be required.
 
 
 GPIO electrical configuration
------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 GPIOs can be configured for several electrical modes of operation by using the
 .set_config() callback. Currently this API supports setting debouncing and
@@ -95,7 +94,7 @@ numbers on the pin controller so they can properly cross-reference each other.
 
 
 GPIOs with debounce support
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Debouncing is a configuration set to a pin indicating that it is connected to
 a mechanical switch or button, or similar that may bounce. Bouncing means the
@@ -112,7 +111,7 @@ is not configurable.
 
 
 GPIOs with open drain/source support
-------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Open drain (CMOS) or open collector (TTL) means the line is not actively driven
 high: instead you provide the drain/collector as output, so when the transistor
@@ -209,7 +208,7 @@ of actively driving the line low, it is set to input.
 
 
 GPIO drivers providing IRQs
----------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 It is custom that GPIO drivers (GPIO chips) are also providing interrupts,
 most often cascaded off a parent interrupt controller, and in some special
 cases the GPIO logic is melded with a SoC's primary interrupt controller.
@@ -359,7 +358,7 @@ below exists.
 
 
 Locking IRQ usage
------------------
+~~~~~~~~~~~~~~~~~
 Input GPIOs can be used as IRQ signals. When this happens, a driver is requested
 to mark the GPIO as being used as an IRQ::
 
@@ -378,7 +377,7 @@ When using the gpiolib irqchip helpers, these callback are automatically
 assigned.
 
 Real-Time compliance for GPIO IRQ chips
----------------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Any provider of irqchips needs to be carefully tailored to support Real Time
 preemption. It is desirable that all irqchips in the GPIO subsystem keep this
@@ -404,7 +403,7 @@ time-compliance:
 
 
 Requesting self-owned GPIO pins
--------------------------------
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Sometimes it is useful to allow a GPIO chip driver to request its own GPIO
 descriptors through the gpiolib API. Using gpio_request() for this purpose
Linus Walleij March 10, 2018, 11:50 a.m. UTC | #3
On Fri, Mar 9, 2018 at 12:40 AM, Jonathan Neuschäfer
<j.neuschaefer@gmx.net> wrote:

> The aim of this patchset is to move the GPIO subsystem's documentation
> under Documentation/driver-api/gpio/ such that it is picked up by Sphinx
> and compiled into HTML.

Awesome!

> I moved everything except for sysfs.txt, because
> this file describes the legacy sysfs ABI, and doesn't seem to serve much
> (non-historical) purpose anymore.
>
> There are still some rough edges:
>
> * I think the API documentation (kernel-doc) should be moved out of
>   index.rst into more appropriate files.
> * The headings are arguably wrong, because driver.rst, consumer.rst,
>   etc. use the "document title" style, even though they are part of the
>   GPIO chapter. But the resulting TOC tree is consistent, and I did not
>   want to change almost all headings.
> * Some of the files could use more :c:func:`...` references and general
>   ReST polish.
>
> But I don't want to make this patchset too large.

It's fine, we take it one step at a time.

On Fri, Mar 09, 2018 at 10:41:20AM -0700, Jonathan Corbet wrote:

> Anyway, I'm happy to take these through the docs tree or see them go via
> GPIO; Linus, what's your preference?

I might have some doc patches that could collide so I can take them.

I take it there will be a v2?

Yours,
Linus Walleij
--
To unsubscribe from this list: send the line "unsubscribe linux-gpio" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
J. Neuschäfer March 10, 2018, 1:29 p.m. UTC | #4
On Sat, Mar 10, 2018 at 12:50:46PM +0100, Linus Walleij wrote:
> On Fri, Mar 9, 2018 at 12:40 AM, Jonathan Neuschäfer
> <j.neuschaefer@gmx.net> wrote:
> 
> > The aim of this patchset is to move the GPIO subsystem's documentation
> > under Documentation/driver-api/gpio/ such that it is picked up by Sphinx
> > and compiled into HTML.
> 
> Awesome!
> 
> > I moved everything except for sysfs.txt, because
> > this file describes the legacy sysfs ABI, and doesn't seem to serve much
> > (non-historical) purpose anymore.
> >
> > There are still some rough edges:
> >
> > * I think the API documentation (kernel-doc) should be moved out of
> >   index.rst into more appropriate files.
> > * The headings are arguably wrong, because driver.rst, consumer.rst,
> >   etc. use the "document title" style, even though they are part of the
> >   GPIO chapter. But the resulting TOC tree is consistent, and I did not
> >   want to change almost all headings.
> > * Some of the files could use more :c:func:`...` references and general
> >   ReST polish.
> >
> > But I don't want to make this patchset too large.
> 
> It's fine, we take it one step at a time.
> 
> On Fri, Mar 09, 2018 at 10:41:20AM -0700, Jonathan Corbet wrote:
> 
> > Anyway, I'm happy to take these through the docs tree or see them go via
> > GPIO; Linus, what's your preference?
> 
> I might have some doc patches that could collide so I can take them.
> 
> I take it there will be a v2?

Not necessarily, but if I need to rebase on a different branch, or on
future linux-next, I'll do that. (Or if some other issue is found.)

I thought that patch 8/8 currently requires commit 93db446a424c ("mtd:
nand: move raw NAND related code to the raw/ subdir"), which is in next
through Boris Brezillon's nand tree, but this isn't true. The patchset
(currently) applies to both v4.16-rc4 and next, AFAICS.


Thanks,
Jonathan Neuschäfer
Linus Walleij March 23, 2018, 3:23 a.m. UTC | #5
On Fri, Mar 9, 2018 at 12:40 AM, Jonathan Neuschäfer
<j.neuschaefer@gmx.net> wrote:

> Jonathan Neuschäfer (8):
>   MAINTAINERS: GPIO: Add Documentation/driver-api/gpio/
>   Documentation: driver-api: Move gpio.rst to gpio/index.rst
>   Documentation: gpio: Move introduction to driver-api
>   Documentation: gpio: Move driver documentation to driver-api
>   Documentation: gpio: Move legacy documentation to driver-api
>   Documentation: gpio: Move gpiod_* consumer documentation to driver-api
>   Documentation: gpio: Move GPIO mapping documentation to driver-api
>   Documentation: gpio: Move drivers-on-gpio.txt to driver-api

I applied all 8 patches to devel for v4.17.

Yours,
Linus Walleij
--
To unsubscribe from this list: send the line "unsubscribe linux-gpio" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
J. Neuschäfer March 23, 2018, 2:24 p.m. UTC | #6
On Fri, Mar 23, 2018 at 04:23:21AM +0100, Linus Walleij wrote:
> On Fri, Mar 9, 2018 at 12:40 AM, Jonathan Neuschäfer
> <j.neuschaefer@gmx.net> wrote:
> 
> > Jonathan Neuschäfer (8):
> >   MAINTAINERS: GPIO: Add Documentation/driver-api/gpio/
> >   Documentation: driver-api: Move gpio.rst to gpio/index.rst
> >   Documentation: gpio: Move introduction to driver-api
> >   Documentation: gpio: Move driver documentation to driver-api
> >   Documentation: gpio: Move legacy documentation to driver-api
> >   Documentation: gpio: Move gpiod_* consumer documentation to driver-api
> >   Documentation: gpio: Move GPIO mapping documentation to driver-api
> >   Documentation: gpio: Move drivers-on-gpio.txt to driver-api
> 
> I applied all 8 patches to devel for v4.17.

Thanks!

Jonathan Neuschäfer