docs: Fix various build warnings/errors
Subsystems (4)
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
PATCH v2 2/4 docs: Add colon clearing sphinx warning
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
@@ -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
PATCH v2 1/4 docs: Fix spelling mistake
In reply to Tobin C. HardingDocumentation 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
@@ -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
PATCH v2 3/4 docs: Remove unnecessary reference link title
In reply to Tobin C. HardingLabels 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
@@ -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
PATCH v2 4/4 docs: Use reference to link to rst file
In reply to Tobin C. HardingCurrent 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
@@ -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
Jonathan Corbet
maintainerRe: [PATCH v2 3/4] docs: Remove unnecessary reference link title
In reply to Tobin C. HardingQuoted 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
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.