Skip to contentSkip to conversation

ReST conversion patches not applied yet

PATCH Applied Mauro Carvalho Chehab 6 participants 20 messages Jul 31, 2019

Subsystems (13)
lore
Share & tools
lore
#0 lore raw

cover ReST conversion patches not applied yet

Hi Jon,

As promised, this is the rebased version of the patches that were not applied from the /26 patch series because you had merge conflicts.

They're all based on your docs-next branch, so should apply fine.

The first one fixes all but one error with a broken reference.

The only broken reference right now is due to a DT patch with was not accepted (no idea why), but whose driver is upstream.

Mauro Carvalho Chehab (6):
docs: fix a couple of new broken references
docs: writing-schema.md: convert from markdown to ReST
spi: docs: convert to ReST and add it to the kABI bookset
docs: fs: cifs: convert to ReST and add to admin-guide book
docs: fs: convert porting to ReST
docs: w1: convert to ReST and add to the kAPI group of docs

 Documentation/ABI/stable/sysfs-bus-w1         |   2 +-
 .../ABI/stable/sysfs-driver-w1_ds28e04        |   4 +-
 .../ABI/stable/sysfs-driver-w1_ds28ea00       |   2 +-
 .../AUTHORS => admin-guide/cifs/authors.rst}  |  64 +-
 .../CHANGES => admin-guide/cifs/changes.rst}  |   4 +
 Documentation/admin-guide/cifs/index.rst      |  21 +
 .../cifs/introduction.rst}                    |   8 +
 .../cifs/TODO => admin-guide/cifs/todo.rst}   |  87 +--
 .../README => admin-guide/cifs/usage.rst}     | 560 +++++++++++-------
 .../cifs/winucase_convert.pl                  |   0
 Documentation/admin-guide/index.rst           |   1 +
 .../bindings/sound/sun8i-a33-codec.txt        |   2 +-
 Documentation/devicetree/writing-schema.md    | 130 ----
 Documentation/devicetree/writing-schema.rst   | 153 +++++
 Documentation/filesystems/porting.rst         |   2 +-
 Documentation/index.rst                       |   2 +
 .../spi/{butterfly => butterfly.rst}          |  44 +-
 Documentation/spi/index.rst                   |  22 +
 Documentation/spi/{pxa2xx => pxa2xx.rst}      |  95 +--
 .../spi/{spi-lm70llp => spi-lm70llp.rst}      |  17 +-
 .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |   3 +
 .../spi/{spi-summary => spi-summary.rst}      | 105 ++--
 Documentation/spi/{spidev => spidev.rst}      |  30 +-
 Documentation/w1/index.rst                    |  21 +
 .../w1/masters/{ds2482 => ds2482.rst}         |  16 +-
 .../w1/masters/{ds2490 => ds2490.rst}         |   6 +-
 Documentation/w1/masters/index.rst            |  14 +
 Documentation/w1/masters/mxc-w1               |  12 -
 Documentation/w1/masters/mxc-w1.rst           |  17 +
 .../w1/masters/{omap-hdq => omap-hdq.rst}     |  12 +-
 .../w1/masters/{w1-gpio => w1-gpio.rst}       |  21 +-
 Documentation/w1/slaves/index.rst             |  16 +
 .../w1/slaves/{w1_ds2406 => w1_ds2406.rst}    |   4 +-
 .../w1/slaves/{w1_ds2413 => w1_ds2413.rst}    |   9 +
 Documentation/w1/slaves/w1_ds2423             |  47 --
 Documentation/w1/slaves/w1_ds2423.rst         |  54 ++
 .../w1/slaves/{w1_ds2438 => w1_ds2438.rst}    |  10 +-
 .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst}  |   5 +
 .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst}  |  16 +-
 .../w1/slaves/{w1_therm => w1_therm.rst}      |  11 +-
 .../w1/{w1.generic => w1-generic.rst}         |  88 +--
 .../w1/{w1.netlink => w1-netlink.rst}         |  89 +--
 MAINTAINERS                                   |   6 +-
 drivers/hwtracing/coresight/Kconfig           |   2 +-
 drivers/iio/dummy/iio_simple_dummy.c          |   2 +-
 drivers/spi/Kconfig                           |   2 +-
 drivers/spi/spi-butterfly.c                   |   2 +-
 drivers/spi/spi-lm70llp.c                     |   2 +-
 fs/jfs/Kconfig                                |   2 +-
 fs/ufs/Kconfig                                |   2 +-
 include/linux/platform_data/sc18is602.h       |   2 +-
 51 files changed, 1126 insertions(+), 722 deletions(-)
 rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
 rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
 create mode 100644 Documentation/admin-guide/cifs/index.rst
 rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
 rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
 rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
 rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
 delete mode 100644 Documentation/devicetree/writing-schema.md
 create mode 100644 Documentation/devicetree/writing-schema.rst
 rename Documentation/spi/{butterfly => butterfly.rst} (71%)
 create mode 100644 Documentation/spi/index.rst
 rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
 rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
 rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
 rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
 rename Documentation/spi/{spidev => spidev.rst} (90%)
 create mode 100644 Documentation/w1/index.rst
 rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
 rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
 create mode 100644 Documentation/w1/masters/index.rst
 delete mode 100644 Documentation/w1/masters/mxc-w1
 create mode 100644 Documentation/w1/masters/mxc-w1.rst
 rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
 rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
 create mode 100644 Documentation/w1/slaves/index.rst
 rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
 rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
 delete mode 100644 Documentation/w1/slaves/w1_ds2423
 create mode 100644 Documentation/w1/slaves/w1_ds2423.rst
 rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
 rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
 rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
 rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
Signature · 1 line
2.21.0
#1 lore raw

PATCH 1/6 docs: fix a couple of new broken references

Those are due to recent changes. Most of the issues can be automatically fixed with:

	$ ./scripts/documentation-file-ref-check --fix

The only exception was the sound binding with required manual work.

---
 Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt | 2 +-
 MAINTAINERS                                                 | 4 ++--
 drivers/hwtracing/coresight/Kconfig                         | 2 +-
 fs/jfs/Kconfig                                              | 2 +-
 fs/ufs/Kconfig                                              | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)
Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt +1 -1
index 2ca3d138528e..7ecf6bd60d27 100644
@@ -4,7 +4,7 @@ Allwinner SUN8I audio codec
 On Sun8i-A33 SoCs, the audio is separated in different parts:
 	  - A DAI driver. It uses the "sun4i-i2s" driver which is
 	  documented here:
-	  Documentation/devicetree/bindings/sound/sun4i-i2s.txt
+	  Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml
 	  - An analog part of the codec which is handled as PRCM registers.
 	  See Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt
 	  - An digital part of the codec which is documented in this current
MAINTAINERS +2 -2
index 6de82f019a52..f109a8bcffda 100644
@@ -8659,7 +8659,7 @@ L:	[email protected]
 W:	http://jfs.sourceforge.net/
 T:	git git://github.com/kleikamp/linux-shaggy.git
 S:	Maintained
-F:	Documentation/filesystems/jfs.txt
+F:	Documentation/admin-guide/jfs.rst
 F:	fs/jfs/
 
 JME NETWORK DRIVER
@@ -16439,7 +16439,7 @@ F:	drivers/hid/hid-udraw-ps3.c
 UFS FILESYSTEM
 M:	Evgeniy Dushistov <[email protected]>
 S:	Maintained
-F:	Documentation/filesystems/ufs.txt
+F:	Documentation/admin-guide/ufs.rst
 F:	fs/ufs/
 
 UHID USERSPACE HID IO DRIVER:
drivers/hwtracing/coresight/Kconfig +1 -1
index 14638db4991d..7a9f5fb08330 100644
@@ -106,7 +106,7 @@ config CORESIGHT_CPU_DEBUG
 	  can quickly get to know program counter (PC), secure state,
 	  exception level, etc. Before use debugging functionality, platform
 	  needs to ensure the clock domain and power domain are enabled
-	  properly, please refer Documentation/trace/coresight-cpu-debug.txt
+	  properly, please refer Documentation/trace/coresight-cpu-debug.rst
 	  for detailed description and the example for usage.
 
 endif
fs/jfs/Kconfig +1 -1
index 22a273bd4648..05cb0e8e4382 100644
@@ -5,7 +5,7 @@ config JFS_FS
 	select CRC32
 	help
 	  This is a port of IBM's Journaled Filesystem .  More information is
-	  available in the file <file:Documentation/filesystems/jfs.txt>.
+	  available in the file <file:Documentation/admin-guide/jfs.rst>.
 
 	  If you do not intend to use the JFS filesystem, say N.
 
fs/ufs/Kconfig +1 -1
index fcb41516ea59..6d30adb6b890 100644
@@ -9,7 +9,7 @@ config UFS_FS
 	  this file system as well. Saying Y here will allow you to read from
 	  these partitions; if you also want to write to them, say Y to the
 	  experimental "UFS file system write support", below. Please read the
-	  file <file:Documentation/filesystems/ufs.txt> for more information.
+	  file <file:Documentation/admin-guide/ufs.rst> for more information.
 
           The recently released UFS2 variant (used in FreeBSD 5.x) is
           READ-ONLY supported.
Signature · 1 line
2.21.0
Acked-by on v1 1/6
#2 lore raw

