[PATCH 00/18] Fix some build warnings/errors with Sphinx

[PATCH 00/18] Fix some build warnings/errors with Sphinx

[Mauro Carvalho Chehab]

I decided to give a try with Sphinx last stable version
(1.17.4), and noticed several issues. The worse one was
with the networking book: a non-standard footnote there
with [*] instead of a number causes it to break PDF building.

So, I took some spare time to address some warnings all over
the tree, and moved a few text documents to a book. I with
I had more time to move the other ones and to solve other
warnings.

Mauro Carvalho Chehab (18):
  docs: can.rst: fix a footnote reference
  docs: fix location of request_firmware & friends
  docs: */index.rst: Add newer documents to their respective index.rst
  docs: admin-guide: add bcache documentation
  docs: core-api: add cachetlb documentation
  docs: core-api: add cgroup-v2 documentation
  docs: core-api: add circular-buffers documentation
  docs: driver-api: add clk documentation
  net: mac80211.h: fix a bad comment line
  rcu: rcupdate.h: get rid of Sphinx warnings at rcu_pointer_handoff()
  docs: crypto_engine.rst: Fix two parse warnings
  time: timer.c: adjust a kernel-doc comment
  wait: wait.h: Get rid of a kernel-doc/Sphinx warnings
  fbdev: modedb.c: fix a kernel-doc markup
  iio: iio.h: use nested struct support on kernel-doc markup
  mtd: rawnand.h: use nested union kernel-doc markups
  docs: uio-howto.rst: use a code block to solve a warning
  w1: w1_io.c: fix a kernel-doc warning

 Documentation/00-INDEX                        | 10 -------
 .../{bcache.txt => admin-guide/bcache.rst}    |  0
 .../cgroup-v2.rst}                            |  0
 Documentation/admin-guide/index.rst           |  2 ++
 .../admin-guide/kernel-parameters.txt         |  2 +-
 .../{cachetlb.txt => core-api/cachetlb.rst}   |  0
 .../circular-buffers.rst}                     |  0
 Documentation/core-api/index.rst              |  2 ++
 Documentation/crypto/crypto_engine.rst        |  8 +++---
 Documentation/crypto/index.rst                |  1 +
 Documentation/dell_rbu.txt                    |  4 +--
 Documentation/{clk.txt => driver-api/clk.rst} |  0
 .../firmware/fallback-mechanisms.rst          |  2 +-
 .../driver-api/firmware/request_firmware.rst  | 17 +++++++-----
 Documentation/driver-api/index.rst            |  2 ++
 Documentation/driver-api/infrastructure.rst   |  2 +-
 Documentation/driver-api/uio-howto.rst        |  3 ++-
 Documentation/memory-barriers.txt             |  4 +--
 Documentation/networking/can.rst              |  4 +--
 .../power/suspend-and-cpuhotplug.txt          |  2 +-
 Documentation/process/index.rst               |  1 +
 Documentation/security/index.rst              |  2 ++
 .../translations/ko_KR/memory-barriers.txt    |  4 +--
 drivers/video/fbdev/core/modedb.c             | 22 ++++++++--------
 drivers/w1/w1_io.c                            |  1 +
 include/linux/iio/iio.h                       | 24 ++++++++---------
 include/linux/mtd/rawnand.h                   | 26 +++++++++++++------
 include/linux/rcupdate.h                      |  5 ++--
 include/linux/wait.h                          |  2 +-
 include/net/mac80211.h                        |  2 +-
 kernel/time/timer.c                           | 14 +++++-----
 31 files changed, 93 insertions(+), 75 deletions(-)
 rename Documentation/{bcache.txt => admin-guide/bcache.rst} (100%)
 rename Documentation/{cgroup-v2.txt => admin-guide/cgroup-v2.rst} (100%)
 rename Documentation/{cachetlb.txt => core-api/cachetlb.rst} (100%)
 rename Documentation/{circular-buffers.txt => core-api/circular-buffers.rst} (100%)
 rename Documentation/{clk.txt => driver-api/clk.rst} (100%)

-- 
2.17.0

[PATCH 15/18] iio: iio.h: use nested struct support on kernel-doc markup

[Mauro Carvalho Chehab]

