09 Jun, 2022
1 commit
-
commit 627f01eab93d8671d4e4afee9b148f9998d20e7c upstream.
One of the changes in Sphinx 5.0.0 [1] says [sic]:
5.0.0 final
- #10474: language does not accept None as it value.
The default value of language becomes to 'en' now.[1]: https://www.sphinx-doc.org/en/master/changes.html#release-5-0-0-released-may-30-2022
It results in a new warning from Sphinx 5.0.0 [sic]:
WARNING: Invalid configuration value found: 'language = None'.
Update your configuration to a valid langauge code. Falling
back to 'en' (English).Silence the warning by using 'en'.
It works with all the Sphinx versions required for building
kernel documentation (1.7.9 or later).Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/bd0c2ddc-2401-03cb-4526-79ca664e1cbe@gmail.com
Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet
Signed-off-by: Greg Kroah-Hartman
07 Sep, 2021
1 commit
-
There were typos in the fallback definitions of dummy LaTeX macros
for systems without CJK fonts.
They cause build errors in "make pdfdocs" on such systems.
Fix them.Fixes: e291ff6f5a03 ("docs: pdfdocs: Add CJK-language-specific font settings")
Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/ad7615a5-f8fa-2bc3-de6b-7ed49d458964@gmail.com
Signed-off-by: Jonathan Corbet
12 Aug, 2021
7 commits
-
Quotation marks in "KR" and "JP" variants of Noto CJK fonts are half
width.
xeCJK assumes they are full width by default and does excessive kerning
around them in Korean and Japanese translations.Give xeCJK proper hints by the \xeCJKDeclareCharClass command.
Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/0da9e3c5-2716-f576-1df5-2f28ea69f0e8@gmail.com
Signed-off-by: Jonathan Corbet -
Noto CJK fonts don't provide italic shapes.
The AutoFakeSlant option of fontspec and xeCJK packages can be used as
a workaround.Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/502335cc-9a95-3c2a-7744-6cc56ecaf628@gmail.com
Signed-off-by: Jonathan Corbet -
CJK documents are much easier to read with a wider baseline stretch.
Applying onehalfspacing option of "setspace" package looks reasonable.Note: \usepackage{setspace} needs to be before that of hyperref in the
preamble.
The 'extrapackages' key (available since Sphinx 2.3) is for this purpose.
For systems with Sphinx < 2.3, dummy commands of \onehalfspacing and
\singlespacing are provided instead.
One-half spacing is not effective in LaTeX sources generated by such
revisions of Sphinx.Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/547a1f1c-0bb5-20a7-ea0e-951bfc3c3925@gmail.com
Signed-off-by: Jonathan Corbet -
In Korean typesetting, inter-phrase spaces in Hangul text have
a similar role as the the inter-word spaces in Latin text.
They can be preserved by the \xeCJKsetup{CJKspace=true} option.Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/68de2e52-e6d1-3f01-c097-15ba7b28a319@gmail.com
Signed-off-by: Jonathan Corbet -
"Noto Serif CJK SC" and its variants suit better with the roman font
of Latin letters.On some distros such as Fedora, it is possible to partially install
"Noto Sans CJK" fonts.
So, if the Serif fonts are not found on the system, fall back to the
Sans fonts.Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/5e454140-5d0c-35d4-8c31-3ffb2420793a@gmail.com
Signed-off-by: Jonathan Corbet -
zh_TW, ko_KR, and ja_JP translations have their preferred glyph sets
different from that of zh_CN.To switch CJK font in the middle of the translations, introduce custom
LaTeX macros listed below:\kerneldocBeginSC
\kerneldocEndSC
\kerneldocBeginTC
\kerneldocEndTC
\kerneldocBeginKR
\kerneldocEndKR
\kerneldocBeginJP
\kerneldocEndJP, and embed a pair of macros in each language's index.rst.
NOTE 1: Update of zh_TW/index.rst is deferred to a follow-up change.
NOTE 2: Custom macros added here do not imply \kerneldocCJK(on|off).
This is intentional. For example, \kerneldocCJKoff needs to be
at the top of Italian translations' index.rst for the footer of
final zh_TW page to be properly typeset.Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/31906baf-7490-68cd-7153-4e4d320fb9b0@gmail.com
Signed-off-by: Jonathan Corbet -
To make generated LaTeX code portable across systems with different sets
of available fonts, convert font-availability check in python code to
LaTeX code by using a conditional command provided by the "fontspec"
package.This will help those who run Sphinx on one machine/container and run
latexmk on other machines/containers.Remove import of check_output as it is unused any more.
Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/4baf88af-316d-8aee-240f-6ccbc20907d7@gmail.com
Signed-off-by: Jonathan Corbet
18 Jun, 2021
1 commit
-
Sphinx 3.0 works at this point (albeit slowly) so stop scaring people
with a loud warning. We also don't need to babble about CJK support in the
LaTeX build.Signed-off-by: Jonathan Corbet
02 Jun, 2021
1 commit
-
Setting a reasonable width to \tymin prevents column squeezing
by tabulary.
Width of 20em works well in almost all the tables still in the
ascii-art format.Excerpt from tabulary package documentation at [1]:
To stop very narrow columns being too 'squeezed' by this process
any columns that are narrower than \tymin are set to their natural
width.[1]: https://mirrors.ctan.org/macros/latex/contrib/tabulary/tabulary.pdf
Note: Sphinx has its own default value of \tymin set in
sphinxlatextables.sty (Sphinx 4.0.2) and sphinxmulticell.sty
(Sphinx 2.4.4) as follows:\setlength{\tymin}{3\fontcharwd\font`0 }
, which is not sufficient for kernel-doc.
Tested against Sphinx versions 2.4.4 and 4.0.2.
Signed-off-by: Akira Yokosawa
Link: https://lore.kernel.org/r/277d68fa-c96a-0ccb-6ce0-4d314851d9fe@gmail.com
Signed-off-by: Jonathan Corbet
27 May, 2021
1 commit
-
Activating xeCJK in English and Italian-translation documents
results in sub-optimal typesetting with wide-looking apostrophes
and quotation marks.The xeCJK package provides macros for enabling and disabling its
effect in the middle of a document, namely \makexeCJKactive and
\makexeCJKinactive.So the goal of this change is to activate xeCJK in the relevant
chapters in translations.To do this:
o Define custom macros in the preamble depending on the
availability of the "Noto Sans CJK" font so that those
macros can be used regardless of the use of xeCJK package.o Patch \sphinxtableofcontents so that xeCJK is inactivated
after table of contents.o Embed those custom macros in each language's index.rst file
as a ".. raw:: latex" construct.Note: A CJK chapter needs \kerneldocCJKon in front of its chapter
heading, while a non-CJK chapter should have \kerneldocCJKoff
below its chapter heading.This is to make sure the CJK font is available to CJK chapter's
heading and ending page's footer.Tested against Sphinx versions 2.4.4 and 4.0.2.
Signed-off-by: Akira Yokosawa
Tested-by: Wu XiangCheng
Reviewed-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/lkml/2061da0a-6ab1-35f3-99c1-dbc415444f37@gmail.com
Link: https://lore.kernel.org/r/83208ddc-5de9-b283-3fd6-92c635348ca0@gmail.com
Signed-off-by: Jonathan Corbet
09 Mar, 2021
1 commit
-
Changeset f546ff0c0c07 ("Move our minimum Sphinx version to 1.7")
cleaned up some compatibility issues with previous Sphinx
versions, but it also dropped the PDF margin sets.Without that, the media documentation won't build fine, as
the margins are too wide to display texts with monospaced
fonts.While here, align the "latex_elements = {" values, and add
a few other sphinxsetup configs in order to allow Sphinx to
wrap long lines on literal blocks.Fixes: f546ff0c0c07 ("Move our minimum Sphinx version to 1.7")
Signed-off-by: Mauro Carvalho ChehabDocumentation/conf.py | 31 +++++++++++++++++++------------
1 file changed, 19 insertions(+), 12 deletions(-)
Link: https://lore.kernel.org/r/911fbac185dd09c7df715cf4153361b81f04b7ad.1614787053.git.mchehab+huawei@kernel.orgSigned-off-by: Jonathan Corbet
23 Feb, 2021
1 commit
-
The current documentation build looks like this:
$ make htmldocs
SPHINX htmldocs --> file:///home/willy/kernel/linux-next/Documentation/output
make[2]: Nothing to be done for 'html'.
WARNING: The kernel documentation build process
support for Sphinx v3.0 and above is brand new. Be prepared for
possible issues in the generated output.
$That extra indentation before my next prompt isn't pretty. This patch
fixes it, but I'm not a pythonista, and maybe there's a better way.Signed-off-by: Matthew Wilcox (Oracle)
Link: https://lore.kernel.org/r/20210215161757.GD2858050@casper.infradead.org
[jc: tweaked for the "better way"]
Signed-off-by: Jonathan Corbet
02 Feb, 2021
1 commit
-
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
12 Dec, 2020
1 commit
-
The time has come to drop support for some truly ancient versions of
sphinx; put in a warning now.Signed-off-by: Jonathan Corbet
04 Dec, 2020
1 commit
-
Add a feature list matrix at the admin-guide.
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/f6c1e366fbc7ce1c9c94c7dc6c7852c6377cc0be.1606748711.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
04 Nov, 2020
1 commit
-
Pull documentation build warning fixes from Jonathan Corbet:
"This contains a series of warning fixes from Mauro; once applied, the
number of warnings from the once-noisy docs build process is nearly
zero.Getting to this point has required a lot of work; once there,
hopefully we can keep things that way.I have packaged this as a separate pull because it does a fair amount
of reaching outside of Documentation/. The changes are all in comments
and in code placement. It's all been in linux-next since last week"* tag 'docs-5.10-warnings' of git://git.lwn.net/linux: (24 commits)
docs: SafeSetID: fix a warning
amdgpu: fix a few kernel-doc markup issues
selftests: kselftest_harness.h: fix kernel-doc markups
drm: amdgpu_dm: fix a typo
gpu: docs: amdgpu.rst: get rid of wrong kernel-doc markups
drm: amdgpu: kernel-doc: update some adev parameters
docs: fs: api-summary.rst: get rid of kernel-doc include
IB/srpt: docs: add a description for cq_size member
locking/refcount: move kernel-doc markups to the proper place
docs: lockdep-design: fix some warning issues
MAINTAINERS: fix broken doc refs due to yaml conversion
ice: docs fix a devlink info that broke a table
crypto: sun8x-ce*: update entries to its documentation
net: phy: remove kernel-doc duplication
mm: pagemap.h: fix two kernel-doc markups
blk-mq: docs: add kernel-doc description for a new struct member
docs: userspace-api: add iommu.rst to the index file
docs: hwmon: mp2975.rst: address some html build warnings
docs: net: statistics.rst: remove a duplicated kernel-doc
docs: kasan.rst: add two missing blank lines
...
30 Oct, 2020
1 commit
-
As we don't want a generic Sphinx extension to execute commands,
change the one proposed to Markus to call the abi_book.pl
script.Use a script to parse the Documentation/ABI directory and output
it at the admin-guide.Acked-by: Jonathan Corbet
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/5651482b06500e69a1acdf92152f90a203e6521d.1604042072.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman
29 Oct, 2020
1 commit
-
One of the checks for Sphinx 3+ is broken, causing some
C warnings to return back with Sphinx 4.0.x.Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/d5abc30056dafeec0778a46263a45401bdc7f11e.1603791716.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
15 Oct, 2020
2 commits
-
After the build fix patches, it is believed that the output
with Sphinx 3.x won't be a problem. Still, the C domain
support was re-written, and this can have caused hidden
issues.So, let's keep the warning, changing it to a lighter
warning text.Signed-off-by: Mauro Carvalho Chehab
-
Sphinx C parser for the C domain is now more pedantic when
trying to identify the function types. That prevents scope
macros to be used as type defines.Yet, since 3.0.2, it is possible to provide it a list of
such macros. Add them, in order to solve several Sphinx 3.x
warnings.Signed-off-by: Mauro Carvalho Chehab
05 Sep, 2020
1 commit
-
The Sphinx 3.x upgrade broke a number of things in our special "cdomain"
module that are not easy to fix. For now, just disable that module for the
3.x build and put out a warning that the build will not be perfect.Signed-off-by: Jonathan Corbet
08 Jun, 2020
1 commit
-
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
Link: https://lore.kernel.org/r/20200526060544.25127-1-grandmaster@al2klimov.de
Signed-off-by: Jonathan Corbet
21 Apr, 2020
1 commit
-
The building system can auto-generate a list of documents since
commit: 9d42afbe6bd4 ("docs: pdf: add all Documentation/*/index.rst to PDF output").The added logic there allows keeping the existing list, but
there's not real reason to keep it. Now, the media document
has gone (it was split into tree).So, it sounds about time to get rid of the manual entries,
and let the script to generate it automatically instead.Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/9345dba7164497dbf28578f6ec271e479379610c.1586881715.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
21 Mar, 2020
1 commit
-
The autosectionlabel extension is nice, as it allows to refer to
a section by its name without requiring any extra tag to create
a reference name.However, on its default, it has two serious problems:
1) the namespace is global. So, two files with different
"introduction" section would create a label with the
same name. This is easily solvable by forcing the extension
to prepend the file name with:autosectionlabel_prefix_document = True
2) It doesn't work hierarchically. So, if there are two level 1
sessions (let's say, one labeled "open" and another one "ioctl")
and both have a level 2 "synopsis" label, both section 2 will
have the same identical name.Currently, there's no way to tell Sphinx to create an
hierarchical reference like:open / synopsis
ioctl / synopsisThis causes around 800 warnings. So, the fix should be to
not let autosectionlabel to produce references for anything
that it is not at a chapter level within any doc, with:autosectionlabel_maxdepth = 2
Fixes: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
Signed-off-by: Mauro Carvalho Chehab
Link: https://lore.kernel.org/r/74f4d8d91c648d7101c45b4b99cc93532f4dadc6.1584716446.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet
20 Mar, 2020
1 commit
-
Fix a couple of dangling links to core-api/namespaces.rst by turning them
into proper references. Enable the autosection extension (available since
Sphinx 1.4) to make this work.Co-developed-by: Federico Vaga
Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet
03 Oct, 2019
1 commit
-
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
Reviewer: Andy Lutomirski ,
Will Drewry
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\bSigned-off-by: Kees Cook
Signed-off-by: Jonathan Corbet
17 Jul, 2019
3 commits
-
If we try to build a book with asian characters with XeLaTeX
and the font is not available, it will produce an error.So, instead, add a logic at conf.py to detect if the proper
font is installed.This will avoid an error while building the document, although
the result may not be readable.Signed-off-by: Mauro Carvalho Chehab
-
In order to be able to output Asian symbols with XeLaTeX, we
need the xeCJK package, and a default font for CJK symbols.Signed-off-by: Mauro Carvalho Chehab
-
Currently, all index files should be manually added to the
latex_documents array at conf.py.While this allows fine-tuning some LaTeX specific things, like
the name of the output file and the name of the document, it
is not uncommon to forget adding new documents there.So, add a logic that will seek for all Documentation/*/index.rst.
If the index is not yet at latex_documents, it includes using
a reasonable default.Signed-off-by: Mauro Carvalho Chehab
01 Jul, 2019
1 commit
-
The handling of dashes in particular results in confusing
documentation in a number of instances, since "--" becomes an
en-dash. This disables SmartyPants wholesale, losing smart quotes
along with smart dashes.With Sphinx 1.6 we could fine-tune the conversion, using the new
smartquotes and smartquotes_action settings.Signed-off-by: Stephen Kitt
Signed-off-by: Jonathan Corbet
27 Jun, 2019
1 commit
-
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
24 May, 2019
1 commit
-
Our version check in Documentation/conf.py never envisioned a world where
Sphinx moved beyond 1.x. Now that the unthinkable has happened, fix our
version check to handle higher version numbers correctly.Cc: stable@vger.kernel.org
Signed-off-by: Jonathan Corbet
25 Oct, 2018
1 commit
-
Pull documentation updates from Jonathan Corbet:
"This is a fairly typical cycle for documentation. There's some welcome
readability improvements for the formatted output, some LICENSES
updates including the addition of the ISC license, the removal of the
unloved and unmaintained 00-INDEX files, the deprecated APIs document
from Kees, more MM docs from Mike Rapoport, and the usual pile of typo
fixes and corrections"* tag 'docs-4.20' of git://git.lwn.net/linux: (41 commits)
docs: Fix typos in histogram.rst
docs: Introduce deprecated APIs list
kernel-doc: fix declaration type determination
doc: fix a typo in adding-syscalls.rst
docs/admin-guide: memory-hotplug: remove table of contents
doc: printk-formats: Remove bogus kobject references for device nodes
Documentation: preempt-locking: Use better example
dm flakey: Document "error_writes" feature
docs/completion.txt: Fix a couple of punctuation nits
LICENSES: Add ISC license text
LICENSES: Add note to CDDL-1.0 license that it should not be used
docs/core-api: memory-hotplug: add some details about locking internals
docs/core-api: rename memory-hotplug-notifier to memory-hotplug
docs: improve readability for people with poorer eyesight
yama: clarify ptrace_scope=2 in Yama documentation
docs/vm: split memory hotplug notifier description to Documentation/core-api
docs: move memory hotplug description into admin-guide/mm
doc: Fix acronym "FEKEK" in ecryptfs
docs: fix some broken documentation references
iommu: Fix passthrough option documentation
...
07 Oct, 2018
1 commit
-
My eyesight is not in good shape, which means that I have difficulty
reading the online Linux documentation. Specifically, body text is
oddly small compared to list items and the contrast of various text
elements is too low for me to be able to see easily.Therefore, alter the HTML theme overrides to make the text larger and
increase the contrast for better visibility, and trust the typeface
choices of the reader's browser.For the PDF output, increase the text size, use a sans-serif typeface
for sans-serif text, and use a serif typeface for "roman" serif text.Signed-off-by: Darrick J. Wong
Acked-by: Dave Chinner
Signed-off-by: Jonathan Corbet
06 Oct, 2018
2 commits
-
Move the ext4 data structures book to Documentation/filesystems/ext4/
since the administrative information moved elsewhere.Signed-off-by: Darrick J. Wong
Signed-off-by: Theodore Ts'o -
Move the ext4 mount option and other administrative stuff to the Linux
administrator's guide.Signed-off-by: Darrick J. Wong
Signed-off-by: Theodore Ts'o
03 Oct, 2018
1 commit
-
The documentation build scripts won't build a pdf for the ext4
documentation unless explicitly called for, so ask for a separate
ext4.pdf to be generated with all the documentation.Signed-off-by: Darrick J. Wong
Signed-off-by: Theodore Ts'o
30 Jul, 2018
1 commit
-
Import the chapter about inode data fork from the on-disk format wiki
page into the kernel documentation.Signed-off-by: Darrick J. Wong
Signed-off-by: Theodore Ts'o