[PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Mauro Carvalho Chehab]

In the past, we did some efforts to ensure that almost all files under
Documentation/*.txt could be built with Sphinx.

Some regressions happened there (and some new files got added).
Fix those files in order to allow them to be able to build with Sphinx.

The changes on this series are trivial, adding the minimum stuff to allow
building those files with sphinx-build with no warnings and to make the
contents minimally consistent with other documentation files.

Mauro Carvalho Chehab (8):
  docs: DMA-API-HOWTO: add a missing "="
  docs: atomic_bitops.txt: add a title for this document
  docs: clearing-warn-once.txt: add a title for this document
  docs: ntb.txt: use Sphinx notation for the two ascii figures
  docs: unaligned-memory-access.txt: use a lowercase title
  docs: video-output.txt: convert it to ReST format
  docs: ntb.txt: add blank lines to clean up some Sphinx warnings
  docs: speculation.txt: mark example blocks as such

 Documentation/DMA-API-HOWTO.txt           |  2 +-
 Documentation/atomic_bitops.txt           |  6 +--
 Documentation/clearing-warn-once.txt      |  2 +
 Documentation/ntb.txt                     | 14 ++++--
 Documentation/speculation.txt             |  8 ++--
 Documentation/unaligned-memory-access.txt |  2 +-
 Documentation/video-output.txt            | 52 +++++++++++------------
 7 files changed, 47 insertions(+), 39 deletions(-)

-- 
2.20.1

[PATCH 1/8] docs: DMA-API-HOWTO: add a missing "="

[Mauro Carvalho Chehab]

The === line is shorter than the section title.

As this will generate a warning with rst build, fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/DMA-API-HOWTO.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/DMA-API-HOWTO.txt b/Documentation/DMA-API-HOWTO.txt
index 1a721d0f35c8..db48c6fd3162 100644
--- a/Documentation/DMA-API-HOWTO.txt
+++ b/Documentation/DMA-API-HOWTO.txt
@@ -147,7 +147,7 @@ networking subsystems make sure that the buffers they use are valid
 for you to DMA from/to.
 
 DMA addressing capabilities
-==========================
+===========================
 
 By default, the kernel assumes that your device can address 32-bits of DMA
 addressing.  For a 64-bit capable device, this needs to be increased, and for
-- 
2.20.1

[PATCH 2/8] docs: atomic_bitops.txt: add a title for this document

[Mauro Carvalho Chehab]

This document misses a title. Add it, in order to follow
the documentation standard.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/atomic_bitops.txt | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/atomic_bitops.txt b/Documentation/atomic_bitops.txt
index be70b32c95d9..093cdaefdb37 100644
--- a/Documentation/atomic_bitops.txt
+++ b/Documentation/atomic_bitops.txt
@@ -1,6 +1,6 @@
-
-On atomic bitops.
-
+=============
+Atomic bitops
+=============
 
 While our bitmap_{}() functions are non-atomic, we have a number of operations
 operating on single bits in a bitmap that are atomic.
-- 
2.20.1

[PATCH 3/8] docs: clearing-warn-once.txt: add a title for this document

[Mauro Carvalho Chehab]

This document misses a title. Add it, in order to follow
the documentation standard.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/clearing-warn-once.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/clearing-warn-once.txt b/Documentation/clearing-warn-once.txt
index 5b1f5d547be1..4aa938262d0e 100644
--- a/Documentation/clearing-warn-once.txt
+++ b/Documentation/clearing-warn-once.txt
@@ -1,3 +1,5 @@
+Clearing WARN_ONCE
+------------------
 
 WARN_ONCE / WARN_ON_ONCE only print a warning once.
 
-- 
2.20.1

[PATCH 4/8] docs: ntb.txt: use Sphinx notation for the two ascii figures

[Mauro Carvalho Chehab]

In order to make it to build with Sphinx, we need to fix the
notation for two ascii artwork.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/ntb.txt | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/Documentation/ntb.txt b/Documentation/ntb.txt
index a043854d28df..344a075f81f5 100644
--- a/Documentation/ntb.txt
+++ b/Documentation/ntb.txt
@@ -41,9 +41,10 @@ mainly used to perform the proper memory window initialization. Typically
 there are two types of memory window interfaces supported by the NTB API:
 inbound translation configured on the local ntb port and outbound translation
 configured by the peer, on the peer ntb port. The first type is
-depicted on the next figure
+depicted on the next figure::
+
+ Inbound translation:
 
-Inbound translation:
  Memory:              Local NTB Port:      Peer NTB Port:      Peer MMIO:
   ____________
  | dma-mapped |-ntb_mw_set_trans(addr)  |
@@ -58,9 +59,10 @@ maps corresponding outbound memory window so to have access to the shared
 memory region.
 
 The second type of interface, that implies the shared windows being
-initialized by a peer device, is depicted on the figure:
+initialized by a peer device, is depicted on the figure::
+
+ Outbound translation:
 
-Outbound translation:
  Memory:        Local NTB Port:    Peer NTB Port:      Peer MMIO:
   ____________                      ______________
  | dma-mapped |                |   | MW base addr |<== memory-mapped IO
-- 
2.20.1

[PATCH 5/8] docs: unaligned-memory-access.txt: use a lowercase title

[Mauro Carvalho Chehab]

As all other titles at the documentation, use lower case
for its title.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/unaligned-memory-access.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/unaligned-memory-access.txt b/Documentation/unaligned-memory-access.txt
index 51b4ff031586..1ee82419d8aa 100644
--- a/Documentation/unaligned-memory-access.txt
+++ b/Documentation/unaligned-memory-access.txt
@@ -1,5 +1,5 @@
 =========================
-UNALIGNED MEMORY ACCESSES
+Unaligned Memory Accesses
 =========================
 
 :Author: Daniel Drake <dsd@gentoo.org>,
-- 
2.20.1

[PATCH 6/8] docs: video-output.txt: convert it to ReST format

[Mauro Carvalho Chehab]

This file doesn't follow the documentation style we use
within the Kernel. Fix it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/video-output.txt | 52 +++++++++++++++++-----------------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/Documentation/video-output.txt b/Documentation/video-output.txt
index e517011be4f9..56d6fa2e2368 100644
--- a/Documentation/video-output.txt
+++ b/Documentation/video-output.txt
@@ -1,34 +1,34 @@
+Video Output Switcher Control
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-		Video Output Switcher Control
-		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-		2006 luming.yu@intel.com
+2006 luming.yu@intel.com
 
 The output sysfs class driver provides an abstract video output layer that
 can be used to hook platform specific methods to enable/disable video output
 device through common sysfs interface. For example, on my IBM ThinkPad T42
 laptop, The ACPI video driver registered its output devices and read/write
-method for 'state' with output sysfs class. The user interface under sysfs is:
+method for 'state' with output sysfs class. The user interface under sysfs is::
 
-linux:/sys/class/video_output # tree .
-.
-|-- CRT0
-|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-|-- DVI0
-|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-|-- LCD0
-|   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-|   |-- state
-|   |-- subsystem -> ../../../class/video_output
-|   `-- uevent
-`-- TV0
-   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
-   |-- state
-   |-- subsystem -> ../../../class/video_output
-   `-- uevent
+  linux:/sys/class/video_output # tree .
+  .
+  |-- CRT0
+  |   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+  |   |-- state
+  |   |-- subsystem -> ../../../class/video_output
+  |   `-- uevent
+  |-- DVI0
+  |   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+  |   |-- state
+  |   |-- subsystem -> ../../../class/video_output
+  |   `-- uevent
+  |-- LCD0
+  |   |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+  |   |-- state
+  |   |-- subsystem -> ../../../class/video_output
+  |   `-- uevent
+  `-- TV0
+     |-- device -> ../../../devices/pci0000:00/0000:00:01.0
+     |-- state
+     |-- subsystem -> ../../../class/video_output
+     `-- uevent
 
-- 
2.20.1

[PATCH 7/8] docs: ntb.txt: add blank lines to clean up some Sphinx warnings

[Mauro Carvalho Chehab]

In order to make it easier to parse and produce the right output,
add some extra blank lines.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/ntb.txt | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/Documentation/ntb.txt b/Documentation/ntb.txt
index 344a075f81f5..074a423c853c 100644
--- a/Documentation/ntb.txt
+++ b/Documentation/ntb.txt
@@ -77,11 +77,13 @@ outbound memory window so to have access to the shared memory region.
 
 As one can see the described scenarios can be combined in one portable
 algorithm.
+
  Local device:
   1) Allocate memory for a shared window
   2) Initialize memory window by translated address of the allocated region
      (it may fail if local memory window initialization is unsupported)
   3) Send the translated address and memory window index to a peer device
+
  Peer device:
   1) Initialize memory window with retrieved address of the allocated
      by another device memory region (it may fail if peer memory window
@@ -90,6 +92,7 @@ algorithm.
 
 In accordance with this scenario, the NTB Memory Window API can be used as
 follows:
+
  Local device:
   1) ntb_mw_count(pidx) - retrieve number of memory ranges, which can
      be allocated for memory windows between local device and peer device
@@ -105,6 +108,7 @@ follows:
   5) Send translated base address (usually together with memory window
      number) to the peer device using, for instance, scratchpad or message
      registers.
+
  Peer device:
   1) ntb_peer_mw_set_trans(pidx, midx) - try to set received from other
      device (related to pidx) translated address for specified memory
-- 
2.20.1

[PATCH 8/8] docs: speculation.txt: mark example blocks as such

[Mauro Carvalho Chehab]

Identify the example blocks there, in order to avoid Sphinx
warnings.

Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
---
 Documentation/speculation.txt | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/speculation.txt b/Documentation/speculation.txt
index e9e6cbae2841..50d7ea857cff 100644
--- a/Documentation/speculation.txt
+++ b/Documentation/speculation.txt
@@ -17,7 +17,7 @@ observed to extract secret information.
 
 For example, in the presence of branch prediction, it is possible for bounds
 checks to be ignored by code which is speculatively executed. Consider the
-following code:
+following code::
 
 	int load_array(int *array, unsigned int index)
 	{
@@ -27,7 +27,7 @@ following code:
 			return array[index];
 	}
 
-Which, on arm64, may be compiled to an assembly sequence such as:
+Which, on arm64, may be compiled to an assembly sequence such as::
 
 	CMP	<index>, #MAX_ARRAY_ELEMS
 	B.LT	less
@@ -44,7 +44,7 @@ microarchitectural state which can be subsequently measured.
 
 More complex sequences involving multiple dependent memory accesses may
 result in sensitive information being leaked. Consider the following
-code, building on the prior example:
+code, building on the prior example::
 
 	int load_dependent_arrays(int *arr1, int *arr2, int index)
 	{
@@ -77,7 +77,7 @@ A call to array_index_nospec(index, size) returns a sanitized index
 value that is bounded to [0, size) even under cpu speculation
 conditions.
 
-This can be used to protect the earlier load_array() example:
+This can be used to protect the earlier load_array() example::
 
 	int load_array(int *array, unsigned int index)
 	{
-- 
2.20.1

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jonathan Corbet]

On Wed, 10 Apr 2019 06:56:19 -0300
Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> In the past, we did some efforts to ensure that almost all files under
> Documentation/*.txt could be built with Sphinx.
> 
> Some regressions happened there (and some new files got added).
> Fix those files in order to allow them to be able to build with Sphinx.
> 
> The changes on this series are trivial, adding the minimum stuff to allow
> building those files with sphinx-build with no warnings and to make the
> contents minimally consistent with other documentation files.

I've applied this set, thanks.

jon

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[David Howells]

Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:

> In the past, we did some efforts to ensure that almost all files under
> Documentation/*.txt could be built with Sphinx.

Would recommend a URL.  Presumably this: http://www.sphinx-doc.org

David

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 12:21 schrieb David Howells:
> Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> 
>> In the past, we did some efforts to ensure that almost all files under
>> Documentation/*.txt could be built with Sphinx.
> 
> Would recommend a URL.  Presumably this: http://www.sphinx-doc.org

I recommend the Sphinx reStructuredText Primer

- https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html

Which is already named in our 'How to write kernel documentation' introduction

- https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation


-- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[David Howells]

Markus Heiser <markus.heiser@darmarit.de> wrote:

> Which is already named in our 'How to write kernel documentation' introduction
> 
> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation

This should really be in Documentation/ directory.

David

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 14:19 schrieb David Howells:
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> Which is already named in our 'How to write kernel documentation' introduction
>>
>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
> 
> This should really be in Documentation/ directory.
> 

I agree with you, it is a kind of information hiding.  If you know proper
places, please send a patch to Jon.

   -- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jonathan Corbet]

On Fri, 12 Apr 2019 14:34:25 +0200
Markus Heiser <markus.heiser@darmarit.de> wrote:

> Am 12.04.19 um 14:19 schrieb David Howells:
> > Markus Heiser <markus.heiser@darmarit.de> wrote:
> >   
> >> Which is already named in our 'How to write kernel documentation' introduction
> >>
> >> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation  
> > 
> > This should really be in Documentation/ directory.
> >   
> 
> I agree with you, it is a kind of information hiding.  If you know proper
> places, please send a patch to Jon.

As Jani pointed out, it's in Documentation/doc-guide.

If you're saying it should be in the top level, I kind of disagree.
Documentation/ is an exercise in hiding information by placing it in the
middle of 200 other, unrelated files.  We've made some progress on that,
and I would like to continue to do so.

Thanks,

jon

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Markus Heiser]

Am 12.04.19 um 17:39 schrieb Jonathan Corbet:
> On Fri, 12 Apr 2019 14:34:25 +0200
> Markus Heiser <markus.heiser@darmarit.de> wrote:
> 
>> Am 12.04.19 um 14:19 schrieb David Howells:
>>> Markus Heiser <markus.heiser@darmarit.de> wrote:
>>>    
>>>> Which is already named in our 'How to write kernel documentation' introduction
>>>>
>>>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>>>
>>> This should really be in Documentation/ directory.
>>>    
>>
>> I agree with you, it is a kind of information hiding.  If you know proper
>> places, please send a patch to Jon.
> 
> As Jani pointed out, it's in Documentation/doc-guide.
> 
> If you're saying it should be in the top level, I kind of disagree.
> Documentation/ is an exercise in hiding information by placing it in the
> middle of 200 other, unrelated files.  We've made some progress on that,
> and I would like to continue to do so.

For those who are new and are willing to document, it migth be a good idea
to have a simple Documentation/README.txt  with a link to doc-guide?

Just a few words, I find with my editor, this is what I find often helpful
when I'am new to a project.

-- Markus --

Re: [PATCH 0/8] Prepare files under Documentation/*.txt to build with Sphinx

[Jani Nikula]

On Fri, 12 Apr 2019, David Howells <dhowells@redhat.com> wrote:
> Markus Heiser <markus.heiser@darmarit.de> wrote:
>
>> Which is already named in our 'How to write kernel documentation' introduction
>> 
>> - https://www.kernel.org/doc/html/latest/doc-guide/sphinx.html#writing-documentation
>
> This should really be in Documentation/ directory.

It is. Documentation/doc-guide/sphinx.rst.

Just double checking, you do know that all of [1] is generated from
Documentation/ using 'make html'?

BR,
Jani.


[1] https://www.kernel.org/doc/html/latest/


-- 
Jani Nikula, Intel Open Source Graphics Center