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 <akiyks@gmail.com>
Signed-off-by: Carlos Bilbao <carlos.bilbao@amd.com>
Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20230718151534.4067460-3-carlos.bilbao@amd.com
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 <masahiroy@kernel.org>
Reviewed-by: Nicolas Schier <nicolas@fjasle.eu>
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 <maxim.cournoyer@gmail.com>
Link: https://lore.kernel.org/r/20221116190210.28407-2-maxim.cournoyer@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <akiyks@gmail.com>
Link: https://lore.kernel.org/r/519bd2d9-1bee-03e1-eeb4-d9883c18be0c@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/cea4ff1237ae9a99bc6509ab1bf9c70acd97e265.1639212812.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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 <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/bd20adabfd428fd3cd0e69c2cf146aa354932936.1638870323.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
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: 51e46c7a40 ("docs, parallelism: Rearrange how jobserver reservations are made")
Cc: stable@vger.kernel.org
Signed-off-by: Kees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20210617225808.3907377-1-keescook@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Python retired in 2020, and some distributions do not provide the
'python' command any more.
As in commit 51839e29cb ("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 <masahiroy@kernel.org>
silence in V=0 builds.
-----BEGIN PGP SIGNATURE-----
iQFDBAABCAAtFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAl+hdscPHGNvcmJldEBs
d24ubmV0AAoJEBdDWhNsDH5YOHYH/jMaHkXTOVQZIFouNn1nSymdk7ErTEinkVKu
l2E1teuyqY6nrZVWut8dtJEPSiMFxkjXP7qyvG3kAUEOz7axi0XhTPudLihBMj2N
xqUuOGoOpLhEa/F2jm1sDbS0NFmYtWkur/kZB4ibMVa5dp1jj61s1qAADhPDUXzH
J7H2AIGpVJkQyzFjslI7thwFGSR80ID49zVnAAI5b+MCayofij3Tn/wqdCGjecNa
5e/qPBxM/E8XkMq0mxUGvOvlDQd01LpCkr01wJeU+lgm3J48iGPnRqiRtae4kSMv
fYIaNvClhYARzMOwi4ExDJHUa0cp99FPXJ3enqsrEqo9yLkUw1I=
=PbGq
-----END PGP SIGNATURE-----
Merge tag 'docs-5.10-3' of git://git.lwn.net/linux
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
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 <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/57a38de85cb4b548857207cf1fc1bf1ee08613c9.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
-----BEGIN PGP SIGNATURE-----
iQIzBAABCAAdFiEE+QmuaPwR3wnBdVwACF8+vY7k4RUFAl7XUmwACgkQCF8+vY7k
4RU4zg//fT32wiVAPHCCp+pDZVnWNeipXE1gnpqghd/qZXfzBPiLEC9sPS74VVkA
jf1hhR33VZpKAKTPg/b074qhRZBywEOdHZnT/0CEE1oNB61shVOnyDYzLGSq95cO
6V55ovbi5IOkrg0QEJbHpG5YHzt+pq5XeWOkqGNsHwla7N7iMGMVYfHepVVDWPnZ
0wGYFF9cAJP+X/uxqkZLDVMA/K1I+QKh6vrj/qx53/eRt8VID3+i8ig3guk4PlUq
7RLw5w/CywtNaGE5zaz7T3i2eoED71JHOTXi6RxdP1z8IDvELZ9mT95GQ+enlwqt
AS6Ju1sV40wviHMv5prJWQjJkrrtYH3S907lIjwBpQLNGbh2+5crCd/6CwumkGgv
1cCZ1dVmXpCe++9mU9AXmSkjsjGPStNcmHMOpc1Pwn9jUV3LQOOSDp8+RYdt1WHU
Iw9cyM8NOpz5Mv/B1/ZPQ1gPb9lr1gE09XyUekxtAI/nl4nNHGWO8QDuX7Odfrv9
8nfo14lk/p6XCTA8dsWJCgI5B1fgnqD4frHKWO9Uctppc/KBW41c8JpQUjBNlG/T
MhtlGwYMVgSQxpQ6wK018JUAFoWkn1Sr0zMKRayqCnMjMLHsaMwE6kq+LgmRBqbB
ersKV/9ZLYqCU1d6PhEVG6xUs6GsWdLcyhALlmHsddPSdpFXdf8=
=KNAo
-----END PGP SIGNATURE-----
Merge tag 'media/v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media
Pull media updates from Mauro Carvalho Chehab:
- Media documentation is now split into admin-guide, driver-api and
userspace-api books (a longstanding request from Jon);
- The media Kconfig was reorganized, in order to make easier to select
drivers and their dependencies;
- The testing drivers now has a separate directory;
- added a new driver for Rockchip Video Decoder IP;
- The atomisp staging driver was resurrected. It is meant to work with
4 generations of cameras on Atom-based laptops, tablets and cell
phones. So, it seems worth investing time to cleanup this driver and
making it in good shape.
- Added some V4L2 core ancillary routines to help with h264 codecs;
- Added an ov2740 image sensor driver;
- The si2157 gained support for Analog TV, which, in turn, added
support for some cx231xx and cx23885 boards to also support analog
standards;
- Added some V4L2 controls (V4L2_CID_CAMERA_ORIENTATION and
V4L2_CID_CAMERA_SENSOR_ROTATION) to help identifying where the camera
is located at the device;
- VIDIOC_ENUM_FMT was extended to support MC-centric devices;
- Lots of drivers improvements and cleanups.
* tag 'media/v5.8-1' of git://git.kernel.org/pub/scm/linux/kernel/git/mchehab/linux-media: (503 commits)
media: Documentation: media: Refer to mbus format documentation from CSI-2 docs
media: s5k5baf: Replace zero-length array with flexible-array
media: i2c: imx219: Drop <linux/clk-provider.h> and <linux/clkdev.h>
media: i2c: Add ov2740 image sensor driver
media: ov8856: Implement sensor module revision identification
media: ov8856: Add devicetree support
media: dt-bindings: ov8856: Document YAML bindings
media: dvb-usb: Add Cinergy S2 PCIe Dual Port support
media: dvbdev: Fix tuner->demod media controller link
media: dt-bindings: phy: phy-rockchip-dphy-rx0: move rockchip dphy rx0 bindings out of staging
media: staging: dt-bindings: phy-rockchip-dphy-rx0: remove non-used reg property
media: atomisp: unify the version for isp2401 a0 and b0 versions
media: atomisp: update TODO with the current data
media: atomisp: adjust some code at sh_css that could be broken
media: atomisp: don't produce errs for ignored IRQs
media: atomisp: print IRQ when debugging
media: atomisp: isp_mmu: don't use kmem_cache
media: atomisp: add a notice about possible leak resources
media: atomisp: disable the dynamic and reserved pools
media: atomisp: turn on camera before setting it
...
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>
Since 2017, there is an space reserved for userspace API,
created by changeset 1d596dee38 ("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 <mchehab+huawei@kernel.org>
[Build system]
- add CONFIG_UNUSED_KSYMS_WHITELIST, which will be useful to define
a fixed set of export symbols for Generic Kernel Image (GKI)
- allow to run 'make dt_binding_check' without .config
- use full schema for checking DT examples in *.yaml files
- make modpost fail for missing MODULE_IMPORT_NS(), which makes more
sense because we know the produced modules are never loadable
- Remove unused 'AS' variable
[Kconfig]
- sanitize DEFCONFIG_LIST, and remove ARCH_DEFCONFIG from Kconfig files
- relax the 'imply' behavior so that symbols implied by y can become m
- make 'imply' obey 'depends on' in order to make 'imply' really weak
[Misc]
- add documentation on building the kernel with Clang/LLVM
- revive __HAVE_ARCH_STRLEN for 32bit sparc to use optimized strlen()
- fix warning from deb-pkg builds when CONFIG_DEBUG_INFO=n
- various script and Makefile cleanups
-----BEGIN PGP SIGNATURE-----
iQJJBAABCgAzFiEEbmPs18K1szRHjPqEPYsBB53g2wYFAl6DbP8VHG1hc2FoaXJv
eUBrZXJuZWwub3JnAAoJED2LAQed4NsGAfkQALZqMCqtX9cAJej04+lnBCzwVPep
6s8/s6vW6PF92sHv+SJtHvKSnDekcZT2xT8dkPDaVmuOye8xhENs5dFZ4tSKO5D0
F8YkkM17mu/cylNZ2UCy/8weh6/TjsD7pa+mFqWo/++30JiXm12v3mVFR568KPXI
kFau/3ALvY1NIr2wUAI2SOd6A4v/Epzpk0ltnFg3f5iWVFKlE03MGueAF+YZzq7v
UrU73HdUxF/SBW2Jz3UtV9XY8P38uQmmtoDE8SZikG4PjW03q9w6pnhntDBl/H2b
dZFg40eG7SHXN4L+OOI32ae9jePHvKpsnjeaeNoT/DZpwpuuxXu7C2EmUy+wCAnM
Rw4+kiAVNppRMRH1GTdp1XjLY6PwPqizzZGmufwX+W3MI8oZdlLSUJLbrO73P/aF
QR3MgkJkjvgmRVPP9fr8SNcZ39tDGI4KqLdWvjVVSC/s86aDnw/34puEfw0lj4vs
gCi923iJQ7Y/QWX63TYZhy96pnedlwE2s6aR1InVER3+XMH9K1nW34CDaKQsp1CB
6zyrd40+K5ETOKo3OAjq4FttlhRkEpX9nIsffCzOz6tybysHTSrCzYhfjpIAzzYj
Et5HpXbegHShIqN44yqBumt6YkTZac6Aub9FzInW2LPzZgiofDaNesDQmnQmIZOa
JlUyBrjXRfwkvCH0
=wT8A
-----END PGP SIGNATURE-----
Merge tag 'kbuild-v5.7' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild
Pull Kbuild updates from Masahiro Yamada:
"Build system:
- add CONFIG_UNUSED_KSYMS_WHITELIST, which will be useful to define a
fixed set of export symbols for Generic Kernel Image (GKI)
- allow to run 'make dt_binding_check' without .config
- use full schema for checking DT examples in *.yaml files
- make modpost fail for missing MODULE_IMPORT_NS(), which makes more
sense because we know the produced modules are never loadable
- Remove unused 'AS' variable
Kconfig:
- sanitize DEFCONFIG_LIST, and remove ARCH_DEFCONFIG from Kconfig
files
- relax the 'imply' behavior so that symbols implied by 'y' can
become 'm'
- make 'imply' obey 'depends on' in order to make 'imply' really weak
Misc:
- add documentation on building the kernel with Clang/LLVM
- revive __HAVE_ARCH_STRLEN for 32bit sparc to use optimized strlen()
- fix warning from deb-pkg builds when CONFIG_DEBUG_INFO=n
- various script and Makefile cleanups"
* tag 'kbuild-v5.7' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild: (34 commits)
Makefile: Update kselftest help information
kbuild: deb-pkg: fix warning when CONFIG_DEBUG_INFO is unset
kbuild: add outputmakefile to no-dot-config-targets
kbuild: remove AS variable
net: wan: wanxl: refactor the firmware rebuild rule
net: wan: wanxl: use $(M68KCC) instead of $(M68KAS) for rebuilding firmware
net: wan: wanxl: use allow to pass CROSS_COMPILE_M68k for rebuilding firmware
kbuild: add comment about grouped target
kbuild: add -Wall to KBUILD_HOSTCXXFLAGS
kconfig: remove unused variable in qconf.cc
sparc: revive __HAVE_ARCH_STRLEN for 32bit sparc
kbuild: refactor Makefile.dtbinst more
kbuild: compute the dtbs_install destination more simply
Makefile: disallow data races on gcc-10 as well
kconfig: make 'imply' obey the direct dependency
kconfig: allow symbols implied by y to become m
net: drop_monitor: use IS_REACHABLE() to guard net_dm_hw_report()
modpost: return error if module is missing ns imports and MODULE_ALLOW_MISSING_NAMESPACE_IMPORTS=n
modpost: rework and consolidate logging interface
kbuild: allow to run dt_binding_check without kernel configuration
...
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 <masahiroy@kernel.org>
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 <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
- remove unneeded asm headers from hexagon, ia64
- add 'dir-pkg' target, which works like 'tar-pkg' but skips archiving
- add 'helpnewconfig' target, which shows help for new CONFIG options
- support 'make nsdeps' for external modules
- make rebuilds faster by deleting $(wildcard $^) checks
- remove compile tests for kernel-space headers
- refactor modpost to simplify modversion handling
- make single target builds faster
- optimize and clean up scripts/kallsyms.c
- refactor various Makefiles and scripts
-----BEGIN PGP SIGNATURE-----
iQJJBAABCgAzFiEEbmPs18K1szRHjPqEPYsBB53g2wYFAl3lKCUVHG1hc2FoaXJv
eUBrZXJuZWwub3JnAAoJED2LAQed4NsGu9sP/iTW/RjDxbAsu0aP8jFqzLK/xKB/
NQn/+dD76TjEmjgew9AXszf2rJL+ixKVymGM08FV59Bbguvi8XmAB/QXK21Sjb5j
rVl3N97TWNkvXM+QJyly23G2UtbubRSPo3g+e70BZrw3lcmrsK+sAmTOL5KtIrNX
9BHM803JwqsMJyvBwTBBw3UFeeBqb38Qx6gmigfSihuDf6pvjoVDKskpsDno3wX7
rdiXYxAsKQLQ/P2ym/bV/Oqe90RqRtV/2/WCpLshlwHkiM9huflv6GjgCkkbAx5H
N3TSptlS7l/2B/XKHgA5ALjHjUlxTGBzLLoevarCd8loKcQXFlgx+vd3nM/WJlHJ
x9UpTklDwGP9eUBsa9W980tEyUVsFGMAC8EcTdW6NN2IRtuCOSA5N2FYYt8/SDd0
2b3PhElTJIp4pTWSYN6JZxB1R8n/YBgxLqOJ6N2U6B9CdKFUCHlwGH23QfN89km/
WEMP85bsaab/dnyxbwelkoYYYyPgUHsC13AbpkHdrDxMbAGO+G1PwpHxC6ErF2en
wRGrcUxWTfHRykO5aJIQtCB9b1fv73134mTzB5fTYd6GtjepGBSBCO9xb2Iy4sc9
Y+nHVVDUrihvSOpJgqh677PcLDutOZR8fFCoc1ZMDAbBsDvrb0Qsee6oEidj98xc
5kXp9YZh/tdh/tdo
=zUaB
-----END PGP SIGNATURE-----
Merge tag 'kbuild-v5.5' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild
Pull Kbuild updates from Masahiro Yamada:
- remove unneeded asm headers from hexagon, ia64
- add 'dir-pkg' target, which works like 'tar-pkg' but skips archiving
- add 'helpnewconfig' target, which shows help for new CONFIG options
- support 'make nsdeps' for external modules
- make rebuilds faster by deleting $(wildcard $^) checks
- remove compile tests for kernel-space headers
- refactor modpost to simplify modversion handling
- make single target builds faster
- optimize and clean up scripts/kallsyms.c
- refactor various Makefiles and scripts
* tag 'kbuild-v5.5' of git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild: (59 commits)
MAINTAINERS: update Kbuild/Kconfig maintainer's email address
scripts/kallsyms: remove redundant initializers
scripts/kallsyms: put check_symbol_range() calls close together
scripts/kallsyms: make check_symbol_range() void function
scripts/kallsyms: move ignored symbol types to is_ignored_symbol()
scripts/kallsyms: move more patterns to the ignored_prefixes array
scripts/kallsyms: skip ignored symbols very early
scripts/kallsyms: add const qualifiers where possible
scripts/kallsyms: make find_token() return (unsigned char *)
scripts/kallsyms: replace prefix_underscores_count() with strspn()
scripts/kallsyms: add sym_name() to mitigate cast ugliness
scripts/kallsyms: remove unneeded length check for prefix matching
scripts/kallsyms: remove redundant is_arm_mapping_symbol()
scripts/kallsyms: set relative_base more effectively
scripts/kallsyms: shrink table before sorting it
scripts/kallsyms: fix definitely-lost memory leak
scripts/kallsyms: remove unneeded #ifndef ARRAY_SIZE
kbuild: make single target builds even faster
modpost: respect the previous export when 'exported twice' is warned
modpost: do not set ->preloaded for symbols from Module.symvers
...
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 <linux@rasmusvillemoes.dk>
Link: https://lore.kernel.org/lkml/eb25959a-9ec4-3530-2031-d9d716b40b20@rasmusvillemoes.dk
Signed-off-by: Kees Cook <keescook@chromium.org>
Link: https://lore.kernel.org/r/20191121205929.40371-4-keescook@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Some "make help" text lines extend beyond 80 characters.
Wrap them before an opening parenthesis, or before 80 characters.
Signed-off-by: Geert Uytterhoeven <geert+renesas@glider.be>
Signed-off-by: Masahiro Yamada <yamada.masahiro@socionext.com>
Commit 9fc3a18a94 ("docs: remove extra conf.py files") broke the setting
of _SPHINXDIRS in Documentation/Makefile. Let's just have it look for an
index.rst file instead.
Fixes: 9fc3a18a94 ("docs: remove extra conf.py files")
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
While sphinx 1.7 and later supports "-jauto" for parallelism, this
effectively ignores the "-j" flag used in the "make" invocation, which
may cause confusion for build systems. Instead, extract the available
parallelism from "make"'s job server (since it is not exposed in any
special variables) and use that for the "sphinx-build" run. Now things
work correctly for builds where -j is specified at the top-level:
make -j16 htmldocs
If -j is not specified, continue to fallback to "-jauto" if available.
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
While this doesn't make sense for production Kernels, in order to
avoid regressions when documents are touched, let's add a
check target at the make file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
My previous fix miserably failed to catch all of the invocations of
"./scripts/sphinx-pre-install", so we got build errors. Try again with
more caffeine.
Reported-by: kbuild test robot <lkp@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Recent makefile changes included an invocation of
./scripts/sphinx-pre-install. Unfortunately, that fails when a separate
build directory is in use with:
/bin/bash: ./scripts/sphinx-pre-install: No such file or directory
Use $(srctree) to fully specify the location of this script.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Since Sphinx version 1.7, it is possible to use "-jauto" in
order to speedup documentation builds. On older versions,
while -j was already supported, one would need to set the
number of threads manually.
So, if SPHINXOPTS is not provided, add -jauto, in order to
speed up the build. That makes it *a lot* times faster than
without -j.
If one really wants to slow things down, it can just use:
make SPHINXOPTS=-j1 htmldocs
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
[ jc: fixed perl magic to determine sphinx version ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Call the script every time a make docs target is selected, on
a simplified check mode.
With this change, the script will set two vars:
$min_version - obtained from `needs_sphinx` var inside
conf.py (currently, '1.3')
$rec_version - obtained from sphinx/requirements.txt.
With those changes, a target like "make htmldocs" will do:
1) If no sphinx-build/sphinx-build3 is found, it will run
the script on normal mode as before, checking for all
system dependencies and providing install hints for the
needed programs and will abort the build;
2) If no sphinx-build/sphinx-build3 is found, but there is
a sphinx_${VER}/bin/activate file, and if
${VER} >= $min_version (string comparation), it will
run in full mode, and will recommend to activate the
virtualenv. If there are multiple virtualenvs, it
will string sort the versions, recommending the
highest version and will abort the build;
3) If Sphinx is detected but has a version lower than
$min_version, it will run in full mode - with will
recommend creating a virtual env using sphinx/requirements.txt,
and will abort the build.
4) If Sphinx is detected and version is lower than
$rec_version, it will run in full mode and will
recommend creating a virtual env using sphinx/requirements.txt.
In this case, it **won't** abort the build.
5) If Sphinx is detected and version is equal or righer than
$rec_version it will return just after detecting the
version ("quick mode"), not checking if are there any
missing dependencies.
Just like before, if one wants to install Sphinx from the
distro, it has to call the script manually and use `--no-virtualenv`
argument to get the hints for his OS:
You should run:
sudo dnf install -y python3-sphinx python3-sphinx_rtd_theme
While here, add a small help for the three optional arguments
for the script.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
In the past, Sphinx was generating a LaTex Makefile that would
run xelatex 3 times. Running it multiple times is needed in order
to make the indexes right.
However, newer versions of it runs it just once, as it expects
the machine to use the "latexmk" build, with automatically
detects the need for rebuilds.
So, add a logic at the Makefile in order to detect if latexmk
is installed. If so, it will call it.
As an additional bonus, the output of latexmk is a little bit
better, making easier to identify build problems.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This adds the build infrastructure for checking DT binding schema
documents and validating dts files using the binding schema.
Check DT binding schema documents:
make dt_binding_check
Build dts files and check using DT binding schema:
make dtbs_check
Optionally, DT_SCHEMA_FILES can be passed in with a schema file(s) to
use for validation. This makes it easier to find and fix errors
generated by a specific schema.
Currently, the validation targets are separate from a normal build to
avoid a hard dependency on the external DT schema project and because
there are lots of warnings generated.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mark Rutland <mark.rutland@arm.com>
Acked-by: Masahiro Yamada <yamada.masahiro@socionext.com>
Cc: Michal Marek <michal.lkml@markovi.net>
Cc: linux-doc@vger.kernel.org
Cc: devicetree@vger.kernel.org
Cc: linux-kbuild@vger.kernel.org
Signed-off-by: Rob Herring <robh@kernel.org>
Add a simple script and build target to do a treewide grep for
references to files under Documentation, and report the non-existing
file in stderr. It tries to take into account punctuation not part of
the filename, and wildcards, but there are bound to be false positives
too. Mostly seems accurate though.
We've moved files around enough to make having this worthwhile.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Enhance documentation help message to specify the default location for
the generated documents.
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Right now, if the building system doesn't find Sphinx, it
bails out, without providing any instructions about what
should be done.
Instead, run a script, providing some guidance about the
steps needed for Sphinx build to work.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
After removal of DocBook, those targets are bogus.
Reported-by: Jim Davis <jim.epost@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Move blackfin gptimers-example to samples and remove it from Documentation
Makefile. Update samples Kconfig and Makefile to build gptimers-example.
blackfin is the last CONFIG_BUILD_DOCSRC target in Documentation/Makefile.
Hence this patch also includes changes to remove CONFIG_BUILD_DOCSRC from
Makefile and lib/Kconfig.debug and updates VIDEO_PCI_SKELETON dependency
on BUILD_DOCSRC.
Documentation/Makefile is not deleted to avoid braking make htmldocs and
make distclean.
Acked-by: Michal Marek <mmarek@suse.com>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Reviewed-by: Kees Cook <keescook@chromium.org>
Reported-by: Valentin Rothberg <valentinrothberg@gmail.com>
Reported-by: Paul Gortmaker <paul.gortmaker@windriver.com>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move pcmcia crc32hash tool from Documentation to tools/pcmcia and
remove it from Documentation Makefile. Update location information
for this tool. Create a new Makefile to build pcmcia. It can be built
from top level directory or from pcmcia directory:
Run make -C tools/pcmcia or cd tools/pcmcia; make
Acked-by: Dominik Brodowski <linux@dominikbrodowski.net>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move laptops dslm tool to tools/laptop/dslm and remove it from
Documentation Makefile. Update location information for this
tool. Create a new Makefile to build dslm. It can be built
from top level directory or from laptops directory:
Run make -C tools/laptop/dslm or cd tools/laptop/dslm; make
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move accounting tool to tools and remove it from Documentation
Makefile. Update location information for this tool. Create a
new Makefile to build accounting. It can be built from top level
directory or from accounting directory:
Run make -C tools/accounting or cd tools/accounting; make
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move auxdisplay examples to samples and remove it from Documentation
Makefile. Create a new Makefile to build auxdisplay. It can be built
from top level directory or from auxdisplay directory:
Run make -C samples/auxdisplay or cd samples/auxdisplay; make
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move watchdog examples to samples and remove it from Documentation
Makefile. Create a new Makefile to build watchdog. It can be built
from top level directory or from watchdog directory:
Run make -C samples/watchdog or cd samples/watchdog; make
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move timers examples to samples and remove it from Documentation
Makefile. Create a new Makefile to build timers. It can be built
from top level directory or from timers directory:
Run make -C samples/timers or cd samples/timers; make
Acked-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Clemens Ladisch <clemens@ladisch.de>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move misc-devices/mei examples to samples/mei and remove it from
Documentation Makefile. Delete misc-devices/Makefile.
Create a new Makefile to build samples/mei. It can be built from top
level directory or from mei directory:
Run make -C samples/mei or cd samples/mei; make
Acked-by: Jonathan Corbet <corbet@lwn.net>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Acked-by: Tomas Winkler <tomas.winkler@intel.com>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move mic/mpssd examples to samples and remove it from Documentation
Makefile. Create a new Makefile to build mic/mpssd. It can be built
from top level directory or from mic/mpssd directory:
Run make -C samples/mic/mpssd or cd samples/mic/mpssd; make
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Remove networking from Documentation Makefile to move the test to
selftests. Update networking/timestamping Makefile to work under
selftests. These tests will not be run as part of selftests suite
and will not be included in install targets. They can be built and
run separately for now.
This is part of the effort to move runnable code from Documentation.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Remove ia64 from Makefile to move the test to selftests.
Update ia64 Makefile to work under selftests. ia64 will not be run as part
of selftests suite and will not be included in install targets. They can be
built separately for now.
The original Makefile built this test on all archirectures and this update
doesn't change that.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Remove vDSO from Makefile to move the to selftests. Update vDSO Makefile
to work under selftests. vDSO will not be run as part of selftests suite
and will not be included in install targets. They can be built separately
for now.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Remove ptp from Makefile to move the test to selftests. Update ptp Makefile
to work under selftests. ptp will not be run as part of selftests suite and
will not be included in install targets. They can be built separately for
now.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
Move prctl tests from Documentation/prctl to selftests/prctl.
Remove prctl from Makefile to move the test. Update prctl Makefile to work
under selftests. prctl will not be run as part of selftests suite and will
not be included in install targets. They can be built separately for now.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Shuah Khan <shuahkh@osg.samsung.com>
