docs: changes: update Sphinx minimal version to 3.4.3

Doing that allows us to get rid of all backward-compatible code.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by:

docs: changes: update Sphinx minimal version to 3.4.3

Doing that allows us to get rid of all backward-compatible code.

Signed-off-by: Mauro Carvalho Chehab <[email protected]>
Reviewed-by: Kees Cook <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/d79e357468c20d86913e9e343d785398f728aabb.1739254187.git.mchehab+huawei@kernel.org

show more ...

compiler_types: add Endianness-dependent __counted_by_{le,be}

Some structures contain flexible arrays at the end and the counter for
them, but the counter has explicit Endianness and thus __counted_

compiler_types: add Endianness-dependent __counted_by_{le,be}

Some structures contain flexible arrays at the end and the counter for
them, but the counter has explicit Endianness and thus __counted_by()
can't be used directly.

To increase test coverage for potential problems without breaking
anything, introduce __counted_by_{le,be}() defined depending on
platform's Endianness to either __counted_by() when applicable or noop
otherwise.
Maybe it would be a good idea to introduce such attributes on compiler
level if possible, but for now let's stop on what we have.

Acked-by: Kees Cook <[email protected]>
Acked-by: Gustavo A. R. Silva <[email protected]>
Signed-off-by: Alexander Lobakin <[email protected]>
Reviewed-by: Przemek Kitszel <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jakub Kicinski <[email protected]>

show more ...

docs: Restore "smart quotes" for quotes

Commit eaae75754d81 ("docs: turn off "smart quotes" in the HTML build")
disabled conversion of quote marks along with that of dashes.
Despite the short summar

docs: Restore "smart quotes" for quotes

Commit eaae75754d81 ("docs: turn off "smart quotes" in the HTML build")
disabled conversion of quote marks along with that of dashes.
Despite the short summary, the change affects not only HTML build
but also other build targets including PDF.

However, as "smart quotes" had been enabled for more than half a
decade already, quite a few readers of HTML pages are likely expecting
conversions of "foo" -> “foo” and 'bar' -> ‘bar’.

Furthermore, in LaTeX typesetting convention, it is common to use
distinct marks for opening and closing quote marks.

To satisfy such readers' expectation, restore conversion of quotes
only by setting smartquotes_action [1].

Link: [1] https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes_action
Cc: [email protected] # v6.4
Signed-off-by: Akira Yokosawa <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

docs: Instruct LaTeX to cope with deeper nesting

The addition of the XFS online fsck documentation starting with
commit a8f6c2e54ddc ("xfs: document the motivation for online fsck design")
added a d

docs: Instruct LaTeX to cope with deeper nesting

The addition of the XFS online fsck documentation starting with
commit a8f6c2e54ddc ("xfs: document the motivation for online fsck design")
added a deeper level of nesting than LaTeX is prepared to deal with. That
caused a pdfdocs build failure with the helpful "Too deeply nested" error
message buried deeply in Documentation/output/filesystems.log.

Increase the "maxlistdepth" parameter to instruct LaTeX that it needs to
deal with the deeper nesting whether it wants to or not.

Suggested-by: Akira Yokosawa <[email protected]>
Tested-by: Akira Yokosawa <[email protected]>
Cc: [email protected] # v6.4+
Link: https://lore.kernel.org/linux-doc/[email protected]/
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: translations: add translations links when they exist

Add a new Sphinx extension that knows about the translations of kernel
documentation and can insert links to the translations at the top of

docs: translations: add translations links when they exist

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 <[email protected]>
Cc: Jani Nikula <[email protected]>
Cc: Akira Yokosawa <[email protected]>
Cc: Yanteng Si <[email protected]>
Signed-off-by: Vegard Nossum <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

docs: conf.py: Ignore __counted_by attribute

It seems that Sphinx is confused by the __counted_by attribute on struct
members. Add it to the list of known attributes.

Reported-by: kernel test robot

docs: conf.py: Ignore __counted_by attribute

It seems that Sphinx is confused by the __counted_by attribute on struct
members. Add it to the list of known attributes.

