08 Apr, 2022
1 commit
-
commit be78837ca3c88eebd405103a7a2ce891c466b0db upstream.
jinja2 release 3.1.0 (March 24, 2022) broke Sphinx
Cc: Mauro Carvalho Chehab
Cc: stable@vger.kernel.org # v5.15+
Link: https://lore.kernel.org/r/7dbff8a0-f4ff-34a0-71c7-1987baf471f9@gmail.com
Signed-off-by: Jonathan Corbet
Signed-off-by: Greg Kroah-Hartman
12 Aug, 2021
1 commit
-
sphinx_rtd_theme 0.5.2 has "docutils
Cc: Mauro Carvalho Chehab
Acked-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/75f14c88-6091-1072-41cb-16b886aee5a0@gmail.com
Signed-off-by: Jonathan Corbet
07 Mar, 2021
1 commit
-
s/automaticly/automatically/
s/buidler/builder/..and a sentence construction fix.
Signed-off-by: Bhaskar Chowdhury
Acked-by: Randy Dunlap
Link: https://lore.kernel.org/r/20210301201052.11067-1-unixbhaskar@gmail.com
Signed-off-by: Jonathan Corbet
05 Feb, 2021
1 commit
-
Previously, a cross-reference to another document could only be created
by writing the full path to the document starting from the
Documentation/ directory.Extend this to also allow relative paths to be used. A relative path
would be just the path, like ../filename.rst, while the absolute path
still needs to start from Documentation, like Documentation/filename.rst.As part of this change, the .rst extension is now required for both
types of paths, since not requiring it would cause the regex to be too
generic.Suggested-by: Jonathan Corbet
Signed-off-by: Nícolas F. R. A. Prado
Link: https://lore.kernel.org/r/20210128010028.58541-2-nfraprado@protonmail.com
[jc: Tweaked the regex to recognize .txt too]
Signed-off-by: Jonathan Corbet
02 Feb, 2021
2 commits
-
The kernel build system as a whole is dropping support for Python 2, so we
should do the same. The effects are rather small, especially considering
that much of the deleted code was not doing anything under any version of
Python anyway.Signed-off-by: Jonathan Corbet
-
As promised, drop support for some ancient sphinx releases, along with a
lot of the cruft that was required to make that support work.Signed-off-by: Jonathan Corbet
23 Dec, 2020
1 commit
-
Pull Kbuild updates from Masahiro Yamada:
- Use /usr/bin/env for shebang lines in scripts
- Remove useless -Wnested-externs warning flag
- Update documents
- Refactor log handling in modpost
- Stop building modules without MODULE_LICENSE() tag
- Make the insane combination of 'static' and EXPORT_SYMBOL an error
- Improve genksyms to handle _Static_assert()
* tag 'kbuild-v5.11' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild:
Documentation/kbuild: Document platform dependency practises
Documentation/kbuild: Document COMPILE_TEST dependencies
genksyms: Ignore module scoped _Static_assert()
modpost: turn static exports into error
modpost: turn section mismatches to error from fatal()
modpost: change license incompatibility to error() from fatal()
modpost: turn missing MODULE_LICENSE() into error
modpost: refactor error handling and clarify error/fatal difference
modpost: rename merror() to error()
kbuild: don't hardcode depmod path
kbuild: doc: document subdir-y syntax
kbuild: doc: clarify the difference between extra-y and always-y
kbuild: doc: split if_changed explanation to a separate section
kbuild: doc: merge 'Special Rules' and 'Custom kbuild commands' sections
kbuild: doc: fix 'List directories to visit when descending' section
kbuild: doc: replace arch/$(ARCH)/ with arch/$(SRCARCH)/
kbuild: doc: update the description about kbuild Makefiles
Makefile.extrawarn: remove -Wnested-externs warning
tweewide: Fix most Shebang lines
10 Dec, 2020
1 commit
-
On the update of Sphinx version to 2.4.4, the "six" library won't be
installed automatically. (which is required by kfigure.py)Main reason of this issue were occurred by the requirements changed from
the sphinx library. In Sphinx v1.7.9, six was listed on the
install_requires, but it has been removed since 2.xThe kfigure.py uses six library explicitly, adding six to
requirements.txt seems reasonableSigned-off-by: JaeSang Yoo
Reviewed-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/20201208014628.GA1361@JSYoo5B-Base.localdomain
Signed-off-by: Jonathan Corbet
08 Dec, 2020
1 commit
-
Change every shebang which does not need an argument to use /usr/bin/env.
This is needed as not every distro has everything under /usr/bin,
sometimes not even bash.Signed-off-by: Finn Behrens
Signed-off-by: Masahiro Yamada
04 Dec, 2020
1 commit
-
The feature files have a special well-defined format. Add
a script that parses them, allowing to search for a feature
and/or by an architecture and to produce ReST-compatible
outputs.Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/bb2e51e5aa883e2583a4a6280f1c1b391bd8ef4c.1606748711.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
01 Dec, 2020
1 commit
-
Sphinx 3.1 introduced namespaces for C cross-references. With this,
each C domain type/function declaration is put inside the namespace that
was active at the time of its declaration.Add support for automatic cross-referencing inside C namespaces by
checking whether the corresponding source file had a C namespace Sphinx
directive, and if so, try cross-referencing inside of it before going to
the global scope.This assumes there's only one namespace (if any) per rst file.
Signed-off-by: Nícolas F. R. A. Prado
Link: https://lore.kernel.org/r/20201117021107.214704-1-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet
04 Nov, 2020
1 commit
-
Pull documentation fixes from Jonathan Corbet:
"A small number of fixes, plus a build tweak to respect the desire for
silence in V=0 builds"* tag 'docs-5.10-3' of git://git.lwn.net/linux:
docs: fix automarkup regression on Python 2
documentation: arm: sunxi: add Allwinner H6 documents
scripts: kernel-doc: split typedef complex regex
scripts: kernel-doc: fix typedef parsing
docs: Makefile: honor V=0 for docs building
03 Nov, 2020
1 commit
-
It turns out that the Python 2 re module lacks the ASCII flag, so don't try
to use it there.Fixes: f66e47f98c1e ("docs: automarkup.py: Fix regexes to solve sphinx 3 warnings")
Reported-by: Dafna Hirschfeld
Signed-off-by: Jonathan Corbet
30 Oct, 2020
7 commits
-
Now that the stable ABI files are compatible with ReST,
parse them without converting complex descriptions as literal
blocks nor escaping special characters.Please notice that escaping special characters will probably
be needed at descriptions, at least for the asterisk character.Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/59ccbaa75ff05f23e701dd9a0bbe118e9343a553.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman -
The Sphinx docutils parser is lazy: if the content is bigger than
a certain number of lines, it silenlty stops parsing it,
producing an incomplete content. This seems to be worse on newer
Sphinx versions, like 2.0.So, change the logic to parse the contents per input file.
Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/4659b60795739308e34d2d00c57ee0742a9cd2ab.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman -
Just like kernel-doc extension, we need to be able to identify
what part of an imported document has issues, as reporting them
as:get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
Makes a lot harder for someone to fix.
It should be noticed that it the line which will be reported is
the line where the "What:" definition is, and not the line
with actually has an error.Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/d6155ab16fb7631f2fa8e7a770eae72f24bf7cc5.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman -
The same way kerneldoc.py needed changes to work with newer
Sphinx, this script needs the same changes.While here, reorganize the include order to match kerneldoc.py.
Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/f2b25caef5db7738629773a03463908d3b39b83a.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman -
The parser breaks with UTF-8 characters with Sphinx 1.4.
Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/9e7c8e3b0efaa1ae0536da6493ab438bd3f9fe58.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman -
The ABI documentation is special: it is not plain text files,
but, instead, files with an strict format, as specified by
Documentation/ABI/README.Add a parser for it.
Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/48abf1a410237e63f85354a8cd7027fdf25657bf.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman -
An extension may want to just inform about something. So, add
support for it.Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/0ddebd8677605d789d53433c8a5344c68da82a73.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman
15 Oct, 2020
10 commits
-
The :c:type:`foo` only works properly with structs before
Sphinx 3.x.On Sphinx 3.x, structs should now be declared using the
.. c:struct, and referenced via :c:struct tag.As we now have the automarkup.py macro, that automatically
convert:
struct foointo cross-references, let's get rid of that, solving
several warnings when building docs with Sphinx 3.x.Reviewed-by: André Almeida # blk-mq.rst
Reviewed-by: Takashi Iwai # sound
Reviewed-by: Mike Rapoport
Reviewed-by: Greg Kroah-Hartman
Signed-off-by: Mauro Carvalho Chehab -
Sphinx 3 added support for declaring C macros with parameters using the
:c:macro role.To support automarkup for both functions and parametrized macros using
the same regex (words ending in ()), try to cross-reference to both, and
only fall back to regular text if neither exist.Signed-off-by: Nícolas F. R. A. Prado
Signed-off-by: Mauro Carvalho Chehab -
With the transition to Sphinx 3, new warnings were caused by
automarkup, exposing bugs in the name matching.When automarkup parsed a text like "struct struct" in the documentation,
it tried to cross-reference to a "struct" symbol, which is recognized as
a C reserved word by Sphinx 3, generating a warning.Add some C reserved words (only the ones that were causing warnings) to
a list and skip them while trying to cross-reference.Signed-off-by: Nícolas F. R. A. Prado
Signed-off-by: Mauro Carvalho Chehab -
With the transition to Sphinx 3, new warnings were generated by
automarkup, exposing bugs in the regexes.The warnings were caused by the expressions matching words in the
translated versions of the documentation, since any unicode character
was matched.Fix the regular expression by making the C regexes use ASCII and
ensuring the expressions only match the beginning of words,
in order to avoid warnings like this:WARNING: Unparseable C cross-reference: '调用debugfs_rename'
That's probably due to the lack of using spaces between words
on Chinese.Signed-off-by: Nícolas F. R. A. Prado
Signed-off-by: Mauro Carvalho Chehab -
While Sphinx 2 used a single c:type role for struct, union, enum and
typedef, Sphinx 3 uses a specific role for each one.
To keep backward compatibility, detect the Sphinx version and use the
correct roles for that version.Signed-off-by: Nícolas F. R. A. Prado
Signed-off-by: Mauro Carvalho Chehab -
Currently, there's no way to exclude identifiers from
a kernel-doc markup. Add support for it.Signed-off-by: Mauro Carvalho Chehab
-
Finding where an error like this was generated:
../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'.Can take some time, as there's no glue about what kernel-doc
tag generated it. It is a way better to display it as:.../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'.
Declaration is 'div_s64_rem'.Signed-off-by: Mauro Carvalho Chehab
-
While most of the C domain parsing is done via kernel-doc,
some RST files use C domain tags directly.While several of them can be removed for Sphinx < 3.0, due
to automarkup.py, and several others that could be
converted into kernel-doc markups, changes like that are
time-consuming, and may not fit all cases.As we already have the cdomain.py for handing backward
compatibility with Sphinx versions below 3.0, let's
make it more complete, in order to cover any usage of the
newer tags outside kernel-doc.This way, it should be feasible to use the new tags inside
the Kernel tree, without losing backward compatibility.This should allow fixing the remaining warnings with
the Kernel tags.Signed-off-by: Mauro Carvalho Chehab
-
Since Sphinx 3.0, the C domain code was rewritten, but only
after version 3.1 it got support for setting namespaces on
C domains, with is something that it is required, in order to
document system calls, like ioctl() and others.As part of changing the documentation subsystem to properly
build with Sphinx 3.1+, add support for such new tag:.. c:namespace::"
Such tag optionally replaces the optional "name" tag for functions,
setting a single namespace domain for all C references found
at the file.With that, it should be possible to convert existing
documentation to be compatible with both Sphinx 1.x/2.x and
3.1+.Signed-off-by: Mauro Carvalho Chehab
-
When kernel-doc is called via kerneldoc.py, there's no need to
auto-detect the Sphinx version, as the Sphinx module already
knows it. So, add an optional parameter to allow changing the
Sphinx dialect.As kernel-doc can also be manually called, keep the auto-detection
logic if the parameter was not specified. On such case, emit
a warning if sphinx-build can't be found at PATH.I ended using a suggestion from Joe for using a more readable
regex, instead of using a complex one with a hidden group like:m/^(\d+)\.(\d+)(?:\.?(\d+)?)/
in order to get the optional argument.
Thanks-to: Joe Perches
Suggested-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
17 Sep, 2020
2 commits
-
Cross-referencing to other documentation pages is possible using the
:doc:`doc-file` directive from Sphinx.Add automatic markup for references to other documentation pages in the
format Documentation/subfolder/doc-file.rst (the extension being
optional).
This requires that the path be passed all the way from the Documentation
folder, which can be longer than passing a relative path through the
:doc: directive, but avoids the markup, making the text cleaner when
read in plain text.Signed-off-by: Nícolas F. R. A. Prado
Link: https://lore.kernel.org/r/20200911133339.327721-3-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet -
The automarkup script previously matched expressions and substituted
them with markup to enable automatic cross-reference all in the same
function.Split the expression matching iteration and the markup substitution into
different functions to make it easier to add new regular expressions and
functions to treat each of them.Signed-off-by: Nícolas F. R. A. Prado
Link: https://lore.kernel.org/r/20200911133339.327721-2-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet
04 Sep, 2020
1 commit
-
In order to cross-reference C types in the documentation, Sphinx
requires the syntax :c:type:`type_name`, or even :c:type:`struct
type_name ` in order to have the link text different from the
target text.Extend automarkup to enable automatic cross-reference of C types by
matching any "struct|union|enum|typedef type_name" expression.
This makes the documentation's plain text cleaner and adds
cross-reference to types without any additional effort by the author.Signed-off-by: Nícolas F. R. A. Prado
Link: https://lore.kernel.org/r/20200903005747.3900333-2-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet
27 Jun, 2020
1 commit
-
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.Deterministic algorithm:
For each file:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.Signed-off-by: Alexander A. Klimov
Link: https://lore.kernel.org/r/20200620075402.22347-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet
08 Jun, 2020
1 commit
-
Rationale:
Reduces attack surface on kernel devs opening the links for MITM
as HTTPS traffic is much harder to manipulate.Deterministic algorithm:
For each file:
For each line:
If doesn't contain `\bxmlns\b`:
For each link, `\bhttp://[^# \t\r\n]*(?:\w|/)`:
If both the HTTP and HTTPS versions
return 200 OK and serve the same content:
Replace HTTP with HTTPS.Signed-off-by: Alexander A. Klimov
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet
21 Apr, 2020
1 commit
-
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.txtSigned-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/498f701c618f7d0cf5f0a37e5889ee926f7c8bf4.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
25 Feb, 2020
1 commit
-
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.Reported-by: Rafael J. Wysocki
Fixes: 51e46c7a4007 ("docs, parallelism: Rearrange how jobserver reservations are made")
Cc: stable@vger.kernel.org # v5.5 only
Signed-off-by: Kees Cook
Signed-off-by: Jonathan Corbet
25 Jan, 2020
1 commit
-
Sphinx 2.1 moved sphinx.environment.NoUri into sphinx.errors; that produced
this warning in the docs build:/usr/lib/python3.7/site-packages/sphinx/registry.py:473:
RemovedInSphinx30Warning: sphinx.environment.NoUri is deprecated.Grab NoUri from the right place and make the warning go away. That symbol
was only added to sphinx.errors in 2.1, so we must still import it from the
old location when running in older versions.Signed-off-by: Jonathan Corbet
23 Nov, 2019
1 commit
-
Rasmus correctly observed that the existing jobserver reservation only
worked if no other build targets were specified. The correct approach
is to hold the jobserver slots until sphinx has finished. To fix this,
the following changes are made:- refactor (and rename) scripts/jobserver-exec to set an environment
variable for the maximally reserved jobserver slots and exec a
child, to release the slots on exit.- create Documentation/scripts/parallel-wrapper.sh which examines both
$PARALLELISM and the detected "-jauto" logic from Documentation/Makefile
to decide sphinx's final -j argument.- chain these together in Documentation/Makefile
Suggested-by: Rasmus Villemoes
Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dk
Signed-off-by: Kees Cook
Link: https://lore.kernel.org/r/20191121205929.40371-4-keescook@chromium.org
Signed-off-by: Jonathan Corbet
08 Nov, 2019
1 commit
-
The 'functions' directive is not only for functions, but also works for
structs/unions. So the name is misleading. This patch renames it to
'identifiers', which specific the functions/types to be included in
documentation. We keep the old name as an alias of the new one before
all documentation are updated.Signed-off-by: Changbin Du
Signed-off-by: Jonathan Corbet
