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

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

[Tobin C. Harding]

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(-)

-- 
2.21.0

[PATCH v2 1/4] 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 ad2b6c852b95..6ab75c11d2c3 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 v2 2/4] docs: Add colon clearing sphinx warning

[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.

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

diff --git a/include/linux/wait.h b/include/linux/wait.h
index 5f3efabc36f4..b6f77cf60dd7 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 v2 3/4] 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 is redundant and  makes the reference
slightly 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

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

[Jonathan Corbet]

On Tue,  9 Apr 2019 10:43:58 +1000
"Tobin C. Harding" <tobin@kernel.org> 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...

> -	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

[Tobin C. Harding]

On Tue, Apr 09, 2019 at 03:20:30PM -0600, Jonathan Corbet wrote:
> On Tue,  9 Apr 2019 10:43:58 +1000
> "Tobin C. Harding" <tobin@kernel.org> 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...
> 
> > -	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.

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.

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

thanks,
Tobin.

[PATCH v2 4/4] 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