Jonathan Corbet [Fri, 20 Mar 2020 23:08:24 +0000 (17:08 -0600)]
Merge branch 'mauro' into docs-next
Mauro says (as he's cleaning up my mess):
This small series address a regression caused by a new patch at
docs-next (and at linux-next).
Before this patch, when a cross-reference to a chapter within the
documentation is needed, we had to add a markup like:
.. _foo:
foo
===
This behavor is now different after this patch:
58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
As a Sphinx extension now creates automatically a reference
like the above, without requiring any extra markup.
That, however, comes with a price: it is not possible anymore to have
two sections with the same name within the entire Kernel docs!
This causes thousands of warnings, as we have sections named
"introduction" on lots of places.
This series solve this regression by doing two changes:
1) The references are now prefixed by the document name. So,
a file named "bar" would have the "foo" reference as "bar:foo".
2) It will only use the first two levels. The first one is (usually) the
name of the document, and the second one the chapter name.
This solves almost all problems we have. Still, there are a few places
where we have two chapters at the same document with the
same name. The first patch addresses this problem.
The second patch limits the escope of the autosectionlabel.
docs: conf.py: avoid thousands of duplicate label warning on Sphinx
The autosectionlabel extension is nice, as it allows to refer to
a section by its name without requiring any extra tag to create
a reference name.
However, on its default, it has two serious problems:
1) the namespace is global. So, two files with different
"introduction" section would create a label with the
same name. This is easily solvable by forcing the extension
to prepend the file name with:
autosectionlabel_prefix_document = True
2) It doesn't work hierarchically. So, if there are two level 1
sessions (let's say, one labeled "open" and another one "ioctl")
and both have a level 2 "synopsis" label, both section 2 will
have the same identical name.
Currently, there's no way to tell Sphinx to create an
hierarchical reference like:
open / synopsis
ioctl / synopsis
This causes around 800 warnings. So, the fix should be to
not let autosectionlabel to produce references for anything
that it is not at a chapter level within any doc, with:
Changeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
enabled a new feature at Sphinx: it will now generate index for each
document title, plus to each chapter inside it.
There's a drawback, though: one document cannot have two sections
with the same name anymore.
A followup patch will change the logic of autosectionlabel to
avoid most creating references for every single section title,
but still we need to be able to reference the chapters inside
a document.
There are a few places where there are two chapters with the
same name. This patch renames one of the chapters, in order to
avoid symbol conflict within the same document.
PS.: as I don't speach Chinese, I had some help from a friend
(Wen Liu) at the Chinese translation for "publishing patches"
for this document:
Jonathan Corbet [Thu, 19 Mar 2020 18:52:01 +0000 (12:52 -0600)]
docs: fix reference to core-api/namespaces.rst
Fix a couple of dangling links to core-api/namespaces.rst by turning them
into proper references. Enable the autosection extension (available since
Sphinx 1.4) to make this work.
Co-developed-by: Federico Vaga <[email protected]> Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/") Signed-off-by: Jonathan Corbet <[email protected]>
Documentation: Better document the softlockup_panic sysctl
Commit 9c44bc03fff4 ("softlockup: allow panic on lockup") added the
softlockup_panic sysctl, but didn't add information about it to the file
Documentation/admin-guide/sysctl/kernel.rst (which in that time certainly
wasn't rst and had other name!).
This patch just adds the respective documentation and references it from
the corresponding entry in Documentation/admin-guide/kernel-parameters.txt.
This patch was strongly based on Scott Wood's commit d22881dc13b6
("Documentation: Better document the hardlockup_panic sysctl").
docs: trace: events.rst: convert some new stuff to ReST format
Some new chapters were added to the documentation. This caused
Sphinx to complain, as the literal blocks there are not properly
tagged as such. Also, a new note added there doesn't follow
the ReST format.
This fixes the following warnings:
Documentation/trace/events.rst:589: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/trace/events.rst:620: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:623: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:626: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:703: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:697: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:722: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:775: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/trace/events.rst:814: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:817: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:820: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:823: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:826: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:829: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:832: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:844: WARNING: Unexpected indentation.
Documentation/trace/events.rst:845: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/trace/events.rst:849: WARNING: Unexpected indentation.
Documentation/trace/events.rst:850: WARNING: Block quote ends without a blank line; unexpected unindent.
Documentation/trace/events.rst:883: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:886: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:889: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:895: WARNING: Bullet list ends without a blank line; unexpected unindent.
Documentation/trace/events.rst:895: WARNING: Inline emphasis start-string without end-string.
Documentation/trace/events.rst:968: WARNING: Inline emphasis start-string without end-string.
Documentation: management-style: Fix formatting of emphsized word
Commit 7f2b3c65b9a1 ("Documentation/ManagementStyle: convert it to ReST
markup") converted _underlined_ to *emphasized* words, but forgot about
an underscore in this case.
Kees Cook [Wed, 4 Mar 2020 19:03:24 +0000 (11:03 -0800)]
docs: deprecated.rst: Clean up fall-through details
Add example of fall-through, list-ify the case ending statements, and
adjust the markup for links and readability. While here, adjust
strscpy() details to mention strscpy_pad().
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Adjust section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add lists markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Use :field: markup;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Adjust document and section titles;
- use :field: markup;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Use notes markups;
- Add it to filesystems/index.rst.
docs: filesystems: convert ramfs-rootfs-initramfs.txt to ReST
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Use notes markups;
- Add lists markups;
- Add it to filesystems/index.rst.
This document has a nice format! Unfortunately, not exactly
ReST. So, several adjustments were required:
- Add a SPDX header;
- Adjust document and section titles;
- Whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add table captions;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
docs: filesystems: convert ocfs2-online-filecheck.txt to ReST
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document title;
- Comment out text-only ToC;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Adjust document title;
- Mark literal blocks as such;
- use :field: markup;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Add table markups;
- Add lists markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Adjust document title;
- Fix list markups;
- Some whitespace fixes and new line breaks;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Use footnoote markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add lists markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- use :field: markup;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Use copyright symbol;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Use copyright symbol;
- Add a document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Use footnoote markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document and section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
docs: filesystems: convert autofs-mount-control.txt to ReST
- Add a SPDX header;
- Adjust document title;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document and section titles;
- Comment out text-only ToC;
- Mark literal blocks as such;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Adjust document title;
- Add table markups;
- Mark literal blocks as such;
- Some whitespace fixes and new line breaks;
- Add it to filesystems/index.rst.
- Add a SPDX header;
- Add a document title;
- Adjust section titles;
- Some whitespace fixes and new line breaks;
- Mark literal blocks as such;
- Add table markups;
- Add it to filesystems/index.rst.
Tim Bird [Tue, 25 Feb 2020 01:34:41 +0000 (18:34 -0700)]
scripts/sphinx-pre-install: add '-p python3' to virtualenv
With Ubuntu 16.04 (and presumably Debian distros of the same age),
the instructions for setting up a python virtual environment should
do so with the python 3 interpreter. On these older distros, the
default python (and virtualenv command) might be python2 based.
Some of the packages that sphinx relies on are now only available
for python3. If you don't specify the python3 interpreter for
the virtualenv, you get errors when doing the pip installs for
various packages
Fix this by adding '-p python3' to the virtualenv recommendation
line.
Jakub Kicinski [Fri, 28 Feb 2020 00:06:50 +0000 (16:06 -0800)]
doc: cgroup: improve formatting of mem stats
If there is an empty line between item and description
Sphinx does not emphasize the item. First half of the
list does not have the empty line and is emphasized
correctly.
docs: kref: Clarify the use of two kref_put() in example code
Eventhough the current documentation explains that the reference count
gets incremented by both kref_init() and kref_get(), it is often
misunderstood that only one instance of kref_put() is needed in the
example code. So let's clarify that a bit.
Stephen Kitt [Wed, 19 Feb 2020 15:34:42 +0000 (16:34 +0100)]
docs: add a script to check sysctl docs
This script allows sysctl documentation to be checked against the
kernel source code, to identify missing or obsolete entries. Running
it against 5.5 shows for example that sysctl/kernel.rst has two
obsolete entries and is missing 52 entries.
Kees Cook [Sat, 22 Feb 2020 00:02:39 +0000 (16:02 -0800)]
docs: Fix empty parallelism argument
When there was no parallelism (no top-level -j arg and a pre-1.7
sphinx-build), the argument passed would be empty ("") instead of just
being missing, which would (understandably) badly confuse sphinx-build.
Fix this by removing the quotes.
There are some issues at the script with regards to :doc:
tags:
- It doesn't escape files under Documentation/sphinx,
leading to false positives;
- It doesn't handle root URLs, like :doc:`/x86/boot`;
- It doesn't output the file with a bad reference.
Address those things, in order to remove false positives
from the list of problems.
docs: admin-guide: edid: Clarify where to run "make"
When both the documentation and the data files lived in
Documentation/EDID, this wasn't necessary, but both have
been moved to other directories in the meantime.
This document describes actions that an admin can do, rather than
interfaces available to driver developers, so admin-guide seems to
be a more appropriate place for it.
projects / linux.git / log