Skip to contentSkip to conversation

docs: Fix various build warnings/errors

PATCH In review Tobin C. Harding 3 participants 7 messages Apr 9, 2019

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

v2 cover docs: Fix various build warnings/errors

Hi Jon,

Here are the first 4 patches from the v1 of this series that are still useful when applied to the current docs-next branch.

Set does a few minor clean ups, nothing too amazing here. Patch 2 removes three Sphinx build warnings:

Patch 3 is slightly subjective, holla at me (anyone) if you don't like it and I'll remove it.

thanks,
Tobin.

Tobin C. Harding (4):
docs: Fix spelling mistake
docs: Add colon clearing sphinx warning
docs: Remove unnecessary reference link title
docs: Use reference to link to rst file

 Documentation/admin-guide/mm/numa_memory_policy.rst | 9 ++++-----
 Documentation/process/howto.rst                     | 2 +-
 Documentation/vm/numa.rst                           | 4 ++--
 include/linux/wait.h                                | 2 +-
 4 files changed, 8 insertions(+), 9 deletions(-)
Signature · 1 line
2.21.0
#1 lore raw

PATCH v2 1/4 docs: Fix spelling mistake

Documentation contains a spelling mistake / typo.

s/descibed/described/

Fix spelling mistake.

---
 Documentation/process/howto.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/process/howto.rst +1 -1
index ad2b6c852b95..6ab75c11d2c3 100644
@@ -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.
Signature · 1 line
2.21.0
#2 lore raw

PATCH v2 2/4 docs: Add colon clearing sphinx warning

In reply to Tobin C. Harding

Sphinx emits various warnings all caused by a missing colon before code block:

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.

---
 include/linux/wait.h | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
include/linux/wait.h +1 -1
index 5f3efabc36f4..b6f77cf60dd7 100644
@@ -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
  *
Signature · 1 line
2.21.0
#3 lore raw

PATCH v2 3/4 docs: Remove unnecessary reference link title

In reply to Tobin C. Harding

Labels that precede a heading use the heading as the link title. Explicitly adding the link title is redundant and makes the reference slightly less maintainable.

Remove unnecessary reference link title.

---
 Documentation/admin-guide/mm/numa_memory_policy.rst | 9 ++++-----
 1 file changed, 4 insertions(+), 5 deletions(-)
Documentation/admin-guide/mm/numa_memory_policy.rst +4 -5
index d78c5b315f72..1ef0146eaa4d 100644
@@ -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,
Signature · 1 line
2.21.0
maintainer
#4 lore raw

Re: [PATCH v2 3/4] docs: Remove unnecessary reference link title

Quoted 5 lines · On Tue, 9 Apr 2019 10:43:58 +1000 "Tobin C. Harding" <[email protected]> wrote:

Labels that precede a heading use the heading as the link title. Explicitly adding the link title is redundant and makes the reference slightly less maintainable.

Remove unnecessary reference link title.

So I agree with the objective, but...

Documentation/admin-guide/mm/numa_memory_policy.rst Shared Policy · line 144

Quoted 2 lines
Documentation/admin-guide/mm/numa_memory_policy.rst +1 -1
-	As mentioned above in :ref:`VMA policies <vma_policy>` section,
+	As mentioned above in :ref:`vma_policy` section,

...this one generates a warning that highlights a flaw in the reasoning here:

Documentation/admin-guide/mm/numa_memory_policy.rst:144: WARNING:
undefined label: vma-policy (if the link has no caption the label must precede a section header)

Said label does not precede a section header, so it can't be used bare in this way.

I'll apply the other three, but this one needs some repairs :)

Thanks,

jon

#5 lore raw

Re: [PATCH v2 3/4] docs: Remove unnecessary reference link title

Quoted 17 lines · Jonathan Corbet
Quoted 5 lines · On Tue, 9 Apr 2019 10:43:58 +1000 "Tobin C. Harding" <[email protected]> wrote:

Labels that precede a heading use the heading as the link title. Explicitly adding the link title is redundant and makes the reference slightly less maintainable.

Remove unnecessary reference link title.

So I agree with the objective, but...

Documentation/admin-guide/mm/numa_memory_policy.rst Shared Policy · line 144

Quoted 2 lines
Documentation/admin-guide/mm/numa_memory_policy.rst +1 -1
-	As mentioned above in :ref:`VMA policies <vma_policy>` section,
+	As mentioned above in :ref:`vma_policy` section,

...this one generates a warning that highlights a flaw in the reasoning here:

Quoted 6 lines

Documentation/admin-guide/mm/numa_memory_policy.rst:144: WARNING:
undefined label: vma-policy (if the link has no caption the label must precede a section header)

Said label does not precede a section header, so it can't be used bare in this way.

That's weird, I did a clean build before and after applying the set and diffed the stderr outputs, I wonder how I missed this.

Quoted 1 line

I'll apply the other three, but this one needs some repairs :)

thanks,
Tobin.

#6 lore raw

PATCH v2 4/4 docs: Use reference to link to rst file

In reply to 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.

---
 Documentation/vm/numa.rst | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)
Documentation/vm/numa.rst +2 -2
index 185d8a568168..5cae13e9a08b 100644
@@ -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
Signature · 1 line
2.21.0