linux.git/Documentation/conf.py, branch v6.6

Documentation: conf.py: Add __force to c_id_attributes

2023-05-19T14:58:10+00:00

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',  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 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20230509175543.2065835-2-james@equiv.tech

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

2023-04-20T23:53:18+00:00

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 
Link: https://lore.kernel.org/lkml/tencent_CB1A298D31FD221496FF657CD7EF406E6605@qq.com
Reviewed-by: Miguel Ojeda 
Signed-off-by: Jonathan Corbet

Merge tag 'docs-6.3' of git://git.lwn.net/linux

2023-02-22T20:00:20+00:00

Pull documentation updates from Jonathan Corbet:
 "It has been a moderately calm cycle for documentation; the significant
  changes include:

   - Some significant additions to the memory-management documentation

   - Some improvements to navigation in the HTML-rendered docs

   - More Spanish and Chinese translations

  ... and the usual set of typo fixes and such"

* tag 'docs-6.3' of git://git.lwn.net/linux: (68 commits)
  Documentation/watchdog/hpwdt: Fix Format
  Documentation/watchdog/hpwdt: Fix Reference
  Documentation: core-api: padata: correct spelling
  docs/mm: Physical Memory: correct spelling in reference to CONFIG_PAGE_EXTENSION
  docs: Use HTML comments for the kernel-toc SPDX line
  docs: Add more information to the HTML sidebar
  Documentation: KVM: Update AMD memory encryption link
  printk: Document that CONFIG_BOOT_PRINTK_DELAY required for boot_delay=
  Documentation: userspace-api: correct spelling
  Documentation: sparc: correct spelling
  Documentation: driver-api: correct spelling
  Documentation: admin-guide: correct spelling
  docs: add workload-tracing document to admin-guide
  docs/admin-guide/mm: remove useless markup
  docs/mm: remove useless markup
  docs/mm: Physical Memory: remove useless markup
  docs/sp_SP: Add process magic-number translation
  docs: ftrace: always use canonical ftrace path
  Doc/damon: fix the data path error
  dma-buf: Add "dma-buf" to title of documentation
  ...

docs: Add more information to the HTML sidebar

2023-02-08T20:28:27+00:00

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 
Reviewed-by: David Gow

bpf: Document usage of the new __bpf_kfunc macro

2023-02-01T23:25:14+00:00

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 
Signed-off-by: Daniel Borkmann 
Acked-by: Stanislav Fomichev 
Link: https://lore.kernel.org/bpf/20230201173016.342758-3-void@manifault.com

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

2023-01-11T22:06:50+00:00

"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 
Cc: Mauro Carvalho Chehab 
Link: https://lore.kernel.org/r/4b162dbe-2a7f-1710-93e0-754cf8680aae@gmail.com
Signed-off-by: Jonathan Corbet

docs: Deprecate use of Sphinx < 2.4.x

2023-01-06T20:04:15+00:00

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

docs/sphinx: More depth in the rtd sidebar toc

2022-11-09T20:28:40+00:00

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 
Cc: Jonathan Corbet 
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/r/20221108115707.1232621-1-daniel.vetter@ffwll.ch
Signed-off-by: Jonathan Corbet

docs: Don't wire font sizes for HTML output

2022-11-01T21:59:40+00:00

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 
Signed-off-by: Jonathan Corbet

docs: decruft Documentation/conf.py

2022-10-18T22:29:35+00:00

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 
Acked-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet