[PATCH 0/9] docs: Fix various build warnings/errors

[PATCH 0/9] docs: Fix various build warnings/errors

[Tobin C. Harding]

Hi,

I had a few hours to spare so I thought I'd clear some Sphinx build
warnings/errors.  There isn't anything too controversial here.  The only
interesting thing I hit was in patch 7 (docs: Remove unknown 'hint'
directive), I couldn't work out if this was a serious directive, a joke,
or a typo.  Please review that patch more carefully than the others.

Patch 4 adds :ref: and raises an issue I've come across a few times now,
could I have your opinion on it please (if you have the time/inclination
to share it)

:ref:`/Documentation/path/to/file.rst <label>`

vs

:ref:`label`

Undeniably the second is better in HTML.  The first is, on one hand,
arguable better to parse when reading the textual file (since you can
see which file it refers to) but on the other hand kinda looks ugly
since it often line wraps poorly and is a bit cluttered if all you want to
see is the path.  Having only the label doesn't _really_ make it worse
in text because often you already know (or don't care) what the path is
(e.g. when there are multiple refs to the same label) and if you do care
you can just grep the docs for the label.

Do you have an opinion on this?

Oh also, do you have a script by any chance that does a clean build of
the docs, saves stderr output, applies a patch, cleanly re-builds the
docs and then diffs the two outputs?  Then rinse-and-repeat for a whole
patch series. Thought I'd ask before I write one.

thanks,
Tobin.

Tobin C. Harding (9):
  docs: Fix spelling mistake
  docs: Add colon clearing sphinx warning
  docs: Remove unnecessary reference link title
  docs: Use reference to link to rst file
  docs: Replace backtick with apostrophe.
  docs: Use correct list markup character
  docs: Remove unknown 'hint' directive
  docs: Fix Title underline too short warning
  docs: Add blank line after SPDX licence identifier

 .../admin-guide/mm/numa_memory_policy.rst     |  9 ++-
 .../driver-api/dmaengine/dmatest.rst          |  4 +-
 Documentation/driver-api/gpio/board.rst       |  5 +-
 Documentation/filesystems/path-lookup.rst     | 24 ++++----
 Documentation/laptops/lg-laptop.rst           | 13 +++--
 Documentation/misc-devices/ibmvmc.rst         |  1 +
 Documentation/networking/snmp_counter.rst     | 58 +++++++++----------
 Documentation/process/howto.rst               |  2 +-
 Documentation/vm/numa.rst                     |  4 +-
 Documentation/vm/slub.rst                     |  2 +-
 include/linux/kernel.h                        |  2 +-
 include/linux/wait.h                          |  2 +-
 12 files changed, 64 insertions(+), 62 deletions(-)

-- 
2.21.0

[PATCH 1/9] docs: Fix spelling mistake

[Tobin C. Harding]

Documentation contains a spelling mistake / typo.

s/descibed/described/

Fix spelling mistake.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/process/howto.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index 58b2f46c4f98..5cac67f8fb17 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -62,7 +62,7 @@ Legal Issues
 The Linux kernel source code is released under the GPL.  Please see the file
 COPYING in the main directory of the source tree. The Linux kernel licensing
 rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are
-descibed in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
+described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
 If you have further questions about the license, please contact a lawyer, and do
 not ask on the Linux kernel mailing list.  The people on the mailing lists are
 not lawyers, and you should not rely on their statements on legal matters.
-- 
2.21.0

[PATCH 2/9] docs: Add colon clearing sphinx warning

[Tobin C. Harding]

Sphinx emits various warnings all caused by missing colons before code
blocks:

	WARNING: Inline emphasis start-string without end-string.
	WARNING: Block quote ends without a blank line; unexpected unindent.
	ERROR: Unexpected indentation.
	WARNING: Block quote ends without a blank line; unexpected unindent.

Add the colon, clearing sphinx warnings.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/vm/slub.rst | 2 +-
 include/linux/wait.h      | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/vm/slub.rst b/Documentation/vm/slub.rst
index 195928808bac..610510d90c33 100644
--- a/Documentation/vm/slub.rst
+++ b/Documentation/vm/slub.rst
@@ -66,7 +66,7 @@ Trying to find an issue in the dentry cache? Try::
 to only enable debugging on the dentry cache.  You may use an asterisk at the
 end of the slab name, in order to cover all slabs with the same prefix.  For
 example, here's how you can poison the dentry cache as well as all kmalloc
-slabs:
+slabs::
 
 	slub_debug=P,kmalloc-*,dentry
 
diff --git a/include/linux/wait.h b/include/linux/wait.h
index ed7c122cb31f..deedfe2b9ffe 100644
--- a/include/linux/wait.h
+++ b/include/linux/wait.h
@@ -101,7 +101,7 @@ init_waitqueue_func_entry(struct wait_queue_entry *wq_entry, wait_queue_func_t f
  * lead to sporadic and non-obvious failure.
  *
  * Use either while holding wait_queue_head::lock or when used for wakeups
- * with an extra smp_mb() like:
+ * with an extra smp_mb() like::
  *
  *      CPU0 - waker                    CPU1 - waiter
  *
-- 
2.21.0

[PATCH 3/9] docs: Remove unnecessary reference link title

[Tobin C. Harding]

Labels that precede a heading use the heading as the link title.
Explicitly adding the link title defeats the purpose of this feature
i.e. makes the reference less maintainable.

Remove unnecessary reference link title.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/admin-guide/mm/numa_memory_policy.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)

diff --git a/Documentation/admin-guide/mm/numa_memory_policy.rst b/Documentation/admin-guide/mm/numa_memory_policy.rst
index d78c5b315f72..1ef0146eaa4d 100644
--- a/Documentation/admin-guide/mm/numa_memory_policy.rst
+++ b/Documentation/admin-guide/mm/numa_memory_policy.rst
@@ -20,8 +20,7 @@ which is an administrative mechanism for restricting the nodes from which
 memory may be allocated by a set of processes. Memory policies are a
 programming interface that a NUMA-aware application can take advantage of.  When
 both cpusets and policies are applied to a task, the restrictions of the cpuset
-takes priority.  See :ref:`Memory Policies and cpusets <mem_pol_and_cpusets>`
-below for more details.
+takes priority.  See :ref:`mem_pol_and_cpusets` below for more details.
 
 Memory Policy Concepts
 ======================
@@ -56,7 +55,7 @@ Task/Process Policy
 	[clone() w/o the CLONE_VM flag] and exec*().  This allows a parent task
 	to establish the task policy for a child task exec()'d from an
 	executable image that has no awareness of memory policy.  See the
-	:ref:`Memory Policy APIs <memory_policy_apis>` section,
+	:ref:`memory_policy_apis` section,
 	below, for an overview of the system call
 	that a task may use to set/change its task/process policy.
 
@@ -77,7 +76,7 @@ VMA Policy
 	A "VMA" or "Virtual Memory Area" refers to a range of a task's
 	virtual address space.  A task may define a specific policy for a range
 	of its virtual address space.   See the
-	:ref:`Memory Policy APIs <memory_policy_apis>` section,
+	:ref:`memory_policy_apis` section,
 	below, for an overview of the mbind() system call used to set a VMA
 	policy.
 
@@ -142,7 +141,7 @@ Shared Policy
 	Although hugetlbfs segments now support lazy allocation, their support
 	for shared policy has not been completed.
 
-	As mentioned above in :ref:`VMA policies <vma_policy>` section,
+	As mentioned above in :ref:`vma_policy` section,
 	allocations of page cache pages for regular files mmap()ed
 	with MAP_SHARED ignore any VMA policy installed on the virtual
 	address range backed by the shared file mapping.  Rather,
-- 
2.21.0

[PATCH 4/9] docs: Use reference to link to rst file

[Tobin C. Harding]

Current document includes the path to an RST doc file.  Since this is an
RST file we can make this a link.  Keeps the path as the link title
since that what the original author wrote.

Use reference to link to rst file.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/vm/numa.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/vm/numa.rst b/Documentation/vm/numa.rst
index 185d8a568168..5cae13e9a08b 100644
--- a/Documentation/vm/numa.rst
+++ b/Documentation/vm/numa.rst
@@ -109,8 +109,8 @@ System administrators and application designers can restrict a task's migration
 to improve NUMA locality using various CPU affinity command line interfaces,
 such as taskset(1) and numactl(1), and program interfaces such as
 sched_setaffinity(2).  Further, one can modify the kernel's default local
-allocation behavior using Linux NUMA memory policy.
-[see Documentation/admin-guide/mm/numa_memory_policy.rst.]
+allocation behavior using Linux NUMA memory policy. [see
+:ref:`Documentation/admin-guide/mm/numa_memory_policy.rst <numa_memory_policy>`].
 
 System administrators can restrict the CPUs and nodes' memories that a non-
 privileged user can specify in the scheduling or NUMA commands and functions
-- 
2.21.0

[PATCH 5/9] docs: Replace backtick with apostrophe.

[Tobin C. Harding]

Sphinx emits:

	WARNING: Inline interpreted text or phrase reference
	start-string without end-string.

This is caused by a spurious backtick.

Replace backtick with apostrophe.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 include/linux/kernel.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/include/linux/kernel.h b/include/linux/kernel.h
index 8f0e68e250a7..59c16c763086 100644
--- a/include/linux/kernel.h
+++ b/include/linux/kernel.h
@@ -134,7 +134,7 @@
  * Rounds @x up to next multiple of @y. If @y will always be a power
  * of 2, consider using the faster round_up().
  *
- * The `const' here prevents gcc-3.3 from calling __divdi3
+ * The 'const' here prevents gcc-3.3 from calling __divdi3
  */
 #define roundup(x, y) (					\
 {							\
-- 
2.21.0

Re: [PATCH 5/9] docs: Replace backtick with apostrophe.

[Randy Dunlap]

On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> Sphinx emits:
> 
> 	WARNING: Inline interpreted text or phrase reference
> 	start-string without end-string.
> 
> This is caused by a spurious backtick.
> 
> Replace backtick with apostrophe.
> 
> Signed-off-by: Tobin C. Harding <tobin@kernel.org>
> ---
>  include/linux/kernel.h | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
> 
> diff --git a/include/linux/kernel.h b/include/linux/kernel.h
> index 8f0e68e250a7..59c16c763086 100644
> --- a/include/linux/kernel.h
> +++ b/include/linux/kernel.h
> @@ -134,7 +134,7 @@
>   * Rounds @x up to next multiple of @y. If @y will always be a power
>   * of 2, consider using the faster round_up().
>   *
> - * The `const' here prevents gcc-3.3 from calling __divdi3
> + * The 'const' here prevents gcc-3.3 from calling __divdi3
>   */
>  #define roundup(x, y) (					\
>  {							\
> 

That line is being removed completely since gcc 3.3 is no longer supported.


-- 
~Randy

[PATCH 6/9] docs: Use correct list markup character

[Tobin C. Harding]

Sphinx uses a star not a hyphen for lists.

Use correct list markup character.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/driver-api/gpio/board.rst |  5 +++--
 Documentation/laptops/lg-laptop.rst     | 12 ++++++------
 2 files changed, 9 insertions(+), 8 deletions(-)

diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst
index a0f294e2e250..a5d5c22ab610 100644
--- a/Documentation/driver-api/gpio/board.rst
+++ b/Documentation/driver-api/gpio/board.rst
@@ -204,8 +204,9 @@ between a caller and a respective .get/set_multiple() callback of a GPIO chip.
 
 In order to qualify for fast bitmap processing, the array must meet the
 following requirements:
-- pin hardware number of array member 0 must also be 0,
-- pin hardware numbers of consecutive array members which belong to the same
+
+* pin hardware number of array member 0 must also be 0.
+* pin hardware numbers of consecutive array members which belong to the same
   chip as member 0 does must also match their array indexes.
 
 Otherwise fast bitmap processing path is not used in order to avoid consecutive
diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/laptops/lg-laptop.rst
index e486fe7ddc35..d9e560dfd045 100644
--- a/Documentation/laptops/lg-laptop.rst
+++ b/Documentation/laptops/lg-laptop.rst
@@ -9,12 +9,12 @@ Hotkeys
 -------
 
 The following FN keys are ignored by the kernel without this driver:
-- FN-F1 (LG control panel)   - Generates F15
-- FN-F5 (Touchpad toggle)    - Generates F13
-- FN-F6 (Airplane mode)      - Generates RFKILL
-- FN-F8 (Keyboard backlight) - Generates F16.
-  This key also changes keyboard backlight mode.
-- FN-F9 (Reader mode)        - Generates F14
+
+* FN-F1 (LG control panel)   - Generates F15
+* FN-F5 (Touchpad toggle)    - Generates F13
+* FN-F6 (Airplane mode)      - Generates RFKILL
+* FN-F8 (Keyboard backlight) - Generates F16 (This key also changes keyboard backlight mode)
+* FN-F9 (Reader mode)        - Generates F14
 
 The rest of the FN key work without a need for a special driver.
 
-- 
2.21.0

Re: [PATCH 6/9] docs: Use correct list markup character

[Randy Dunlap]

On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> Sphinx uses a star not a hyphen for lists.
> 
> Use correct list markup character.
> 
> Signed-off-by: Tobin C. Harding <tobin@kernel.org>

Hi Tobin,

The blank line insertions are all that is needed.
And I have already sent a patch for that.

Also, a list can begin with any of:
"A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed by whitespace, is a bullet list item (a.k.a. "unordered" list item)."

from http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists


> ---
>  Documentation/driver-api/gpio/board.rst |  5 +++--
>  Documentation/laptops/lg-laptop.rst     | 12 ++++++------
>  2 files changed, 9 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/driver-api/gpio/board.rst b/Documentation/driver-api/gpio/board.rst
> index a0f294e2e250..a5d5c22ab610 100644
> --- a/Documentation/driver-api/gpio/board.rst
> +++ b/Documentation/driver-api/gpio/board.rst
> @@ -204,8 +204,9 @@ between a caller and a respective .get/set_multiple() callback of a GPIO chip.
>  
>  In order to qualify for fast bitmap processing, the array must meet the
>  following requirements:
> -- pin hardware number of array member 0 must also be 0,
> -- pin hardware numbers of consecutive array members which belong to the same
> +
> +* pin hardware number of array member 0 must also be 0.
> +* pin hardware numbers of consecutive array members which belong to the same
>    chip as member 0 does must also match their array indexes.
>  
>  Otherwise fast bitmap processing path is not used in order to avoid consecutive
> diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/laptops/lg-laptop.rst
> index e486fe7ddc35..d9e560dfd045 100644
> --- a/Documentation/laptops/lg-laptop.rst
> +++ b/Documentation/laptops/lg-laptop.rst
> @@ -9,12 +9,12 @@ Hotkeys
>  -------
>  
>  The following FN keys are ignored by the kernel without this driver:
> -- FN-F1 (LG control panel)   - Generates F15
> -- FN-F5 (Touchpad toggle)    - Generates F13
> -- FN-F6 (Airplane mode)      - Generates RFKILL
> -- FN-F8 (Keyboard backlight) - Generates F16.
> -  This key also changes keyboard backlight mode.
> -- FN-F9 (Reader mode)        - Generates F14
> +
> +* FN-F1 (LG control panel)   - Generates F15
> +* FN-F5 (Touchpad toggle)    - Generates F13
> +* FN-F6 (Airplane mode)      - Generates RFKILL
> +* FN-F8 (Keyboard backlight) - Generates F16 (This key also changes keyboard backlight mode)
> +* FN-F9 (Reader mode)        - Generates F14
>  
>  The rest of the FN key work without a need for a special driver.
>  
> 


-- 
~Randy

Re: [PATCH 6/9] docs: Use correct list markup character

[Tobin C. Harding]

On Thu, Mar 07, 2019 at 07:40:14PM -0800, Randy Dunlap wrote:
> On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> > Sphinx uses a star not a hyphen for lists.
> > 
> > Use correct list markup character.
> > 
> > Signed-off-by: Tobin C. Harding <tobin@kernel.org>
> 
> Hi Tobin,
> 
> The blank line insertions are all that is needed.
> And I have already sent a patch for that.
> 
> Also, a list can begin with any of:
> "A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed by whitespace, is a bullet list item (a.k.a. "unordered" list item)."

Oh, cool.  I didn't realise.  Thanks Randy.

	Tobin

[PATCH 7/9] docs: Remove unknown 'hint' directive

[Tobin C. Harding]

Current RST file contains an unknown directive causing Sphinx to emit

	ERROR: Unexpected indentation.

Use normal language construct instead.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/driver-api/dmaengine/dmatest.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst
index 8d81f1a7169b..25eecd2769b0 100644
--- a/Documentation/driver-api/dmaengine/dmatest.rst
+++ b/Documentation/driver-api/dmaengine/dmatest.rst
@@ -59,8 +59,8 @@ parameter, that specific channel is requested using the dmaengine and a thread
 is created with the existing parameters. This thread is set as pending
 and will be executed once run is set to 1. Any parameters set after the thread
 is created are not applied.
-.. hint::
-  available channel list could be extracted by running the following command::
+
+Hint: available channel list could be extracted by running the following command::
 
     % ls -1 /sys/class/dma/
 
-- 
2.21.0

Re: [PATCH 7/9] docs: Remove unknown 'hint' directive

[Randy Dunlap]

On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> Current RST file contains an unknown directive causing Sphinx to emit
> 
> 	ERROR: Unexpected indentation.
> 
> Use normal language construct instead.
> 
> Signed-off-by: Tobin C. Harding <tobin@kernel.org>

This is a good idea.  My previous patch eliminated the warning but the
..hint is not presented very well in the generated output.  :)

Thanks.

> ---
>  Documentation/driver-api/dmaengine/dmatest.rst | 4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst
> index 8d81f1a7169b..25eecd2769b0 100644
> --- a/Documentation/driver-api/dmaengine/dmatest.rst
> +++ b/Documentation/driver-api/dmaengine/dmatest.rst
> @@ -59,8 +59,8 @@ parameter, that specific channel is requested using the dmaengine and a thread
>  is created with the existing parameters. This thread is set as pending
>  and will be executed once run is set to 1. Any parameters set after the thread
>  is created are not applied.
> -.. hint::
> -  available channel list could be extracted by running the following command::
> +
> +Hint: available channel list could be extracted by running the following command::
>  
>      % ls -1 /sys/class/dma/
>  
> 


-- 
~Randy

Re: [PATCH 7/9] docs: Remove unknown 'hint' directive

[Markus Heiser]

Am 08.03.19 um 04:51 schrieb Randy Dunlap:
> On 3/7/19 1:11 PM, Tobin C. Harding wrote:
>> Current RST file contains an unknown directive causing Sphinx to emit
>>
>> 	ERROR: Unexpected indentation.
>>
>> Use normal language construct instead.
>>
>> Signed-off-by: Tobin C. Harding <tobin@kernel.org>
> 
> This is a good idea.  My previous patch eliminated the warning but the
> ..hint is not presented very well in the generated output.  :)
> 
> Thanks.
> 
>> ---
>>   Documentation/driver-api/dmaengine/dmatest.rst | 4 ++--
>>   1 file changed, 2 insertions(+), 2 deletions(-)
>>
>> diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst
>> index 8d81f1a7169b..25eecd2769b0 100644
>> --- a/Documentation/driver-api/dmaengine/dmatest.rst
>> +++ b/Documentation/driver-api/dmaengine/dmatest.rst
>> @@ -59,8 +59,8 @@ parameter, that specific channel is requested using the dmaengine and a thread
>>   is created with the existing parameters. This thread is set as pending
>>   and will be executed once run is set to 1. Any parameters set after the thread
>>   is created are not applied.