Reported-by: kernel test robot <[email protected]>
Closes: https://lore.kernel.org/oe-kbuild-all/[email protected]/
Cc: Jonathan Corbet <[email protected]>
Cc: "Gustavo A. R. Silva" <[email protected]>
Cc: [email protected]
Cc: [email protected]
Signed-off-by: Kees Cook <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

docs: Raise the minimum Sphinx requirement to 2.4.4

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.

docs: Raise the minimum Sphinx requirement to 2.4.4

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 <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

Documentation: add tux logo

We already have the logo, let's use it.

Testing: make htmldocs

Cc: Miguel Ojeda <[email protected]>
Signed-off-by: Vegard Nossum <[email protected]>
Signed-off-by

Documentation: add tux logo

We already have the logo, let's use it.

Testing: make htmldocs

Cc: Miguel Ojeda <[email protected]>
Signed-off-by: Vegard Nossum <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

Documentation: conf.py: Add __force to c_id_attributes

Fixes the following error in the docs build that occurs with recent
versions of Sphinx when parsing kerneldocs for a function with the
'__force

Documentation: conf.py: Add __force to c_id_attributes

Fixes the following error in the docs build that occurs with recent
versions of Sphinx when parsing kerneldocs for a function with the
'__force' macro in its signature:

./include/linux/err.h:51: WARNING: Error in declarator or parameters
Error in declarator or parameters
Invalid C declaration: Expected identifier, got keyword: void [error at 35]
void * ERR_CAST (__force const void *ptr)
-----------------------------------^

Currently, almost all of the few in-signature occurrences of '__force'
are in the error pointer functions. Of those, ERR_CAST() is the only
one with kerneldocs, but the kerneldocs aren't even being used to
generate documentation. This change will allow all the error pointer
functions to be properly documented.

In addition to '__force', <linux/compiler_types.h> also defines
'__nocast', '__safe', and '__private'. These are not currently used in
any function signatures and do not need to be added to the docs config.

Signed-off-by: James Seo <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Link: https://lore.kernel.org/r/[email protected]

show more ...

docs: turn off "smart quotes" in the HTML build

We have long disabled the "html_use_smartypants" option to prevent Sphinx
from mangling "--" sequences (among others). Unfortunately, Sphinx changed

docs: turn off "smart quotes" in the HTML build

We have long disabled the "html_use_smartypants" option to prevent Sphinx
from mangling "--" sequences (among others). Unfortunately, Sphinx changed
that option to "smartquotes" in the 1.6.6 release, and seemingly didn't see
fit to warn about the use of the obsolete option, resulting in the
aforementioned mangling returning. Disable this behavior again and hope
that the option name stays stable for a while.

Reported-by: Zipeng Zhang <[email protected]>
Link: https://lore.kernel.org/lkml/[email protected]
Reviewed-by: Miguel Ojeda <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Add more information to the HTML sidebar

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