Solve those Sphinx warnings:

    ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.sign' not described in 'iio_chan_spec'
    ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.realbits' not described in 'iio_chan_spec'
    ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.storagebits' not described in 'iio_chan_spec'
    ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.shift' not described in 'iio_chan_spec'
    ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.repeat' not described in 'iio_chan_spec'
    ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.endianness' not described in 'iio_chan_spec'

    ./include/linux/iio/iio.h:191: WARNING: Unexpected indentation.
    ./include/linux/iio/iio.h:192: WARNING: Block quote ends without a blank line; unexpected unindent.
    ./include/linux/iio/iio.h:198: WARNING: Definition list ends without a blank line; unexpected unindent.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 include/linux/iio/iio.h | 24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

diff --git a/include/linux/iio/iio.h b/include/linux/iio/iio.h
index 11579fd4126e..a74cb177dc6f 100644
--- a/include/linux/iio/iio.h
+++ b/include/linux/iio/iio.h
@@ -183,18 +183,18 @@ struct iio_event_spec {
  * @address:		Driver specific identifier.
  * @scan_index:		Monotonic index to give ordering in scans when read
  *			from a buffer.
- * @scan_type:		sign:		's' or 'u' to specify signed or unsigned
- *			realbits:	Number of valid bits of data
- *			storagebits:	Realbits + padding
- *			shift:		Shift right by this before masking out
- *					realbits.
- *			repeat:		Number of times real/storage bits
- *					repeats. When the repeat element is
- *					more than 1, then the type element in
- *					sysfs will show a repeat value.
- *					Otherwise, the number of repetitions is
- *					omitted.
- *			endianness:	little or big endian
+ * @scan_type:		struct describing the scan type
+ * @scan_type.sign:		's' or 'u' to specify signed or unsigned
+ * @scan_type.realbits:		Number of valid bits of data
+ * @scan_type.storagebits:	Realbits + padding
+ * @scan_type.shift:		Shift right by this before masking out
+ *				realbits.
+ * @scan_type.repeat:		Number of times real/storage bits repeats.
+ *				When the repeat element is more than 1, then
+ *				the type element in sysfs will show a repeat
+ *				value. Otherwise, the number of repetitions
+ *				is omitted.
+ * @scan_type.endianness:	little or big endian
  * @info_mask_separate: What information is to be exported that is specific to
  *			this channel.
  * @info_mask_separate_available: What availability information is to be
-- 
2.17.0

Re: [PATCH 15/18] iio: iio.h: use nested struct support on kernel-doc markup

[Jonathan Cameron]

On Mon,  7 May 2018 06:35:51 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> Solve those Sphinx warnings:
> 
>     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.sign' not described in 'iio_chan_spec'
>     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.realbits' not described in 'iio_chan_spec'
>     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.storagebits' not described in 'iio_chan_spec'
>     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.shift' not described in 'iio_chan_spec'
>     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.repeat' not described in 'iio_chan_spec'
>     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.endianness' not described in 'iio_chan_spec'
> 
>     ./include/linux/iio/iio.h:191: WARNING: Unexpected indentation.
>     ./include/linux/iio/iio.h:192: WARNING: Block quote ends without a blank line; unexpected unindent.
>     ./include/linux/iio/iio.h:198: WARNING: Definition list ends without a blank line; unexpected unindent.
> 
> Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Great thanks.  I couldn't figure out how to do this last time
I looked at it.

Applied to the togreg branch of iio.git and pushed out as testing for
the autobuilders to ignore it.

Thanks,

Jonathan
> ---
>  include/linux/iio/iio.h | 24 ++++++++++++------------
>  1 file changed, 12 insertions(+), 12 deletions(-)
> 
> diff --git a/include/linux/iio/iio.h b/include/linux/iio/iio.h
> index 11579fd4126e..a74cb177dc6f 100644
> --- a/include/linux/iio/iio.h
> +++ b/include/linux/iio/iio.h
> @@ -183,18 +183,18 @@ struct iio_event_spec {
>   * @address:		Driver specific identifier.
>   * @scan_index:		Monotonic index to give ordering in scans when read
>   *			from a buffer.
> - * @scan_type:		sign:		's' or 'u' to specify signed or unsigned
> - *			realbits:	Number of valid bits of data
> - *			storagebits:	Realbits + padding
> - *			shift:		Shift right by this before masking out
> - *					realbits.
> - *			repeat:		Number of times real/storage bits
> - *					repeats. When the repeat element is
> - *					more than 1, then the type element in
> - *					sysfs will show a repeat value.
> - *					Otherwise, the number of repetitions is
> - *					omitted.
> - *			endianness:	little or big endian
> + * @scan_type:		struct describing the scan type
> + * @scan_type.sign:		's' or 'u' to specify signed or unsigned
> + * @scan_type.realbits:		Number of valid bits of data
> + * @scan_type.storagebits:	Realbits + padding
> + * @scan_type.shift:		Shift right by this before masking out
> + *				realbits.
> + * @scan_type.repeat:		Number of times real/storage bits repeats.
> + *				When the repeat element is more than 1, then
> + *				the type element in sysfs will show a repeat
> + *				value. Otherwise, the number of repetitions
> + *				is omitted.
> + * @scan_type.endianness:	little or big endian
>   * @info_mask_separate: What information is to be exported that is specific to
>   *			this channel.
>   * @info_mask_separate_available: What availability information is to be

Re: [PATCH 15/18] iio: iio.h: use nested struct support on kernel-doc markup

[Mauro Carvalho Chehab]

Em Mon, 7 May 2018 18:08:03 +0100
Jonathan Cameron <jic23@kernel.org> escreveu:

> On Mon,  7 May 2018 06:35:51 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > Solve those Sphinx warnings:
> > 
> >     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.sign' not described in 'iio_chan_spec'
> >     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.realbits' not described in 'iio_chan_spec'
> >     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.storagebits' not described in 'iio_chan_spec'
> >     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.shift' not described in 'iio_chan_spec'
> >     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.repeat' not described in 'iio_chan_spec'
> >     ./include/linux/iio/iio.h:270: warning: Function parameter or member 'scan_type.endianness' not described in 'iio_chan_spec'
> > 
> >     ./include/linux/iio/iio.h:191: WARNING: Unexpected indentation.
> >     ./include/linux/iio/iio.h:192: WARNING: Block quote ends without a blank line; unexpected unindent.
> >     ./include/linux/iio/iio.h:198: WARNING: Definition list ends without a blank line; unexpected unindent.
> > 
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>  
> Great thanks.  I couldn't figure out how to do this last time
> I looked at it.

Support for nested structs were only recently introduced :-)

> 
> Applied to the togreg branch of iio.git and pushed out as testing for
> the autobuilders to ignore it.

Thanks!
Mauro

Re: [PATCH 00/18] Fix some build warnings/errors with Sphinx

[Jonathan Corbet]

On Mon,  7 May 2018 06:35:36 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> I decided to give a try with Sphinx last stable version
> (1.17.4), and noticed several issues. The worse one was
> with the networking book: a non-standard footnote there
> with [*] instead of a number causes it to break PDF building.
> 
> So, I took some spare time to address some warnings all over
> the tree, and moved a few text documents to a book. 

OK, I've applied the ones that seem to make sense for me to take now.
There's comments on the firmware one, and I'd rather have Tejun's OK for
the cgroup one.  The code-comment changes should probably go via the
usual maintainers.

> I with
> I had more time to move the other ones and to solve other
> warnings.

You and me both - but each step helps!

Thanks,

jon

Re: [PATCH 00/18] Fix some build warnings/errors with Sphinx

[Luis R. Rodriguez]

On Tue, May 08, 2018 at 10:13:42AM -0600, Jonathan Corbet wrote:
> On Mon,  7 May 2018 06:35:36 -0300
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
> > I decided to give a try with Sphinx last stable version
> > (1.17.4), and noticed several issues. The worse one was
> > with the networking book: a non-standard footnote there
> > with [*] instead of a number causes it to break PDF building.
> > 
> > So, I took some spare time to address some warnings all over
> > the tree, and moved a few text documents to a book. 
> 
> OK, I've applied the ones that seem to make sense for me to take now.
> There's comments on the firmware one, 

I'll fold in the fixes for the firmware API which do apply to my queue.

  Luis