Adjust the path of the ABI files for firewire.rst to prevent a
documentation build error. Prevents this problem:
Sphinx parallel build error:
docutils.utils.SystemMessage: Documentation/driver-api/firewire.rst:22: (SEVERE/4) Problems with "include" directive path:
InputError: [Errno 2] No such file or directory: '../Documentation/driver-api/ABI/stable/firewire-cdev'.
Fixes: 2f4830ef96 ("FireWire: add driver-api Introduction section")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220119033905.4779-1-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Our documentation encourages the use of list-table formats, but that advice
runs counter to the objective of keeping the plain-text documentation as
useful and readable as possible. Turn that advice around the other way so
that people don't keep adding these tables.
Acked-by: Christoph Hellwig <hch@lst.de>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Since commit d18b01789a ("docs: Add automatic cross-reference for
documentation pages"), references that were already explicitly defined
with "ref:" and referred to other pages with a path have been doubled.
This is reported as the following error by Firefox:
Start tag "a" seen but an element of the same type was already open.
End tag "a" violates nesting rules.
As well as the invalid HTML, this also obscures the URI fragment links
to subsections because the second link overrides the first. For example
on the page admin-guide/hw-vuln/mds.html the last link should be to the
"Default Mitigations" subsection using a # URI fragment:
admin-guide/hw-vuln/l1tf.html#default-mitigations
But it is obsured by a second link to the whole page:
admin-guide/hw-vuln/l1tf.html
The full HTML with the double <a> tags looks like this:
<a class="reference internal" href="l1tf.html#default-mitigations">
<span class="std std-ref">
<a class="reference internal" href="l1tf.html">
<span class="doc">L1TF - L1 Terminal Fault</span>
</a>
</span>
</a>
After this commit, there is only a single link:
<a class="reference internal" href="l1tf.html#default-mitigations">
<span class="std std-ref">Documentation/admin-guide/hw-vuln//l1tf.rst</span>
</a>
Now that the second link is removed, the browser correctly jumps to the
default-mitigations subsection when clicking the link.
The fix is to check that nodes in the document to be modified are not
already references. A reference is counted as any text that is a
descendant of a reference type node. Only plain text should be converted
to new references, otherwise the doubling occurs.
Testing
=======
* Test that the build stdout is the same (ignoring ordering), and that
no new warnings are printed.
* Diff all .html files and check that the only modifications occur
to the bad double links.
* The auto linking of bare references to pages without "ref:" is still
working.
Fixes: d18b01789a ("docs: Add automatic cross-reference for documentation pages")
Reviewed-by: Nícolas F. R. A. Prado <n@nfraprado.net>
Signed-off-by: James Clark <james.clark@arm.com>
Link: https://lore.kernel.org/r/20220105143640.330602-2-james.clark@arm.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The config RANDOMIZE_SLAB does not exist, the authors probably intended to
refer to the config RANDOMIZE_BASE, which provides kernel address-space
randomization. They probably just confused SLAB with BASE (these two
four-letter words coincidentally share three common letters), as they also
point out the config SLAB_FREELIST_RANDOM as further randomization within
the same sentence.
Fix the reference of the config for kernel address-space randomization to
the config that provides that.
Fixes: 6e88559470 ("Documentation: Add section about CPU vulnerabilities for Spectre")
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20211230171940.27558-1-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Most readers are probably going to figure out that the config is actually
all upper-case letters, as all Kconfig symbols are this way.
Properly capitalizing makes the script ./scripts/checkkconfigsymbols.py
happy, which otherwise would report this as a reference to a non-existing
Kconfig symbol.
So, use the right capitalization for the MAGIC_SYSRQ config in the kgdb
documentation.
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20211230172423.30430-1-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation/vm/overcommit-accounting.rst says that the overcommit
amount can be set via vm.overcommit_ratio and vm.overcommit_kbytes.
Add a clarification that those only take effect in overcommit handling
mode 2 ("Don't overcommit"), i.e. they do not act as an "additional"
limit that is always enforced.
Signed-off-by: Anssi Hannula <anssi.hannula@iki.fi>
Reviewed-by: David Hildenbrand <david@redhat.com>
Link: https://lore.kernel.org/r/20211211194159.3137362-1-anssi.hannula@iki.fi
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There were some things which made rendered document
look not very elegant. That was because:
1. Numbered lists were formatted in more of Markdown way
rather than true reStructuredText and so were displayed
as a plain text with leading numbers.
Well, moreover numbered lists were not needed as in all cases
we were just listing a couple of options w/o any intention to
follow any particular order, so a simpler unordered list fits
better and looks cleaner.
2. URL's of external resources were added as they are
(which is OK in a plain text, but make not much sense in
a HTML where we may use more human-friendly link names
with URL's hidden.
3. Some URL's had trailing slashes which were not really needed
Fix all items from above!
Signed-off-by: Alexey Brodkin <abrodkin@synopsys.com>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Vineet Gupta <vgupta@kernel.org>
Link: https://lore.kernel.org/r/20211202215747.19923-1-abrodkin@synopsys.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This is actually an overlay on the top of the RTD theme, which
requires to include first the RTD theme.
It should be noticed that, when the dark theme is used, the
DOCS_CSS files won't be the last CSS themes. So, it won't
override the dark.css style by default. So, it is needed
to force the them override with "!important".
This small script, for instance, produces a nice output with
the RTD dark theme:
DOCS_THEME=sphinx_rtd_dark_mode
cat << EOF > dark_override.css
html body {
font-family: arial,helvetica,sans-serif;
}
html[data-theme='dark'] body {
color: white !important;
}
html[data-theme='dark'] .sig-name {
color: green !important;
}
html[data-theme='dark'] .wy-menu-vertical a {
color: #ffcc00 !important;
}
html[data-theme="dark"] h1, html[data-theme="dark"] h2, html[data-theme="dark"] h3 {
color: #ffcc00 !important;
}
html[data-theme="dark"] h4, html[data-theme="dark"] h5, html[data-theme="dark"] h6 {
color: #ffcc00 !important;
}
html[data-theme="dark"] h7, html[data-theme="dark"] h8, html[data-theme="dark"] h9 {
color: #ffcc00 !important;
}
html[data-theme="dark"] .wy-nav-content a, html[data-theme="dark"] .wy-nav-content a:visited {
color: #ffcc00 !important;
}
EOF
make DOCS_CSS=dark_override.css DOCS_THEME=sphinx_rtd_dark_mode htmldocs
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/90d316e055ef7f4c9021b9eada8f8d3b2e750a66.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