Here a blank line is missed. Thats while '.. hint:' directive is not detected
well.  Without the blank line the '.. hint:` string is a part of the section
above.

>> -.. hint::
>> -  available channel list could be extracted by running the following command::
>> +
>> +Hint: available channel list could be extracted by running the following command::
>>   
>>       % ls -1 /sys/class/dma/

   -- Markus --

Re: [PATCH 7/9] docs: Remove unknown 'hint' directive

[Randy Dunlap]

On 3/8/19 12:27 AM, Markus Heiser wrote:
> 
> Am 08.03.19 um 04:51 schrieb Randy Dunlap:
>> On 3/7/19 1:11 PM, Tobin C. Harding wrote:
>>> Current RST file contains an unknown directive causing Sphinx to emit
>>>
>>>     ERROR: Unexpected indentation.
>>>
>>> Use normal language construct instead.
>>>
>>> Signed-off-by: Tobin C. Harding <tobin@kernel.org>
>>
>> This is a good idea.  My previous patch eliminated the warning but the
>> ..hint is not presented very well in the generated output.  :)
>>
>> Thanks.
>>
>>> ---
>>>   Documentation/driver-api/dmaengine/dmatest.rst | 4 ++--
>>>   1 file changed, 2 insertions(+), 2 deletions(-)
>>>
>>> diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst
>>> index 8d81f1a7169b..25eecd2769b0 100644
>>> --- a/Documentation/driver-api/dmaengine/dmatest.rst
>>> +++ b/Documentation/driver-api/dmaengine/dmatest.rst
>>> @@ -59,8 +59,8 @@ parameter, that specific channel is requested using the dmaengine and a thread
>>>   is created with the existing parameters. This thread is set as pending
>>>   and will be executed once run is set to 1. Any parameters set after the thread
>>>   is created are not applied.
> 
> 
> Here a blank line is missed. Thats while '.. hint:' directive is not detected
> well.  Without the blank line the '.. hint:` string is a part of the section
> above.