Re: [PATCH 1/6] docs: fix a couple of new broken references

Quoted 4 lines · Mauro Carvalho Chehab

Those are due to recent changes. Most of the issues can be automatically fixed with:

Quoted 8 lines
        $ ./scripts/documentation-file-ref-check --fix

The only exception was the sound binding with required manual work.

---
 Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt | 2 +-
Quoted 5 lines
 MAINTAINERS                                                 | 4 ++--
 drivers/hwtracing/coresight/Kconfig                         | 2 +-
 fs/jfs/Kconfig                                              | 2 +-
 fs/ufs/Kconfig                                              | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)
Acked-by on v1 1/6
#3 lore raw

Re: [PATCH 1/6] docs: fix a couple of new broken references

In reply to Mauro Carvalho Chehab
Quoted 9 lines · Mauro Carvalho Chehab

Those are due to recent changes. Most of the issues can be automatically fixed with:

	$ ./scripts/documentation-file-ref-check --fix

The only exception was the sound binding with required manual work.

Quoted 83 lines
---
 Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt | 2 +-
 MAINTAINERS                                                 | 4 ++--
 drivers/hwtracing/coresight/Kconfig                         | 2 +-
 fs/jfs/Kconfig                                              | 2 +-
 fs/ufs/Kconfig                                              | 2 +-
 5 files changed, 6 insertions(+), 6 deletions(-)
Documentation/devicetree/bindings/sound/sun8i-a33-codec.txt +1 -1
index 2ca3d138528e..7ecf6bd60d27 100644
@@ -4,7 +4,7 @@ Allwinner SUN8I audio codec
 On Sun8i-A33 SoCs, the audio is separated in different parts:
 	  - A DAI driver. It uses the "sun4i-i2s" driver which is
 	  documented here:
-	  Documentation/devicetree/bindings/sound/sun4i-i2s.txt
+	  Documentation/devicetree/bindings/sound/allwinner,sun4i-a10-i2s.yaml
 	  - An analog part of the codec which is handled as PRCM registers.
 	  See Documentation/devicetree/bindings/sound/sun8i-codec-analog.txt
 	  - An digital part of the codec which is documented in this current
MAINTAINERS +2 -2
index 6de82f019a52..f109a8bcffda 100644
@@ -8659,7 +8659,7 @@ L:	[email protected]
 W:	http://jfs.sourceforge.net/
 T:	git git://github.com/kleikamp/linux-shaggy.git
 S:	Maintained
-F:	Documentation/filesystems/jfs.txt
+F:	Documentation/admin-guide/jfs.rst
 F:	fs/jfs/
 
 JME NETWORK DRIVER
@@ -16439,7 +16439,7 @@ F:	drivers/hid/hid-udraw-ps3.c
 UFS FILESYSTEM
 M:	Evgeniy Dushistov <[email protected]>
 S:	Maintained
-F:	Documentation/filesystems/ufs.txt
+F:	Documentation/admin-guide/ufs.rst
 F:	fs/ufs/
 
 UHID USERSPACE HID IO DRIVER:
drivers/hwtracing/coresight/Kconfig +1 -1
index 14638db4991d..7a9f5fb08330 100644
@@ -106,7 +106,7 @@ config CORESIGHT_CPU_DEBUG
 	  can quickly get to know program counter (PC), secure state,
 	  exception level, etc. Before use debugging functionality, platform
 	  needs to ensure the clock domain and power domain are enabled
-	  properly, please refer Documentation/trace/coresight-cpu-debug.txt
+	  properly, please refer Documentation/trace/coresight-cpu-debug.rst
 	  for detailed description and the example for usage.
 
 endif
fs/jfs/Kconfig +1 -1
index 22a273bd4648..05cb0e8e4382 100644
@@ -5,7 +5,7 @@ config JFS_FS
 	select CRC32
 	help
 	  This is a port of IBM's Journaled Filesystem .  More information is
-	  available in the file <file:Documentation/filesystems/jfs.txt>.
+	  available in the file <file:Documentation/admin-guide/jfs.rst>.
 
 	  If you do not intend to use the JFS filesystem, say N.
 
fs/ufs/Kconfig +1 -1
index fcb41516ea59..6d30adb6b890 100644
@@ -9,7 +9,7 @@ config UFS_FS
 	  this file system as well. Saying Y here will allow you to read from
 	  these partitions; if you also want to write to them, say Y to the
 	  experimental "UFS file system write support", below. Please read the
-	  file <file:Documentation/filesystems/ufs.txt> for more information.
+	  file <file:Documentation/admin-guide/ufs.rst> for more information.
 
           The recently released UFS2 variant (used in FreeBSD 5.x) is
           READ-ONLY supported.
#4 lore raw

PATCH 2/6 docs: writing-schema.md: convert from markdown to ReST

In reply to Mauro Carvalho Chehab

The documentation standard is ReST and not markdown.

---
 Documentation/devicetree/writing-schema.md  | 130 -----------------
 Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++++
 2 files changed, 153 insertions(+), 130 deletions(-)
 delete mode 100644 Documentation/devicetree/writing-schema.md
 create mode 100644 Documentation/devicetree/writing-schema.rst
