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

["Jonathan Neuschäfer" <j.neuschaefer@gmx.net>]

[-- Attachment #1: Type: text/plain, Size: 5444 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 819 bytes --]