I added a blank line and the ..hint still is not handled in any special
manner.  That's why I prefer Tobin's patch.

>>> -.. hint::
>>> -  available channel list could be extracted by running the following command::
>>> +
>>> +Hint: available channel list could be extracted by running the following command::
>>>         % ls -1 /sys/class/dma/
> 
>   -- Markus --
> 


-- 
~Randy

Re: [PATCH 7/9] docs: Remove unknown 'hint' directive

[Randy Dunlap]

On 3/8/19 8:04 AM, Randy Dunlap wrote:
> On 3/8/19 12:27 AM, Markus Heiser wrote:
>>
>> Am 08.03.19 um 04:51 schrieb Randy Dunlap:
>>> On 3/7/19 1:11 PM, Tobin C. Harding wrote:
>>>> Current RST file contains an unknown directive causing Sphinx to emit
>>>>
>>>>     ERROR: Unexpected indentation.
>>>>
>>>> Use normal language construct instead.
>>>>
>>>> Signed-off-by: Tobin C. Harding <tobin@kernel.org>
>>>
>>> This is a good idea.  My previous patch eliminated the warning but the
>>> ..hint is not presented very well in the generated output.  :)
>>>
>>> Thanks.
>>>
>>>> ---
>>>>   Documentation/driver-api/dmaengine/dmatest.rst | 4 ++--
>>>>   1 file changed, 2 insertions(+), 2 deletions(-)
>>>>
>>>> diff --git a/Documentation/driver-api/dmaengine/dmatest.rst b/Documentation/driver-api/dmaengine/dmatest.rst
>>>> index 8d81f1a7169b..25eecd2769b0 100644
>>>> --- a/Documentation/driver-api/dmaengine/dmatest.rst
>>>> +++ b/Documentation/driver-api/dmaengine/dmatest.rst
>>>> @@ -59,8 +59,8 @@ parameter, that specific channel is requested using the dmaengine and a thread
>>>>   is created with the existing parameters. This thread is set as pending
>>>>   and will be executed once run is set to 1. Any parameters set after the thread
>>>>   is created are not applied.
>>
>>
>> Here a blank line is missed. Thats while '.. hint:' directive is not detected
>> well.  Without the blank line the '.. hint:` string is a part of the section
>> above.
> 
> I added a blank line and the ..hint still is not handled in any special
> manner.  That's why I prefer Tobin's patch.

