| Age | Commit message (Collapse) | Author | Files | Lines |
|---|
|
Now that get_feat is in Python, we don't need to use subprocess
to fork an executable file: we can use the feature classes
directly.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <c59d2542d7cc914fd5f8c84df966e63adc924cdc.1763492868.git.mchehab+huawei@kernel.org>
|
|
As we want to call Python code directly at the Sphinx extension,
convert get_feat.pl to Python.
The code was made to be (almost) bug-compatible with the Perl
version, with two exceptions:
1. Currently, Perl script outputs a wrong table if arch is set
to a non-existing value;
2. the ReST table output when --feat is used without --arch
has an invalid format, as the number of characters for the
table delimiters are wrong.
Those two bugs were fixed while testing the conversion.
Additionally, another caveat was solved:
the output when --feat is used without arch and the feature
doesn't exist doesn't contain an empty table anymore.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <03c26cee1ec567804735a33047e625ef5ab7bfa8.1763492868.git.mchehab+huawei@kernel.org>
|
|
Now that we have tools/lib/python for our Python modules, turn them into
proper packages with a single namespace so that everything can just use
tools/lib/python in sys.path. No functional change.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251110220430.726665-3-corbet@lwn.net>
|
|
"scripts/lib" was always a bit of an awkward place for Python modules. We
already have tools/lib; create a tools/lib/python, move the libraries
there, and update the users accordingly.
While at it, move the contents of tools/docs/lib. Rather than make another
directory, just put these documentation-oriented modules under "kdoc".
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251110220430.726665-2-corbet@lwn.net>
|
|
Move this tool out of scripts/ to join the other documentation tools; fix
up a couple of erroneous references in the process.
It's worth noting that this script will fail badly unless one has a
PYTHONPATH referencing scripts/lib/abi.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The scripts for managing the features docs are found in three different
directories; unite them all under tools/docs and update references as
needed.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Quoth Mauro:
This series should probably be called:
"Move the trick-or-treat build hacks accumulated over time
into a single place and document them."
as this reflects its main goal. As such:
- it places the jobserver logic on a library;
- it removes sphinx/parallel-wrapper.sh;
- the code now properly implements a jobserver-aware logic
to do the parallelism when called via GNU make, failing back to
"-j" when there's no jobserver;
- converts check-variable-fonts.sh to Python and uses it via
function call;
- drops an extra script to generate man pages, adding a makefile
target for it;
- ensures that return code is 0 when PDF successfully builds;
- about half of the script is comments and documentation.
I tried to do my best to document all tricks that are inside the
script. This way, the docs build steps is now documented.
It should be noticed that it is out of the scope of this series
to change the implementation. Surely the process can be improved,
but first let's consolidate and document everything on a single
place.
Such script was written in a way that it can be called either
directly or via a Makefile. Running outside Makefile is
interesting specially when debug is needed. The command line
interface replaces the need of having lots of env vars before
calling sphinx-build:
$ ./tools/docs/sphinx-build-wrapper --help
usage: sphinx-build-wrapper [-h]
[--sphinxdirs SPHINXDIRS [SPHINXDIRS ...]] [--conf CONF]
[--builddir BUILDDIR] [--theme THEME] [--css CSS] [--paper {,a4,letter}] [-v]
[-j JOBS] [-i] [-V [VENV]]
{cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs}
Kernel documentation builder
positional arguments:
{cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs}
Documentation target to build
options:
-h, --help show this help message and exit
--sphinxdirs SPHINXDIRS [SPHINXDIRS ...]
Specific directories to build
--conf CONF Sphinx configuration file
--builddir BUILDDIR Sphinx configuration file
--theme THEME Sphinx theme to use
--css CSS Custom CSS file for HTML/EPUB
--paper {,a4,letter} Paper size for LaTeX/PDF output
-v, --verbose place build in verbose mode
-j, --jobs JOBS Sets number of jobs to use with sphinx-build
-i, --interactive Change latex default to run in interactive mode
-V, --venv [VENV] If used, run Sphinx from a venv dir (default dir: sphinx_latest)
the only mandatory argument is the target, which is identical with
"make" targets.
The call inside Makefile doesn't use the last four arguments. They're
there to help identifying problems at the build:
-v makes the output verbose;
-j helps to test parallelism;
-i runs latexmk in interactive mode, allowing to debug PDF
build issues;
-V is useful when testing it with different venvs.
When used with GNU make (or some other make which implements jobserver),
a call like:
make -j <targets> htmldocs
will make the wrapper to automatically use POSIX jobserver to claim
the number of available job slots, calling sphinx-build with a
"-j" parameter reflecting it. ON such case, the default can be
overriden via SPHINXDIRS argument.
Visiable changes when compared with the old behavior:
When V=0, the only visible difference is that:
- pdfdocs target now returns 0 on success, 1 on failures.
This addresses an issue over the current process where we
it always return success even on failures;
- it will now print the name of PDF files that failed to build,
if any.
In verbose mode, sphinx-build-wrapper and sphinx-build command lines
are now displayed.
|
|
Improve the suggestions algorithm by using get_close_matches() if
no suggestions with the same name are found. As we're now building
a dict, when the name is identical, but on a different domain,
the search is O(1), making it a lot faster.
The get_close_matches is also fast, as there is just one loop,
instead of 3.
This can be useful to detect typos on references, with could
be the base of a futuere extension that will handle ref unmatches
for the entire build, allowing someone to find typos and fix them.
As difflib and get_close_matches are there since the early
Python 3.x days, we don't need to handle any extra dependencies
to use it.
We're keeping the default values for the search, e.g. n=3, cutoff=0.6.
With that, we now have things like:
$ make SPHINXDIRS="userspace-api/media" htmldocs
...
include/uapi/linux/videodev2.h:199: WARNING: Invalid xref: c:type:`v4l2_memory`. Possible alternatives:
c:type:`v4l2_meta_format` (from v4l/dev-meta)
c:type:`v4l2_rect` (from v4l/dev-overlay)
c:type:`v4l2_area` (from v4l/ext-ctrls-image-source) [ref.missing]
...
include/uapi/linux/videodev2.h:1985: WARNING: Invalid xref: c:type:`V4L.v4l2_queryctrl`. Possible alternatives:
std:label:`v4l2-queryctrl` (from v4l/vidioc-queryctrl)
std:label:`v4l2-query-ext-ctrl` (from v4l/vidioc-queryctrl)
At the first example, it was not a typo, but a symbol that doesn't
seem to be properly documented. The second example points to
v4l2-queryctrl, which is a close match for the symbol.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <7365feb74cbdd6b982c87baf5863360ab98cf727.1759329363.git.mchehab+huawei@kernel.org>
|
|
Add an extra parameter to parse_file to make it handle exceptions
internally, cleaning up the API.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <8575bbc94ff706aa7e7cc3a188399ca17a3169e6.1759329363.git.mchehab+huawei@kernel.org>
|
|
Specially when using c::namespace, it is not hard to break
a reference by forgetting to add a domain. Also, different
cases and using "-"/"_" the wrong way are typical cases that
people often gets wrong.
We might use a more complex logic here to also check for typos,
but let's keep it plain, simple.
This is enough to get thos exeptions from media controller:
.../include/uapi/linux/media.h:26: WARNING: Invalid xref: c:type:`media_device_info`. Possible alternatives:
c:type:`MC.media_device_info` (from mediactl/media-ioc-device-info)
.../include/uapi/linux/media.h:149: WARNING: Invalid xref: c:type:`media_entity_desc`. Possible alternatives:
c:type:`MC.media_entity_desc` (from mediactl/media-ioc-enum-entities)
.../include/uapi/linux/media.h:228: WARNING: Invalid xref: c:type:`media_link_desc`. Possible alternatives:
c:type:`MC.media_link_desc` (from mediactl/media-ioc-enum-links)
.../include/uapi/linux/media.h:235: WARNING: Invalid xref: c:type:`media_links_enum`. Possible alternatives:
c:type:`MC.media_links_enum` (from mediactl/media-ioc-enum-links)
.../include/uapi/linux/media.h:212: WARNING: Invalid xref: c:type:`media_pad_desc`. Possible alternatives:
c:type:`MC.media_pad_desc` (from mediactl/media-ioc-enum-links)
.../include/uapi/linux/media.h:298: WARNING: Invalid xref: c:type:`media_v2_entity`. Possible alternatives:
c:type:`MC.media_v2_entity` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:312: WARNING: Invalid xref: c:type:`media_v2_interface`. Possible alternatives:
c:type:`MC.media_v2_interface` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:307: WARNING: Invalid xref: c:type:`media_v2_intf_devnode`. Possible alternatives:
c:type:`MC.media_v2_intf_devnode` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:341: WARNING: Invalid xref: c:type:`media_v2_link`. Possible alternatives:
c:type:`MC.media_v2_link` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:333: WARNING: Invalid xref: c:type:`media_v2_pad`. Possible alternatives:
c:type:`MC.media_v2_pad` (from mediactl/media-ioc-g-topology)
.../include/uapi/linux/media.h:349: WARNING: Invalid xref: c:type:`media_v2_topology`. Possible alternatives:
c:type:`MC.media_v2_topology` (from mediactl/media-ioc-g-topology)
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <4c75d277e950e619ea00ba2dea336853a4aac976.1759329363.git.mchehab+huawei@kernel.org>
|
|
On TOC output, we need to embeed line numbers with ViewList.
Change the parse class to produce a line-number parsed result,
and adjust the output accordingly.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <74eed96e32f79eaaef7a99ffe7c3224fed369c27.1759329363.git.mchehab+huawei@kernel.org>
|
|
The code here was meant to handle 3 functions:
1. allow having a separate conf.py file, per subdir;
2. generate a list of latex documents.
3. set "subproject" tag if SPHINXDIRS points to a subdir.
We don't have (1) anymore, and (3) is now properly handled
entirely inside conf.py.
So, only (3) is still needed, and this is a single-line change
at conf.py.
So, drop it, moving the remaining code to conf.py.
While here, drop a duplicated $(RUSTDOC) command-line argument.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <ec998f9f268a401ca6aa36e3221d39c97efeccaa.1758361087.git.mchehab+huawei@kernel.org>
|
|
This is not used anymore, as it was a logic we had to support
pre Sphinx 3.x, as shown at:
afde706afde2 ("Make the docs build "work" with Sphinx 3.x")
Remove it.
Fixes: b26717852db7 ("docs: conf.py: drop backward support for old Sphinx versions")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <3b86d236c64af17924e4cfedbbfb8bc60059802f.1758381727.git.mchehab+huawei@kernel.org>
|
|
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <c8ce0c78d0761370e4c9091a9423d9df9a357187.1758196090.git.mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
As we're reorganizing the place where doc scripts are located,
move this one to tools/docs.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <5e2c40d3aebfd67b7ac7817f548bd1fa4ff661a8.1758196090.git.mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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>
|
|
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.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250830170808.3911151-1-vegard.nossum@oracle.com
|
|
The old behavior is not using anymore, so let's drop it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/00cdf3cbe2481aac875c543ded14b5eacfe071ec.1756732363.git.mchehab+huawei@kernel.org
|
|
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.
Reported-by: Stephen Rothwell <sfr@canb.auug.org.au>
Closes: https://lore.kernel.org/all/20250901142639.4de35a11@canb.auug.org.au/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/da91980ce42f31730dc982920167b2757b9d2769.1756732363.git.mchehab+huawei@kernel.org
|
|
Now that we have a replacement in place, drop the old version.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/d3a5397df44e53b02fa62f782d1e7ce6e08ed04f.1755872208.git.mchehab+huawei@kernel.org
|
|
As we're actually a fork of Sphinx Include, update its
docstring to contain the documentation for the actual
implemented parameters.
Let's use :param: for parameters, as defined at:
https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/f193160889a2dc296b4df2cc7ebc9934d717ccef.1755872208.git.mchehab+huawei@kernel.org
|
|
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:
- required_arguments
- optional_arguments
- option_spec
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a9f2eebf11c6b0c3a2e3bf42e71392cdfd2835d1.1755872208.git.mchehab+huawei@kernel.org
|
|
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/b484fe5fcbf6e5217f112f205fbf54f0bbc3dcca.1755872208.git.mchehab+huawei@kernel.org
|
|
While not required, better to have caller functions at the end.
As apply_range() is now called by xref_text(), move it to be
before the latter.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a6ce0fd7c03a01338753fd81ed0c4631f78311d6.1755872208.git.mchehab+huawei@kernel.org
|
|
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a0953af8b71e64aaf2e0ba4593ad39e19587d50a.1755872208.git.mchehab+huawei@kernel.org
|
|
When generate-cross-refs is used, instead of just implementing
the default of generating a literal block, we can also
generate a ReST file as a TOC.
The advantage is that, by being a ReST file, missing references
will point to the place inside the header file that has the
broken link.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/c0d32cd1ef94017e05984b0a38bd2516f7db21e2.1755872208.git.mchehab+huawei@kernel.org
|
|
Simplify run() even more by moving the code which handles
with code and literal blocks to their own functions.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/78d08dfa3f08adabc30bf93b8a1cde4e19b7bd41.1755872208.git.mchehab+huawei@kernel.org
|
|
Originally, parse-readers were generating an output where
the first two lines were setting a literal block.
The script now gets only the actual parsed data without that,
so it is now safe to allow start-line and end-line parameters
to be handled.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/5dff693860a6a3faade15c24abdc380f09db468d.1755872208.git.mchehab+huawei@kernel.org
|
|
Cleanup run() function by moving the range logic to a separate
function.
Here, I ended checking the current Sphinx implementation, as it
has some extra logic for the range check.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/12fa2204a9e7e309ae4b8694a37ebad9327ca634.1755872208.git.mchehab+huawei@kernel.org
|
|
The run function is too complex. merge run() and _run() into
a single function and move the read logic to separate functions.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/04776a94c85b6c931c198a149f08b299c9f571a3.1755872208.git.mchehab+huawei@kernel.org
|
|
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/73be9a198746421687e2eee916ccf8bf67980b7d.1755872208.git.mchehab+huawei@kernel.org
|
|
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/efc39c8e54a2056ae2fdb94d5006fcb19e227198.1755872208.git.mchehab+huawei@kernel.org
|
|
With the help of tools like black, pylint, autopep8 and flake,
improve the code style in preparation for further changes.
No functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/f64c3af47fdfd632bb5f8eb88e3c7d94b0b84a66.1755872208.git.mchehab+huawei@kernel.org
|
|
As suggested by Jon, we should start having a tools/docs
directory, instead of placing everything under scripts.
In the specific case of parse-headers.py, the previous
location is where we're placing Sphinx extensions, which is
not the right place for execs.
Move it to tools/docs/parse-headers.py.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0f5ac2d704cffe9834e589b39549d2393e1237ef.1755872208.git.mchehab+huawei@kernel.org
|
|
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0c011090272f7a1068545409222f970ddb1ed431.1755872208.git.mchehab+huawei@kernel.org
|
|
The kernel-doc markups inside headers may contain @var markups.
With the current rule, this would be converted into:
\* @:c:type:`DMX_BUFFER_FLAG_DISCONTINUITY_INDICATOR <dmx_buffer_flags>`\:
Fix it adding a non-printed space if needed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8d06bb713d6ec8de65179dd93defe479715409b6.1755872208.git.mchehab+huawei@kernel.org
|
|
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.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/2c1e61d1fb1b2a2838b443beee89c1528831997f.1755872208.git.mchehab+huawei@kernel.org
|
|
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.
While here, try to better document it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/ae5cfa8dff37e280cc9493fc95a51cd0cc0ba127.1755872208.git.mchehab+huawei@kernel.org
|
|
Change the --debug logic to help comparing its results with
a new python script.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/1064011717951eac257889a3032303c9d4440711.1755872208.git.mchehab+huawei@kernel.org
|
|
"whan" -> "when"
Signed-off-by: Iris Shi <0.0@owo.li>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8e5ddb7d-8faf-314f-b1b1-2d15d6900862@owo.li
|
|
As reported by Donald, this code:
rst_parser = RSTParser()
rst_parser.parse('\n'.join(result), document)
breaks line parsing. As an alternative, I tested a variant of it:
rst_parser.parse(result, document)
but still line number was not preserved. As Donald noted,
standard Parser classes don't have a direct mechanism to preserve
line numbers from ViewList().
So, instead, let's use a mechanism similar to what we do already at
kerneldoc.py: call the statemachine mechanism directly there.
I double-checked when states and statemachine were introduced:
both were back in 2002. I also tested doc build with docutils 0.16
and 0.21.2. It worked with both, so it seems to be stable enough
for our needs.
Reported-by: Donald Hunter <donald.hunter@gmail.com>
Closes: https://lore.kernel.org/linux-doc/m24ivk78ng.fsf@gmail.com/T/#u
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
As reported by Akira, older docutils versions are not compatible
with the way some Sphinx versions send tab_width. Add a code to
address it.
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/linux-doc/598b2cb7-2fd7-4388-96ba-2ddf0ab55d2a@gmail.com/
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
Instead of printing line numbers from the temp converted ReST
file, get them from the original source.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
Add a simple sphinx.Parser to handle yaml files and add the
the code to handle Netlink specs. All other yaml files are
ignored.
The code was written in a way that parsing yaml for different
subsystems and even for different parts of Netlink are easy.
All it takes to have a different parser is to add an
import line similar to:
from doc_generator import YnlDocGenerator
adding the corresponding parser somewhere at the extension:
netlink_parser = YnlDocGenerator()
And then add a logic inside parse() to handle different
doc outputs, depending on the file location, similar to:
if "/netlink/specs/" in fname:
msg = self.netlink_parser.parse_yaml_file(fname)
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>
|
|
The logic there which adds a dependency note to Sphinx cache
is not taking into account that the build dir may not be
the source dir. This causes a performance regression:
$ time make O=/tmp/foo SPHINXDIRS=admin-guide htmldocs
[OUTDATED]
Added: set()
Changed: {'abi-obsolete', 'abi-removed', 'abi-stable-files', 'abi-obsolete-files', 'abi-stable', 'abi', 'abi-removed-files', 'abi-testing-files', 'abi-testing', 'gpio/index', 'gpio/obsolete'}
Removed: set()
All docs count: 385
Found docs count: 385
real 0m11,324s
user 0m15,783s
sys 0m1,164s
To get the root cause of the problem (ABI files reported as changed),
I used this changeset:
diff --git a/Documentation/conf.py b/Documentation/conf.py
index e8766e689c1b..ab486623bd8b 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -571,3 +571,16 @@ def setup(app):
"""Patterns need to be updated at init time on older Sphinx versions"""
app.connect('config-inited', update_patterns)
+ app.connect('env-get-outdated', on_outdated)
+
+def on_outdated(app, env, added, changed, removed):
+ """Track cache outdated due to added/changed/removed files"""
+ print("\n[OUTDATED]")
+ print(f"Added: {added}")
+ print(f"Changed: {changed}")
+ print(f"Removed: {removed}")
+ print(f"All docs count: {len(env.all_docs)}")
+ print(f"Found docs count: {len(env.found_docs)}")
+
+ # Just return what we have
+ return added | changed | removed
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/linux-doc/c174f7c5-ec21-4eae-b1c3-f643cca90d9d@gmail.com/
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e25673d87357457bc54ee863e97ff8f75956580d.1752752211.git.mchehab+huawei@kernel.org
|
|
We no longer support Python 2 in the docs build chain at all, so we
certainly do not need to admonish folks to keep this file working with it.
Cc: Jani Nikula <jani.nikula@intel.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-7-corbet@lwn.net
|
|
Several Sphinx extensions and tools are missing SPDX tags.
Add them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/1a62226c5fe524eb87bdb80b33bc7ec880a68880.1750585188.git.mchehab+huawei@kernel.org
|
|
Those days, it is hard to install a virtual env that would
build docs with Sphinx 3.4.3, as even python 3.13 is not
compatible anymore with it.
/usr/bin/python3.9 -m venv sphinx_3.4.3
. sphinx_3.4.3/bin/activate
pip install -r Documentation/sphinx/min_requirements.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e38a44ee64ebfa37eac5f64e47af51c7ac051d5a.1750571906.git.mchehab+huawei@kernel.org
|
|
Docutils emits a deprecation warning when the set_class() element method is
used; that warning disappears into the ether, but it also causes a crash
with docutils 0.19.
Avoid the deprecated function and just append directly to the "classes"
attribute like the documentation says instead.
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Closes: https://lore.kernel.org/de7bae91-3200-481f-9db2-c0dc382c91dd@gmail.com/
Fixes: d6d1df92c25f ("docs: automarkup: Mark up undocumented entities too")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The automarkup code generates markup and a cross-reference link for
functions, structs, etc. for which it finds kerneldoc documentation.
Undocumented entities are left untouched; that creates an inconsistent
reading experience and has caused some writers to go to extra measures to
cause the markup to happen.
Mark up detected C entities regardless of whether they are documented.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Remove a few declarations that are no longer doing anything now that we
have left Sphinx 2 behind.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Get rid of logger.verbose() which is causing the logger to not
work.
Also, instead of having try/except everywhere, place them on a
common place.
While here, get rid of some bogus logs.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Acked-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <a2cc32d5d519ed343158a915c39e8dc536a8ddb7.1747817887.git.mchehab+huawei@kernel.org>
|
|
Instead of re-creating the objects every time, initialize it
just once.
This allows caching previously parsed objects.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <b00788f26e161512858a6e01a673c34743c954df.1745564565.git.mchehab+huawei@kernel.org>
|
|
Better integrate with the new kernel-doc tool by calling the
Python classes directly if KERNELDOC=scripts/kernel-doc.py.
This way, warnings won't be duplicated anymore, as files
will be parsed only once.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/1556a6c005d8e0fafa951f74725e984e1c7459bf.1744685912.git.mchehab+huawei@kernel.org
|
|
Several of the markup functions contain the same code, calling into
sphinx's pending_xref and resolve_xref functions to add and resolve a
cross-reference, with only a few of the parameters changed (domain,
reference type, markup content). Move this logic to its own function and
reuse it in the markup functions.
No functional change.
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250408-automarkup-resolve-xref-helper-v2-1-e0a9b8fc7fdd@collabora.com
|
|
Documentation/driver-api/infiniband.rst has a kernel-doc tag
with "\" characters at the end:
.. kernel-doc:: drivers/infiniband/ulp/iser/iscsi_iser.c
:functions: iscsi_iser_pdu_alloc iser_initialize_task_headers \
iscsi_iser_task_init iscsi_iser_mtask_xmit iscsi_iser_task_xmit \
iscsi_iser_cleanup_task iscsi_iser_check_protection \
iscsi_iser_conn_create iscsi_iser_conn_bind \
iscsi_iser_conn_start iscsi_iser_conn_stop \
iscsi_iser_session_destroy iscsi_iser_session_create \
iscsi_iser_set_param iscsi_iser_ep_connect iscsi_iser_ep_poll \
iscsi_iser_ep_disconnect
This is not handled well, as the "\" strings will be just stored inside
Sphinx options.
While the actual problem deserves being fixed, better to relax the
keneldoc.py extension to silently strip "\" from the end of strings,
as otherwise this may cause troubles when preparing arguments to
be executed by kernel-doc.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/4c652d6c57b20500c135b95294e554d9e9a97f42.1744106242.git.mchehab+huawei@kernel.org
|
|
It is useful to know what kernel-doc command was used during
document build time, as it allows one to check the output the same
way as Sphinx extension does.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a2f01590814b111e138f278e8a721024fdf2d445.1744106242.git.mchehab+huawei@kernel.org
|
|
Python 2 is already EOL for quite some time. Drop support for
it.
Also, the minimal Sphinx version is now 3.4.3. So, we can drop
support for Sphinx < 3.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/5cb57d158e42957d4bff06db38be141d849ac13b.1739254867.git.mchehab+huawei@kernel.org
|
|
Now that Documentation/ABI is processed by automarkup, let it
generate cross-references for RC sysfs devnodes.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/7c2f9a9970a15df8b5e3a6ecd21bcedcc8881ce1.1739254867.git.mchehab+huawei@kernel.org
|
|
As the current minimal supported Sphinx version is 3.4.3, drop
support for older versions.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org
|
|
None of the descriptions at the Sphinx extensions are using
non-ascii characters, so no need to place them under u"""
notation.
Also, according with:
https://docs.python.org/3/deprecations/pending-removal-in-3.16.html
the 'u' format code is scheduled to be removed in Python 3.16.
So, let's just use """.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Kees Cook <kees@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8a42f6be53464af4b866492a7e9ddf29c0429997.1739254187.git.mchehab+huawei@kernel.org
|
|
Sphinx logging system doesn't like warnings during module load,
as it understands that such logs are produced at the wrong time:
WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:27; /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70
WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:89; /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70
So, use a function to allocate/process ABI files and use it to
be called at kernel_abi.py, as automarkup also needs it to
produce the right cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/b0e79dc60d556e3b39fa6774d3b7bf734b73f352.1739182025.git.mchehab+huawei@kernel.org
|
|
Now that all ABI files are handled together, we can add a feature
at automarkup for it to generate cross-references for ABI symbols.
The cross-reference logic can produce references for all existing
files, except for README (as this is not parsed).
For symbols, they need to be an exact match of what it is
described at the docs, which is not always true due to wildcards.
If symbols at /sys /proc and /config are identical, a cross-reference
will be used.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/0b97a51b68b1c20127ad4a6a55658557fe0848d0.1739182025.git.mchehab+huawei@kernel.org
|
|
Right now, the logic parses ABI files on 4 steps, one for each
directory. While this is fine in principle, by doing that, not
all symbol cross-references will be created.
Change the logic to do the parsing only once in order to get
a global dictionary to be used when creating ABI cross-references.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/5205c53838b6ea25f4cdd4cc1e3d17c0141e75a6.1739182025.git.mchehab+huawei@kernel.org
|
|
Sphinx doesn't like to have lines split with str.split("\n").
Instead, it uses its own splitter, with handles line breaks the way
Spinx expects. Not using it cause issues at the output files.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/d4ad5b977799616544376210364d5cec686119ef.1739182025.git.mchehab+huawei@kernel.org
|
|
Instead of producing a big message with all ABI contents and then
parse as a whole, simplify the code by handling each ABI symbol
in separate. As an additional benefit, there's no need to place
file/line nubers inlined at the data and use a regex to convert
them.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/15be22955e3c6df49d7256c8fd24f62b397ad0ff.1739182025.git.mchehab+huawei@kernel.org
|
|
Instead of running get_abi.py script, import AbiParser class and
handle messages directly there using an interactor. This shold save some
memory, as there's no need to exec python inside the Sphinx python
extension.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8dbc244dcda97112c1b694e2512a5d600e62873b.1739182025.git.mchehab+huawei@kernel.org
|
|
Use the new script instead of the old one when generating ABI docs.
For now, execute it via exec. Future changes will better integrate it
by using the class defined there directly.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e7fcb121c0612c94f6f54f0d742cd3a26a46cd7d.1739182025.git.mchehab+huawei@kernel.org
|
|
Make pylint and flake8 happier with this module's coding style
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/02a9ec0fab61e4c94b9c2ff555bc0e9d93f59100.1739182025.git.mchehab+huawei@kernel.org
|
|
In the past, there was a need for a wrapper due to different
Sphinx versions support (before Sphinx 1.6). This is long gone,
and now it is just a wrapper. Get rig of it to simplify
the code.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/48bf16f199250d7048ca164d1b90773861915157.1739182025.git.mchehab+huawei@kernel.org
|
|
In zh_CN part of translations.pdf, there are several ASCII-art
diagrams whose vertical lines look sometimes jagged.
This is due to the interference between default settings of xeCJK
and fancyvrb (employed in sphinxVerbatim env), where extra space
is inserted between a latin char and a non-latin char when they
are next to each other (i.e., no explicit white space).
This issue can be suppressed by invoking \CJKsetecglue{} at the
beginning of every sphinxVerbatim enviornment.
\AtBeginEnvironment, provided by the etoolbox package, is useful in
this case.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240905050941.31439-1-akiyks@gmail.com
|
|
Running "make htmldocs" on a newly installed Sphinx 7.3.7 ends up in
a build error:
Sphinx parallel build error:
AttributeError: module 'docutils.nodes' has no attribute 'reprunicode'
docutils 0.21 has removed nodes.reprunicode, quote from release note [1]:
* Removed objects:
docutils.nodes.reprunicode, docutils.nodes.ensure_str()
Python 2 compatibility hacks
Sphinx 7.3.0 supports docutils 0.21 [2]:
kernel_include.py, whose origin is misc.py of docutils, uses reprunicode.
Upstream docutils removed the offending line from the corresponding file
(docutils/docutils/parsers/rst/directives/misc.py) in January 2022.
Quoting the changelog [3]:
Deprecate `nodes.reprunicode` and `nodes.ensure_str()`.
Drop uses of the deprecated constructs (not required with Python 3).
Do the same for kernel_include.py.
Tested against:
- Sphinx 2.4.5 (docutils 0.17.1)
- Sphinx 3.4.3 (docutils 0.17.1)
- Sphinx 5.3.0 (docutils 0.18.1)
- Sphinx 6.2.1 (docutils 0.19)
- Sphinx 7.2.6 (docutils 0.20.1)
- Sphinx 7.3.7 (docutils 0.21.2)
Link: http://www.docutils.org/RELEASE-NOTES.html#release-0-21-2024-04-09 [1]
Link: https://www.sphinx-doc.org/en/master/changes.html#release-7-3-0-released-apr-16-2024 [2]
Link: https://github.com/docutils/docutils/commit/c8471ce47a24 [3]
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/faf5fa45-2a9d-4573-9d2e-3930bdc1ed65@gmail.com
|
|
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 <corbet@lwn.net>
Link: https://lore.kernel.org/r/8734tqsrt7.fsf@meer.lwn.net/
Reported-by: Иван Иванович <relect@bk.ru>
Link: https://lore.kernel.org/linux-doc/1708585803.600323099@f111.i.mail.ru/
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240406020416.25096-1-akiyks@gmail.com
|
|
As discussed (see Links), there is some inertia to move to the recent
Sphinx versions for the doc build environment.
As first step, drop the version constraints and the related comments. As
sphinx depends on jinja2, jinja2 is pulled in automatically. So drop that.
Then, the sphinx-pre-install script will fail though with:
Can't get default sphinx version from ./Documentation/sphinx/requirements.txt at ./scripts/sphinx-pre-install line 305.
The script simply expects to parse a version constraint with Sphinx in the
requirements.txt. That version is used in the script for suggesting the
virtualenv directory name.
To suggest a virtualenv directory name, when there is no version given in
the requirements.txt, one could try to guess the version that would be
downloaded with 'pip install -r Documentation/sphinx/requirements.txt'.
However, there seems no simple way to get that version without actually
setting up the venv and running pip. So, instead, name the directory with
the fixed name 'sphinx_latest'.
Finally update the Sphinx build documentation to reflect this directory
name change.
Link: https://lore.kernel.org/linux-doc/874jf4m384.fsf@meer.lwn.net/
Link: https://lore.kernel.org/linux-doc/20240226093854.47830-1-lukas.bulwahn@gmail.com/
Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
Tested-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20240301141800.30218-1-lukas.bulwahn@gmail.com>
|
|
Now that Sphinx 2.4.4 or better is required, get rid of
\providecommand{}'s for compatibility with Sphinx 1.7.9.
While at it, reword the comment on \sphinxtableofcontentshook
for better description of why it needs to be emptied.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <ed1ec6f2-0050-46f6-807d-8679f26427e9@gmail.com>
|
|
Bring in the build fixes so that we can successfully build PDFs again.
|
|
If the directory passed to the '.. kernel-feat::' directive does not
exist or the get_feat.pl script does not find any files to extract
features from, Sphinx will report the following error:
Sphinx parallel build error:
UnboundLocalError: local variable 'fname' referenced before assignment
make[2]: *** [Documentation/Makefile:102: htmldocs] Error 2
This is due to how I changed the script in c48a7c44a1d0 ("docs:
kernel_feat.py: fix potential command injection"). Before that, the
filename passed along to self.nestedParse() in this case was weirdly
just the whole get_feat.pl invocation.
We can fix it by doing what kernel_abi.py does -- just pass
self.arguments[0] as 'fname'.
Fixes: c48a7c44a1d0 ("docs: kernel_feat.py: fix potential command injection")
Cc: Justin Forbes <jforbes@fedoraproject.org>
Cc: Salvatore Bonaccorso <carnil@debian.org>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: stable@vger.kernel.org
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Link: https://lore.kernel.org/r/20240205175133.774271-2-vegard.nossum@oracle.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
kerneldoc.py is mostly indented with 4 spaces (like PEP8 suggests);
replace the last remaining tabs for consistency.
No functional change.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240215134828.1277109-6-vegard.nossum@oracle.com
|
|
Akira Yokosawa reported [1] that the "translations" extension we added in
commit 7418ec5b151f ("docs: translations: add translations links when they
exist") broke the build on Sphinx versions v6.1.3 through 7.1.2 (possibly
others) with the following error:
Exception occurred:
File "/usr/lib/python3.12/site-packages/sphinx/util/nodes.py", line 624, in _copy_except__document
newnode = self.__class__(rawsource=self.rawsource, **self.attributes)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: LanguagesNode.__init__() missing 1 required positional argument: 'current_language'
The full traceback has been saved in /tmp/sphinx-err-7xmwytuu.log, if you want to report the issue to the developers.
Solve this problem by making 'current_language' a true element attribute
of the LanguagesNode element, which is probably the more correct way to do
it anyway.
Tested on Sphinx 2.x, 3.x, 6.x, and 7.x.
[1]: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/
Fixes: 7418ec5b151f ("docs: translations: add translations links when they exist")
Reported-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Closes: https://lore.kernel.org/all/54a56c2e-a27c-45a0-b712-02a7bc7d2673@gmail.com/
Tested-by: Akira Yokosawa <akiyks@gmail.com> # Sphinx 4.3.2, 5.3.0 and 6.2.1
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240215064109.1193556-1-vegard.nossum@oracle.com
|
|
If the directory passed to the '.. kernel-feat::' directive does not
exist or the get_feat.pl script does not find any files to extract
features from, Sphinx will report the following error:
Sphinx parallel build error:
UnboundLocalError: local variable 'fname' referenced before assignment
make[2]: *** [Documentation/Makefile:102: htmldocs] Error 2
This is due to how I changed the script in c48a7c44a1d0 ("docs:
kernel_feat.py: fix potential command injection"). Before that, the
filename passed along to self.nestedParse() in this case was weirdly
just the whole get_feat.pl invocation.
We can fix it by doing what kernel_abi.py does -- just pass
self.arguments[0] as 'fname'.
Fixes: c48a7c44a1d0 ("docs: kernel_feat.py: fix potential command injection")
Cc: Justin Forbes <jforbes@fedoraproject.org>
Cc: Salvatore Bonaccorso <carnil@debian.org>
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: stable@vger.kernel.org
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Link: https://lore.kernel.org/r/20240205175133.774271-2-vegard.nossum@oracle.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
When on the documentation home page, there won't be any ".current"
element since no entry from the TOC was selected yet. That results in a
javascript error. Fix that by only trying to set the scrollTop if we
have matches for current entries.
Signed-off-by: Gustavo Sousa <gustavo.sousa@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240123162157.61819-2-gustavo.sousa@intel.com
|
|
Pull documentation fixes from Jonathan Corbet:
"A handful of late-arriving documentation fixes"
* tag 'docs-6.8-2' of git://git.lwn.net/linux:
docs, kprobes: Add loongarch as supported architecture
docs, kprobes: Update email address of Masami Hiramatsu
docs: admin-guide: hw_random: update rng-tools website
Documentation/core-api: fix spelling mistake in workqueue
docs: kernel_feat.py: fix potential command injection
Documentation: constrain alabaster package to older versions
|
|
Pull documentation update from Jonathan Corbet:
"Another moderately busy cycle for documentation, including:
- The minimum Sphinx requirement has been raised to 2.4.4, following
a warning that was added in 6.2
- Some reworking of the Documentation/process front page to,
hopefully, make it more useful
- Various kernel-doc tweaks to, for example, make it deal properly
with __counted_by annotations
- We have also restored a warning for documentation of nonexistent
structure members that disappeared a while back. That had the
delightful consequence of adding some 600 warnings to the docs
build. A sustained effort by Randy, Vegard, and myself has
addressed almost all of those, bringing the documentation back into
sync with the code. The fixes are going through the appropriate
maintainer trees
- Various improvements to the HTML rendered docs, including automatic
links to Git revisions and a nice new pulldown to make translations
easy to access
- Speaking of translations, more of those for Spanish and Chinese
... plus the usual stream of documentation updates and typo fixes"
* tag 'docs-6.8' of git://git.lwn.net/linux: (57 commits)
MAINTAINERS: use tabs for indent of CONFIDENTIAL COMPUTING THREAT MODEL
A reworked process/index.rst
ring-buffer/Documentation: Add documentation on buffer_percent file
Translated the RISC-V architecture boot documentation.
Docs: remove mentions of fdformat from util-linux
Docs/zh_CN: Fix the meaning of DEBUG to pr_debug()
Documentation: move driver-api/dcdbas to userspace-api/
Documentation: move driver-api/isapnp to userspace-api/
Documentation/core-api : fix typo in workqueue
Documentation/trace: Fixed typos in the ftrace FLAGS section
kernel-doc: handle a void function without producing a warning
scripts/get_abi.pl: ignore some temp files
docs: kernel_abi.py: fix command injection
scripts/get_abi: fix source path leak
CREDITS, MAINTAINERS, docs/process/howto: Update man-pages' maintainer
docs: translations: add translations links when they exist
kernel-doc: Align quick help and the code
MAINTAINERS: add reviewer for Spanish translations
docs: ignore __counted_by attribute in structure definitions
scripts: kernel-doc: Clarify missing struct member description
..
|
|
The kernel-feat directive passes its argument straight to the shell.
This is unfortunate and unnecessary.
Let's always use paths relative to $srctree/Documentation/ and use
subprocess.check_call() instead of subprocess.Popen(shell=True).
This also makes the code shorter.
This is analogous to commit 3231dd586277 ("docs: kernel_abi.py: fix
command injection") where we did exactly the same thing for
kernel_abi.py, somehow I completely missed this one.
Link: https://fosstodon.org/@jani/111676532203641247
Reported-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20240110174758.3680506-1-vegard.nossum@oracle.com
|
|
The 'alabaster' theme dropped support for Sphinx < v3.4:
0.7.14 – 2024-01-08
* Dropped support for Python 3.8 and earlier.
* Dropped support for Sphinx 3.3 and earlier.
[...]
(Source: https://alabaster.readthedocs.io/en/latest/changelog.html)
This manifests as an error when running 'make htmldocs' in a virtualenv
constructed from Documentation/sphinx/requirements.txt:
Sphinx version error:
The alabaster extension used by this project needs at least Sphinx v3.4; it therefore cannot be built with this version.
Raising the Sphinx version is not really a good option at this point,
since 3.x through 6.x have horrible performance regressions (7.x still
does, but not quite as bad).
Instead, constrain the 'alabaster' package to versions that still support
Sphinx 2.4.4.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Link: https://lore.kernel.org/r/20240110104646.3647600-1-vegard.nossum@oracle.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The kernel-abi directive passes its argument straight to the shell.
This is unfortunate and unnecessary.
Let's always use paths relative to $srctree/Documentation/ and use
subprocess.check_call() instead of subprocess.Popen(shell=True).
This also makes the code shorter.
Link: https://fosstodon.org/@jani/111676532203641247
Reported-by: Jani Nikula <jani.nikula@intel.com>
Cc: stable@vger.kernel.org
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20231231235959.3342928-2-vegard.nossum@oracle.com
|
|
Commit f061c9f7d058 ("Documentation: Document each netlink family") added
a new Python script that is invoked during 'make htmldocs' and which reads
the netlink YAML spec files.
Using the virtualenv from scripts/sphinx-pre-install, we get this new
error wen running 'make htmldocs':
Traceback (most recent call last):
File "./tools/net/ynl/ynl-gen-rst.py", line 26, in <module>
import yaml
ModuleNotFoundError: No module named 'yaml'
make[2]: *** [Documentation/Makefile:112: Documentation/networking/netlink_spec/rt_link.rst] Error 1
make[1]: *** [Makefile:1708: htmldocs] Error 2
Fix this by adding 'pyyaml' to requirements.txt.
Note: This was somehow present in the original patch submission:
<https://lore.kernel.org/all/20231103135622.250314-1-leitao@debian.org/>
I'm not sure why the pyyaml requirement disappeared in the meantime.
Fixes: f061c9f7d058 ("Documentation: Document each netlink family")
Cc: Breno Leitao <leitao@debian.org>
Cc: Jakub Kicinski <kuba@kernel.org>
Cc: David S. Miller <davem@davemloft.net>
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Reviewed-by: Simon Horman <horms@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
|
|
Add a new Sphinx extension that knows about the translations of kernel
documentation and can insert links to the translations at the top of
the document.
It basically works like this:
1. Register a new node type, LanguagesNode.
2. Register a new transform, TranslationsTransform, that inserts a new
LanguageNode at the top of every document. The LanguageNode contains
"pending references" to translations of the document. The key here
is that these are pending (i.e. unresolved) references that may or
may not actually exist.
3. Register a 'doctree-resolved' event that iterates over all the
LanguageNode nodes. Any unresolved references are filtered out; the
list of resolved references is passed to the 'translations.html'
template and rendered as an HTML node (if HTML output is selected).
Testing: make htmldocs, make latexdocs with Sphinx v4.3.2 and Firefox.
v2:
- changed bar into a drop-down menu
- fixed language labels
- fixed hysteresis reported by Akira Yokosawa
Cc: Federico Vaga <federico.vaga@vaga.pv.it>
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Akira Yokosawa <akiyks@gmail.com>
Cc: Yanteng Si <siyanteng@loongson.cn>
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20231215123701.2712807-1-vegard.nossum@oracle.com
|
|
Commit 31abfdda6527 (docs: Deprecate use of Sphinx < 2.4.x) in 6.2 added a
warning that support for older versions of Sphinx would be going away.
There have been no complaints, so the time has come. Raise the minimum
Sphinx version to 2.4.4 and clean out some compatibility code that we no
longer need.
Reviewed-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/874jgs47fq.fsf@meer.lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
There aren't a ton of references to commits in the documentation, but
they do exist, and we can use automarkup to linkify them to make them
easier to follow.
Use something like this to find references to commits:
git grep -P 'commit.*[0-9a-f]{8,}' Documentation/
Also fix a few of these to standardize on the exact format that is
already used in changelogs.
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20231027115420.205279-1-vegard.nossum@oracle.com
|
|
Remove the repeated word "the" in comments.
Signed-off-by: Charles Han <hanchunchao@inspur.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20231018023046.30022-1-hanchunchao@inspur.com>
|
|
Sphinx 7.2+ is switching to using pathlib.Path
instead of str to represent paths. This fixes the
current deprecation warnings and eventual breakage.
This conversion will be a no-op when using older
Sphinx versions.
Signed-off-by: Oliver Faso <erer1243@gmail.com>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20230910040811.53046-1-erer1243@gmail.com
|
|
Python 3.6 introduced a DeprecationWarning for invalid escape sequences.
This is upgraded to a SyntaxWarning in Python 3.12, and will eventually
be a syntax error.
Fix these now to get ahead of it before it's an error.
Signed-off-by: Benjamin Gray <bgray@linux.ibm.com>
Message-ID: <20230912060801.95533-3-bgray@linux.ibm.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Fix typos in Documentation.
Signed-off-by: Bjorn Helgaas <bhelgaas@google.com>
Link: https://lore.kernel.org/r/20230814212822.193684-4-helgaas@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
This line was initially placed in {# jinja2 comments #}, but that led to an
"invalid token" complaint from spdxcheck.py. Rather than fix the script
for a usage we'll likely never see anywhere else, just switch to an HTML
comment, which spdxcheck.py thinks is fine.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Add a new sidebar template that creates a more RTD-like "fisheye" view of
the current place in the document hierarchy. It is far from ideal, but
some readers may find it better for navigating through the documentation as
a whole.
Add some CSS trickery as well to make the table of contents less intrusive
when viewing the pages on a small screen.
Reviewed-by: Akira Yokosawa <akiyks@gmail.com>
Reviewed-by: David Gow <davidgow@google.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Sphinx 6.0 removed the execfile_() function, which we use as part of the
configuration process. They *did* warn us... Just open-code the
functionality as is done in Sphinx itself.
Tested (using SPHINX_CONF, since this code is only executed with an
alternative config file) on various Sphinx versions from 2.5 through 6.0.
Reported-by: Martin Liška <mliska@suse.cz>
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
We don't default to the RTD theme anymore, so sphinx-pre-install need not
insist on installing it.
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
On distros whose texlive packaging is fine-grained, texlive-xecjk
can be installed/removed independently of other texlive packages.
Conditionally loading xeCJK depending only on the existence of the
"Noto Sans CJK SC" font might end up in xelatex error of
"xeCJK.sty not found!".
Improve the situation by testing existence of xeCJK.sty before
loading it.
This is useful on RHEL 9 and its clone distros where texlive-xecjk
doesn't work at the moment due to a missing dependency [1].
"make pdfdocs" for non-CJK contents should work after removing
texlive-xecjk.
Link: [1] https://bugzilla.redhat.com/show_bug.cgi?id=2086254
Fixes: 398f7abdcb7e ("docs: pdfdocs: Pull LaTeX preamble part out of conf.py")
Cc: stable@vger.kernel.org # v5.18+
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/c24c2a87-70b2-5342-bcc9-de467940466e@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The automarkup code tries to look up symbols once as a function, and once
as a macro. The Sphinx C domain code, though, totally ignores that
distinction and will return the same results either way. So just look
things up once and be done with it; the resulting output does not change,
but htmldocs build time drops by about 5%.
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220630163630.714673-3-corbet@lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The automarkup code tries to create a lot of cross-references that don't
exist. Cross-reference lookups are expensive, especially in later versions
of Sphinx, so there is value in avoiding unnecessary ones. Remember
attempts that failed and do not retry them.
This improves the htmldocs build time by 5-10% depending on the phase of
the moon and other factors.
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/20220630163630.714673-2-corbet@lwn.net
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
It turns out that networking.pdf has exceeded 100 chapters and
titles of chapters >= 100 collide with their counts in its table
of contents (TOC).
Increase relevant params by 0.6em in the preamble to avoid such
ugly collisions.
While at it, fix a typo in comment (subsection).
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/bdb60ba3-7813-47d0-74f9-7c31dd912d95@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
jinja2 release 3.1.0 (March 24, 2022) broke Sphinx<4.0.
This looks like the result of deprecating Python 3.6.
It has been tested against Sphinx 4.3.0 and later.
Setting an upper limit of <3.1 to junja2 can unbreak Sphinx<4.0
including Sphinx 2.4.4.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
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 <corbet@lwn.net>
|
|
In order to make it more standard and ReST compatible,
change the meta-tag used with --enable-lineno from:
#define LINENO
to
.. LINENO
In practice, no functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
In order to make it more standard and ReST compatible,
change the meta-tag used with --enable-lineno from:
#define LINENO
to
.. LINENO
In practice, no functional changes.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/125ffd31fbc77ad9eee4d6906e1830b8162fa6ca.1648290305.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The files included by kernel-include should be added as build
dependencies, in order for sphinx-build to rebuild the corresponding
docs if any changes at the included file happens.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/d30fc4fa422a13b7e1623d690945c46b58a55e79.1648290305.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Ensure that Sphinx-build will handle the files parsed by
get_abi.pl as dependencies. This way, if they are touched,
the ABI output will be regenerated.
Reported-by: Hans de Goede <hdegoede@redhat.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/10bc3d3bc74f514a539cd3b48b9d287d2b6f99e2.1648290305.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Ensure that the feature files will be regenerated if any
changes happen at the Documentation/features files that were
processed by gen_feat.pl.
Signed-off-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/5cdf7a8300019129dcc09d4c2557f75908754445.1648290305.git.mchehab@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
SVG -> PDF conversion is not required in "make htmldocs".
It is pointless to always warn of a missing converter.
Demote the log message in setupTools() to verbose.
For "make pdfdocs" (or "make latexdocs"), promote the dynamic
message of "include SVG raw" to a warn.
Expand the message and recommend installing Inkscape or
ImageMagick.
Fixes: 8ccd05697a9d ("docs: sphinx/kfigure.py: Use inkscape(1) for SVG -> PDF conversion")
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: linux-doc@vger.kernel.org
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/c80e1481-10d4-7151-fe59-e846259eb0d4@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Use past tense as the fonts can be installed after the fact.
Add suggestion to install "Noto Sans CJK" and "Noto Serif CJK"
font families. ("Noto Serif CJK" is optional.)
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/dfefa601-c58d-c86c-953f-5e4454db9409@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Expand comments in LaTeX code and mention some of important points
told in changelogs of conf.py changes.
Hopefully they can help future contributors in this area.
No code change involved.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/bce9261b-1950-3146-07b2-07bd2ec79158@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Quote from Jon's remark [1]:
I do notice that Documentation/conf.py is getting large and
unapproachable. At some future point, it might be nice to pull
all of the latex stuff out into a separate file where it won't
scare people who stumble into it by accident.
Pull LaTeX preamble settings added since commit 3b4c963243b1 ("docs:
conf.py: adjust the LaTeX document output") out into
sphinx/kerneldoc-preamble.sty.
It will be copied to the build directory by the added
"latex_additional_files" setting in conf.py.
As a bonus, LaTeX/TeX code can be maintained without escaping backslashes.
To compensate the loss of change history in sphinx/kerneldoc-preamble.sty,
here is a list of changes made in conf.py:
- f7ebe6b76940 ("docs: Activate exCJK only in CJK chapters")
- 0afd4df0d16a ("docs: pdfdocs: Prevent column squeezing by tabulary")
- 659653c9e546 ("docs: pdfdocs: Refactor config for CJK document")
- e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings")
- 7eb368cc319b ("docs: pdfdocs: Choose Serif font as CJK mainfont if possible")
- 35382965bdd2 ("docs: pdfdocs: Preserve inter-phrase space in Korean translations")
- 77abc2c230b1 ("docs: pdfdocs: One-half spacing for CJK translations")
- 788d28a25799 ("docs: pdfdocs: Permit AutoFakeSlant for CJK fonts")
- 29ac9822358f ("docs: pdfdocs: Teach xeCJK about character classes of quotation marks")
- 7c5c18bdb656 ("docs: pdfdocs: Fix typo in CJK-language specific font settings")
- aa872e0647dc ("docs: pdfdocs: Adjust \headheight for fancyhdr")
- 8716ef413aa5 ("docs: pdfdocs: Tweak width params of TOC")
- 66939df53948 ("docs: pdfdocs: Switch default CJK font to KR variants")
- 7b686a2ea1e4 ("docs: pdfdocs: Enable CJKspace in TOC for Korean titles")
- 5d9158e3c762 ("docs/translations: Skip CJK contents if suitable fonts not found")
- b774cc46313b ("docs: pdfdocs: Move CJK monospace font setting to main conf.py")
[1]: https://lore.kernel.org/all/87zgmr66cn.fsf@meer.lwn.net/
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Link: https://lore.kernel.org/r/aaa9dca1-27c0-c414-77f3-c5587db0cc5b@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Depending on its version, distro config, and system-setup type,
inkscape(1) emits various warning messages which are harmless in
command-line uses.
List of such warning messages (incomplete, long ones wrapped):
- Gtk-Message: hh:mm:ss.nnn: Failed to load module "canberra-gtk-module"
- Unable to init server: Could not connect: Connection refused
- Failed to get connection
- ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_new_for_name:
assertion 'connection != NULL' failed
- ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_proxy_call:
assertion 'DBUS_IS_G_PROXY (proxy)' failed
- ** (inkscape:xxx): CRITICAL **: hh:mm:ss.nnn: dbus_g_connection_register_g_object:
assertion 'connection != NULL' failed
- ** (inkscape:xxx): WARNING **: hh:mm:ss.nnn:
Fonts dir '/usr/share/inkscape/fonts' does not exist and will be ignored.
To avoid unnecessary anxiety, capture the message and output it via
kernellog.verbose or kernellog.warn depending on the exit code.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/e26a7b53-9155-8394-4a31-6006379b65a5@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Using convert(1) of ImageMagick for SVG -> PDF conversion results in
PDFs containing raster (bitmap) images which sometimes look blurry.
Ideally speaking, SVG to PDF conversion should retain vector graphics
in SVG.
rsvg-convert(1) can do such conversions with regard to SVG files
generated by dot(1).
Unfortunately, rsvg-convert(1) does not cover some of SVG features
specific to Inkscape.
inkscape(1) of Inkscape naturally covers such SVG features.
So add a route in svg2pdf() so that inkscape(1) is used when it is
available.
Note:
After this change, if you have Inkscape installed, ImageMagick nor
librsvg are not required.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/3eea2a8d-c52d-ee07-cf7b-83784c6f6e4b@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
To prevent any regression on existing build systems, limit the
fallback of converting DOT -> raster PDF only when both of the
following conditions are met.
o dot(1) doesn't support -Tpdf
o rsvg-convert(1) is not found
While we are here, add kernellog.verbose messages related to
rsvg-convert, 'dot -Tpdf', and 'dot -Tsvg' commands.
Suggested-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/e76f61e1-7366-ba00-b119-8ea6a2499861@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
On openSUSE, dot(1) command does not support direct PDF output.
On other distros, generated PDF images have unnecessarily wide margins,
especially for small graphs.
By using dot(1) for DOT -> SVG, then rsvg-convert(1) for SVG -> PDF,
more optimal PDF images can be obtained, with the bonus of improved
portability across various distros.
Add rules in kfigure.py so that the above mentioned route is taken
when rsvg-convert(1) is available.
Note that rsvg-convert(1) is recommended by sphinx_pre_install.
So it is most likely that existing systems for building pdfdocs have
rsvg-convert(1) installed.
Note:
SVG features supported by rsvg-convert(1) vary depending on its
version and distro config.
For example, the one found on Ubuntu Bionic (version 2.40.20) does
poor job in rendering some of SVG files drawn by Inkscape.
SVG files generated by dot(1) are converted nicely even with such
old versions of rsvg-convert.
So this change does not affect the quality of such figures in any
way.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/15b56dd3-081a-2469-c3a4-dfc1ca4c6c2d@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Since commit d18b01789ae5 ("docs: Add automatic cross-reference for
documentation pages"), references that were already explicitly defined
with "ref:" and referred to other pages with a path have been doubled.
This is reported as the following error by Firefox:
Start tag "a" seen but an element of the same type was already open.
End tag "a" violates nesting rules.
As well as the invalid HTML, this also obscures the URI fragment links
to subsections because the second link overrides the first. For example
on the page admin-guide/hw-vuln/mds.html the last link should be to the
"Default Mitigations" subsection using a # URI fragment:
admin-guide/hw-vuln/l1tf.html#default-mitigations
But it is obsured by a second link to the whole page:
admin-guide/hw-vuln/l1tf.html
The full HTML with the double <a> tags looks like this:
<a class="reference internal" href="l1tf.html#default-mitigations">
<span class="std std-ref">
<a class="reference internal" href="l1tf.html">
<span class="doc">L1TF - L1 Terminal Fault</span>
</a>
</span>
</a>
After this commit, there is only a single link:
<a class="reference internal" href="l1tf.html#default-mitigations">
<span class="std std-ref">Documentation/admin-guide/hw-vuln//l1tf.rst</span>
</a>
Now that the second link is removed, the browser correctly jumps to the
default-mitigations subsection when clicking the link.
The fix is to check that nodes in the document to be modified are not
already references. A reference is counted as any text that is a
descendant of a reference type node. Only plain text should be converted
to new references, otherwise the doubling occurs.
Testing
=======
* Test that the build stdout is the same (ignoring ordering), and that
no new warnings are printed.
* Diff all .html files and check that the only modifications occur
to the bad double links.
* The auto linking of bare references to pages without "ref:" is still
working.
Fixes: d18b01789ae5 ("docs: Add automatic cross-reference for documentation pages")
Reviewed-by: Nícolas F. R. A. Prado <n@nfraprado.net>
Signed-off-by: James Clark <james.clark@arm.com>
Link: https://lore.kernel.org/r/20220105143640.330602-2-james.clark@arm.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Use "its" for possessive form instead of the contraction "it's".
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20211222062354.23224-1-rdunlap@infradead.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
sphinx_rtd_theme 0.5.2 has "docutils<0.17" in its requirements.
docutils 0.17 released this April caused regression in
sphinx_rtd_theme 0.5.1 [1].
By removing docutils and moving sphinx_rtd_theme before Sphinx in
requirements.txt, the requirement of "docutils<0.17" can be met
naturally.
[1]: https://github.com/readthedocs/sphinx_rtd_theme/issues/1112
Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Acked-by: Mauro Carvalho Chehab <mchehab@kernel.org>
Link: https://lore.kernel.org/r/75f14c88-6091-1072-41cb-16b886aee5a0@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
s/automaticly/automatically/
s/buidler/builder/
..and a sentence construction fix.
Signed-off-by: Bhaskar Chowdhury <unixbhaskar@gmail.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Link: https://lore.kernel.org/r/20210301201052.11067-1-unixbhaskar@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <corbet@lwn.net>
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
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 <corbet@lwn.net>
|
|
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 <corbet@lwn.net>
|
|
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 <corbet@lwn.net>
|
|
git://git.kernel.org/pub/scm/linux/kernel/git/masahiroy/linux-kbuild
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
|
|
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.x
The kfigure.py uses six library explicitly, adding six to
requirements.txt seems reasonable
Signed-off-by: JaeSang Yoo <jsyoo5b@gmail.com>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20201208014628.GA1361@JSYoo5B-Base.localdomain
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <me@kloenk.de>
Signed-off-by: Masahiro Yamada <masahiroy@kernel.org>
|
|
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 <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/bb2e51e5aa883e2583a4a6280f1c1b391bd8ef4c.1606748711.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20201117021107.214704-1-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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
|
|
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 <dafna.hirschfeld@collabora.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/59ccbaa75ff05f23e701dd9a0bbe118e9343a553.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
|
|
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 <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/4659b60795739308e34d2d00c57ee0742a9cd2ab.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
|
|
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 <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/d6155ab16fb7631f2fa8e7a770eae72f24bf7cc5.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
|
|
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 <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/f2b25caef5db7738629773a03463908d3b39b83a.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
|
|
The parser breaks with UTF-8 characters with Sphinx 1.4.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9e7c8e3b0efaa1ae0536da6493ab438bd3f9fe58.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
|
|
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 <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/48abf1a410237e63f85354a8cd7027fdf25657bf.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
|
|
An extension may want to just inform about something. So, add
support for it.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/0ddebd8677605d789d53433c8a5344c68da82a73.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
|
|
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 foo
into cross-references, let's get rid of that, solving
several warnings when building docs with Sphinx 3.x.
Reviewed-by: André Almeida <andrealmeid@collabora.com> # blk-mq.rst
Reviewed-by: Takashi Iwai <tiwai@suse.de> # sound
Reviewed-by: Mike Rapoport <rppt@linux.ibm.com>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
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 <nfraprado@protonmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
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 <nfraprado@protonmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
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 <nfraprado@protonmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
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 <nfraprado@protonmail.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
Currently, there's no way to exclude identifiers from
a kernel-doc markup. Add support for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
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 <mchehab+huawei@kernel.org>
|
|
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 <mchehab+huawei@kernel.org>
|
|
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 <mchehab+huawei@kernel.org>
|
|
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 <patch> argument.
Thanks-to: Joe Perches <joe@perches.com>
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
|
|
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 <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20200911133339.327721-3-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20200911133339.327721-2-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <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 <nfraprado@protonmail.com>
Link: https://lore.kernel.org/r/20200903005747.3900333-2-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200620075402.22347-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <grandmaster@al2klimov.de>
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
There are some docs that have nested tables. While this was
always part of the spec, only Sphinx version 2.4.x can
translate it to LaTeX.
In other words, if someone is using a Sphinx version < 2.4,
the LaTeX and PDF output won't work for some of the docs.
So, it seems that it is time to raise the bar again
for the recommented version.
The Sphinx check script is already smart enough to keep
working, with older versions, warning the users that
an upgrade is recommended (and explaining how):
Sphinx version 1.7.9
Warning: It is recommended at least Sphinx version 2.4.4.
Detected OS: Fedora release 31 (Thirty One).
To upgrade Sphinx, use:
/usr/bin/virtualenv sphinx_2.4.4
. sphinx_2.4.4/bin/activate
pip install -r ./Documentation/sphinx/requirements.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/498f701c618f7d0cf5f0a37e5889ee926f7c8bf4.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <rafael@kernel.org>
Fixes: 51e46c7a4007 ("docs, parallelism: Rearrange how jobserver reservations are made")
Cc: stable@vger.kernel.org # v5.5 only
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
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 <corbet@lwn.net>
|
|
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>
|
|
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 <changbin.du@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
In order to have the MAINTAINERS file visible in the rendered ReST
output, this makes some small changes to the existing MAINTAINERS file
to allow for better machine processing, and adds a new Sphinx directive
"maintainers-include" to perform the rendering.
Features include:
- Per-subsystem reference links: subsystem maintainer entries can be
trivially linked to both internally and external. For example:
https://www.kernel.org/doc/html/latest/process/maintainers.html#secure-computing
- Internally referenced .rst files are linked so they can be followed
when browsing the resulting rendering. This allows, for example, the
future addition of maintainer profiles to be automatically linked.
- Field name expansion: instead of the short fields (e.g. "M", "F",
"K"), use the indicated inline "full names" for the fields (which are
marked with "*"s in MAINTAINERS) so that a rendered subsystem entry
is more human readable. Email lists are additionally comma-separated.
For example:
SECURE COMPUTING
Mail: Kees Cook <keescook@chromium.org>
Reviewer: Andy Lutomirski <luto@amacapital.net>,
Will Drewry <wad@chromium.org>
SCM: git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git seccomp
Status: Supported
Files: kernel/seccomp.c include/uapi/linux/seccomp.h
include/linux/seccomp.h tools/testing/selftests/seccomp/*
tools/testing/selftests/kselftest_harness.h
userspace-api/seccomp_filter
Content regex: \bsecure_computing \bTIF_SECCOMP\b
Signed-off-by: Kees Cook <keescook@chromium.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
With the introduction of Documentation/sphinx/automarkup.py, socket() is
parsed as a reference to the in-kernel definition of socket. Sphinx then
decides that struct socket is a good match, which is usually not
intended, when the syscall is meant instead. This was observed in
Documentation/networking/af_xdp.rst.
Prevent socket() from being misinterpreted by adding it to the Skipfuncs
list in automarkup.py.
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
In Python, like in C, when a comma is omitted in a list of strings, the
two strings around the missing comma are concatenated.
Cc: stable@vger.kernel.org # v5.2 only
Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net>
Reviewed-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The logic with seeks for a subdir passed via SPHINXDIRS is
incomplete: if one uses something like:
make SPHINXDIRS=arm pdfdocs
It will find both "arm" and "arm64" directories. Worse than
that, it will convert "arm64/index" to "4/index".
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
|
|
Right now, for every directory that we need to have LaTeX output,
a conf.py file is required.
That causes an extra overhead and it is actually a hack, as
the latex_documents line there are usually a copy of the ones
that are there already at the main conf.py.
So, instead, re-use the global latex_documents var, just
adjusting the path to be relative ones.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
|
|
When using the automarkup extension with:
make pdfdocs
without passing an specific book, the code will raise an exception:
File "/devel/v4l/docs/Documentation/sphinx/automarkup.py", line 86, in auto_markup
node.parent.replace(node, markup_funcs(name, app, node))
File "/devel/v4l/docs/Documentation/sphinx/automarkup.py", line 59, in markup_funcs
'function', target, pxref, lit_text)
File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/domains/c.py", line 308, in resolve_xref
contnode, target)
File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/util/nodes.py", line 450, in make_refnode
'#' + targetid)
File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/builders/latex/__init__.py", line 159, in get_relative_uri
return self.get_target_uri(to, typ)
File "/devel/v4l/docs/sphinx_2.0/lib/python3.7/site-packages/sphinx/builders/latex/__init__.py", line 152, in get_target_uri
raise NoUri
sphinx.environment.NoUri
This happens because not all references will belong to a single
PDF/LaTeX document.
Better to just ignore those than breaking Sphinx build.
Fixes: d74b0d31ddde ("Docs: An initial automarkup extension for sphinx")
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
[jc: Narrowed the "except" and tweaked the comment]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Rather than fill our text files with :c:func:`function()` syntax, just do
the markup via a hook into the sphinx build process.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
As discussed at the linux-doc ML, while we'll still support
version 1.3, it is time to recommend a more modern version.
So, let's switch the minimal requirements to Sphinx 1.7.9,
as it has the "-jauto" flag, with makes a lot faster when
building documentation.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
There's a new warning about a deprecation function. Add a
logic at cdomain.py to avoid that.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
AutoReporter is going away; recent versions of sphinx emit a warning like:
Documentation/sphinx/kerneldoc.py:125:
RemovedInSphinx20Warning: AutodocReporter is now deprecated.
Use sphinx.util.docutils.switch_source_input() instead.
Make the switch. But switch_source_input() only showed up in 1.7, so we
have to do ugly version checks to keep things working in older versions.
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Recent versions of sphinx will emit messages like:
Documentation/sphinx/kerneldoc.py:103:
RemovedInSphinx20Warning: app.warning() is now deprecated.
Use sphinx.util.logging instead.
Switch to sphinx.util.logging to make this unsightly message go away.
Alas, that interface was only added in version 1.6, so we have to add a
version check to keep things working with older sphinxes.
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
When kernel-doc:: specified in .rst document without explicit directives,
it outputs both comment and DOC: sections. If a DOC: section was explicitly
included in the same document it will be duplicated. For example, the
output generated for Documentation/core-api/idr.rst [1] has "IDA
description" in the "IDA usage" section and in the middle of the API
reference.
This patch enables using "functions" directive without parameters to output
all the documentation excluding DOC: sections.
[1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html
Signed-off-by: Mike Rapoport <rppt@linux.vnet.ibm.com>
Acked-by: Matthew Wilcox <willy@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The description speaks about the option ``--man`` but it
does not exist. Instead, there is the option ``--usage``
$ ./Documentation/sphinx/parse-headers.pl --man
Unknown option: man
Usage:
parse_headers.pl [<options>] <C_FILE> <OUT_FILE> [<EXCEPTIONS_FILE>]
Where <options> can be: --debug, --help or --man.
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The old HOWTO was removed a long time ago. The flat table
version is not metioned elsewhere, so just get rid of the
text.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Jonathan Corbet <corbet@lwn.net>
|
|
From now on, I'll start using my @kernel.org as my development e-mail.
As such, let's remove the entries that point to the old
mchehab@s-opensource.com at MAINTAINERS file.
For the files written with a copyright with mchehab@s-opensource,
let's keep Samsung on their names, using mchehab+samsung@kernel.org,
in order to keep pointing to my employer, with sponsors the work.
For the files written before I join Samsung (on July, 4 2013),
let's just use mchehab@kernel.org.
For bug reports, we can simply point to just kernel.org, as
this will reach my mchehab+samsung inbox anyway.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Brian Warner <brian.warner@samsung.com>
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
|
|
Sphinx 1.7 removed sphinx.util.compat.Directive so people
who have upgraded cannot build the documentation. Switch to
docutils.parsers.rst.Directive which has been available since
docutils 0.5 released in 2009.
Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694
Co-developed-by: Takashi Iwai <tiwai@suse.de>
Acked-by: Jani Nikula <jani.nikula@intel.com>
Cc: stable@vger.kernel.org
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
This patch fixes some spelling typos found in kfigure.py
Signed-off-by: Masanari Iida <standby24x7@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
On python3, Popen() universal_newlines=True converts the subprocess
stdout to unicode text using a codec based on user preferences. Given
LANG indicating ascii and utf-8 stdout from the subprocess, you'd get:
WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno
../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't
decode byte 0xe2 in position 6368: ordinal not in range(128)
Fix this by dropping universal_newlines=True and replacing the implicit
LANG specific decode with an explicit utf-8 decode. This also gets rid
of the annoying conditional code for python 2 vs. 3.
Fixes: ba3501859354 ("Documentation/sphinx: fix kernel-doc extension on python3")
Reference: http://mid.mail-archive.com/54c23e8e-89c0-5cea-0dcc-e938952c5642@infradead.org
Reported-and-tested-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Instead of using 3 commands to install a virtualenv, use
a single one, reading the requirements from this file:
Documentation/sphinx/requirements.txt
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
There were a few bits and pieces left over from the now-disused DocBook
toolchain; git rid of them.
Reported-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
As everything was converted to ReST, we don't need this
script anymore.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
Currently, the script just assumes to be called at
Documentation/sphinx/. Change it to work on any directory,
and make it abort if something gets wrong.
Also, be sure that both parameters are specified.
That should avoid troubles like this:
$ Documentation/sphinx/tmplcvt Documentation/DocBook/writing_usb_driver.tmpl
sed: couldn't open file convert_template.sed: No such file or directory
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Using the development version of sphinx caused the parsing of the
version to fail.
Signed-off-by: Rémy Léone <remy.leone@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
This patch brings scalable figure, image handling and a concept to
embed *render* markups:
* DOT (http://www.graphviz.org)
* SVG
For image handling use the 'image' replacement::
.. kernel-image:: svg_image.svg
:alt: simple SVG image
For figure handling use the 'figure' replacement::
.. kernel-figure:: svg_image.svg
:alt: simple SVG image
SVG image example
Embed *render* markups (or languages) like Graphviz's **DOT** is
provided by the *render* directive.::
.. kernel-render:: DOT
:alt: foobar digraph
:caption: Embedded **DOT** (Graphviz) code.
digraph foo {
"bar" -> "baz";
}
The *render* directive is a concept to integrate *render* markups and
languages, yet supported markups:
* DOT: render embedded Graphviz's **DOT**
* SVG: render embedded Scalable Vector Graphics (**SVG**)
Cc: Jani Nikula <jani.nikula@linux.intel.com>
Cc: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Tested-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com> (v2 - v5)
Signed-off-by: Markus Heiser <markus.heiser@darmarit.de> (v1, v6)
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
In docutils 0.13, the return type of get_column_widths method of the
Table directive has changed [1], which breaks our flat-table directive
and leads to a TypeError when trying to build the docs [2].
This patch adds support for the new return type, while keeping support
for older docutils versions too.
[1] https://sourceforge.net/p/docutils/patches/120/
[2] https://sourceforge.net/p/docutils/bugs/303/
Signed-off-by: Dmitry Shachnev <mitya57@debian.org>
Cc: <stable@vger.kernel.org> # 4.8.x-
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Keeping both rst and in-file documentation in sync can be harsh.
So, simplify the script's internal documntation to a bare minimum,
and add a mention to the ReST file with its full documentation.
This way, a quick help is still available at the command line,
while the complete one is maintained at the ReST format.
As we won't be using pad2rst anymore, do a cleanup at the ReST
file.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Provide a man page for parse-headers.pl, describing
how to use it.
The documentation on ReST format was generated via pod2rst:
http://search.cpan.org/~dowens/Pod-POM-View-Restructured-0.02/bin/pod2rst
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Python module names should not have hyphens per [PEP 8]. Drop the hyphen
from kernel-doc.py. The extension directive remains unchanged.
[PEP 8] https://www.python.org/dev/peps/pep-0008/#package-and-module-names
Reported-by: Markus Heiser <markus.heiser@darmarit.de>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Merge back from docs-next in order to get the cdomain extension.
With such extension, the number of warnings when building docs
in nitpick mode reduced from 22 to 2 warnings.
* docs-next/docs-next:
docs/driver-model: fix typo
DMA-API-HOWTO: <asm/generic/scatterlist.h> is no more
doc-rst:c-domain: function-like macros arguments
doc-rst:c-domain: fix sphinx version incompatibility
Documentation/filesystems: Fixed typo
docs: Don't format internal MPT docs
docs: split up serial-interfaces.rst
docs: Pull the HSI documentation together
docs: Special-case function-pointer parameters in kernel-doc
docs: make kernel-doc handle varargs properly
x86: fix memory ranges in mm documentation
documentation/scsi: Remove nodisconnect parameter
doc: ioctl: Add some clarifications to botching-up-ioctls
docs: split up the driver book
Docs: sphinxify device-drivers.tmpl
|
|
Handle signatures of function-like macros well. Don't try to deduce
arguments types of function-like macros.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The self.indexnode's tuple has changed in sphinx version 1.4, from a
former 4 element tuple to a 5 element tuple.
https://github.com/sphinx-doc/sphinx/commit/e6a5a3a92e938fcd75866b4227db9e0524d58f7c
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Instead of keep using the normal reference, move to the C
domain ones. Using C domains everywhere will allow
cross-references between kAPI and uAPI docs.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
Add a parser for the --debug option, in order to allow
seeing what the parser is doing.
Acked-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
The setup() function of a Sphinx-extension can return a dictionary. This
is treated by Sphinx as metadata of the extension [1].
With metadata "parallel_read_safe = True" a extension is marked as
save for "parallel reading of source". This is needed if you want
build in parallel with N processes. E.g.:
make SPHINXOPTS=-j4 htmldocs
will no longer log warnings like:
WARNING: the foobar extension does not declare if it is safe for
parallel reading, assuming it isn't - please ask the extension author
to check and make it explicit.
Add metadata to extensions:
* kernel-doc
* flat-table
* kernel-include
[1] http://www.sphinx-doc.org/en/stable/extdev/#extension-metadata
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Moved the *duplicate C object description* warnings for function
declarations in the nitpicky mode. In nitpick mode, you can suppress
those warnings (e.g. ioctl) with::
nitpicky = True
nitpick_ignore = [
("c:func", "ioctl"),
]
See Sphinx documentation for the config values for ``nitpick`` and
``nitpick_ignore`` [1].
With this change all the ".. cpp:function:: int ioctl(..)" descriptions
(found in the media book) can be migrated to ".. c:function:: int
ioctl(..)", without getting any warnings. E.g.::
.. cpp:function:: int ioctl( int fd, int request, struct cec_event *argp )
.. c:function:: int ioctl( int fd, int request, struct cec_event *argp )
The main effect, is that we get those *CPP-types* back into Sphinx's C-
namespace and we need no longer to distinguish between c/cpp references,
when we refer a function like the ioctl.
[1] http://www.sphinx-doc.org/en/stable/config.html?highlight=nitpick#confval-nitpicky
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Add option 'name' to the "c:function:" directive. With option 'name'
the ref-name of a function can be modified. E.g.::
.. c:function:: int ioctl( int fd, int request )
:name: VIDIOC_LOG_STATUS
The func-name (e.g. ioctl) remains in the output but the ref-name
changed from ``ioctl`` to ``VIDIOC_LOG_STATUS``. The index entry for
this function is also changed to ``VIDIOC_LOG_STATUS`` and the function
can now referenced by::
:c:func:`VIDIOC_LOG_STATUS`
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Add a sphinx-extension to customize the sphinx c-domain. No functional
changes right yet, just the boilerplate code.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
[ jc: coding-style tweak ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Let's escape the LaTeX characters, to avoid troubles when
outputing them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Add a generic way to build only a reST sub-folder with or
without a individual *build-theme*.
* control *sub-folders* by environment SPHINXDIRS
* control *build-theme* by environment SPHINX_CONF
Folders with a conf.py file, matching $(srctree)/Documentation/*/conf.py
can be build and distributed *stand-alone*. E.g. to compile only the
html of 'media' and 'gpu' folder use::
make SPHINXDIRS="media gpu" htmldocs
To use an additional sphinx-build configuration (*build-theme*) set the
name of the configuration file to SPHINX_CONF. E.g. to compile only the
html of 'media' with the *nit-picking* build use::
make SPHINXDIRS=media SPHINX_CONF=conf_nitpick.py htmldocs
With this, the Documentation/conf.py is read first and updated with the
configuration values from the Documentation/media/conf_nitpick.py.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
* 'docs-next' of git://git.lwn.net/linux:
doc-rst: kernel-doc: fix handling of address_space tags
Revert "doc/sphinx: Enable keep_warnings"
doc-rst: kernel-doc directive, fix state machine reporter
docs: deprecate kernel-doc-nano-HOWTO.txt
doc/sphinx: Enable keep_warnings
Documentation: add watermark_scale_factor to the list of vm systcl file
kernel-doc: Fix up warning output
docs: Get rid of some kernel-documentation warnings
|
|
Add a reporter replacement that assigns the correct source name and line
number to a system message, as recorded in a ViewList.
[1] http://mid.gmane.org/CAKMK7uFMQ2wOp99t-8v06Om78mi9OvRZWuQsFJD55QA20BB3iw@mail.gmail.com
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Tested-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The function that replace references add a "\ " at the end of
references, to avoid the ReST markup parser to not identify
them as references. That works fine except for the end of lines,
as a sequence of { '\', ' ', '\n' } characters makes Sphinx
to ignore the end of line. So, strip those escape/spaces at the
end of lines.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
The kernel-include directive is needed to include the auto generated rst
content from a build (pre-) process. E.g. the linux_tv Makefile
generates intermediate reST-files from header files. Since there is a O=
option:
make O=dir [targets] Locate all output files in "dir"
We need to include intermediate reST files from arbitrary (O=/tmp/foo)
locations:
The 'kernel-include' reST-directive is a replacement for the 'include'
directive. The 'kernel-include' directive expand environment variables
in the path name and allows to include files from arbitrary locations.
.. hint::
Including files from arbitrary locations (e.g. from '/etc') is a
security risk for builders. This is why the 'include' directive from
docutils *prohibit* pathnames pointing to locations *above* the
filesystem tree where the reST document with the include directive is
placed.
Substrings of the form $name or ${name} are replaced by the value of
environment variable name. Malformed variable names and references to
non-existing variables are left unchanged.
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