Documentation/devicetree/writing-schema.md deleted +0 -130
deleted file mode 100644
index dc032db36262..000000000000
@@ -1,130 +0,0 @@
-# Writing DeviceTree Bindings in json-schema
-
-Devicetree bindings are written using json-schema vocabulary. Schema files are
-written in a JSON compatible subset of YAML. YAML is used instead of JSON as it
-considered more human readable and has some advantages such as allowing
-comments (Prefixed with '#').
-
-## Schema Contents
-
-Each schema doc is a structured json-schema which is defined by a set of
-top-level properties. Generally, there is one binding defined per file. The
-top-level json-schema properties used are:
-
-- __$id__ - A json-schema unique identifier string. The string must be a valid
-URI typically containing the binding's filename and path. For DT schema, it must
-begin with "http://devicetree.org/schemas/". The URL is used in constructing
-references to other files specified in schema "$ref" properties. A $ref values
-with a leading '/' will have the hostname prepended. A $ref value a relative
-path or filename only will be prepended with the hostname and path components
-of the current schema file's '$id' value. A URL is used even for local files,
-but there may not actually be files present at those locations.
-
-- __$schema__ - Indicates the meta-schema the schema file adheres to.
-
-- __title__ - A one line description on the contents of the binding schema.
-
-- __maintainers__ - A DT specific property. Contains a list of email address(es)
-for maintainers of this binding.
-
-- __description__ - Optional. A multi-line text block containing any detailed
-information about this binding. It should contain things such as what the block
-or device does, standards the device conforms to, and links to datasheets for
-more information.
-
-- __select__ - Optional. A json-schema used to match nodes for applying the
-schema. By default without 'select', nodes are matched against their possible
-compatible string values or node name. Most bindings should not need select.
-
-- __allOf__ - Optional. A list of other schemas to include. This is used to
-include other schemas the binding conforms to. This may be schemas for a
-particular class of devices such as I2C or SPI controllers.
-
-- __properties__ - A set of sub-schema defining all the DT properties for the
-binding. The exact schema syntax depends on whether properties are known,
-common properties (e.g. 'interrupts') or are binding/vendor specific properties.
-
-  A property can also define a child DT node with child properties defined
-under it.
-
-  For more details on properties sections, see 'Property Schema' section.
-
-- __patternProperties__ - Optional. Similar to 'properties', but names are regex.
-
-- __required__ - A list of DT properties from the 'properties' section that
-must always be present.
-
-- __examples__ - Optional. A list of one or more DTS hunks implementing the
-binding. Note: YAML doesn't allow leading tabs, so spaces must be used instead.
-
-Unless noted otherwise, all properties are required.
-
-## Property Schema
-
-The 'properties' section of the schema contains all the DT properties for a
-binding. Each property contains a set of constraints using json-schema
-vocabulary for that property. The properties schemas are what is used for
-validation of DT files.
-
-For common properties, only additional constraints not covered by the common
-binding schema need to be defined such as how many values are valid or what
-possible values are valid.
-
-Vendor specific properties will typically need more detailed schema. With the
-exception of boolean properties, they should have a reference to a type in
-schemas/types.yaml. A "description" property is always required.
-
-The Devicetree schemas don't exactly match the YAML encoded DT data produced by
-dtc. They are simplified to make them more compact and avoid a bunch of
-boilerplate. The tools process the schema files to produce the final schema for
-validation. There are currently 2 transformations the tools perform.
-
-The default for arrays in json-schema is they are variable sized and allow more
-entries than explicitly defined. This can be restricted by defining 'minItems',
-'maxItems', and 'additionalItems'. However, for DeviceTree Schemas, a fixed
-size is desired in most cases, so these properties are added based on the
-number of entries in an 'items' list.
-
-The YAML Devicetree format also makes all string values an array and scalar
-values a matrix (in order to define groupings) even when only a single value
-is present. Single entries in schemas are fixed up to match this encoding.
-
-## Testing
-
-### Dependencies
-
-The DT schema project must be installed in order to validate the DT schema
-binding documents and validate DTS files using the DT schema. The DT schema
-project can be installed with pip:
-
-`pip3 install git+https://github.com/devicetree-org/dt-schema.git@master`
-
-dtc must also be built with YAML output support enabled. This requires that
-libyaml and its headers be installed on the host system.
-
-### Running checks
-
-The DT schema binding documents must be validated using the meta-schema (the
-schema for the schema) to ensure they are both valid json-schema and valid
-binding schema. All of the DT binding documents can be validated using the
-`dt_binding_check` target:
-
-`make dt_binding_check`
-
-In order to perform validation of DT source files, use the `dtbs_check` target:
-
-`make dtbs_check`
-
-This will first run the `dt_binding_check` which generates the processed schema.
-
-It is also possible to run checks with a single schema file by setting the
-'DT_SCHEMA_FILES' variable to a specific schema file.
-
-`make dtbs_check DT_SCHEMA_FILES=Documentation/devicetree/bindings/trivial-devices.yaml`
-
-
-## json-schema Resources
-
-[JSON-Schema Specifications](http://json-schema.org/)
-
-[Using JSON Schema Book](http://usingjsonschema.com/)
Documentation/devicetree/writing-schema.rst new file +153 -0

153 lines not on this page · raw message

Signature · 1 line
2.21.0
maintainer Applied
#5 lore raw

Re: [PATCH 2/6] docs: writing-schema.md: convert from markdown to ReST

Quoted 10 lines · Mauro Carvalho Chehab

The documentation standard is ReST and not markdown.

---
 Documentation/devicetree/writing-schema.md  | 130 -----------------
 Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++++
 2 files changed, 153 insertions(+), 130 deletions(-)
 delete mode 100644 Documentation/devicetree/writing-schema.md
 create mode 100644 Documentation/devicetree/writing-schema.rst

Applied, thanks.

Rob

maintainer Applied
#6 lore raw

Re: [PATCH 2/6] docs: writing-schema.md: convert from markdown to ReST

Quoted 12 lines · On Wed, 31 Jul 2019 14:45:00 -0600 Rob Herring <[email protected]> wrote:
Quoted 10 lines · Mauro Carvalho Chehab

The documentation standard is ReST and not markdown.

---
 Documentation/devicetree/writing-schema.md  | 130 -----------------
 Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++++
 2 files changed, 153 insertions(+), 130 deletions(-)
 delete mode 100644 Documentation/devicetree/writing-schema.md
 create mode 100644 Documentation/devicetree/writing-schema.rst  
Quoted 1 line

Applied, thanks.

I've applied that to docs-next as well - your ack suggested to me that you weren't intending to take it...

jon

maintainer
#7 lore raw

Re: [PATCH 2/6] docs: writing-schema.md: convert from markdown to ReST

Quoted 16 lines · Jonathan Corbet
Quoted 12 lines · On Wed, 31 Jul 2019 14:45:00 -0600 Rob Herring <[email protected]> wrote:
Quoted 10 lines · Mauro Carvalho Chehab

The documentation standard is ReST and not markdown.

---
 Documentation/devicetree/writing-schema.md  | 130 -----------------
 Documentation/devicetree/writing-schema.rst | 153 ++++++++++++++++++++
 2 files changed, 153 insertions(+), 130 deletions(-)
 delete mode 100644 Documentation/devicetree/writing-schema.md
 create mode 100644 Documentation/devicetree/writing-schema.rst
Quoted 4 lines
Quoted 1 line

Applied, thanks.

I've applied that to docs-next as well - your ack suggested to me that you weren't intending to take it...

Well, I acked it first when it was in one big patch, then suggested it be split out in case we have changes to it (wishful thinking).

Rob

#8 lore raw

PATCH 3/6 spi: docs: convert to ReST and add it to the kABI bookset

In reply to Mauro Carvalho Chehab

While there's one file there with briefily describes the uAPI, the documentation was written just like most subsystems: focused on kernel developers. So, add it together with driver-api books.

---
 Documentation/index.rst                       |   1 +
 .../spi/{butterfly => butterfly.rst}          |  44 ++++----
 Documentation/spi/index.rst                   |  22 ++++
 Documentation/spi/{pxa2xx => pxa2xx.rst}      |  95 ++++++++--------
 .../spi/{spi-lm70llp => spi-lm70llp.rst}      |  17 ++-
 .../spi/{spi-sc18is602 => spi-sc18is602.rst}  |   3 +
 .../spi/{spi-summary => spi-summary.rst}      | 105 ++++++++++--------
 Documentation/spi/{spidev => spidev.rst}      |  30 +++--
 drivers/iio/dummy/iio_simple_dummy.c          |   2 +-
 drivers/spi/Kconfig                           |   2 +-
 drivers/spi/spi-butterfly.c                   |   2 +-
 drivers/spi/spi-lm70llp.c                     |   2 +-
 include/linux/platform_data/sc18is602.h       |   2 +-
 13 files changed, 198 insertions(+), 129 deletions(-)
 rename Documentation/spi/{butterfly => butterfly.rst} (71%)
 create mode 100644 Documentation/spi/index.rst
 rename Documentation/spi/{pxa2xx => pxa2xx.rst} (83%)
 rename Documentation/spi/{spi-lm70llp => spi-lm70llp.rst} (88%)
 rename Documentation/spi/{spi-sc18is602 => spi-sc18is602.rst} (97%)
 rename Documentation/spi/{spi-summary => spi-summary.rst} (93%)
 rename Documentation/spi/{spidev => spidev.rst} (90%)
Documentation/index.rst +1 -0
index 6217acab92db..472b8abe52e9 100644
@@ -116,6 +116,7 @@ needed).
    power/index
    target/index
    timers/index
+   spi/index
    watchdog/index
    virtual/index
    input/index
Documentation/spi/butterfly.rst renamed from Documentation/spi/butterfly +25 -19

66 lines not on this page · raw message

Documentation/spi/index.rst new file +22 -0
new file mode 100644
index 000000000000..06c34ea11bcf
@@ -0,0 +1,22 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=================================
+Serial Peripheral Interface (SPI)
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   spi-summary
+   spidev
+   butterfly
+   pxa2xx
+   spi-lm70llp
+   spi-sc18is602
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
Documentation/spi/pxa2xx.rst renamed from Documentation/spi/pxa2xx +50 -45

214 lines not on this page · raw message

Documentation/spi/spi-lm70llp.rst renamed from Documentation/spi/spi-lm70llp +11 -6
similarity index 88%
rename from Documentation/spi/spi-lm70llp
rename to Documentation/spi/spi-lm70llp.rst
index 463f6d01fa15..07631aef4343 100644
@@ -1,8 +1,11 @@
+==============================================
 spi_lm70llp :  LM70-LLP parport-to-SPI adapter
 ==============================================
 
 Supported board/chip:
+
   * National Semiconductor LM70 LLP evaluation board
+
     Datasheet: http://www.national.com/pf/LM/LM70.html
 
 Author:
@@ -29,9 +32,10 @@ available (on page 4) here:
 
 The hardware interfacing on the LM70 LLP eval board is as follows:
 
+   ======== == =========   ==========
    Parallel                 LM70 LLP
-     Port      Direction   JP2 Header
-   ----------- --------- ----------------
+     Port   .  Direction   JP2 Header
+   ======== == =========   ==========
       D0     2      -         -
       D1     3     -->      V+   5
       D2     4     -->      V+   5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows:
       D7     9     -->      SI/O 5
      GND    25      -       GND  7
     Select  13     <--      SI/O 1
-   ----------- --------- ----------------
+   ======== == =========   ==========
 
 Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin
 is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13.
 
 Thanks to
 ---------
-o David Brownell for mentoring the SPI-side driver development.
-o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
-o Nadir Billimoria for help interpreting the circuit schematic.
+
+- David Brownell for mentoring the SPI-side driver development.
+- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.
+- Nadir Billimoria for help interpreting the circuit schematic.
Documentation/spi/spi-sc18is602.rst renamed from Documentation/spi/spi-sc18is602 +3 -0
similarity index 97%
rename from Documentation/spi/spi-sc18is602
rename to Documentation/spi/spi-sc18is602.rst
index 0feffd5af411..2a31dc722321 100644
@@ -1,8 +1,11 @@
+===========================
 Kernel driver spi-sc18is602
 ===========================
 
 Supported chips:
+
   * NXP SI18IS602/602B/603
+
     Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf
 
 Author:
Documentation/spi/spi-summary.rst renamed from Documentation/spi/spi-summary +59 -46

254 lines not on this page · raw message

Documentation/spi/spidev.rst renamed from Documentation/spi/spidev +22 -8
similarity index 90%
rename from Documentation/spi/spidev
rename to Documentation/spi/spidev.rst
index 3d14035b1766..f05dbc5ccdbc 100644
@@ -1,7 +1,13 @@
+=================
+SPI userspace API
+=================
+
 SPI devices have a limited userspace API, supporting basic half-duplex
 read() and write() access to SPI slave devices.  Using ioctl() requests,
 full duplex transfers and device I/O configuration are also available.
 
+::
+
 	#include <fcntl.h>
 	#include <unistd.h>
 	#include <sys/ioctl.h>
@@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
 busybox; it's less featureful, but often enough.)  For a SPI device with
 chipselect C on bus B, you should see:
 
-    /dev/spidevB.C ... character special device, major number 153 with
+    /dev/spidevB.C ...
+	character special device, major number 153 with
 	a dynamically chosen minor device number.  This is the node
 	that userspace programs will open, created by "udev" or "mdev".
 
-    /sys/devices/.../spiB.C ... as usual, the SPI device node will
+    /sys/devices/.../spiB.C ...
+	as usual, the SPI device node will
 	be a child of its SPI master controller.
 
-    /sys/class/spidev/spidevB.C ... created when the "spidev" driver
+    /sys/class/spidev/spidevB.C ...
+	created when the "spidev" driver
 	binds to that device.  (Directory or symlink, based on whether
 	or not you enabled the "deprecated sysfs files" Kconfig option.)
 
@@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
 Several ioctl() requests let your driver read or override the device's current
 settings for data transfer parameters:
 
-    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
+    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
+	pass a pointer to a byte which will
 	return (RD) or assign (WR) the SPI transfer mode.  Use the constants
 	SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
 	(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
@@ -88,22 +98,26 @@ settings for data transfer parameters:
 	Note that this request is limited to SPI mode flags that fit in a
 	single byte.
 
-    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
+    SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
+	pass a pointer to a uin32_t
 	which will return (RD) or assign (WR) the full SPI transfer mode,
 	not limited to the bits that fit in one byte.
 
-    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
+    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
+	pass a pointer to a byte
 	which will return (RD) or assign (WR) the bit justification used to
 	transfer SPI words.  Zero indicates MSB-first; other values indicate
 	the less common LSB-first encoding.  In both cases the specified value
 	is right-justified in each word, so that unused (TX) or undefined (RX)
 	bits are in the MSBs.
 
-    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
+    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
+	pass a pointer to
 	a byte which will return (RD) or assign (WR) the number of bits in
 	each SPI transfer word.  The value zero signifies eight bits.
 
-    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
+    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
+	pass a pointer to a
 	u32 which will return (RD) or assign (WR) the maximum SPI transfer
 	speed, in Hz.  The controller can't necessarily assign that specific
 	clock speed.
drivers/iio/dummy/iio_simple_dummy.c +1 -1
index d28974ad9e0e..6cb02299a215 100644
@@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
  * i2c:
  * Documentation/i2c/writing-clients.rst
  * spi:
- * Documentation/spi/spi-summary
+ * Documentation/spi/spi-summary.rst
  */
 static const struct iio_sw_device_ops iio_dummy_device_ops = {
 	.probe = iio_dummy_probe,
drivers/spi/Kconfig +1 -1
index 3a1d8f1170de..d5a24fe983e7 100644
@@ -543,7 +543,7 @@ config SPI_PXA2XX
 	help
 	  This enables using a PXA2xx or Sodaville SSP port as a SPI master
 	  controller. The driver can be configured to use any SSP port and
-	  additional documentation can be found a Documentation/spi/pxa2xx.
+	  additional documentation can be found a Documentation/spi/pxa2xx.rst.
 
 config SPI_PXA2XX_PCI
 	def_tristate SPI_PXA2XX && PCI && COMMON_CLK
drivers/spi/spi-butterfly.c +1 -1
index 8c77d1114ad3..7e71a351f3b7 100644
@@ -23,7 +23,7 @@
  * with a battery powered AVR microcontroller and lots of goodies.  You
  * can use GCC to develop firmware for this.
  *
- * See Documentation/spi/butterfly for information about how to build
+ * See Documentation/spi/butterfly.rst for information about how to build
  * and use this custom parallel port cable.
  */
 
drivers/spi/spi-lm70llp.c +1 -1
index f18f912c9dea..174dba29b1dd 100644
@@ -34,7 +34,7 @@
  * available (on page 4) here:
  *  http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
  *
- * Also see Documentation/spi/spi-lm70llp.  The SPI<->parport code here is
+ * Also see Documentation/spi/spi-lm70llp.rst.  The SPI<->parport code here is
  * (heavily) based on spi-butterfly by David Brownell.
  *
  * The LM70 LLP connects to the PC parallel port in the following manner:
include/linux/platform_data/sc18is602.h +1 -1
index e066d3b0d6d8..0e91489edfe6 100644
@@ -4,7 +4,7 @@
  *
  * Copyright (C) 2012 Guenter Roeck <[email protected]>
  *
- * For further information, see the Documentation/spi/spi-sc18is602 file.
+ * For further information, see the Documentation/spi/spi-sc18is602.rst file.
  */
 
 /**
Signature · 1 line
2.21.0
#9 lore raw

PATCH 4/6 docs: fs: cifs: convert to ReST and add to admin-guide book

In reply to Mauro Carvalho Chehab

The filenames for cifs documentation is not using the same convention as almost all Kernel documents is using. So, rename them to a more appropriate name. Then, manually convert the documentation files for CIFS to ReST.

By doing a manual conversion, we can preserve the original author's style, while making it to look more like the other Kernel documents.

Most of the conversion here is trivial. The most complex one was the README file (which was renamed to usage.rst).

---
 .../AUTHORS => admin-guide/cifs/authors.rst}  |  64 +-
 .../CHANGES => admin-guide/cifs/changes.rst}  |   4 +
 Documentation/admin-guide/cifs/index.rst      |  21 +
 .../cifs/introduction.rst}                    |   8 +
 .../cifs/TODO => admin-guide/cifs/todo.rst}   |  87 +--
 .../README => admin-guide/cifs/usage.rst}     | 560 +++++++++++-------
 .../cifs/winucase_convert.pl                  |   0
 Documentation/admin-guide/index.rst           |   1 +
 MAINTAINERS                                   |   2 +-
 9 files changed, 460 insertions(+), 287 deletions(-)
 rename Documentation/{filesystems/cifs/AUTHORS => admin-guide/cifs/authors.rst} (60%)
 rename Documentation/{filesystems/cifs/CHANGES => admin-guide/cifs/changes.rst} (91%)
 create mode 100644 Documentation/admin-guide/cifs/index.rst
 rename Documentation/{filesystems/cifs/cifs.txt => admin-guide/cifs/introduction.rst} (98%)
 rename Documentation/{filesystems/cifs/TODO => admin-guide/cifs/todo.rst} (58%)
 rename Documentation/{filesystems/cifs/README => admin-guide/cifs/usage.rst} (72%)
 rename Documentation/{filesystems => admin-guide}/cifs/winucase_convert.pl (100%)
Documentation/admin-guide/cifs/authors.rst renamed from Documentation/filesystems/cifs/AUTHORS +35 -29
similarity index 60%
rename from Documentation/filesystems/cifs/AUTHORS
rename to Documentation/admin-guide/cifs/authors.rst
index 75865da2ce14..b02d6dd6c070 100644
@@ -1,5 +1,10 @@
+=======
+Authors
+=======
+
 Original Author
-===============
+---------------
+
 Steve French ([email protected])
 
 The author wishes to express his appreciation and thanks to:
@@ -12,7 +17,7 @@ side of the original CIFS Unix extensions and reviewing and implementing
 portions of the newer CIFS POSIX extensions into the Samba 3 file server. Thank
 Dave Boutcher of IBM Rochester (author of the OS/400 smb/cifs filesystem client)
 for proving years ago that very good smb/cifs clients could be done on Unix-like
-operating systems.  Volker Lendecke, Andrew Tridgell, Urban Widmark, John 
+operating systems.  Volker Lendecke, Andrew Tridgell, Urban Widmark, John
 Newbigin and others for their work on the Linux smbfs module.  Thanks to
 the other members of the Storage Network Industry Association CIFS Technical
 Workgroup for their work specifying this highly complex protocol and finally
@@ -20,33 +25,34 @@ thanks to the Samba team for their technical advice and encouragement.
 
 Patch Contributors
 ------------------
-Zwane Mwaikambo
-Andi Kleen
-Amrut Joshi
-Shobhit Dayal
-Sergey Vlasov
-Richard Hughes
-Yury Umanets
-Mark Hamzy (for some of the early cifs IPv6 work)
-Domen Puncer
-Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
-Vince Negri and Dave Stahl (for finding an important caching bug)
-Adrian Bunk (kcalloc cleanups)
-Miklos Szeredi 
-Kazeon team for various fixes especially for 2.4 version.
-Asser Ferno (Change Notify support)
-Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
-Gunter Kukkukk (testing and suggestions for support of old servers)
-Igor Mammedov (DFS support)
-Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
-Scott Lovenberg
-Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
-Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
-Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
-Shirish Pargaonkar (for many ACL patches over the years)
-Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
-Paulo Alcantara
-Long Li (some great work on RDMA, SMB Direct)
+
+- Zwane Mwaikambo
+- Andi Kleen
+- Amrut Joshi
+- Shobhit Dayal
+- Sergey Vlasov
+- Richard Hughes
+- Yury Umanets
+- Mark Hamzy (for some of the early cifs IPv6 work)
+- Domen Puncer
+- Jesper Juhl (in particular for lots of whitespace/formatting cleanup)
+- Vince Negri and Dave Stahl (for finding an important caching bug)
+- Adrian Bunk (kcalloc cleanups)
+- Miklos Szeredi
+- Kazeon team for various fixes especially for 2.4 version.
+- Asser Ferno (Change Notify support)
+- Shaggy (Dave Kleikamp) for innumerable small fs suggestions and some good cleanup
+- Gunter Kukkukk (testing and suggestions for support of old servers)
+- Igor Mammedov (DFS support)
+- Jeff Layton (many, many fixes, as well as great work on the cifs Kerberos code)
+- Scott Lovenberg
+- Pavel Shilovsky (for great work adding SMB2 support, and various SMB3 features)
+- Aurelien Aptel (for DFS SMB3 work and some key bug fixes)
+- Ronnie Sahlberg (for SMB3 xattr work, bug fixes, and lots of great work on compounding)
+- Shirish Pargaonkar (for many ACL patches over the years)
+- Sachin Prabhu (many bug fixes, including for reconnect, copy offload and security)
+- Paulo Alcantara
+- Long Li (some great work on RDMA, SMB Direct)
 
 
 Test case and Bug Report contributors
Documentation/admin-guide/cifs/changes.rst renamed from Documentation/filesystems/cifs/CHANGES +4 -0
similarity index 91%
rename from Documentation/filesystems/cifs/CHANGES
rename to Documentation/admin-guide/cifs/changes.rst
index 1df7f4910eb2..71f2ecb62299 100644
@@ -1,3 +1,7 @@
+=======
+Changes
+=======
+
 See https://wiki.samba.org/index.php/LinuxCIFSKernel for summary
 information (that may be easier to read than parsing the output of
 "git log fs/cifs") about fixes/improvements to CIFS/SMB2/SMB3 support (changes
Documentation/admin-guide/cifs/index.rst new file +21 -0
new file mode 100644
index 000000000000..fad5268635f5
@@ -0,0 +1,21 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====
+CIFS
+====
+
+.. toctree::
+   :maxdepth: 2
+
+   introduction
+   usage
+   todo
+   changes
+   authors
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
Documentation/admin-guide/cifs/introduction.rst renamed from Documentation/filesystems/cifs/cifs.txt +8 -0
similarity index 98%
rename from Documentation/filesystems/cifs/cifs.txt
rename to Documentation/admin-guide/cifs/introduction.rst
index 1be3d21c286e..0b98f672d36f 100644
@@ -1,3 +1,7 @@
+============
+Introduction
+============
+
   This is the client VFS module for the SMB3 NAS protocol as well
   as for older dialects such as the Common Internet File System (CIFS)
   protocol which was the successor to the Server Message Block
@@ -33,7 +37,9 @@
   tools (including smbinfo and setcifsacl) that can be obtained from
 
       https://git.samba.org/?p=cifs-utils.git
+
   or
+
       git://git.samba.org/cifs-utils.git
 
   mount.cifs should be installed in the directory with the other mount helpers.
@@ -41,5 +47,7 @@
   For more information on the module see the project wiki page at
 
       https://wiki.samba.org/index.php/LinuxCIFS
+
   and
+
       https://wiki.samba.org/index.php/LinuxCIFS_utils
Documentation/admin-guide/cifs/todo.rst renamed from Documentation/filesystems/cifs/TODO +47 -40

156 lines not on this page · raw message

Documentation/admin-guide/cifs/usage.rst renamed from Documentation/filesystems/cifs/README +343 -217

1,000 lines not on this page · raw message

Documentation/admin-guide/cifs/winucase_convert.pl renamed from Documentation/filesystems/cifs/winucase_convert.pl +0 -0
similarity index 100%
rename from Documentation/filesystems/cifs/winucase_convert.pl
rename to Documentation/admin-guide/cifs/winucase_convert.pl
Documentation/admin-guide/index.rst +1 -0
index 534373816d7f..34cc20ee7f3a 100644
@@ -77,6 +77,7 @@ configure specific aspects of kernel behavior to your liking.
    blockdev/index
    ext4
    binderfs
+   cifs/index
    xfs
    jfs
    ufs
MAINTAINERS +1 -1
index f109a8bcffda..0abd3b598a1e 100644
@@ -4099,7 +4099,7 @@ L:	[email protected] (moderated for non-subscribers)
 W:	http://linux-cifs.samba.org/
 T:	git git://git.samba.org/sfrench/cifs-2.6.git
 S:	Supported
-F:	Documentation/filesystems/cifs/
+F:	Documentation/admin-guide/cifs/
 F:	fs/cifs/
 
 COMPACTPCI HOTPLUG CORE
Signature · 1 line
2.21.0
#10 lore raw

PATCH 5/6 docs: fs: convert porting to ReST

In reply to Mauro Carvalho Chehab

This file has its own proper style, except that, after a while, the coding style gets violated and whitespaces are placed on different ways.

As Sphinx and ReST are very sentitive to whitespace differences, I had to opt if each entry after required/mandatory/... fields should start with zero spaces or with a tab. I opted to start them all from the zero position, in order to avoid needing to break lines with more than 80 columns, with would make harder for review.

Most of the other changes at porting.rst were made to use an unified notation with works nice as a text file while also produce a good html output after being parsed.

---
 Documentation/filesystems/porting.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/filesystems/porting.rst +1 -1
index 66aa521e6376..f18506083ced 100644
@@ -158,7 +158,7 @@ Callers of notify_change() need ->i_mutex now.
 New super_block field ``struct export_operations *s_export_op`` for
 explicit support for exporting, e.g. via NFS.  The structure is fully
 documented at its declaration in include/linux/fs.h, and in
-Documentation/filesystems/nfs/Exporting.
+Documentation/filesystems/nfs/exporting.rst.
 
 Briefly it allows for the definition of decode_fh and encode_fh operations
 to encode and decode filehandles, and allows the filesystem to use
Signature · 1 line
2.21.0
maintainer
#11 lore raw

Re: [PATCH 5/6] docs: fs: convert porting to ReST

Quoted 24 lines · On Wed, 31 Jul 2019 17:08:52 -0300 Mauro Carvalho Chehab…

This file has its own proper style, except that, after a while, the coding style gets violated and whitespaces are placed on different ways.

As Sphinx and ReST are very sentitive to whitespace differences, I had to opt if each entry after required/mandatory/... fields should start with zero spaces or with a tab. I opted to start them all from the zero position, in order to avoid needing to break lines with more than 80 columns, with would make harder for review.

Most of the other changes at porting.rst were made to use an unified notation with works nice as a text file while also produce a good html output after being parsed.

---
 Documentation/filesystems/porting.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/filesystems/porting.rst +0 -0
index 66aa521e6376..f18506083ced 100644

Documentation/filesystems/porting.rst Callers of notify_change() need ->i_mutex now. · line 164

Quoted 8 lines
Documentation/filesystems/porting.rst +1 -1
@@ -158,7 +158,7 @@ Callers of notify_change() need ->i_mutex now.
 New super_block field ``struct export_operations *s_export_op`` for
 explicit support for exporting, e.g. via NFS.  The structure is fully
 documented at its declaration in include/linux/fs.h, and in
-Documentation/filesystems/nfs/Exporting.
+Documentation/filesystems/nfs/exporting.rst.
 
 Briefly it allows for the definition of decode_fh and encode_fh operations
 to encode and decode filehandles, and allows the filesystem to use

This patch doesn't match the changelog at all. I think it's one leftover fix after the previous version of the patch was applied...?

jon

#12 lore raw

Re: [PATCH 5/6] docs: fs: convert porting to ReST

Em Wed, 31 Jul 2019 14:17:07 -0600
Jonathan Corbet <[email protected]> escreveu:

Quoted 33 lines
Quoted 30 lines · On Wed, 31 Jul 2019 17:08:52 -0300 Mauro Carvalho Chehab…

This file has its own proper style, except that, after a while, the coding style gets violated and whitespaces are placed on different ways.

As Sphinx and ReST are very sentitive to whitespace differences, I had to opt if each entry after required/mandatory/... fields should start with zero spaces or with a tab. I opted to start them all from the zero position, in order to avoid needing to break lines with more than 80 columns, with would make harder for review.

Most of the other changes at porting.rst were made to use an unified notation with works nice as a text file while also produce a good html output after being parsed.

---
 Documentation/filesystems/porting.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/filesystems/porting.rst +1 -1
index 66aa521e6376..f18506083ced 100644
@@ -158,7 +158,7 @@ Callers of notify_change() need ->i_mutex now.
 New super_block field ``struct export_operations *s_export_op`` for
 explicit support for exporting, e.g. via NFS.  The structure is fully
 documented at its declaration in include/linux/fs.h, and in
-Documentation/filesystems/nfs/Exporting.
+Documentation/filesystems/nfs/exporting.rst.
 
Quoted 5 lines

Documentation/filesystems/porting.rst Callers of notify_change() need ->i_mutex now. · line 164

Quoted 2 lines
Documentation/filesystems/porting.rst +0 -0
 Briefly it allows for the definition of decode_fh and encode_fh operations
 to encode and decode filehandles, and allows the filesystem to use  

This patch doesn't match the changelog at all. I think it's one leftover fix after the previous version of the patch was applied...?

Gah, sorry. Yeah, you're right: this is just a fixup patch.

Quoted 2 lines

jon

Thanks,
Mauro

#13 lore raw

PATCH 6/6 docs: w1: convert to ReST and add to the kAPI group of docs

In reply to Mauro Carvalho Chehab

The 1wire documentation was written with w1 developers in mind, so, it makes sense to add it together with the driver-api set.

---
 Documentation/ABI/stable/sysfs-bus-w1         |  2 +-
 .../ABI/stable/sysfs-driver-w1_ds28e04        |  4 +-
 .../ABI/stable/sysfs-driver-w1_ds28ea00       |  2 +-
 Documentation/index.rst                       |  1 +
 Documentation/w1/index.rst                    | 21 +++++
 .../w1/masters/{ds2482 => ds2482.rst}         | 16 +++-
 .../w1/masters/{ds2490 => ds2490.rst}         |  6 +-
 Documentation/w1/masters/index.rst            | 14 +++
 Documentation/w1/masters/mxc-w1               | 12 ---
 Documentation/w1/masters/mxc-w1.rst           | 17 ++++
 .../w1/masters/{omap-hdq => omap-hdq.rst}     | 12 +--
 .../w1/masters/{w1-gpio => w1-gpio.rst}       | 21 +++--
 Documentation/w1/slaves/index.rst             | 16 ++++
 .../w1/slaves/{w1_ds2406 => w1_ds2406.rst}    |  4 +-
 .../w1/slaves/{w1_ds2413 => w1_ds2413.rst}    |  9 ++
 Documentation/w1/slaves/w1_ds2423             | 47 ----------
 Documentation/w1/slaves/w1_ds2423.rst         | 54 +++++++++++
 .../w1/slaves/{w1_ds2438 => w1_ds2438.rst}    | 10 ++-
 .../w1/slaves/{w1_ds28e04 => w1_ds28e04.rst}  |  5 ++
 .../w1/slaves/{w1_ds28e17 => w1_ds28e17.rst}  | 16 ++--
 .../w1/slaves/{w1_therm => w1_therm.rst}      | 11 ++-
 .../w1/{w1.generic => w1-generic.rst}         | 88 ++++++++++--------
 .../w1/{w1.netlink => w1-netlink.rst}         | 89 +++++++++++--------
 23 files changed, 308 insertions(+), 169 deletions(-)
 create mode 100644 Documentation/w1/index.rst
 rename Documentation/w1/masters/{ds2482 => ds2482.rst} (71%)
 rename Documentation/w1/masters/{ds2490 => ds2490.rst} (98%)
 create mode 100644 Documentation/w1/masters/index.rst
 delete mode 100644 Documentation/w1/masters/mxc-w1
 create mode 100644 Documentation/w1/masters/mxc-w1.rst
 rename Documentation/w1/masters/{omap-hdq => omap-hdq.rst} (90%)
 rename Documentation/w1/masters/{w1-gpio => w1-gpio.rst} (75%)
 create mode 100644 Documentation/w1/slaves/index.rst
 rename Documentation/w1/slaves/{w1_ds2406 => w1_ds2406.rst} (96%)
 rename Documentation/w1/slaves/{w1_ds2413 => w1_ds2413.rst} (81%)
 delete mode 100644 Documentation/w1/slaves/w1_ds2423
 create mode 100644 Documentation/w1/slaves/w1_ds2423.rst
 rename Documentation/w1/slaves/{w1_ds2438 => w1_ds2438.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e04 => w1_ds28e04.rst} (93%)
 rename Documentation/w1/slaves/{w1_ds28e17 => w1_ds28e17.rst} (88%)
 rename Documentation/w1/slaves/{w1_therm => w1_therm.rst} (95%)
 rename Documentation/w1/{w1.generic => w1-generic.rst} (59%)
 rename Documentation/w1/{w1.netlink => w1-netlink.rst} (77%)
Documentation/ABI/stable/sysfs-bus-w1 +1 -1
index 140d85b4ae92..992dfb183ed0 100644
@@ -6,6 +6,6 @@ Description:	Bus scanning interval, microseconds component.
 		control systems are attached/generate presence for as short as
 		100 ms - hence the tens-to-hundreds milliseconds scan intervals
 		are required.
-		see Documentation/w1/w1.generic for detailed information.
+		see Documentation/w1/w1-generic.rst for detailed information.
 Users:		any user space application which wants to know bus scanning
 		interval
Documentation/ABI/stable/sysfs-driver-w1_ds28e04 +2 -2
index 26579ee868c9..3e1c1fa8d54d 100644
@@ -2,7 +2,7 @@ What:		/sys/bus/w1/devices/.../pio
 Date:		May 2012
 Contact:	Markus Franke <[email protected]>
 Description:	read/write the contents of the two PIO's of the DS28E04-100
-		see Documentation/w1/slaves/w1_ds28e04 for detailed information
+		see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
 Users:		any user space application which wants to communicate with DS28E04-100
 
 
@@ -11,5 +11,5 @@ What:		/sys/bus/w1/devices/.../eeprom
 Date:		May 2012
 Contact:	Markus Franke <[email protected]>
 Description:	read/write the contents of the EEPROM memory of the DS28E04-100
-		see Documentation/w1/slaves/w1_ds28e04 for detailed information
+		see Documentation/w1/slaves/w1_ds28e04.rst for detailed information
 Users:		any user space application which wants to communicate with DS28E04-100
Documentation/ABI/stable/sysfs-driver-w1_ds28ea00 +1 -1
index e928def14f28..534e63731a49 100644
@@ -2,5 +2,5 @@ What:		/sys/bus/w1/devices/.../w1_seq
 Date:		Apr 2015
 Contact:	Matt Campbell <[email protected]>
 Description:	Support for the DS28EA00 chain sequence function
-		see Documentation/w1/slaves/w1_therm for detailed information
+		see Documentation/w1/slaves/w1_therm.rst for detailed information
 Users:		any user space application which wants to communicate with DS28EA00
Documentation/index.rst +1 -0
index 472b8abe52e9..0a564f3c336e 100644
@@ -117,6 +117,7 @@ needed).
    target/index
    timers/index
    spi/index
+   w1/index
    watchdog/index
    virtual/index
    input/index
Documentation/w1/index.rst new file +21 -0
new file mode 100644
index 000000000000..57cba81865e2
@@ -0,0 +1,21 @@
+. SPDX-License-Identifier: GPL-2.0
+
+================
+1-Wire Subsystem
+================
+
+.. toctree::
+   :maxdepth: 1
+
+
+   w1-generic.rst
+   w1-netlink.rst
+   masters/index
+   slaves/index
+
+.. only::  subproject and html
+
+   Indices
+   =======
+
+   * :ref:`genindex`
Documentation/w1/masters/ds2482.rst renamed from Documentation/w1/masters/ds2482 +12 -4
similarity index 71%
rename from Documentation/w1/masters/ds2482
rename to Documentation/w1/masters/ds2482.rst
index 56f8edace6ac..17ebe8f660cd 100644
@@ -1,13 +1,19 @@
+====================
 Kernel driver ds2482
 ====================
 
 Supported chips:
+
   * Maxim DS2482-100, Maxim DS2482-800
+
     Prefix: 'ds2482'
+
     Addresses scanned: None
+
     Datasheets:
-        http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
-        http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
+
+        - http://datasheets.maxim-ic.com/en/ds/DS2482-100.pdf
+        - http://datasheets.maxim-ic.com/en/ds/DS2482-800.pdf
 
 Author: Ben Gardner <[email protected]>
 
@@ -23,9 +29,11 @@ General Remarks
 ---------------
 
 Valid addresses are 0x18, 0x19, 0x1a, and 0x1b.
+
 However, the device cannot be detected without writing to the i2c bus, so no
 detection is done. You should instantiate the device explicitly.
 
-$ modprobe ds2482
-$ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
+::
 
+  $ modprobe ds2482
+  $ echo ds2482 0x18 > /sys/bus/i2c/devices/i2c-0/new_device
Documentation/w1/masters/ds2490.rst renamed from Documentation/w1/masters/ds2490 +5 -1
similarity index 98%
rename from Documentation/w1/masters/ds2490
rename to Documentation/w1/masters/ds2490.rst
index 3e091151dd80..7e5b50f9c0f5 100644
@@ -1,7 +1,9 @@
+====================
 Kernel driver ds2490
 ====================
 
 Supported chips:
+
   * Maxim DS2490 based
 
 Author: Evgeniy Polyakov <[email protected]>
@@ -18,6 +20,7 @@ which has 0x81 family ID integrated chip and DS2490
 low-level operational chip.
 
 Notes and limitations.
+
 - The weak pullup current is a minimum of 0.9mA and maximum of 6.0mA.
 - The 5V strong pullup is supported with a minimum of 5.9mA and a
   maximum of 30.4 mA.  (From DS2490.pdf)
@@ -65,4 +68,5 @@ Notes and limitations.
   reattaching would clear the problem.  usbmon output in the guest and
   host did not explain the problem.  My guess is a bug in either qemu
   or the host OS and more likely the host OS.
--- 03-06-2008 David Fries <[email protected]>
+
+03-06-2008 David Fries <[email protected]>
Documentation/w1/masters/index.rst new file +14 -0
new file mode 100644
index 000000000000..4442a98850ad
@@ -0,0 +1,14 @@
+. SPDX-License-Identifier: GPL-2.0
+
+=====================
+1-wire Master Drivers
+=====================
+
+.. toctree::
+   :maxdepth: 1
+
+   ds2482
+   ds2490
+   mxc-w1
+   omap-hdq
+   w1-gpio
Documentation/w1/masters/mxc-w1 deleted +0 -12
deleted file mode 100644
index 38be1ad65532..000000000000
@@ -1,12 +0,0 @@
-Kernel driver mxc_w1
-====================
-
-Supported chips:
-  * Freescale MX27, MX31 and probably other i.MX SoCs
-    Datasheets:
-        http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
-	http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=
-	Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
-
-Author: Originally based on Freescale code, prepared for mainline by
-	Sascha Hauer <[email protected]>
Documentation/w1/masters/mxc-w1.rst new file +17 -0
new file mode 100644
index 000000000000..334f9893103f
@@ -0,0 +1,17 @@
+====================
+Kernel driver mxc_w1
+====================
+
+Supported chips:
+
+  * Freescale MX27, MX31 and probably other i.MX SoCs
+
+    Datasheets:
+
+        - http://www.freescale.com/files/32bit/doc/data_sheet/MCIMX31.pdf?fpsp=1
+	- http://cache.freescale.com/files/dsp/doc/archive/MCIMX27.pdf?fsrch=1&WT_TYPE=Data%20Sheets&WT_VENDOR=FREESCALE&WT_FILE_FORMAT=pdf&WT_ASSET=Documentation
+
+Author:
+
+	Originally based on Freescale code, prepared for mainline by
+	Sascha Hauer <[email protected]>
Documentation/w1/masters/omap-hdq.rst renamed from Documentation/w1/masters/omap-hdq +7 -5
similarity index 90%
rename from Documentation/w1/masters/omap-hdq
rename to Documentation/w1/masters/omap-hdq.rst
index 234522709a5f..345298a59e50 100644
@@ -1,9 +1,10 @@
-Kernel driver for omap HDQ/1-wire module.
+========================================
+Kernel driver for omap HDQ/1-wire module
 ========================================
 
 Supported chips:
 ================
-	HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
+HDQ/1-wire controller on the TI OMAP 2430/3430 platforms.
 
 A useful link about HDQ basics:
 ===============================
@@ -40,9 +41,10 @@ driver(drivers/w1/slaves/w1_bq27000.c) sets the ID to 1.
 Please note to load both the modules with a different ID if required, but note
 that the ID used should be same for both master and slave driver loading.
 
-e.g:
-insmod omap_hdq.ko W1_ID=2
-inamod w1_bq27000.ko F_ID=2
+e.g::
+
+  insmod omap_hdq.ko W1_ID=2
+  inamod w1_bq27000.ko F_ID=2
 
 The driver also supports 1-wire mode. In this mode, there is no need to
 pass slave ID as parameter. The driver will auto-detect slaves connected
Documentation/w1/masters/w1-gpio.rst renamed from Documentation/w1/masters/w1-gpio +12 -9
similarity index 75%
rename from Documentation/w1/masters/w1-gpio
rename to Documentation/w1/masters/w1-gpio.rst
index 623961d9e83f..18fdb7366372 100644
@@ -1,3 +1,4 @@
+=====================
 Kernel driver w1-gpio
 =====================
 
@@ -16,28 +17,30 @@ Documentation/devicetree/bindings/w1/w1-gpio.txt
 Example (mach-at91)
 -------------------
 
-#include <linux/gpio/machine.h>
-#include <linux/w1-gpio.h>
+::
 
-static struct gpiod_lookup_table foo_w1_gpiod_table = {
+  #include <linux/gpio/machine.h>
+  #include <linux/w1-gpio.h>
+
+  static struct gpiod_lookup_table foo_w1_gpiod_table = {
 	.dev_id = "w1-gpio",
 	.table = {
 		GPIO_LOOKUP_IDX("at91-gpio", AT91_PIN_PB20, NULL, 0,
 			GPIO_ACTIVE_HIGH|GPIO_OPEN_DRAIN),
 	},
-};
+  };
 
-static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
+  static struct w1_gpio_platform_data foo_w1_gpio_pdata = {
 	.ext_pullup_enable_pin	= -EINVAL,
-};
+  };
 
-static struct platform_device foo_w1_device = {
+  static struct platform_device foo_w1_device = {
 	.name			= "w1-gpio",
 	.id			= -1,
 	.dev.platform_data	= &foo_w1_gpio_pdata,
-};
+  };
 
-...
+  ...
 	at91_set_GPIO_periph(foo_w1_gpio_pdata.pin, 1);
 	at91_set_multi_drive(foo_w1_gpio_pdata.pin, 1);
 	gpiod_add_lookup_table(&foo_w1_gpiod_table);
Documentation/w1/slaves/index.rst new file +16 -0
new file mode 100644
index 000000000000..d0697b202f09
@@ -0,0 +1,16 @@
+. SPDX-License-Identifier: GPL-2.0
+
+====================
+1-wire Slave Drivers
+====================
+
+.. toctree::
+   :maxdepth: 1
+
+   w1_ds2406
+   w1_ds2413
+   w1_ds2423
+   w1_ds2438
+   w1_ds28e04
+   w1_ds28e17
+   w1_therm
Documentation/w1/slaves/w1_ds2406.rst renamed from Documentation/w1/slaves/w1_ds2406 +3 -1
similarity index 96%
rename from Documentation/w1/slaves/w1_ds2406
rename to Documentation/w1/slaves/w1_ds2406.rst
index 8137fe6f6c3d..d3e68266084f 100644
@@ -1,7 +1,9 @@
+=======================
 w1_ds2406 kernel driver
 =======================
 
 Supported chips:
+
   * Maxim DS2406 (and other family 0x12) addressable switches
 
 Author: Scott Alfter <[email protected]>
@@ -9,7 +11,7 @@ Author: Scott Alfter <[email protected]>
 Description
 -----------
 
-The w1_ds2406 driver allows connected devices to be switched on and off. 
+The w1_ds2406 driver allows connected devices to be switched on and off.
 These chips also provide 128 bytes of OTP EPROM, but reading/writing it is
 not supported.  In TSOC-6 form, the DS2406 provides two switch outputs and
 can be provided with power on a dedicated input.  In TO-92 form, it provides
Documentation/w1/slaves/w1_ds2413.rst renamed from Documentation/w1/slaves/w1_ds2413 +9 -0
similarity index 81%
rename from Documentation/w1/slaves/w1_ds2413
rename to Documentation/w1/slaves/w1_ds2413.rst
index 936263a8ccb4..c15bb5b919b7 100644
@@ -1,11 +1,16 @@
+=======================
 Kernel driver w1_ds2413
 =======================
 
 Supported chips:
+
   * Maxim DS2413 1-Wire Dual Channel Addressable Switch
 
 supported family codes:
+
+        ================        ====
         W1_FAMILY_DS2413        0x3A
+        ================        ====
 
 Author: Mariusz Bialonczyk <[email protected]>
 
@@ -20,11 +25,13 @@ Reading state
 The "state" file provides one-byte value which is in the same format as for
 the chip PIO_ACCESS_READ command (refer the datasheet for details):
 
+======== =============================================================
 Bit 0:   PIOA Pin State
 Bit 1:   PIOA Output Latch State
 Bit 2:   PIOB Pin State
 Bit 3:   PIOB Output Latch State
 Bit 4-7: Complement of Bit 3 to Bit 0 (verified by the kernel module)
+======== =============================================================
 
 This file is readonly.
 
@@ -34,9 +41,11 @@ You can set the PIO pins using the "output" file.
 It is writable, you can write one-byte value to this sysfs file.
 Similarly the byte format is the same as for the PIO_ACCESS_WRITE command:
 
+======== ======================================
 Bit 0:   PIOA
 Bit 1:   PIOB
 Bit 2-7: No matter (driver will set it to "1"s)
+======== ======================================
 
 
 The chip has some kind of basic protection against transmission errors.
Documentation/w1/slaves/w1_ds2423 deleted +0 -47

47 lines not on this page · raw message

Documentation/w1/slaves/w1_ds2423.rst new file +54 -0

54 lines not on this page · raw message

Documentation/w1/slaves/w1_ds2438.rst renamed from Documentation/w1/slaves/w1_ds2438 +8 -2
similarity index 93%
rename from Documentation/w1/slaves/w1_ds2438
rename to Documentation/w1/slaves/w1_ds2438.rst
index e64f65a09387..a29309a3f8e5 100644
@@ -2,10 +2,13 @@ Kernel driver w1_ds2438
 =======================
 
 Supported chips:
+
   * Maxim DS2438 Smart Battery Monitor
 
 supported family codes:
+        ================        ====
         W1_FAMILY_DS2438        0x26
+        ================        ====
 
 Author: Mariusz Bialonczyk <[email protected]>
 
@@ -56,8 +59,11 @@ Opening and reading this file initiates the CONVERT_V (voltage conversion)
 command of the chip.
 
 Depending on a sysfs filename a different input for the A/D will be selected:
-vad: general purpose A/D input (VAD)
-vdd: battery input (VDD)
+
+vad:
+    general purpose A/D input (VAD)
+vdd:
+    battery input (VDD)
 
 After the voltage conversion the value is returned as decimal ASCII.
 Note: To get a volts the value has to be divided by 100.
Documentation/w1/slaves/w1_ds28e04.rst renamed from Documentation/w1/slaves/w1_ds28e04 +5 -0
similarity index 93%
rename from Documentation/w1/slaves/w1_ds28e04
rename to Documentation/w1/slaves/w1_ds28e04.rst
index 7819b65cfa48..b12b118890d3 100644
@@ -1,11 +1,16 @@
+========================
 Kernel driver w1_ds28e04
 ========================
 
 Supported chips:
+
   * Maxim DS28E04-100 4096-Bit Addressable 1-Wire EEPROM with PIO
 
 supported family codes:
+
+        =================	====
 	W1_FAMILY_DS28E04	0x1C
+        =================	====
 
 Author: Markus Franke, <[email protected]> <[email protected]>
 
Documentation/w1/slaves/w1_ds28e17.rst renamed from Documentation/w1/slaves/w1_ds28e17 +10 -6
similarity index 88%
rename from Documentation/w1/slaves/w1_ds28e17
rename to Documentation/w1/slaves/w1_ds28e17.rst
index 7fcfad5b4a37..e2d9f96d8f2c 100644
@@ -1,11 +1,16 @@
+========================
 Kernel driver w1_ds28e17
 ========================
 
 Supported chips:
+
   * Maxim DS28E17 1-Wire-to-I2C Master Bridge
 
 supported family codes:
+
+        =================  ====
 	W1_FAMILY_DS28E17  0x19
+        =================  ====
 
 Author: Jan Kandziora <[email protected]>
 
@@ -20,11 +25,11 @@ a DS28E17 can be accessed by the kernel or userspace tools as if they were
 connected to a "native" I2C bus master.
 
 
-An udev rule like the following
--------------------------------------------------------------------------------
-SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
-        SYMLINK+="i2c-$attr{name}"
--------------------------------------------------------------------------------
+An udev rule like the following::
+
+  SUBSYSTEM=="i2c-dev", KERNEL=="i2c-[0-9]*", ATTRS{name}=="w1-19-*", \
+          SYMLINK+="i2c-$attr{name}"
+
 may be used to create stable /dev/i2c- entries based on the unique id of the
 DS28E17 chip.
 
@@ -65,4 +70,3 @@ structure is created.
 
 
 See https://github.com/ianka/w1_ds28e17 for even more information.
-
Documentation/w1/slaves/w1_therm.rst renamed from Documentation/w1/slaves/w1_therm +9 -2
similarity index 95%
rename from Documentation/w1/slaves/w1_therm
rename to Documentation/w1/slaves/w1_therm.rst
index d1f93af36f38..90531c340a07 100644
@@ -1,7 +1,9 @@
+======================
 Kernel driver w1_therm
-====================
+======================
 
 Supported chips:
+
   * Maxim ds18*20 based temperature sensors.
   * Maxim ds1825 based temperature sensors.
 
@@ -13,12 +15,16 @@ Description
 
 w1_therm provides basic temperature conversion for ds18*20 devices, and the
 ds28ea00 device.
-supported family codes:
+
+Supported family codes:
+
+====================	====
 W1_THERM_DS18S20	0x10
 W1_THERM_DS1822		0x22
 W1_THERM_DS18B20	0x28
 W1_THERM_DS1825		0x3B
 W1_THERM_DS28EA00	0x42
+====================	====
 
 Support is provided through the sysfs w1_slave file.  Each open and
 read sequence will initiate a temperature conversion then provide two
@@ -51,6 +57,7 @@ If so, it will activate the master's strong pullup.
 In case the detection of parasite devices using this command fails
 (seems to be the case with some DS18S20) the strong pullup can
 be force-enabled.
+
 If the strong pullup is enabled, the master's strong pullup will be
 driven when the conversion is taking place, provided the master driver
 does support the strong pullup (or it falls back to a pullup
Documentation/w1/w1-generic.rst renamed from Documentation/w1/w1.generic +50 -38

129 lines not on this page · raw message

Documentation/w1/w1-netlink.rst renamed from Documentation/w1/w1.netlink +51 -38

161 lines not on this page · raw message

Signature · 1 line
2.21.0
maintainer
#14 lore raw
In reply to Mauro Carvalho Chehab
Quoted 9 lines · On Wed, 31 Jul 2019 17:08:47 -0300 Mauro Carvalho Chehab…

As promised, this is the rebased version of the patches that were not applied from the /26 patch series because you had merge conflicts.

They're all based on your docs-next branch, so should apply fine.

The first one fixes all but one error with a broken reference.

The only broken reference right now is due to a DT patch with was not accepted (no idea why), but whose driver is upstream.

All but 5/6 applied, thanks.

jon

maintainer
#15 lore raw
Quoted 5 lines · Jonathan Corbet
Quoted 3 lines · Mauro Carvalho Chehab

As promised, this is the rebased version of the patches that were not applied from the /26 patch series because you had merge conflicts.

Quoted 8 lines
Quoted 6 lines

They're all based on your docs-next branch, so should apply fine.

The first one fixes all but one error with a broken reference.

The only broken reference right now is due to a DT patch with was not accepted (no idea why), but whose driver is upstream.

All but 5/6 applied, thanks.

Oh, I still hadn't reviewed this version of the SPI stuff :(

There were outstanding questions about where it was going to get moved to but if I read the diff correctly it looks like it didn't actually get moved in the end?

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

#16 lore raw

Em Wed, 31 Jul 2019 21:20:07 +0100
Mark Brown <[email protected]> escreveu:

Quoted 8 lines · Jonathan Corbet
Quoted 7 lines
Quoted 5 lines · Mauro Carvalho Chehab

As promised, this is the rebased version of the patches that were not applied from the /26 patch series because you had merge conflicts.

They're all based on your docs-next branch, so should apply fine.

Quoted 8 lines
Quoted 6 lines
Quoted 4 lines

The first one fixes all but one error with a broken reference.

The only broken reference right now is due to a DT patch with was not accepted (no idea why), but whose driver is upstream.

All but 5/6 applied, thanks.

Oh, I still hadn't reviewed this version of the SPI stuff :(

It is basically the one sent on that /26 patch series, just rebased on the top of docs-next.

Quoted 3 lines

There were outstanding questions about where it was going to get moved to but if I read the diff correctly it looks like it didn't actually get moved in the end?

Yeah, it doesn't have the move. My understanding from our discussions is that we didn't reach a conclusion.

In any case, I can send a separate patch with the move part once we reach an agreement about what's the best way to proceed (or you can do it directly, if you prefer so).

Thanks,
Mauro

maintainer
#17 lore raw
Quoted 8 lines · Mauro Carvalho Chehab

Mark Brown <[email protected]> escreveu:

Quoted 3 lines

There were outstanding questions about where it was going to get moved to but if I read the diff correctly it looks like it didn't actually get moved in the end?

Yeah, it doesn't have the move. My understanding from our discussions is that we didn't reach a conclusion.

Yes, that was my understanding too which was why I was surprised to see this going in. This is OK then, I'd have acked it.

Quoted 3 lines

In any case, I can send a separate patch with the move part once we reach an agreement about what's the best way to proceed (or you can do it directly, if you prefer so).

I'm not likely to do anything without someone sending patches, I'm not clear on the utility of the move with the current division of the manuals. I don't know if it makes sense to have an embedded developer's manual as well?

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel

#18 lore raw

Em Wed, 31 Jul 2019 21:37:12 +0100
Mark Brown <[email protected]> escreveu:

Quoted 13 lines · Mauro Carvalho Chehab
Quoted 8 lines

Mark Brown <[email protected]> escreveu:

Quoted 3 lines

There were outstanding questions about where it was going to get moved to but if I read the diff correctly it looks like it didn't actually get moved in the end?

Yeah, it doesn't have the move. My understanding from our discussions is that we didn't reach a conclusion.

Yes, that was my understanding too which was why I was surprised to see this going in. This is OK then, I'd have acked it.

Quoted 7 lines
Quoted 3 lines

In any case, I can send a separate patch with the move part once we reach an agreement about what's the best way to proceed (or you can do it directly, if you prefer so).

I'm not likely to do anything without someone sending patches, I'm not clear on the utility of the move with the current division of the manuals.

Same here: I do see value on having docs focused on their audience.

Yet, I'm not so sure how worth is to break some subsystem documentation into books, as, on some cases, this would mean huge efforts.

I'd prefer to see the big picture first, finishing the conversion and then looking at the resulting docs.

Meanwhile, if someone needs something that it is at the wrong book, he can just use some search tool to seek what he needs, no matter on what book the relevant information is stored.

Quoted 2 lines

I don't know if it makes sense to have an embedded developer's manual as well?

Yeah, that's a good question.

Jon is planning todo a documentation track at LPC. One of the things that should be discussed, IMO, is how we'll organize the books.

I suspect that, once we finish the conversion of the remaining ~300 files to ReST, the next logical step is to check what are the gaps and have a list of pending tasks.

Thanks,
Mauro

maintainer
#19 lore raw
Quoted 3 lines · Mauro Carvalho Chehab

Meanwhile, if someone needs something that it is at the wrong book, he can just use some search tool to seek what he needs, no matter on what book the relevant information is stored.

OTOH it might be weird for the intended audience of the book.

Quoted 9 lines

Mark Brown <[email protected]> escreveu:

Quoted 2 lines

I don't know if it makes sense to have an embedded developer's manual as well?

Yeah, that's a good question.

Jon is planning todo a documentation track at LPC. One of the things that should be discussed, IMO, is how we'll organize the books.

I'll be at Plumbers, not sure what the schedule's looking like yet though.

_______________________________________________
linux-arm-kernel mailing list
[email protected]
http://lists.infradead.org/mailman/listinfo/linux-arm-kernel