Nak.  :(
I had looked at the wrong output file.
With my "blank line patch" applied, the ..hint directive does work,
so only the blank line is needed, as Markus said.


>>>> -.. hint::
>>>> -  available channel list could be extracted by running the following command::
>>>> +
>>>> +Hint: available channel list could be extracted by running the following command::
>>>>         % ls -1 /sys/class/dma/
>>
>>   -- Markus --
>>
> 
> 


-- 
~Randy

[PATCH 8/9] docs: Fix Title underline too short warning

[Tobin C. Harding]

Sphinx emits a bunch of 'Title underline too short' warnings.  We can
fix these by using the correct length underlines.

Fix Title underline too short warning by amending heading underline.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/filesystems/path-lookup.rst | 24 +++++-----
 Documentation/networking/snmp_counter.rst | 58 +++++++++++------------
 2 files changed, 41 insertions(+), 41 deletions(-)

diff --git a/Documentation/filesystems/path-lookup.rst b/Documentation/filesystems/path-lookup.rst
index 9d6b68853f5b..80e22eda4132 100644
--- a/Documentation/filesystems/path-lookup.rst
+++ b/Documentation/filesystems/path-lookup.rst
@@ -344,7 +344,7 @@ In particular it is held while scanning chains in the dcache hash
 table, and the mount point hash table.
 
 Bringing it together with ``struct nameidata``
---------------------------------------------
+----------------------------------------------
 
 .. _First edition Unix: http://minnie.tuhs.org/cgi-bin/utree.pl?file=V1/u2.s
 
@@ -355,7 +355,7 @@ converts a "name" to an "inode".  ``struct nameidata`` contains (among
 other fields):
 
 ``struct path path``
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
 
 A ``path`` contains a ``struct vfsmount`` (which is
 embedded in a ``struct mount``) and a ``struct dentry``.  Together these
@@ -366,13 +366,13 @@ step.  A reference through ``d_lockref`` and ``mnt_count`` is always
 held.
 
 ``struct qstr last``
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
 
 This is a string together with a length (i.e. _not_ ``nul`` terminated)
 that is the "next" component in the pathname.
 
 ``int last_type``
-~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~
 
 This is one of ``LAST_NORM``, ``LAST_ROOT``, ``LAST_DOT``, ``LAST_DOTDOT``, or
 ``LAST_BIND``.  The ``last`` field is only valid if the type is
@@ -381,7 +381,7 @@ components of the symlink have been processed yet.  Others should be
 fairly self-explanatory.
 
 ``struct path root``
-~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~
 
 This is used to hold a reference to the effective root of the
 filesystem.  Often that reference won't be needed, so this field is
@@ -510,7 +510,7 @@ potentially interesting things about these dentries corresponding
 to three different flags that might be set in ``dentry->d_flags``:
 
 ``DCACHE_MANAGE_TRANSIT``
-~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If this flag has been set, then the filesystem has requested that the
 ``d_manage()`` dentry operation be called before handling any possible
@@ -529,7 +529,7 @@ filesystem, which will then give it a special pass through
 ``d_manage()`` by returning ``-EISDIR``.
 
 ``DCACHE_MOUNTED``
-~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~
 
 This flag is set on every dentry that is mounted on.  As Linux
 supports multiple filesystem namespaces, it is possible that the
@@ -542,7 +542,7 @@ If this flag is set, and ``d_manage()`` didn't return ``-EISDIR``,
 and a new ``dentry`` (both with counted references).
 
 ``DCACHE_NEED_AUTOMOUNT``
-~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
 If ``d_manage()`` allowed us to get this far, and ``lookup_mnt()`` didn't
 find a mount point, then this flag causes the ``d_automount()`` dentry
@@ -698,7 +698,7 @@ With that little refresher on seqlocks out of the way we can look at
 the bigger picture of how RCU-walk uses seqlocks.
 
 ``mount_lock`` and ``nd->m_seq``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 We already met the ``mount_lock`` seqlock when REF-walk used it to
 ensure that crossing a mount point is performed safely.  RCU-walk uses
@@ -727,7 +727,7 @@ results would have been the same.  This ensures the invariant holds,
 at least for vfsmount structures.
 
 ``dentry->d_seq`` and ``nd->seq``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 In place of taking a count or lock on ``d_reflock``, RCU-walk samples
 the per-dentry ``d_seq`` seqlock, and stores the sequence number in the
@@ -774,7 +774,7 @@ getting a counted reference to the new dentry before dropping that for
 the old dentry which we saw in REF-walk.
 
 No ``inode->i_rwsem`` or even ``rename_lock``
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A semaphore is a fairly heavyweight lock that can only be taken when it is
 permissible to sleep.  As ``rcu_read_lock()`` forbids sleeping,
@@ -796,7 +796,7 @@ locking.  This neatly handles all cases, so adding extra checks on
 rename_lock would bring no significant value.
 
 ``unlazy walk()`` and ``complete_walk()``
--------------------------------------
+-----------------------------------------
 
 That "dropping down to REF-walk" typically involves a call to
 ``unlazy_walk()``, so named because "RCU-walk" is also sometimes
diff --git a/Documentation/networking/snmp_counter.rst b/Documentation/networking/snmp_counter.rst
index fe8f741193be..4054f3614730 100644
--- a/Documentation/networking/snmp_counter.rst
+++ b/Documentation/networking/snmp_counter.rst
@@ -5,7 +5,7 @@ SNMP counter
 This document explains the meaning of SNMP counters.
 
 General IPv4 counters
-====================
+=====================
 All layer 4 packets and ICMP packets will change these counters, but
 these counters won't be changed by layer 2 packets (such as STP) or
 ARP packets.
@@ -112,7 +112,7 @@ dropped in the IP sending path and no route is found for it.
 .. _RFC1213 ipOutNoRoutes: https://tools.ietf.org/html/rfc1213#page-29
 
 ICMP counters
-============
+=============
 * IcmpInMsgs and IcmpOutMsgs
 Defined by `RFC1213 icmpInMsgs`_ and `RFC1213 icmpOutMsgs`_
 
@@ -209,7 +209,7 @@ and the sending packet path use IcmpOutErrors. When IcmpInCsumErrors
 is increased, IcmpInErrors would always be increased too.
 
 relationship of the ICMP counters
--------------------------------
+---------------------------------
 The sum of IcmpMsgOutType[N] is always equal to IcmpOutMsgs, as they
 are updated at the same time. The sum of IcmpMsgInType[N] plus
 IcmpInErrors should be equal or larger than IcmpInMsgs. When kernel
@@ -229,7 +229,7 @@ IcmpInMsgs should be less than the sum of IcmpMsgOutType[N] plus
 IcmpInErrors.
 
 General TCP counters
-==================
+====================
 * TcpInSegs
 Defined in `RFC1213 tcpInSegs`_
 
@@ -356,7 +356,7 @@ process might be failed due to some errors (e.g. memory alloc failed).
 
 
 TCP Fast Path
-============
+=============
 When kernel receives a TCP packet, it has two paths to handler the
 packet, one is fast path, another is slow path. The comment in kernel
 code provides a good explanation of them, I pasted them below::
@@ -401,7 +401,7 @@ increase 1.
 
 
 TCP abort
-========
+=========
 * TcpExtTCPAbortOnData
 It means TCP layer has data in flight, but need to close the
 connection. So TCP layer sends a RST to the other side, indicate the
@@ -465,7 +465,7 @@ TcpExtTCPAbortFailed will be increased.
 .. _RFC2525 2.17 section: https://tools.ietf.org/html/rfc2525#page-50
 
 TCP Hybrid Slow Start
-====================
+=====================
 The Hybrid Slow Start algorithm is an enhancement of the traditional
 TCP congestion window Slow Start algorithm. It uses two pieces of
 information to detect whether the max bandwidth of the TCP path is
@@ -497,7 +497,7 @@ TcpExtTCPHystartDelayDetect is the average CWND which detected by the
 packet delay.
 
 TCP retransmission and congestion control
-======================================
+=========================================
 The TCP protocol has two retransmission mechanisms: SACK and fast
 recovery. They are exclusive with each other. When SACK is enabled,
 the kernel TCP stack would use SACK, or kernel would use fast
@@ -590,7 +590,7 @@ The TCP stack receives a DSACK, which indicate an out of order
 duplicate packet is received.
 
 invalid SACK and DSACK
-====================
+======================
 When a SACK (or DSACK) block is invalid, a corresponding counter would
 be updated. The validation method is base on the start/end sequence
 number of the SACK block. For more details, please refer the comment
@@ -619,7 +619,7 @@ will be updated. If the undo_marker is set, TcpExtTCPDSACKIgnoredOld
 will be updated. As implied in its name, it might be an old packet.
 
 SACK shift
-=========
+==========
 The linux networking stack stores data in sk_buff struct (skb for
 short). If a SACK block acrosses multiple skb, the TCP stack will try
 to re-arrange data in these skb. E.g. if a SACK block acknowledges seq
@@ -640,7 +640,7 @@ A skb should be shifted or merged, but the TCP stack doesn't do it for
 some reasons.
 
 TCP out of order
-===============
+================
 * TcpExtTCPOFOQueue
 The TCP layer receives an out of order packet and has enough memory
 to queue it.
@@ -656,7 +656,7 @@ packet. the overlay part will be dropped. All of TcpExtTCPOFOMerge
 packets will also be counted into TcpExtTCPOFOQueue.
 
 TCP PAWS
-=======
+========
 PAWS (Protection Against Wrapped Sequence numbers) is an algorithm
 which is used to drop old packets. It depends on the TCP
 timestamps. For detail information, please refer the `timestamp wiki`_
@@ -672,7 +672,7 @@ Packets are dropped by PAWS in Syn-Sent status.
 Packets are dropped by PAWS in any status other than Syn-Sent.
 
 TCP ACK skip
-===========
+============
 In some scenarios, kernel would avoid sending duplicate ACKs too
 frequently. Please find more details in the tcp_invalid_ratelimit
 section of the `sysctl document`_. When kernel decides to skip an ACK
@@ -729,7 +729,7 @@ unacknowledged number (more strict than `RFC 5961 section 5.2`_).
 .. _RFC 5961 section 5.2: https://tools.ietf.org/html/rfc5961#page-11
 
 TCP receive window
-=================
+==================
 * TcpExtTCPWantZeroWindowAdv
 Depending on current memory usage, the TCP stack tries to set receive
 window to zero. But the receive window might still be a no-zero
@@ -745,7 +745,7 @@ The TCP receive window is set to no-zero value from zero.
 
 
 Delayed ACK
-==========
+===========
 The TCP Delayed ACK is a technique which is used for reducing the
 packet count in the network. For more details, please refer the
 `Delayed ACK wiki`_
@@ -771,7 +771,7 @@ triggered by other reasons, such as a packet is duplicated in the
 network.
 
 Tail Loss Probe (TLP)
-===================
+=====================
 TLP is an algorithm which is used to detect TCP packet loss. For more
 details, please refer the `TLP paper`_.
 
@@ -784,10 +784,10 @@ A TLP probe packet is sent.
 A packet loss is detected and recovered by TLP.
 
 examples
-=======
+========
 
 ping test
---------
+---------
 Run the ping command against the public dns server 8.8.8.8::
 
   nstatuser@nstat-a:~$ ping 8.8.8.8 -c 1
@@ -831,7 +831,7 @@ and its corresponding Echo Reply packet are constructed by:
 So the IpExtInOctets and IpExtOutOctets are 20+16+48=84.
 
 tcp 3-way handshake
-------------------
+-------------------
 On server side, we run::
 
   nstatuser@nstat-b:~$ nc -lknv 0.0.0.0 9000
@@ -873,7 +873,7 @@ ACK, so client sent 2 packets, received 1 packet, TcpInSegs increased
 1, TcpOutSegs increased 2.
 
 TCP normal traffic
------------------
+------------------
 Run nc on server::
 
   nstatuser@nstat-b:~$ nc -lkv 0.0.0.0 9000
@@ -996,7 +996,7 @@ and the packet received from client qualified for fast path, so it
 was counted into 'TcpExtTCPHPHits'.
 
 TcpExtTCPAbortOnClose
---------------------
+---------------------
 On the server side, we run below python script::
 
   import socket
@@ -1030,7 +1030,7 @@ If we run tcpdump on the server side, we could find the server sent a
 RST after we type Ctrl-C.
 
 TcpExtTCPAbortOnMemory and TcpExtTCPAbortOnTimeout
------------------------------------------------
+--------------------------------------------------
 Below is an example which let the orphan socket count be higher than
 net.ipv4.tcp_max_orphans.
 Change tcp_max_orphans to a smaller value on client::
@@ -1152,7 +1152,7 @@ FIN_WAIT_1 state finally. So we wait for a few minutes, we could find
   TcpExtTCPAbortOnTimeout         10                 0.0
 
 TcpExtTCPAbortOnLinger
----------------------
+----------------------
 The server side code::
 
   nstatuser@nstat-b:~$ cat server_linger.py
@@ -1197,7 +1197,7 @@ After run client_linger.py, check the output of nstat::
   TcpExtTCPAbortOnLinger          1                  0.0
 
 TcpExtTCPRcvCoalesce
--------------------
+--------------------
 On the server, we run a program which listen on TCP port 9000, but
 doesn't read any data::
 
@@ -1257,7 +1257,7 @@ the receiving queue. So the TCP layer merged the two packets, and we
 could find the TcpExtTCPRcvCoalesce increased 1.
 
 TcpExtListenOverflows and TcpExtListenDrops
-----------------------------------------
+-------------------------------------------
 On server, run the nc command, listen on port 9000::
 
   nstatuser@nstat-b:~$ nc -lkv 0.0.0.0 9000
@@ -1305,7 +1305,7 @@ TcpExtListenOverflows and TcpExtListenDrops would be larger, because
 the SYN of the 4th nc was dropped, the client was retrying.
 
 IpInAddrErrors, IpExtInNoRoutes and IpOutNoRoutes
-----------------------------------------------
+-------------------------------------------------
 server A IP address: 192.168.122.250
 server B IP address: 192.168.122.251
 Prepare on server A, add a route to server B::
@@ -1400,7 +1400,7 @@ a route for the 8.8.8.8 IP address, so server B increased
 IpOutNoRoutes.
 
 TcpExtTCPACKSkippedSynRecv
-------------------------
+--------------------------
 In this test, we send 3 same SYN packets from client to server. The
 first SYN will let server create a socket, set it to Syn-Recv status,
 and reply a SYN/ACK. The second SYN will let server reply the SYN/ACK
@@ -1448,7 +1448,7 @@ Check snmp cunter on nstat-b::
 As we expected, TcpExtTCPACKSkippedSynRecv is 1.
 
 TcpExtTCPACKSkippedPAWS
-----------------------
+-----------------------
 To trigger PAWS, we could send an old SYN.
 
 On nstat-b, let nc listen on port 9000::
@@ -1485,7 +1485,7 @@ failed, the nstat-b replied an ACK for the first SYN, skipped the ACK
 for the second SYN, and updated TcpExtTCPACKSkippedPAWS.
 
 TcpExtTCPACKSkippedSeq
---------------------
+----------------------
 To trigger TcpExtTCPACKSkippedSeq, we send packets which have valid
 timestamp (to pass PAWS check) but the sequence number is out of
 window. The linux TCP stack would avoid to skip if the packet has
-- 
2.21.0

Re: [PATCH 8/9] docs: Fix Title underline too short warning

[Randy Dunlap]

On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> Sphinx emits a bunch of 'Title underline too short' warnings.  We can
> fix these by using the correct length underlines.
> 
> Fix Title underline too short warning by amending heading underline.
> 
> Signed-off-by: Tobin C. Harding <tobin@kernel.org>
> ---
>  Documentation/filesystems/path-lookup.rst | 24 +++++-----
>  Documentation/networking/snmp_counter.rst | 58 +++++++++++------------
>  2 files changed, 41 insertions(+), 41 deletions(-)

Hi,

These are already fixed.  Did you try the pending docs tree
(for which a pull request was sent a few hours ago)?

thanks,
-- 
~Randy

Re: [PATCH 8/9] docs: Fix Title underline too short warning

[Tobin C. Harding]

On Thu, Mar 07, 2019 at 07:42:03PM -0800, Randy Dunlap wrote:
> On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> > Sphinx emits a bunch of 'Title underline too short' warnings.  We can
> > fix these by using the correct length underlines.
> > 
> > Fix Title underline too short warning by amending heading underline.
> > 
> > Signed-off-by: Tobin C. Harding <tobin@kernel.org>
> > ---
> >  Documentation/filesystems/path-lookup.rst | 24 +++++-----
> >  Documentation/networking/snmp_counter.rst | 58 +++++++++++------------
> >  2 files changed, 41 insertions(+), 41 deletions(-)
> 
> Hi,
> 
> These are already fixed.  Did you try the pending docs tree
> (for which a pull request was sent a few hours ago)?

Oh man, - face palm.  I've been hacking on mm lately and they use
mainline, thanks for response.

	  Tobin

[PATCH 9/9] docs: Add blank line after SPDX licence identifier

[Tobin C. Harding]

Sphinx emits warning

	WARNING: Explicit markup ends without a blank line; unexpected
	unindent.

This is caused by a missing line after the SPDX license identifier.

Add blank line after SPDX licence identifier.

Signed-off-by: Tobin C. Harding <tobin@kernel.org>
---
 Documentation/laptops/lg-laptop.rst   | 1 +
 Documentation/misc-devices/ibmvmc.rst | 1 +
 2 files changed, 2 insertions(+)

diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/laptops/lg-laptop.rst
index d9e560dfd045..f2012d2dcb9d 100644
--- a/Documentation/laptops/lg-laptop.rst
+++ b/Documentation/laptops/lg-laptop.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0+
+
 LG Gram laptop extra features
 =============================
 
diff --git a/Documentation/misc-devices/ibmvmc.rst b/Documentation/misc-devices/ibmvmc.rst
index 46ded79554d4..b46df4ea2b81 100644
--- a/Documentation/misc-devices/ibmvmc.rst
+++ b/Documentation/misc-devices/ibmvmc.rst
@@ -1,4 +1,5 @@
 .. SPDX-License-Identifier: GPL-2.0+
+
 ======================================================
 IBM Virtual Management Channel Kernel Driver (IBMVMC)
 ======================================================
-- 
2.21.0

Re: [PATCH 9/9] docs: Add blank line after SPDX licence identifier

[Randy Dunlap]

On 3/7/19 1:11 PM, Tobin C. Harding wrote:
> Sphinx emits warning
> 
> 	WARNING: Explicit markup ends without a blank line; unexpected
> 	unindent.
> 
> This is caused by a missing line after the SPDX license identifier.
> 
> Add blank line after SPDX licence identifier.
> 
> Signed-off-by: Tobin C. Harding <tobin@kernel.org>

These are also already fixed.

> ---
>  Documentation/laptops/lg-laptop.rst   | 1 +
>  Documentation/misc-devices/ibmvmc.rst | 1 +
>  2 files changed, 2 insertions(+)
> 
> diff --git a/Documentation/laptops/lg-laptop.rst b/Documentation/laptops/lg-laptop.rst
> index d9e560dfd045..f2012d2dcb9d 100644
> --- a/Documentation/laptops/lg-laptop.rst
> +++ b/Documentation/laptops/lg-laptop.rst
> @@ -1,4 +1,5 @@
>  .. SPDX-License-Identifier: GPL-2.0+
> +
>  LG Gram laptop extra features
>  =============================
>  
> diff --git a/Documentation/misc-devices/ibmvmc.rst b/Documentation/misc-devices/ibmvmc.rst
> index 46ded79554d4..b46df4ea2b81 100644
> --- a/Documentation/misc-devices/ibmvmc.rst
> +++ b/Documentation/misc-devices/ibmvmc.rst
> @@ -1,4 +1,5 @@
>  .. SPDX-License-Identifier: GPL-2.0+
> +
>  ======================================================
>  IBM Virtual Management Channel Kernel Driver (IBMVMC)
>  ======================================================
> 


-- 
~Randy

Re: [PATCH 0/9] docs: Fix various build warnings/errors

[Markus Heiser]

Am 07.03.19 um 22:11 schrieb Tobin C. Harding:
> Hi,
> 
> I had a few hours to spare so I thought I'd clear some Sphinx build
> warnings/errors.  There isn't anything too controversial here.  The only
> interesting thing I hit was in patch 7 (docs: Remove unknown 'hint'
> directive), I couldn't work out if this was a serious directive, a joke,
> or a typo.  

Hi Tobin,

the problem was a missing empty line (see my comment on this patch).

The reST primer from sphinx-doc is always a good reference for the daily work

   http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives

-- Markus --

Re: [PATCH 0/9] docs: Fix various build warnings/errors

[Tobin C. Harding]

On Fri, Mar 08, 2019 at 09:40:03AM +0100, Markus Heiser wrote:
> 
> Am 07.03.19 um 22:11 schrieb Tobin C. Harding:
> > Hi,
> > 
> > I had a few hours to spare so I thought I'd clear some Sphinx build
> > warnings/errors.  There isn't anything too controversial here.  The only
> > interesting thing I hit was in patch 7 (docs: Remove unknown 'hint'
> > directive), I couldn't work out if this was a serious directive, a joke,
> > or a typo.
> 
> Hi Tobin,
> 
> the problem was a missing empty line (see my comment on this patch).
> 
> The reST primer from sphinx-doc is always a good reference for the daily work
> 
>   http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives

Thanks Marcus, that's actually how I came to the conclusion that they
should by asterisks.

	http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks

Anyways, as usual LKML sorted me out :)

