docs: Makefile: use the new script to check for bad ABI references

The get_abi.pl script was replaced by get_abi.py. Update it at docs
makefile.

Reported-by: kernel test robot <[email protected]>
Close

docs: Makefile: use the new script to check for bad ABI references

The get_abi.pl script was replaced by get_abi.py. Update it at docs
makefile.

Reported-by: kernel test robot <[email protected]>
Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

tools: ynl: move python code to separate sub-directory

Move python code to a separate directory so it can be
packaged as a python module. Updates existing references
in selftests and docs.

Also ren

tools: ynl: move python code to separate sub-directory

Move python code to a separate directory so it can be
packaged as a python module. Updates existing references
in selftests and docs.

Also rename ynl-gen-[c|rst] to ynl_gen_[c|rst], avoid
dashes as these prevent easy imports for entrypoints.

Signed-off-by: Jan Stancek <[email protected]>
Reviewed-by: Donald Hunter <[email protected]>
Link: https://patch.msgid.link/a4151bad0e6984e7164d395125ce87fd2e048bf1.1736343575.git.jstancek@redhat.com
Signed-off-by: Jakub Kicinski <[email protected]>

show more ...

kbuild: use $(src) instead of $(srctree)/$(src) for source directory

Kbuild conventionally uses $(obj)/ for generated files, and $(src)/ for
checked-in source files. It is merely a convention withou

kbuild: use $(src) instead of $(srctree)/$(src) for source directory

Kbuild conventionally uses $(obj)/ for generated files, and $(src)/ for
checked-in source files. It is merely a convention without any functional
difference. In fact, $(obj) and $(src) are exactly the same, as defined
in scripts/Makefile.build:

src := $(obj)

When the kernel is built in a separate output directory, $(src) does
not accurately reflect the source directory location. While Kbuild
resolves this discrepancy by specifying VPATH=$(srctree) to search for
source files, it does not cover all cases. For example, when adding a
header search path for local headers, -I$(srctree)/$(src) is typically
passed to the compiler.

This introduces inconsistency between upstream and downstream Makefiles
because $(src) is used instead of $(srctree)/$(src) for the latter.

To address this inconsistency, this commit changes the semantics of
$(src) so that it always points to the directory in the source tree.

Going forward, the variables used in Makefiles will have the following
meanings:

$(obj) - directory in the object tree
$(src) - directory in the source tree (changed by this commit)
$(objtree) - the top of the kernel object tree
$(srctree) - the top of the kernel source tree

Consequently, $(srctree)/$(src) in upstream Makefiles need to be replaced
with $(src).

Signed-off-by: Masahiro Yamada <[email protected]>
Reviewed-by: Nicolas Schier <[email protected]>

show more ...

docs: Detect variable fonts and suggest denylisting them

Fedora and openSUSE has started deploying "variable font" [1] format
Noto CJK fonts [2, 3]. "CJK" here stands for "Chinese, Japanese,
and Ko

docs: Detect variable fonts and suggest denylisting them

Fedora and openSUSE has started deploying "variable font" [1] format
Noto CJK fonts [2, 3]. "CJK" here stands for "Chinese, Japanese,
and Korean".

Unfortunately, XeTeX/XeLaTeX doesn't understand those fonts for
historical reasons and builds of translations.pdf end up in errors
if such fonts are present on the build host.

To help developers work around the issue, add a script to check the
presence of "variable font" Noto CJK fonts and to emit suggestions.
The script is invoked in the error path of "make pdfdocs" so that the
suggestions are made only when a PDF build actually fails.

The first suggestion is to denylist those "variable font" files by
activating a per-user and command-local fontconfig setting.

For further info and backgrounds, please refer to the header comment
of scripts/check-variable-font.sh newly added in this commit.

Link: [1] https://en.wikipedia.org/wiki/Variable_font
Link: [2] https://fedoraproject.org/wiki/Changes/Noto_CJK_Variable_Fonts
Link: [3] https://build.opensuse.org/request/show/1157217
Reported-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]/
Reported-by: Иван Иванович <[email protected]>
Link: https://lore.kernel.org/linux-doc/[email protected]/
Cc: Randy Dunlap <[email protected]>
Signed-off-by: Akira Yokosawa <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs

Commit f061c9f7d058 ("Documentation: Document each netlink family")
added recipes for YAML -> RST conversion.
Then comm

docs: Makefile: Add dependency to $(YNL_INDEX) for targets other than htmldocs