docs: Add more information to the HTML sidebar

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 <[email protected]>
Reviewed-by: David Gow <[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

bpf: Document usage of the new __bpf_kfunc macro

Now that the __bpf_kfunc macro has been added to linux/btf.h, include a
blurb about it in the kfuncs.rst file. In order for the macro to
successfully

bpf: Document usage of the new __bpf_kfunc macro

Now that the __bpf_kfunc macro has been added to linux/btf.h, include a
blurb about it in the kfuncs.rst file. In order for the macro to
successfully render with .. kernel-doc, we'll also need to add it to the
c_id_attributes array.

Signed-off-by: David Vernet <[email protected]>
Signed-off-by: Daniel Borkmann <[email protected]>
Acked-by: Stanislav Fomichev <[email protected]>
Link: https://lore.kernel.org/bpf/[email protected]

show more ...

docs/conf.py: Use about.html only in sidebar of alabaster theme

"about.html" is available only for the alabaster theme [1].
Unconditionally putting it to html_sidebars prevents us from
using other t

docs/conf.py: Use about.html only in sidebar of alabaster theme

"about.html" is available only for the alabaster theme [1].
Unconditionally putting it to html_sidebars prevents us from
using other themes which respect html_sidebars.

Remove about.html from the initialization and insert it at the
front for the alabaster theme.

Link: [1] https://alabaster.readthedocs.io/en/latest/installation.html#sidebars
Fixes: d5389d3145ef ("docs: Switch the default HTML theme to alabaster")
Signed-off-by: Akira Yokosawa <[email protected]>
Cc: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Deprecate use of Sphinx < 2.4.x

The Sphinx 2.4 release is three years old, and it is becoming increasingly
difficult to even find a system with an sufficiently archaic Python
installation that

docs: Deprecate use of Sphinx < 2.4.x

The Sphinx 2.4 release is three years old, and it is becoming increasingly
difficult to even find a system with an sufficiently archaic Python
installation that can run versions older than that. I can no longer test
changes against anything prior to 2.4.x.

Move toward raising our minimum Sphinx requirement to 2.4.x so we can
delete some older support code and claim to support a range of versions
that we can actually test.

In the absence of screams, the actual removal of support can happen later
in 2023.

Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs/sphinx: More depth in the rtd sidebar toc

We love to nest our documenation for good structure, but that means
the table of contents needs to keep up or you can't navigate them.

Realized this t

docs/sphinx: More depth in the rtd sidebar toc

We love to nest our documenation for good structure, but that means
the table of contents needs to keep up or you can't navigate them.

Realized this trying to find the drm property documentation, which
with some shuffling around disappeared. Why I didn't realize we can do
this earlier, no idea.

Since the relevant parts of the toc are only loaded if you're in the
right .html file there's no harm in going all the way to unlimited.

Note that this has no impact on the alabaster theme (which has a much
simpler sidebar toc which doesn't show the entire hierarchy, only
what's in the local rendered file) nor on the various :toctree:
rendered inline in the output.

Signed-off-by: Daniel Vetter <[email protected]>
Cc: Jonathan Corbet <[email protected]>
Cc: [email protected]
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Don't wire font sizes for HTML output

The alabaster theme likes to provide explicit sizes for fonts, which
overrides the users's own browser settings and is guaranteed to displease
folks. Set

docs: Don't wire font sizes for HTML output

The alabaster theme likes to provide explicit sizes for fonts, which
overrides the users's own browser settings and is guaranteed to displease
folks. Set the font size to "inherit" so that the users browser settings
control the font size they get. We can use the font_size configuration
option for the main body font (changing the size I'd already put there),
but the sidebar size can only be set via custom CSS.

Reported-by: Bagas Sanjaya <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: decruft Documentation/conf.py

Remove the ancient support for the Sphinx "classic" theme; everybody will
have alabaster, so that fallback is no longer needed.

While in the neighborhood: get ri

docs: decruft Documentation/conf.py

Remove the ancient support for the Sphinx "classic" theme; everybody will
have alabaster, so that fallback is no longer needed.

While in the neighborhood: get rid of lots of useless comment lines. They
describe the state of Sphinx options when we first created that file and
are just clutter now.

Suggested-by: Mauro Carvalho Chehab <[email protected]>
Acked-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: tweak some Alabaster style parameters

This is just the beginning: tighten up the layout a bit to improve the
information density in the browser. Also reconfigure the page width in
terms of ch

docs: tweak some Alabaster style parameters

This is just the beginning: tighten up the layout a bit to improve the
information density in the browser. Also reconfigure the page width in
terms of character units (em) rather than pixels, making it more
display-independent. To that end, add a custom.css file to
tweak Alabaster CSS settings.

Acked-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: Switch the default HTML theme to alabaster

The read-the-docs theme is not entirely attractive and doesn't give us
control over the left column. "Alabaster" is deemed the default Sphinx
theme,

docs: Switch the default HTML theme to alabaster

The read-the-docs theme is not entirely attractive and doesn't give us
control over the left column. "Alabaster" is deemed the default Sphinx
theme, it is currently maintained and shipped bundled with Sphinx itself,
so there is no need to install it separately. Switch over to this theme as
the default for building kernel documentation; the DOCS_THEME environment
variable can still be used to select a different theme.

Acked-by: Mauro Carvalho Chehab <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: reconfigure the HTML left column

Use the html_sidebars directive to get a more useful set of links in the
left column.

Unfortunately, this is a no-op with the default RTD theme, but others
ob

docs: reconfigure the HTML left column

Use the html_sidebars directive to get a more useful set of links in the
left column.

Unfortunately, this is a no-op with the default RTD theme, but others
observe it.

Reviewed-by: David Vernet <[email protected]>
Acked-by: Jani Nikula <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>
Acked-by: Randy Dunlap <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs/conf.py: Respect env variable SPHINX_IMGMATH

On some distros with coarse-grained packaging policy, dvipng is
installed along with latex. In such cases, math rendering will
use imgmath by defau

docs/conf.py: Respect env variable SPHINX_IMGMATH

On some distros with coarse-grained packaging policy, dvipng is
installed along with latex. In such cases, math rendering will
use imgmath by default. It is possible to override the choice by
specifying the option string of "-D html_math_renderer='mathjax'"
to sphinx-build (Sphinx >= 1.8).

To provide developers an easier-to-use knob, add code for an env
variable "SPHINX_IMGMATH" which overrides the automatic choice
of math renderer for html docs.

SPHINX_IMGMATH=yes : Load imgmath even if dvipng is not found
SPHINX_IMGMATH=no : Don't load imgmath (fall back to mathjax)

Signed-off-by: Akira Yokosawa <[email protected]>
Acked-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs/conf.py: Treat mathjax as fallback math renderer

Currently, math expressions using the "math::" directive or
the ":math:" role of Sphinx need the imgmath extension for proper
rendering in html

docs/conf.py: Treat mathjax as fallback math renderer

Currently, math expressions using the "math::" directive or
the ":math:" role of Sphinx need the imgmath extension for proper
rendering in html and epub builds.
imgmath requires dvipng (and latex).
Otherwise, "make htmldocs" will complain of missing commands.

As a matter of fact, the mathjax extension is loaded by default since
Sphinx v1.8 and it is good enough for html docs without any dependency
on texlive packages.

Stop loading the imgmath extension for html docs unless requirements
for imgmath are met.

To find out whether required commands are available, add a helper
find_command(), which is a wrapper of shutil.which().

For epub docs, keep the same behavior of always loading imgmath.

Signed-off-by: Akira Yokosawa <[email protected]>
Acked-by: Mauro Carvalho Chehab <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
[jc: Took out the writing of the math_renderer decision]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs/conf.py: add function attribute '__fix_address' to conf.py

Stephen Rothwell reported htmldocs warning when merging net-next:

Documentation/networking/kapi:26: net/core/skbuff.c:780: WARNING: E

docs/conf.py: add function attribute '__fix_address' to conf.py

Stephen Rothwell reported htmldocs warning when merging net-next:

Documentation/networking/kapi:26: net/core/skbuff.c:780: WARNING: Error in declarator or parameters
Invalid C declaration: Expecting "(" in parameters. [error at 19]
void __fix_address kfree_skb_reason (struct sk_buff *skb, enum skb_drop_reason reason)
-------------------^

Add __fix_address keyword to c_id_attributes array in conf.py to fix
the warning.

Link: https://lore.kernel.org/linux-next/[email protected]/
Reported-by: Stephen Rothwell <[email protected]>
Signed-off-by: Menglong Dong <[email protected]>
Tested-by: Bagas Sanjaya <[email protected]>
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs/conf.py: Cope with removal of language=None in Sphinx 5.0.0

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.

docs/conf.py: Cope with removal of language=None in Sphinx 5.0.0

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 <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Cc: [email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...

docs: pdfdocs: Pull LaTeX preamble part out of conf.py

Quote from Jon's remark [1]:

I do notice that Documentation/conf.py is getting large and
unapproachable. At some future point, it mig

docs: pdfdocs: Pull LaTeX preamble part out of conf.py

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/[email protected]/

Suggested-by: Jonathan Corbet <[email protected]>
Signed-off-by: Akira Yokosawa <[email protected]>
Link: https://lore.kernel.org/r/[email protected]
Signed-off-by: Jonathan Corbet <[email protected]>

show more ...