thanks,
Tobin.

Re: [PATCH 0/9] docs: Fix various build warnings/errors

[Markus Heiser]

Am 08.03.19 um 21:16 schrieb Tobin C. Harding:
>> Hi Tobin,
>>
>> the problem was a missing empty line (see my comment on this patch).
>>
>> The reST primer from sphinx-doc is always a good reference for the daily work
>>
>>    http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
> Thanks Marcus, that's actually how I came to the conclusion that they
> should by asterisks.
> 
> 	http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks
> 
> Anyways, as usual LKML sorted me out :)

Its only a 'primer', a reduced introduction.  But it gives also some "(ref)"s
to the docutils origin where the refernce of reST is located.

E.g. the first "(ref)" of the chapter "Lists and Quote-like blocks" (you linked
above) points to the bullet list reference at:

   http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#bullet-lists

"""A text block which begins with a "*", "+", "-", "•", "‣", or "⁃", followed by 
whitespace, is a bullet list item"""


-- Markus --

Re: [PATCH 0/9] docs: Fix various build warnings/errors

[Jonathan Corbet]

On Fri,  8 Mar 2019 08:11:44 +1100
"Tobin C. Harding" <tobin@kernel.org> wrote:

> I had a few hours to spare so I thought I'd clear some Sphinx build
> warnings/errors.

So there were comments on various parts of this series; were you planning
to respin it with those taken into account?  Certainly we're all in favor
of fewer warnings!

Thanks,

jon

Re: [PATCH 0/9] docs: Fix various build warnings/errors

[Tobin C. Harding]

On Mon, Mar 25, 2019 at 10:33:33AM -0600, Jonathan Corbet wrote:
> On Fri,  8 Mar 2019 08:11:44 +1100
> "Tobin C. Harding" <tobin@kernel.org> wrote:
> 
> > I had a few hours to spare so I thought I'd clear some Sphinx build
> > warnings/errors.
> 
> So there were comments on various parts of this series; were you planning
> to respin it with those taken into account?  Certainly we're all in favor
> of fewer warnings!

Oh I thought this was dead.  I was under the impression that because I'd
worked off the wrong tree Randy had fixed all these already.

I'll go back and check if any of these fixes are useful still.

Thanks,
Tobin.