| Age | Commit message (Collapse) | Author | Files | Lines |
|---|
|
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>
|
|
Add one extra escape character to avoid those warnings:
Documentation/linux_tv/videodev2.h.rst:6: WARNING: Inline substitution_reference start-string without end-string.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
At videodev2.h, we have hundreds of symbols that don't
currently have a reference yet. Let's ignore for how, while
we don't improve those cross-refs.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
We should not let comments to mangle with the symbols
parsing. Unfortunately, videodev2.h has lots of those
in the middle of enums and structs. So, we need to improve
our parser to discard them.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
The typedef handler should do two things to be generic:
1) parse typedef enums;
2) accept both possible syntaxes:
typedef struct foo { .. } foo_t;
typedef struct { .. } foo_t;
Unfortunately, this is needed to parse some legacy DVB
files, like dvb/audio.h.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
When typedef is used on its multiline format, we need to
also parse enum and struct in the same line.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
Be more formal about the valid symbols that are expected by
the parser, to match what c language expects.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
The dmx.h header has two things that causes the parser to
break while handling enums:
per-header enums and the '{' starts on a new line
Both makes the parser to get lexical marks to be detected
as if they were symbols.
Fix it.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
When something is deprecated, highlight it, as we want it
to be clearer to the reader.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
As we had to escape the symbols for the ReST markup to not do
the wrong thing, the logic to discover start/end of strings
are not trivial. Improve the end delimiter detection, in order
to highlight more occurrences of the strings.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
This script parses a header file and converts it into a
parsed-literal block, creating references for ioctls,
defines, typedefs, enums and structs.
It also allow an external file to modify the rules, in
order to fix the expressions.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
Implements the reST flat-table directive.
The ``flat-table`` is a double-stage list similar to the ``list-table`` with
some additional features:
* column-span: with the role ``cspan`` a cell can be extended through
additional columns
* row-span: with the role ``rspan`` a cell can be extended through
additional rows
* auto span rightmost cell of a table row over the missing cells on the right
side of that table-row. With Option ``:fill-cells:`` this behavior can
changed from *auto span* to *auto fill*, which automaticly inserts (empty)
list tables
The *list tables* formats are double stage lists. Compared to the
ASCII-art they migth be less comfortable for readers of the
text-files. Their advantage is, that they are easy to create/modify
and that the diff of a modification is much more meaningfull, because
it is limited to the modified content.
The initial implementation was taken from the sphkerneldoc project [1]
[1] https://github.com/return42/sphkerneldoc/commits/master/scripts/site-python/linuxdoc/rstFlatTable.py
Signed-off-by: Markus Heiser <markus.heiser@darmarIT.de>
[jc: fixed typos and misspellings in the docs]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Let the user specify file patterns where to look for the EXPORT_SYMBOLs
in addition to the file with kernel-doc comments. This is directly based
on the -export-file FILE option added to kernel-doc in "kernel-doc: add
support for specifying extra files for EXPORT_SYMBOLs", but we extend
that with globbing patterns in the Sphinx extension.
The file patterns are added as options to the :export: and :internal:
arguments of the kernel-doc directive. For example, to extract the
documentation of exported functions from include/net/mac80211.h:
.. kernel-doc:: include/net/mac80211.h
:export: net/mac80211/*.c
Without the file pattern, no exported functions would be found, as the
EXPORT_SYMBOLs are placed in the various source files under
net/mac80211.
The matched files are also added as dependencies on the document in
Sphinx, as they may affect the output. This is one of the reasons to do
the globbing in the Sphinx extension instead of in scripts/kernel-doc.
The file pattern remains optional, and is not needed if the kernel-doc
comments and EXPORT_SYMBOLs are placed in the source file passed in as
the main argument to the kernel-doc directive. This is the most common
case across the kernel source tree.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
Using the default str.split doesn't return empty strings like the
current version does.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
Leftover cruft. No functional changes.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
Design is pretty simple: kernel-doc inserts breadcrumbs with line
numbers, and sphinx picks them up. At first I went with a sphinx
comment, but inserting those at random places seriously upsets the
parser, and must be filtered. Hence why this version now uses "#define
LINEO " since one of these ever escape into output it's pretty clear
there is a bug.
It seems to work well, and at least the 2-3 errors where sphinx
complained about something that was not correct in kernel-doc text the
line numbers matched up perfectly.
v2: Instead of noodling around in the parser state machine, create
a ViewList and parse it ourselves. This seems to be the recommended
way, per Jani's suggestion.
v3:
- Split out ViewList pach. Splitting the kernel-doc changes from the
sphinx ones isn't possible, since emitting the LINENO lines wreaks
havoc with the rst formatting. We must filter them.
- Improve the regex per Jani's suggestions, and compile it just once
for speed.
- Now that LINENO lines are eaten, also add them to function parameter
descriptions. Much less content and offset than for in-line struct
member descriptions, but still nice to know which exact continuation
line upsets sphinx.
- Simplify/clarify the line +/-1 business a bit.
v4: Split out the scripts/kernel-doc changes and make line-numbers
opt-in, as suggested by Jani.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@ffwll.ch>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
Instead of just forcefully inserting our kernel-doc input and letting
the state machine stumble over it the recommended way is to create
ViewList, parse that and then return the list of parsed nodes.
Suggested by Jani.
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
With this error output becomes almost readable. The line numbers are
still totally bonghits, but that's a lot harder to pull out of
kerneldoc. We'd essentially have to insert some special markers in the
kernel-doc output, split the output along these markers and then
insert each block separately using
state_machine.insert_input(block, source, first_line)
Cc: Jani Nikula <jani.nikula@intel.com>
Cc: linux-doc@vger.kernel.org
Cc: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
Reconcile differences between python2 and python3 on dealing with
stdout, stderr from Popen. This fixes "name 'unicode' is not defined"
errors on python3. We'll need to try to keep the extension working on
both python-sphinx and python3-sphinx so we don't need two copies.
Reported-and-tested-by: Marius Vlad <marius.c.vlad@intel.com>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
Add "struct" in the label of the reference.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
Function references should include the parens (), struct references
should not include "struct".
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
This script uses pandoc to convert existing DocBook template files to RST
templates. A couple of sed scripts are need to massage things both before
and after the conversion, but the result is then usable with no hand
editing.
[Jani: Change usage to tmplcvt <in> <out>. Fix escaping for docproc
directives. Add support the new kernel-doc extension.]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
|
Add an extension to handle kernel-doc directives, to call kernel-doc
according to the arguments and parameters given to the reStructuredText
directive.
The syntax for the kernel-doc directive is:
.. kernel-doc:: FILENAME
:export:
:internal:
:functions: FUNCTION [FUNCTION ...]
:doc: SECTION TITLE
Of the directive options export, internal, functions, and doc, currently
only one option may be given at a time.
The FILENAME is relative from the kernel source tree root.
The extension notifies Sphinx about the document dependency on FILENAME,
causing the document to be rebuilt when the file has been changed.
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
|
