Mauro sez:
Patches 1 to 5 contain changes to the documentation toolset:
- The first 3 patches help to reduce a lot the number of reported
kernel-doc issues, by making the tool more smart.
- Patches 4 and 5 are meant to partially address the PDF
build, with now requires Sphinx version 2.4 or upper.
The remaining patches fix broken references detected by
this tool:
./scripts/documentation-file-ref-check
and address other random errors due to tags being mis-interpreted
or mis-used.
They are independent each other, but some may depend on
the kernel-doc improvements.
There are two ascii art drawings there. Use a block markup tag there
in order to get rid of those warnings:
./lib/bitmap.c:189: WARNING: Unexpected indentation.
./lib/bitmap.c:190: WARNING: Block quote ends without a blank line; unexpected unindent.
./lib/bitmap.c:190: WARNING: Unexpected indentation.
./lib/bitmap.c:191: WARNING: Line block ends without a blank line.
It should be noticed that there's actually a syntax violation
right now, as something like:
/**
...
@src:
will be handled as a definition for @src parameter, and not as
part of a diagram. So, we need to add something before it, in
order for this to be processed the way it should.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/1e2568fdfa838c1a0d8cc2a1d70dd4b6de99bfb1.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Use *foo makes the toolchain to think that this is an emphasis, causing
those warnings:
./fs/inode.c:1609: WARNING: Inline emphasis start-string without end-string.
./fs/inode.c:1609: WARNING: Inline emphasis start-string without end-string.
./fs/inode.c:1615: WARNING: Inline emphasis start-string without end-string.
So, use, instead, ``*foo``, in order to mark it as a literal block.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/e8da46a0e57f2af6d63a0c53665495075698e28a.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The Sphinx build system for PDF is too complex and generate
lots of ancillary files, including one PDF file for each
image.
So, at the end, the main latex dir has 156 pdf files, instead
of the 71 ones that would match each generated book. That's
confusing and it makes harder to identify when something didn't
work.
So, instead, let's move the final PDF output(s) to a separate
dir. This way, the latex/ dir will have the temporary and the
final *.tex files, while the final pdf files that built ok
will be under the pdf/ directory.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/832752cbc9678a6e8d3d634bc3356d655d44684f.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Several parts of this document define literals: ioctl names,
function calls, directory patches, etc. Mark those as literal
blocks, in order to improve its readability (both at text mode
and after parsed by Sphinx.
This fixes those two warnings:
Documentation/admin-guide/mm/userfaultfd.rst:139: WARNING: Inline emphasis start-string without end-string.
Documentation/admin-guide/mm/userfaultfd.rst:139: WARNING: Inline emphasis start-string without end-string.
produced during documentation build.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/2ae061761baf8fe00cdf8a7e6dae293756849a05.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Currrently, two warnings are generated when building docs:
./drivers/base/platform.c:136: WARNING: Unexpected indentation.
./drivers/base/platform.c:214: WARNING: Unexpected indentation.
As examples are code blocks, they should use "::" markup. However,
Example::
Is currently interpreted as a new section.
While we could fix kernel-doc to accept such new syntax, it is
easier to just replace it with:
For Example::
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/564273815a76136fb5e453969b1012a786d99e28.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sphinx produce some warnings due to a bad table format:
Documentation/admin-guide/ras.rst:358: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/admin-guide/ras.rst:358: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/admin-guide/ras.rst:363: WARNING: Definition list ends without a blank line; unexpected unindent.
Documentation/admin-guide/ras.rst:363: WARNING: Definition list ends without a blank line; unexpected unindent.
Rearrange the things there in order to supress the warnings
while being precise at the Sphinx output about how ranks are
mapped into csrows.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9e1bb44d6dbedb5b6f049d081b47da1f9620de16.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are some warnings with this file:
/Documentation/PCI/boot-interrupts.rst:42: WARNING: Unexpected indentation.
/Documentation/PCI/boot-interrupts.rst:52: WARNING: Block quote ends without a blank line; unexpected unindent.
/Documentation/PCI/boot-interrupts.rst:92: WARNING: Unexpected indentation.
/Documentation/PCI/boot-interrupts.rst:98: WARNING: Unexpected indentation.
/Documentation/PCI/boot-interrupts.rst:136: WARNING: Unexpected indentation.
It turns that this file conversion to ReST could be improved,
in order to remove the warnings and provide a better output.
So, fix the warnings by adjusting blank lines, add a table and
some list markups. Also, mark endnodes as such.
Acked-by: Bjorn Helgaas <bhelgaas@google.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/a6a9eb16eede10731bcce69a600ab12d92e6ba47.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Get rid of those warnings:
Documentation/arm64/booting.rst:253: WARNING: Unexpected indentation.
Documentation/arm64/booting.rst:259: WARNING: Block quote ends without a blank line; unexpected unindent.
By adding an extra blank lines where needed.
While here, use list markups on some places, as otherwise Sphinx
will consider the next lines as continuation of the privious ones.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/121b267be0a102fde73498c31792e5a9309013cc.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This file was removed, and another file was added instead of
it, on two separate commits.
Splitting a single logical change (doc conversion) on two
patches is a bad thing, as it makes harder to discover what
crap happened.
Anyway, this patch fixes the broken reference, making it
pointing to the new location of the file.
Fixes: 922003733d ("dt-bindings: phy: Remove Cadence MHDP PHY dt binding")
Fixes: c6d8eef38b7f ("dt-bindings: phy: Add Cadence MHDP PHY bindings in YAML format.")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/3f1cf6d74e392f3ee9f894d82cb7ee29d04c1b6d.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There's a conversion from a plain text binding file into 4 yaml ones.
The old file got removed, causing this new warning:
Warning: MAINTAINERS references a file that doesn't exist: Documentation/devicetree/bindings/arm/arm-boards
Address it by replacing the old reference by the new ones
Fixes: 2d483550b6 ("dt-bindings: arm: Drop the non-YAML bindings")
Fixes: 33fbfb3eaf ("dt-bindings: arm: Add Integrator YAML schema")
Fixes: 4b900070d5 ("dt-bindings: arm: Add Versatile YAML schema")
Fixes: 7db625b9fa ("dt-bindings: arm: Add RealView YAML schema")
Fixes: 4fb00d9066 ("dt-bindings: arm: Add Versatile Express and Juno YAML schema")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/eae3440fb70c1b1666973e34fd3fd6b8ab4a3bc7.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The building system can auto-generate a list of documents since
commit: 9d42afbe6b ("docs: pdf: add all Documentation/*/index.rst to PDF output").
The added logic there allows keeping the existing list, but
there's not real reason to keep it. Now, the media document
has gone (it was split into tree).
So, it sounds about time to get rid of the manual entries,
and let the script to generate it automatically instead.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9345dba7164497dbf28578f6ec271e479379610c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
There are some docs that have nested tables. While this was
always part of the spec, only Sphinx version 2.4.x can
translate it to LaTeX.
In other words, if someone is using a Sphinx version < 2.4,
the LaTeX and PDF output won't work for some of the docs.
So, it seems that it is time to raise the bar again
for the recommented version.
The Sphinx check script is already smart enough to keep
working, with older versions, warning the users that
an upgrade is recommended (and explaining how):
Sphinx version 1.7.9
Warning: It is recommended at least Sphinx version 2.4.4.
Detected OS: Fedora release 31 (Thirty One).
To upgrade Sphinx, use:
/usr/bin/virtualenv sphinx_2.4.4
. sphinx_2.4.4/bin/activate
pip install -r ./Documentation/sphinx/requirements.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/498f701c618f7d0cf5f0a37e5889ee926f7c8bf4.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Sphinx is very pedantic with respect to blank lines. Sometimes,
in order to make it to properly handle something, we need to
add a blank line. However, currently, any blank line inside a
kernel-doc comment like:
/*
* @foo: bar
*
* foobar
*
* some description
will be considered as if "foobar" was part of the description.
This patch changes kernel-doc behavior. After it, foobar will
be considered as part of the parameter text. The description
will only be considered as such if it starts with:
zero spaces after asterisk:
*foo
one space after asterisk:
* foo
or have a explicit Description section:
* Description:
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/c07d2862792d75a2691d69c9eceb7b89a0164cc0.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
On a few places, it sometimes need to indicate a negation of a
parameter, like:
!@fshared
This pattern happens, for example, at:
kernel/futex.c
and it is perfectly valid. However, kernel-doc currently
transforms it into:
!**fshared**
This won't do what it would be expected.
Fortunately, fixing the script is a simple matter of storing
the "!" before "@" and adding it after the bold markup, like:
**!fshared**
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/0314b47f8c3e1f9db00d5375a73dc3cddd8a21f2.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The pattern @foo->bar() is valid, as it can be used by a
function pointer inside a struct passed as a parameter.
Right now, it causes a warning:
./drivers/firewire/core-transaction.c:606: WARNING: Inline strong start-string without end-string.
In this specific case, the kernel-doc markup is:
/**
* fw_core_remove_address_handler() - unregister an address handler
* @handler: callback
*
* To be called in process context.
*
* When fw_core_remove_address_handler() returns, @handler->callback() is
* guaranteed to not run on any CPU anymore.
*/
With seems valid on my eyes. So, instead of trying to hack
the kernel-doc markup, let's teach it about how to handle
such things. This should likely remove lots of other similar
warnings as well.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/48b46426d7bf6ff7529f20e5718fbf4e9758e62c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
The Arch-linux detection is hit by catting /etc/issue, whose
contents is (nowadays):
Arch Linux \r (\l)
It sounds a little ackward to print such string, so,
instead, let's use the /etc/os-release file, with exists
on lots of distributions and should provide a more reliable
result.
We'll keep the old tests before it, in order to avoid possible
regressions with the other distros, although the new way should
probably work on all the currently supported distributions.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/472924557afdf2b5492ae2a48c5ecfae216d54e2.1586883286.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
If execute ./scripts/documentation-file-ref-check in a directory which is
not a git tree, it will exit without a line break, fix it.
Without this patch:
[loongson@localhost linux-5.7-rc1]$ ./scripts/documentation-file-ref-check
Warning: can't check if file exists, as this is not a git tree[loongson@localhost linux-5.7-rc1]$
With this patch:
[loongson@localhost linux-5.7-rc1]$ ./scripts/documentation-file-ref-check
Warning: can't check if file exists, as this is not a git tree
[loongson@localhost linux-5.7-rc1]$
Signed-off-by: Tiezhu Yang <yangtiezhu@loongson.cn>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/1586857308-2040-1-git-send-email-yangtiezhu@loongson.cn
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
When kernel-doc generates a 'c:function' directive for a function
one of whose arguments is a function pointer, it fails to print
the close-paren after the argument list of the function pointer
argument. For instance:
long work_on_cpu(int cpu, long (*fn) (void *, void * arg)
in driver-api/basics.html is missing a ')' separating the
"void *" of the 'fn' arguments from the ", void * arg" which
is an argument to work_on_cpu().
Add the missing close-paren, so that we render the prototype
correctly:
long work_on_cpu(int cpu, long (*fn)(void *), void * arg)
(Note that Sphinx stops rendering a space between the '(fn*)' and the
'(void *)' once it gets something that's syntactically valid.)
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Link: https://lore.kernel.org/r/20200414143743.32677-1-peter.maydell@linaro.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This sorts the actual field names too, potentially causing even more
chaos and confusion at merge time if you have edited the MAINTAINERS
file. But the end result is a more consistent layout, and hopefully
it's a one-time pain minimized by doing this just before the -rc1
release.
This was entirely scripted:
./scripts/parse-maintainers.pl --input=MAINTAINERS --output=MAINTAINERS --order
Requested-by: Joe Perches <joe@perches.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
They are all supposed to be sorted, but people who add new entries don't
always know the alphabet. Plus sometimes the entry names get edited,
and people don't then re-order the entry.
Let's see how painful this will be for merging purposes (the MAINTAINERS
file is often edited in various different trees), but Joe claims there's
relatively few patches in -next that touch this, and doing it just
before -rc1 is likely the best time. Fingers crossed.
This was scripted with
/scripts/parse-maintainers.pl --input=MAINTAINERS --output=MAINTAINERS
but then I also ended up manually upper-casing a few entry names that
stood out when looking at the end result.
Requested-by: Joe Perches <joe@perches.com>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>
Pull x86 fixes from Thomas Gleixner:
"A set of three patches to fix the fallout of the newly added split
lock detection feature.
It addressed the case where a KVM guest triggers a split lock #AC and
KVM reinjects it into the guest which is not prepared to handle it.
Add proper sanity checks which prevent the unconditional injection
into the guest and handles the #AC on the host side in the same way as
user space detections are handled. Depending on the detection mode it
either warns and disables detection for the task or kills the task if
the mode is set to fatal"
* tag 'x86-urgent-2020-04-12' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip:
KVM: VMX: Extend VMXs #AC interceptor to handle split lock #AC in guest
KVM: x86: Emulate split-lock access as a write in emulator
x86/split_lock: Provide handle_guest_split_lock()
