Use the existing documentation logo as the HTML favicon.
This makes generated documentation pages use a matching browser tab
icon without introducing a separate favicon asset.
Signed-off-by: Rito Rhymes <rito@ritovision.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260321125532.9568-1-rito@ritovision.com>
The root document usually has a special :ref:`genindex` link to the
generated index. This is also the case for Documentation/index.rst. The
other index.rst files deeper in the directory hierarchy usually don't.
For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
but some other index.rst in the hierarchy. Currently they have a
".. only::" block to add the index link when doing SPHINXDIRS html
builds.
This is obviously very tedious and repetitive. The link is also added to
all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
root document.
Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
include it at the end of the root document for subproject builds in an
ad-hoc source-read extension defined in conf.py.
For now, keep having the boilerplate in translations, because this
approach currently doesn't cover translated index link headers.
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
[jc: did s/doctree/kern_doc_dir/ ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>
Mauro's work to include documentation from our Python modules. His cover
letter follows:
This is an extended version of:
https://lore.kernel.org/linux-doc/cover.1768488832.git.mchehab+huawei@kernel.org/
It basically adds everything we currently have inside libs/tool/python
to "tools" book inside documentation.
This version should be independent of the other series yet to be merged,
(including the jobserver one).
The vast amount of changes here are docstring cleanups and additions.
They mainly consists on:
- ensuring that every phrase will end with a period, making it uniform
along all files;
- cleaning ups to better uniform docstrings;
- variable descriptions now use "#:" markup, as it allows autodoc to
add them inside the documentation;
- added some missing docstrings;
- some new blank lines at comments to make ReST syntax parser happy;
- add a couple of sphinx markups (mainly, code blocks).
Most of those are minor changes, affecting only comments.
It also has one patch per libarary type, adding them to docs.
For kernel-doc, I did the cleanups first, as there is one code block
inside tools/lib/python/kdoc/latex_fonts.py that would cause a Sphinx
crash without such markups.
The series actually starts with 3 fixes:
- avoid "*" markups on indexes with deep> 3 to override text
- a variable rename to stop abusing doctree name
- don't rely on cwd to get Documentation/ location
patch 4 adds support to document scripts either at:
- tools/
- scripts/
patch 5 contains a CSS to better display autodoc html output.
For those who want to play with documentation, documenting a python
file is very simple. All it takes is to use:
.. automodule:: lib.python.<dir+name>
Usually, we add a couple of control members to it to adjust
the desired documentation scope (add/remove members, showing class
inheritance, showing members that currently don't have
docstrings, etc). That's why we're using:
.. automodule:: lib.python.kdoc.enrich_formatter
:members:
:show-inheritance:
:undoc-members:
(and similar) inside tools/kdoc*.rst.
autodoc allows filtering in/out members, file docstrings, etc.
It also allows documenting just some members or functions with
directives like:
..autofunction:
..automember:
Sphinx also has a helper script to generate .rst files with
documentation:
$ sphinx-apidoc -o foobar tools/lib/python/
which can be helpful to discover what should be documented,
although changes are needed to use what it produces.
The code here was meant to handle 3 functions:
1. allow having a separate conf.py file, per subdir;
2. generate a list of latex documents.
3. set "subproject" tag if SPHINXDIRS points to a subdir.
We don't have (1) anymore, and (3) is now properly handled
entirely inside conf.py.
So, only (3) is still needed, and this is a single-line change
at conf.py.
So, drop it, moving the remaining code to conf.py.
While here, drop a duplicated $(RUSTDOC) command-line argument.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <ec998f9f268a401ca6aa36e3221d39c97efeccaa.1758361087.git.mchehab+huawei@kernel.org>
Makes it more adehent with modern Sphinx LaTeX build setup as
defined at:
https://www.sphinx-doc.org/en/master/latex.html
There, it suggests:
1) to add: 'printindex'
“printindex” call, the last thing in the file. Override if you want to generate
the index differently, append some content after the index, or change the font.
As LaTeX uses two-column mode for the index it is often advisable to set this
key to r'\footnotesize\raggedright\printindex'.
This indeed solved a corner case on a distro where the index was not properly
generated.
2) to add at the main example:
\PassOptionsToPackage{svgnames}{xcolor}
3) I got a corner case on one of the distros was using xindy to produce
indexes. This ended causing the build logic to incorretly try to use
T1 fontenc, which is not UTF-8 compatible.
This patch adds:
\PassOptionsToPackage{xindy}{language=english,codepage=utf8,noautomatic}
to cover such case. It should be noticed that, as the config doesn't
have \usepackage{xindy}, this will be used only if latexmk ends
using xindy.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/08d16c2ad817910eb5606842f776d3f77d83282f.1755763127.git.mchehab+huawei@kernel.org
While PDF docs work fine on RPM-based distros, it causes conflicts
on Debian & friends.
There are multiple root causes here:
- the latex_elements still resambles the one from Sphinx 1.x
times, where font configurations were stored under
"preamble". It doesn't follow the current recommended way from
Sphinx documentation:
https://www.sphinx-doc.org/en/master/latex.html
- instead of setting the main font, from where other fonts are
derivated, it sets romanfont;
- "fontenc" is not set. This allows the *.tex output file to
contain an UTF-8 incompatible fontset:
\usepackage[T1]{fontenc}
Address such issues to help preventing incompatible usage of
both T1 font and UTF-8 ones that comes from DejaVu font
family.
On some distros, this even generate a LaTeX font warning about
corrupted NFSS tables like this (I got it when running it in
interactive mode):
Package: fontenc 2021/04/29 v2.0v Standard LaTeX package
LaTeX Font Info: Trying to load font information for T1+lmr on input line 11
6.
LaTeX Font Info: No file T1lmr.fd. on input line 116.
LaTeX Font Warning: Font shape `T1/lmr/m/n' undefined
(Font) using `T1/lmr/m/n' instead on input line 116.
! Corrupted NFSS tables.
wrong@fontshape ...message {Corrupted NFSS tables}
error@fontshape else let f...
l.116 ...\familydefault\seriesdefault\shapedefault
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/8104ce56a5ea3509fbb56a8163b779d38a6aaa9c.1755763127.git.mchehab+huawei@kernel.org
Instead of manually calling ynl_gen_rst.py, use a Sphinx extension.
This way, no .rst files would be written to the Kernel source
directories.
We are using here a toctree with :glob: property. This way, there
is no need to touch the netlink/specs/index.rst file every time
a new Netlink spec is added/renamed/removed.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Donald Hunter <donald.hunter@gmail.com>
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 <keescook@chromium.org>
Acked-by: Gustavo A. R. Silva <gustavoars@kernel.org>
Signed-off-by: Alexander Lobakin <aleksander.lobakin@intel.com>
Reviewed-by: Przemek Kitszel <przemyslaw.kitszel@intel.com>
Link: https://lore.kernel.org/r/20240327142241.1745989-2-aleksander.lobakin@intel.com
Signed-off-by: Jakub Kicinski <kuba@kernel.org>