Commit f061c9f7d058 ("Documentation: Document each netlink family")
added recipes for YAML -> RST conversion.
Then commit 7da8bdbf8f5d ("docs: Makefile: Fix make cleandocs by
deleting generated .rst files") made sure those converted .rst files
are cleaned by "make cleandocs".

However, they took care of htmldocs build only.

If one of other targets such as latexdocs or epubdocs is built
without building htmldocs, missing .rst files can cause additional
WARNINGs from sphinx-build as follow:

./Documentation/userspace-api/netlink/specs.rst:18: WARNING: undefined label: 'specs'
./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/rt_link'
./Documentation/userspace-api/netlink/netlink-raw.rst:64: WARNING: unknown document: '../../networking/netlink_spec/tc'
./Documentation/userspace-api/netlink/index.rst:21: WARNING: undefined label: 'specs'

Add dependency to $(YNL_INDEX) for other targets and allow any targets
to be built cleanly right after "make cleandocs".

Signed-off-by: Akira Yokosawa <[email protected]>
Cc: [email protected] # v6.7
Cc: Thorsten Blum <[email protected]>
Cc: Breno Leitao <[email protected]>
Cc: Jakub Kicinski <[email protected]>
Cc: "David S. Miller" <[email protected]>
Reviwed-by: Breno Leitao <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Message-ID: <[email protected]>

show more ...

docs: Makefile: Fix make cleandocs by deleting generated .rst files

The script tools/net/ynl/ynl-gen-rst.py (YNL_TOOL) generates several .rst
files (YNL_INDEX, YNL_RST_FILES) in Documentation/networ

docs: Makefile: Fix make cleandocs by deleting generated .rst files

The script tools/net/ynl/ynl-gen-rst.py (YNL_TOOL) generates several .rst
files (YNL_INDEX, YNL_RST_FILES) in Documentation/networking/netlink_spec
(YNL_RST_DIR) which are not deleted by make cleandocs.

Fix make cleandocs by deleting the generated .rst files.

Signed-off-by: Thorsten Blum <[email protected]>
Reviewed-by: Vegard Nossum <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

doc/netlink: Regenerate netlink .rst files if ynl-gen-rst changes

Add ynl-gen-rst.py to the dependencies for the netlink .rst files in the
doc Makefile so that the docs get regenerated if the ynl-ge

doc/netlink: Regenerate netlink .rst files if ynl-gen-rst changes

Add ynl-gen-rst.py to the dependencies for the netlink .rst files in the
doc Makefile so that the docs get regenerated if the ynl-gen-rst.py
script is modified. Use $(Q) to honour V=1 in the rules that run
ynl-gen-rst.py

Reviewed-by: Jakub Kicinski <[email protected]>
Reviewed-by: Breno Leitao <[email protected]>
Signed-off-by: Donald Hunter <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jakub Kicinski <[email protected]>

show more ...

Documentation: Document each netlink family

This is a simple script that parses the Netlink YAML spec files
(Documentation/netlink/specs/), and generates RST files to be rendered
in the Network -> N

Documentation: Document each netlink family

This is a simple script that parses the Netlink YAML spec files
(Documentation/netlink/specs/), and generates RST files to be rendered
in the Network -> Netlink Specification documentation page.

Create a python script that is invoked during 'make htmldocs', reads the
YAML specs input file and generate the correspondent RST file.

Create a new Documentation/networking/netlink_spec index page, and
reference each Netlink RST file that was processed above in this main
index.rst file.

In case of any exception during the parsing, dump the error and skip
the file.

Do not regenerate the RST files if the input files (YAML) were not
changed in-between invocations.

Suggested-by: Jakub Kicinski <[email protected]>
Signed-off-by: Breno Leitao <[email protected]>

----
Changelog:

V3:
* Do not regenerate the RST files if the input files were not
changed. In order to do it, a few things changed:
- Rely on Makefile more to find what changed, and trigger
individual file processing
- The script parses file by file now (instead of batches)
- Create a new option to generate the index file

V2:
* Moved the logic from a sphinx extension to a external script
* Adjust some formatting as suggested by Donald Hunter and Jakub
* Auto generating all the rsts instead of having stubs
* Handling error gracefully
Reviewed-by: Jakub Kicinski <[email protected]>
Signed-off-by: David S. Miller <[email protected]>

show more ...

docs: Integrate rustdoc generation into htmldocs

Change target `make htmldocs` to combine RST Sphinx and the generation of
Rust documentation, when support is available and .config exists.

Reviewed

docs: Integrate rustdoc generation into htmldocs

Change target `make htmldocs` to combine RST Sphinx and the generation of
Rust documentation, when support is available and .config exists.

Reviewed-by: Akira Yokosawa <[email protected]>
Signed-off-by: Carlos Bilbao <[email protected]>
Reviewed-by: Martin Rodriguez Reboredo <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

kbuild: do not print extra logs for V=2

Some scripts increase the verbose level when V=1, but others when
not V=0.

I think the former is correct because V=2 is not a log level but
a switch to print

kbuild: do not print extra logs for V=2

Some scripts increase the verbose level when V=1, but others when
not V=0.

I think the former is correct because V=2 is not a log level but
a switch to print the reason for rebuilding.

Signed-off-by: Masahiro Yamada <[email protected]>
Reviewed-by: Nicolas Schier <[email protected]>

show more ...

doc: add texinfodocs and infodocs targets

Sphinx supports generating Texinfo sources and Info documentation,
which can be navigated easily and is convenient to search (via the
indexed nodes or ancho

doc: add texinfodocs and infodocs targets

Sphinx supports generating Texinfo sources and Info documentation,
which can be navigated easily and is convenient to search (via the
indexed nodes or anchors, for example).

Signed-off-by: Maxim Cournoyer <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Makefile: Add -no-shell-escape option to LATEXOPTS

It turns out that LaTeX enables \write18, which allows (some) shell
commands to be executed from the document source, by default. This the
o

docs: Makefile: Add -no-shell-escape option to LATEXOPTS

It turns out that LaTeX enables \write18, which allows (some) shell
commands to be executed from the document source, by default. This the
often-seen warning during a pdfdocs build:

restricted \write18 enabled

That is a potential security problem and is entirely unnecessary; nothing
in the kernel PDF docs build needs that capability. So disable \write18
explicitly.

Signed-off-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: address some text issues with css/theme support

Fix:
- overriden ->overridden
- some whitespace issues introduced at the css/theme
Makefile help.

Reported-by: Randy Dunlap <rdunlap@infradea

docs: address some text issues with css/theme support

Fix:
- overriden ->overridden
- some whitespace issues introduced at the css/theme
Makefile help.

Reported-by: Randy Dunlap <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Link: https://lore.kernel.org/r/b0b166025019f7cc4f122bd789c79ba28cc2d29d.1639212812.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Makefile: use the right path for DOCS_CSS

When make is used with O=<dir>, the location of the css file
won't be get right:

$ make DOCS_THEME=nature DOCS_CSS=my_css.css O=DOCS SPHINXDIRS=x

docs: Makefile: use the right path for DOCS_CSS

When make is used with O=<dir>, the location of the css file
won't be get right:

$ make DOCS_THEME=nature DOCS_CSS=my_css.css O=DOCS SPHINXDIRS=x86 -j9 htmldocs
make[1]: Entering directory '/work/lnx/next/next-2021-1210/DOCS'
...
cp: cannot stat 'my_css.css': No such file or directory

Fix it in a way that both relative and absolute paths will be
handled.

Reported-by: Randy Dunlap <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Randy Dunlap <[email protected]>
Tested-by: Randy Dunlap <[email protected]>
Link: https://lore.kernel.org/r/cea4ff1237ae9a99bc6509ab1bf9c70acd97e265.1639212812.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: allow to pass extra DOCS_CSS themes via make

Specially when the RTD theme is not used, it makes sense to
allow specifying extra CSS files via a make variable.

Signed-off-by: Mauro Carvalho Ch

docs: allow to pass extra DOCS_CSS themes via make

Specially when the RTD theme is not used, it makes sense to
allow specifying extra CSS files via a make variable.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/03d09bf41ad39aa0abfe2ea3c879b09aa3a0948d.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: allow selecting a Sphinx theme

Instead of having RTD as an almost mandatory theme, allow the
user to select other themes via DOCS_THEME environment var.

There's a catch, though: as the curren

docs: allow selecting a Sphinx theme

Instead of having RTD as an almost mandatory theme, allow the
user to select other themes via DOCS_THEME environment var.

There's a catch, though: as the current theme override logic is
dependent of the RTD theme, we need to move the code which
adds the CSS overrides to be inside the RTD theme logic.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Makefile: Use CONFIG_SHELL not SHELL

Fix think-o about which variable to find the Kbuild-configured shell.
This has accidentally worked due to most shells setting $SHELL by
default.

Fixes: 51

docs: Makefile: Use CONFIG_SHELL not SHELL

Fix think-o about which variable to find the Kbuild-configured shell.
This has accidentally worked due to most shells setting $SHELL by
default.

Fixes: 51e46c7a4007 ("docs, parallelism: Rearrange how jobserver reservations are made")
Cc: [email protected]
Signed-off-by: Kees Cook <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

kbuild: remove PYTHON variable

Python retired in 2020, and some distributions do not provide the
'python' command any more.

As in commit 51839e29cb59 ("scripts: switch explicitly to Python 3"),
we

kbuild: remove PYTHON variable

Python retired in 2020, and some distributions do not provide the
'python' command any more.

As in commit 51839e29cb59 ("scripts: switch explicitly to Python 3"),
we need to use more specific 'python3' to invoke scripts even if they
are written in a way compatible with both Python 2 and 3.

This commit removes the variable 'PYTHON', and switches the existing
users to 'PYTHON3'.

BTW, PEP 394 (https://www.python.org/dev/peps/pep-0394/) is a helpful
material.

Signed-off-by: Masahiro Yamada <[email protected]>

show more ...

docs: Kconfig/Makefile: add a check for broken ABI files

The files under Documentation/ABI should follow the syntax
as defined at Documentation/ABI/README.

Allow checking if they're following the s

docs: Kconfig/Makefile: add a check for broken ABI files

The files under Documentation/ABI should follow the syntax
as defined at Documentation/ABI/README.

Allow checking if they're following the syntax by running
the ABI parser script on COMPILE_TEST.

With that, when there's a problem with a file under
Documentation/ABI, it would produce a warning like:

Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#14:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_cor' doesn't have a description
Warning: file ./Documentation/ABI/testing/sysfs-bus-pci-devices-aer_stats#21:
What '/sys/bus/pci/devices/<dev>/aer_stats/aer_rootport_total_err_fatal' doesn't have a description

Acked-by: Jonathan Corbet <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/57a38de85cb4b548857207cf1fc1bf1ee08613c9.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <[email protected]>

show more ...

docs: Makefile: honor V=0 for docs building

Reduce the number of displayed mesages when building the
docs with V=0.

Suggested-by: Stephen Rothwell <[email protected]>
Signed-off-by: Mauro Carval

docs: Makefile: honor V=0 for docs building

Reduce the number of displayed mesages when building the
docs with V=0.

Suggested-by: Stephen Rothwell <[email protected]>
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/478c114a2399b68a18de94ee5f98649304f3903b.1603796153.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Makefile: place final pdf docs on a separate dir

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

docs: Makefile: place final pdf docs on a separate dir

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 <[email protected]>
Link: https://lore.kernel.org/r/832752cbc9678a6e8d3d634bc3356d655d44684f.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

media: docs: move uAPI book to userspace-api/media

Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee3862 ("docs: Create a user-space API guide").

As the media

media: docs: move uAPI book to userspace-api/media

Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee3862 ("docs: Create a user-space API guide").

As the media subsystem was one of the first subsystems to use
Sphinx, until this patch, we were keeping things on a separate
place.

Let's just use the new location, as having all uAPI altogether
will likely make things easier for developers.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>

show more ...

kbuild: remove trailing slash from devicetree/binding/ for descending

obj-* needs a trailing slash for a directory, but subdir-* does not
because it already implies a directory.

Also, change subdir

kbuild: remove trailing slash from devicetree/binding/ for descending

obj-* needs a trailing slash for a directory, but subdir-* does not
because it already implies a directory.

Also, change subdir-y to subdir- to ensure this is effective only
for cleaning targets.

This makes the cleaning log consistent. (no trailing slash)

Before:

$ make clean
CLEAN Documentation/devicetree/bindings/

After:

$ make clean
CLEAN Documentation/devicetree/bindings

Signed-off-by: Masahiro Yamada <[email protected]>

show more ...

Documentation: sort _SPHINXDIRS for 'make help'

Sort the _SPHINXDIRS so that the 'make help' output is easier to read &
search and in a predictable order instead of some unknown pseudo-random
order.

Documentation: sort _SPHINXDIRS for 'make help'

Sort the _SPHINXDIRS so that the 'make help' output is easier to read &
search and in a predictable order instead of some unknown pseudo-random
order.

Signed-off-by: Randy Dunlap <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs, parallelism: Rearrange how jobserver reservations are made

Rasmus correctly observed that the existing jobserver reservation only
worked if no other build targets were specified. The correct a

docs, parallelism: Rearrange how jobserver reservations are made

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 <[email protected]>
Link: https://lore.kernel.org/lkml/[email protected]
Signed-off-by: Kees Cook <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...