tools/docs: sphinx-* break documentation bulds on openSUSE
Before this patch, building htmldocs on opensuseLEAP works
fine:
# make htmldocs
Available Python versions:
/usr/bin/python3.11
Python 3.6.15 not supported. Changing to /usr/bin/python3.11
Python 3.6.15 not supported. Changing to /usr/bin/python3.11
Using alabaster theme
Using Python kernel-doc
...
As the logic detects that Python 3.6 is too old and recommends
intalling python311-Sphinx. If installed, documentation builds
work like a charm.
Yet, some develpers complained that running python3.11 instead
of python3 should not happen. So, let's break the build to make
them happier:
$ make htmldocs
Python 3.6.15 not supported. Bailing out
You could run, instead:
/usr/bin/python3.11 tools/docs/sphinx-build-wrapper htmldocs \
--sphinxdirs=. --conf=conf.py --builddir=Documentation/output --theme= --css= \
--paper=
All optional dependencies are met.
Needed package dependencies are met.
2. sphinx-build-wrapper will auto-detect python3.11 and
suggest a way to build the docs using the parameters passed
via make variables. In this specific example:
3. As this needs to be executed outside docs Makefile, it won't run
the validation check scripts nor build Rust documentation if
enabled, as the extra scripts are part of the docs Makefile.
tools/docs: sphinx-build-wrapper: move rust doc builder to wrapper
Simplify even further the docs Makefile by moving rust build logic
to the wrapper.
After this change, running make on an environment with rust enabled
works as expected.
With CONFIG_RUST:
$ make O=/tmp/foo LLVM=1 SPHINXDIRS=peci htmldocs
make[1]: Entrando no diretório '/tmp/foo'
Using alabaster theme
Using Python kernel-doc
GEN Makefile
DESCEND objtool
CC arch/x86/kernel/asm-offsets.s
INSTALL libsubcmd_headers
CALL /new_devel/docs/scripts/checksyscalls.sh
RUSTC L rust/core.o
BINDGEN rust/bindings/bindings_generated.rs
BINDGEN rust/bindings/bindings_helpers_generated.rs
...
Without it:
$ make SPHINXDIRS=peci htmldocs
Using alabaster theme
Using Python kernel-doc
Both work as it is it is supposed to do.
After the change, it is also possible to build directly with the script
by passing "--rustodoc".
if CONFIG_RUST, this works fine:
$ ./tools/docs/sphinx-build-wrapper --sphinxdirs peci --rustdoc -- htmldocs
Using alabaster theme
Using Python kernel-doc
SYNC include/config/auto.conf
...
RUSTC L rust/core.o
...
If not, it will produce a warning that RUST may be disabled:
$ ./tools/docs/sphinx-build-wrapper --sphinxdirs peci --rustdoc -- htmldocs
Using alabaster theme
Using Python kernel-doc
***
*** Configuration file ".config" not found!
***
*** Please run some configurator (e.g. "make oldconfig" or
*** "make menuconfig" or "make xconfig").
***
make[1]: *** [/new_devel/docs/Makefile:829: .config] Error 1
make: *** [Makefile:248: __sub-make] Error 2
Ignored errors when building rustdoc: Command '['make', 'LLVM=1', 'rustdoc']' returned non-zero exit status 2.. Is RUST enabled?
scripts: kdoc_parser.py: warn about Python version only once
When running kernel-doc over multiple documents, it emits
one error message per file with is not what we want:
$ python3.6 scripts/kernel-doc.py . --none
...
Warning: ./include/trace/events/swiotlb.h:0 Python 3.7 or later is required for correct results
Warning: ./include/trace/events/iommu.h:0 Python 3.7 or later is required for correct results
Warning: ./include/trace/events/sock.h:0 Python 3.7 or later is required for correct results
...
Change the logic to warn it only once at the library:
$ python3.6 scripts/kernel-doc.py . --none
Warning: Python 3.7 or later is required for correct results
Warning: ./include/cxl/features.h:0 Python 3.7 or later is required for correct results
When running from command line, it warns twice, but that sounds
ok.
tools: kernel-doc: add a see also section at man pages
While cross-references are complex, as related ones can be on
different files, we can at least correlate the ones that belong
to the same file, adding a SEE ALSO section for them.
The result is not bad. See for instance:
$ tools/docs/sphinx-build-wrapper --sphinxdirs driver-api/media -- mandocs
$ man Documentation/output/driver-api/man/edac_pci_add_device.9
tools/docs: sphinx-build-wrapper: Fix output for duplicated names
When SPHINXDIRS is used, basename may be identical for different
files. If this happens, the summary and error detection won't be
accurate.
Fix it by using relative names from builddir.
While here, don't duplicate names. Report, instead:
- SUCCESS
output PDF file was built
- FAILED
latexmk/xelatex didn't build any PDF output
- FAILED: no .tex files were generated
Sphinx didn't build any tex file for SPHINXDIRS directories
- FAILED ({python exception})
When a concurrent.futures is catched. Usually indicates an
internal error at the build logic.
With that, building multiple dirs with the same name is reported
properly:
$ make V=1 SPHINXDIRS="admin-guide/media driver-api/media userspace-api/media" pdfdocs
tools/docs: sphinx-build-wrapper: allow building PDF files in parallel
Use POSIX jobserver when available or -j<number> to run PDF
builds in parallel, restoring pdf build performance. Yet,
running it when debugging troubles is a bad idea, so, when
calling directly via command line, except if "-j" is splicitly
requested, it will serialize the build.
With such change, a PDF doc builds now takes around 5 minutes
on a Ryzen 9 machine with 32 cpu threads:
# Explicitly paralelize both Sphinx and LaTeX pdf builds
$ make cleandocs; time scripts/sphinx-build-wrapper pdfdocs -j 33
real 5m17.901s
user 15m1.499s
sys 2m31.482s
# Use POSIX jobserver to paralelize both sphinx-build and LaTeX
$ make cleandocs; time make pdfdocs
real 5m22.369s
user 15m9.076s
sys 2m31.419s
# Serializes PDF build, while keeping Sphinx parallelized.
# it is equivalent of passing -jauto via command line
$ make cleandocs; time scripts/sphinx-build-wrapper pdfdocs
tools/docs: sphinx-build-wrapper: add an argument for LaTeX interactive mode
By default, we use LaTeX batch mode to build docs. This way, when
an error happens, the build fails. This is good for normal builds,
but when debugging problems with pdf generation, the best is to
use interactive mode.
We already support it via LATEXOPTS, but having a command line
argument makes it easier:
The only usage of this script was docs Makefile. Now that
it is using the new sphinx-build-wrapper, which has inside
the code from parallel-wrapper.sh, we can drop this script.
tools/docs: sphinx-build-wrapper: add a wrapper for sphinx-build
There are too much magic inside docs Makefile to properly run
sphinx-build. Create an ancillary script that contains all
kernel-related sphinx-build call logic currently at Makefile.
Such script is designed to work both as an standalone command
and as part of a Makefile. As such, it properly handles POSIX
jobserver used by GNU make.
On a side note, there was a line number increase due to the
conversion (ignoring comments) is:
Comments and descriptions adds:
tools/docs/sphinx-build-wrapper | 261 +++++++++++++++++++++++++++++++-
So, about half of the script are comments/descriptions.
This is because some things are more verbosed on Python and because
it requires reading env vars from Makefile. Besides it, this script
has some extra features that don't exist at the Makefile:
- It can be called directly from command line;
- It properly return PDF build errors.
When running the script alone, it will only take handle sphinx-build
targets. On other words, it won't runn make rustdoc after building
htmlfiles, nor it will run the extra check scripts.
tools/docs: python_version: move version check from sphinx-pre-install
The sphinx-pre-install code has some logic to deal with Python
version, which ensures that a minimal version will be enforced
for documentation build logic.
Move it to a separate library to allow re-using its code.
tools/docs: sphinx-pre-install: allow check for alternatives and bail out
The caller script may not want an automatic execution of the new
version. Add two parameters to allow showing alternatives and to
bail out if version is incompatible.
check-variable-fonts.py: add a helper to display instructions
Use lib docstring to output the comments via --help/-h. With
that, update the default instructions to recomment it instead
of asking the user to read the source code.
tools/docs: check-variable-fonts.py: split into a lib and an exec file
As we'll be using the actual code inside sphinx-build-wrapper,
split the library from the executable, placing the exec at
the new place we've been using:
scripts: check-variable-fonts.sh: convert to Python
This script handle errors when trying to build translations
with make pdfdocs.
As part of our cleanup work to remove hacks from docs Makefile,
convert this to python, preparing it to be part of a library
to be called by sphinx-build-wrapper.
Convert the code inside jobserver-exec to a class and
properly document it.
Using a class allows reusing the jobserver logic on other
scripts.
While the main code remains unchanged, being compatible with
Python 2.6 and 3.0+, its coding style now follows a more
modern standard, having tabs replaced by a 4-spaces
indent, passing autopep8, black and pylint.
The code allows using a pythonic way to enter/exit a python
code, e.g. it now supports:
with JobserverExec() as jobserver:
jobserver.run(sys.argv[1:])
With the new code, the __exit__() function should ensure
that the jobserver slot will be closed at the end, even if
something bad happens somewhere.
Alex Tran [Tue, 2 Sep 2025 02:30:37 +0000 (19:30 -0700)]
docs: filesystems: sysfs: add remaining top level sysfs directory descriptions
Finish top level sysfs directory descriptions for block, class, firmware,
hypervisor, kernel, and power. Did not write one for net directory. See
commit bc3a88431672 ("docs: filesystems: sysfs: remove top level sysfs net
directory")
Signed-off-by: Alex Tran <alex.t.tran@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902023039.1351270-1-alex.t.tran@gmail.com>
Alex Tran [Tue, 2 Sep 2025 02:30:38 +0000 (19:30 -0700)]
docs: filesystems: sysfs: clarify symlink destinations in dev and bus/devices descriptions
Change sysfs bus/devices and dev directory descriptions to
provide more verbose information about the specific symlink
destination the devices point to.
Signed-off-by: Alex Tran <alex.t.tran@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902023039.1351270-2-alex.t.tran@gmail.com>
Alex Tran [Tue, 2 Sep 2025 02:30:39 +0000 (19:30 -0700)]
docs: filesystems: sysfs: remove top level sysfs net directory
The net/ directory is not present as a top level sysfs directory
in standard Linux systems. Network interfaces can be accessible
via /sys/class/net instead.
Signed-off-by: Alex Tran <alex.t.tran@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902023039.1351270-3-alex.t.tran@gmail.com>
Add a newline after both subheadings to avoid any ambiguous formatting,
especially in htmldocs. Without the newline, subheadings are rendered as
part of the following paragraphs, which can be confusing to read.
Suggested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Thorsten Blum <thorsten.blum@linux.dev> Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250916222944.2547948-2-thorsten.blum@linux.dev>
Jonathan Corbet [Mon, 8 Sep 2025 22:01:15 +0000 (16:01 -0600)]
docs: kdoc: consolidate some of the macro-processing logic
The logic to handle macros is split in dump_function(); bring it all
together into a single place and add a comment saying what's going on.
Remove the unneeded is_define_proto variable, and tighten up the code
a bit.
Jonathan Corbet [Mon, 8 Sep 2025 19:22:42 +0000 (13:22 -0600)]
docs: kdoc: Simplify the dump_function() prototype regexes
The regexes for the parsing of function prototypes were more complicated
than they needed to be and difficult to understand -- at least, I spent a
fair amount of time bashing my head against them. Simplify them, and add
some documentation comments as well.
Jonathan Corbet [Fri, 5 Sep 2025 21:53:05 +0000 (15:53 -0600)]
docs: kdoc: remove a couple of spurious regex characters
The "name" regex in dump_function() includes both the tilde and colon
characters, but neither has any place in function prototypes. Remove the
characters, after which the regex simplifies to "\w+"
Jonathan Corbet [Thu, 4 Sep 2025 22:49:52 +0000 (16:49 -0600)]
doc: kdoc: unify transform handling
Both functions and structs are passed through a set of regex-based
transforms, but the two were structured differently, despite being the same
thing. Create a utility function to apply transformations and use it in
both cases.
Jonathan Corbet [Thu, 4 Sep 2025 19:33:56 +0000 (13:33 -0600)]
docs: kdoc: trim __cacheline_group_* with the other annotations
The special case for __cacheline_group_begin/end() can be handled by just
adding another pattern to the struct_prefixes, eliminating the need for a
special case in push_parameter().
One change is that these annotations no longer appear in the rendered
output, just like all the other annotations that we clean out.
Currently, LKMM docs are not included in any of kernel documentation
books.
Commit e40573a43d16 ("docs: put atomic*.txt and memory-barriers.txt
into the core-api book") covered plain-text docs under Documentation/
by using the "include::" directive along with the ":literal:" option.
As LKMM docs are not under Documentation/, the same approach would not
work due to the directive's restriction.
As a matter of fact, kernel documentation has an extended directive
by the name of "kernel-include::", which loosens such restriction and
accepts any files under the kernel source tree.
Rather than moving LKMM docs around, use the latter and pull them into
the dev-tools book next to KCSAN.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Cc: Paul E. McKenney <paulmck@kernel.org> Acked-by: Paul E. McKenney <paulmck@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <7ce84a93-5cbc-420e-894a-06a0372c52ab@gmail.com>
Jonathan Corbet [Tue, 9 Sep 2025 19:35:37 +0000 (13:35 -0600)]
docs: kdoc: handle the obsolescensce of docutils.ErrorString()
The ErrorString() and SafeString() docutils functions were helpers meant to
ease the handling of encodings during the Python 3 transition. There is no
real need for them after Python 3.6, and docutils 0.22 removes them,
breaking the docs build
Handle this by just injecting our own one-liner version of ErrorString(),
and removing the sole SafeString() call entirely.
Reported-by: Zhixu Liu <zhixu.liu@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <87ldmnv2pi.fsf@trenco.lwn.net>
Jonathan Corbet [Mon, 8 Sep 2025 19:32:10 +0000 (13:32 -0600)]
docs: update the guidance for Link: tags
As stated definitively by Linus, the use of Link: tags should be limited to
situations where there is additional useful information to be found at the
far end of the link. Update our documentation to reflect that policy, and
to remove the suggestion for a Git hook to add those tags automatically.
Documentation: update maintainer-pgp-guide for latest best practices
Freshen up the maintainer PGP guide:
- Bump minimum GnuPG version requirement from 2.2 to 2.4, since 2.2 is
no longer maintained
- All major hardware tokens now support Curve25519, so remove outdated
ECC support callouts
- Update hardware device recommendations (Nitrokey Pro 2 -> Nitrokey 3)
- Broaden backup media terminology (USB thumb drive -> external media)
- Update wording to follow vale's linter recommendations
- Various minor wording improvements for clarity
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Reviewed-by: Paul Barker <paul@pbarker.dev> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250902-pgp-guide-updates-v1-1-62ac7312d3f9@linuxfoundation.org>
Every now and then people send stylistic patches and use Fixes
purely to refer to a commit which added the ugly or unnecessary
code. Reword the docs about Fixes.
It should hopefully be enough to lead with the word "bug"
rather than "issue". We can add more verbiage later, tho, let's
try the word swap first. I always feel like the more words the
smaller the chance someone will actually read the docs.
Signed-off-by: Jakub Kicinski <kuba@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250904144533.2146576-1-kuba@kernel.org>
Jonathan Corbet [Tue, 9 Sep 2025 19:40:35 +0000 (13:40 -0600)]
Merge branch 'renames' into docs-mw
From Vegard Nossum:
When we rename an .rst file, that also changes the URL for the document
at https://docs.kernel.org/ and results in a 404, which can be anonying
for people who bookmark URLs and/or follow links from search engines
and old changelogs and emails.
In order to be able to fearlessly rename individual documentation files
and reorganize Documentation/, add two scripts:
- tools/docs/gen-renames.py : use git to figure out which .rst files
have been renamed
- tools/docs/gen-redirects.py : actually generate .html stubs for the
locations, redirecting to the new locations
The reason for splitting this into two is that trawling git history is
slightly slow (on the order of 20-30 seconds on my laptop) whereas just
generating the HTML files is very fast. This also allows us to cache
the historical renames in Documentation/.renames.txt or add manual
fixups as needed.
Documentation: w1: Fix SPDX comment syntax on masters and slaves toctree index
Commit e9bb627561535d ("docs: w1: convert to ReST and add to the kAPI
group of docs") converts 1-Wire docs to reST alongside with SPDX
comment, yet the comment is written in one dot as opposed to two in
order to be recognized as comment directive, which spills it into
htmldocs output. This issue is partially fixed in d8fb03e1ea64e7 ("docs:
w1: Fix SPDX-License-Identifier syntax") as it only touches top-level w1
toctree.
Do the same fix on masters and slaves toctrees.
Fixes: e9bb62756153 ("docs: w1: convert to ReST and add to the kAPI group of docs") Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Krzysztof Kozlowski <krzysztof.kozlowski@linaro.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20250909022142.18007-1-bagasdotme@gmail.com>
Vegard Nossum [Sat, 30 Aug 2025 17:08:08 +0000 (19:08 +0200)]
docs: sphinx: remove SPDX/copyright comments from HTML output
Use Jinja2 comments instead of HTML comments for the SPDX and copyright
lines. This prevents them from appearing in the HTML output, which was
never the intention; the HTML output has its own copyright line at the
bottom of the document.
docs: kernel_include.py: fix an issue when O= is used
As reported by Stephen, building docs with O= is now
broken. Fix it by ensuring that it will seek files under
Kernel source tree.
The original logic was defined to accept including files
under Documentation/output. The new logic doesn't need it
anymore for media, but it might still be useful to preserve
the previous behavior. So, I ended preserving it.
The rule as-is is wrong, as it was inverted. Besides that, after
retest building all repos with suggested LaTeX packages given
by sphinx-pre-install, I was unable to reproduce the issues
I saw with xindy in the past.
So, let's just drop. If anyone reports issues with xindy, we
may need to readd, but at the right way, e.g. {options}{pkgname}.
Bagas Sanjaya [Tue, 19 Aug 2025 06:12:52 +0000 (13:12 +0700)]
Documentation: sharedsubtree: Align text
The docs make heavy use of lists. As it is currently written, these
generate a lot of unnecessary hanging indents since these are not
semantically meant to be definition lists by accident.
Bagas Sanjaya [Tue, 19 Aug 2025 06:12:50 +0000 (13:12 +0700)]
Documentation: sharedsubtree: Use proper enumerator sequence for enumerated lists
Sphinx does not recognize mixed-letter sequences (e.g. 2a) as enumerator
for enumerated lists. As such, lists that use such sequences end up as
definition lists instead.
Use proper enumeration sequences for this purpose.
Fix minor spelling and grammatical issues in the ext4 atomic_writes
documentation.
Signed-off-by: Mallikarjun Thammanavar <mallikarjunst09@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Darrick J. Wong <djwong@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250819124604.8995-1-mallikarjunst09@gmail.com
Jonathan Corbet [Fri, 29 Aug 2025 21:58:48 +0000 (15:58 -0600)]
Merge branch 'mauro' into docs-mw
Another build series from Mauro:
The goal of this series is to drop one of the most ancient and ugliest
hack from the documentation build system. Before migrating to Sphinx,
the media subsystem already had a very comprehensive uAPI book, together
with a build time system to detect and point for any documentation gaps.
When migrating to Sphinx, we ported the logic to a Perl script
(parse-headers.pl) and Markus came up with a Sphinx extension
(kernel_include.py). We also added some files to control how parse-headers
produce results, and a Makefile.
At the initial Sphinx versions (1.4.1 if I recall correctly), when
a new symbol is added to videodev2.h, a new warning were
produced at documentatiion time, it the patchset didn't have
the corresponding documentation path.
While kernel-include is generic, the only user at the moment is the media
subsystem.
This series gets rid of the Python script, replacing it by a command
line script and a class. The parse header class can optionally be used by
kernel-include to produce an enriched code that will contain cross-references.
As the other conversions, it starts with a bug-compatible version of
parse-headers, but the subsequent patches add more functionalities and
fix bugs.
It should be noticed that modern of Sphinx disabled the cross-reference
warnings. So, at the next series, I'll be re-adding it in a controlled way
(e.g. just for the references from kernel-include that has an special
argument).
The script also supports now generating a "toc" output, which will be used
at the next series.
scripts: sphinx-build-wrapper: get rid of uapi/media Makefile
Now that kernel-include directive supports parsing data
structs directly, we can finally get rid of the horrible hack
we added to support parsing media uAPI symbols.
As a side effect, Documentation/output doesn't have anymore
media auto-generated .rst files on it.
docs: kernel_include.py: remove Include class inheritance
While the original code came from the Sphinx Include class,
such class is monolithic: it has only one function that does
everything, and 3 variables that are used:
So, basically those are the only members that remain from
the original class, but hey! Those are the same vars that every
other Sphinx directive extension has to define!
In summary, keeping inheritance here doesn't make much sense.
Worse than that, kernel-include doesn't support the current set
of options that the original Include class has, but it also
has its own set of options.
So, let's fill in the argument vars with what it does
support, dropping the rest.
docs: kernel_include.py: remove line numbers from parsed-literal
When parsed-literal directive is added to rawtext, while cross
references will be properly displayed, Sphinx will ignore
line numbers. So, it is not worth adding them.
docs: kernel_include.py: append line numbers to better report errors
It is best to point to the original line of code that generated
an error than to point to the beginning of a directive.
Add support for it. It should be noticed that this won't work
for literal or code blocks, as Sphinx will ignore it, pointing
to the beginning of the directive. Yet, when the output is known
to be in ReST format, like on TOC, this makes the error a lot
more easier to be handled.
docs: kernel_include.py: generate warnings for broken refs
In the past, Sphinx used to warn about broken references. That's
basically the rationale for adding media uAPI files: to get
warnings about missed symbols.
This is not true anymore. So, we need to explicitly check them
after doctree-resolved event.
While here, move setup() to the end, to make it closer to
what we do on other extensions.
kernel_include extension was originally designed to be used by the
media comprehensive uAPI documentation, where, instead of simpler
kernel-doc markups, the uAPI documentation is enriched with a larger
text, with images, complex tables, graphs, etc.
There, we wanted to include the much simpler yet documented .h
file.
This extension is needed to include files from other parts of the
Kernel tree outside Documentation, because the original Sphinx
include tag doesn't allow going outside of the directory passed
via sphinx-build command line.
Yet, the cross-references themselves to the full documentation
were using a perl script to create cross-references against the
comprehensive documentation.
As the perl script is now converted to Phython and there is a
Python class producing an include-compatible output with cross
references, add two optional arguments to kernel_include.py:
1. :generate-cross-refs:
If present, instead of reading the file, it calls ParseDataStructs()
class, which converts C data structures into cross-references to
be linked to ReST files containing a more comprehensive documentation;
Don't use it together with :start-line: and/or :end-line:, as
filtering input file line range is currently not supported.
2. :exception-file:
Used together with :generate-cross-refs:. Points to a file containing
rules to ignore C data structs or to use a different reference name,
optionally using a different reference type.
tools: docs: parse_data_structs.py: add methods to return output
When running it from command line, we want to write an output
file, but when used as a class, one may just want the output
content returned as a string.
Split write_output() on two methods to allow both usecases.
docs: parse-headers.py: simplify the rules for hashes
Normal :ref domain accept either hashes or underscores, but
c-domain ones don't. Fix it and remove unneeded places where
we opt to disable underscore transformation.
Ideally, we should have a rule about the default, or change
the way media docs have their references.
When printing --help, we'd like the name of the files
from __doc__ to match the displayed positional arguments at
both usage and argument description lines.
Use a custom formatter class to convert ``foo`` into ANSI SGR
code to bold the argument, if is TTY, and adjust the help
text to match the argument names.
Here on Plasma, that makes it display it colored, wich is
really cool. Yet, I opted for SGR, as the best is to follow
the terminal color schema for bold.
When the Kernel started to use Sphinx, we had to come up with
a solution to parse media headers. On that time, we didn't have
much experience with Sphinx extensions. So, we came up with our
own script-based solution that were basically implementing a
set of rules we used to have at the Makefile.
Convert it to Python, keeping it bug-compatible with the
original script.
projects / thirdparty / linux.git / log
