linux-stable.git/Documentation/doc-guide, branch v6.9

docs: drop the version constraints for sphinx and dependencies

2024-03-03T15:17:20+00:00

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 
Tested-by: Vegard Nossum 
Signed-off-by: Lukas Bulwahn 
Signed-off-by: Jonathan Corbet 
Message-ID: <20240301141800.30218-1-lukas.bulwahn@gmail.com>

Documentation: multiple .rst files: Fix grammar and more consistent formatting

2024-02-05T17:24:54+00:00

sphinx.rst:
- Remove unnecessary newline
- Fix grammar s/on/in/
- Fix grammar s/check/checks/
- Capitalize heading "The C domain"

changes.rst:
- Remove colon after "pahole" to be consistent with other entries

howto.rst:
- Fix grammar s/you will/will you/
- Hyphenate "real-world problems"

Signed-off-by: Thorsten Blum 
Reviewed-by: Randy Dunlap 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240205000117.3285-1-thorsten.blum@toblux.com

doc-guide: kernel-doc: tell about object-like macros

2024-01-30T20:31:09+00:00

Since 2014 kernel-doc has supported describing object-like macros
but it is not documented anywhere. I should have required some
documentation for it when I merged the patch. :(

There are currently only 3 uses of this (all in DRM headers, in
include/drm/*.h).

Add object-like macro kernel-doc documentation now so that more may
know about it and use it.

Fixes: cbb4d3e6510b ("scripts/kernel-doc: handle object-like macros")
Signed-off-by: Randy Dunlap 
Cc: Jonathan Corbet 
Cc: linux-doc@vger.kernel.org
Acked-by: Daniel Vetter 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240107012400.32587-1-rdunlap@infradead.org

docs: add blurb about target audience to maintainer-profile

2024-01-30T20:16:46+00:00

It's good to be clear about who the intended target audience for any
given piece of documentation is, as this will help us put new text in
the correct place. Let's encourage submitters to state it explicitly
rather than relying on where they placed it in the directory hierarchy
as there isn't necessarily a one-to-one correspondence between them.

Target audience: documentation contributors and reviewers.

Signed-off-by: Vegard Nossum 
Acked-by: Randy Dunlap 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20240111094838.3695697-1-vegard.nossum@oracle.com

docs: Raise the minimum Sphinx requirement to 2.4.4

2023-12-15T15:36:33+00:00

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 
Link: https://lore.kernel.org/r/874jgs47fq.fsf@meer.lwn.net
Signed-off-by: Jonathan Corbet

docs: automarkup: linkify git revs

2023-11-17T20:13:24+00:00

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 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20231027115420.205279-1-vegard.nossum@oracle.com

docs: doc-guide: mention 'make refcheckdocs'

2023-10-23T02:38:55+00:00

Add this to the section on fixing warnings.

Cc: Mauro Carvalho Chehab 
Cc: Jonathan Corbet 
Signed-off-by: Vegard Nossum 
Signed-off-by: Jonathan Corbet 
Message-ID: <20231022184910.919201-1-vegard.nossum@oracle.com>

Documentation: doc-guide: use '%' constant indicator in Return: examples

2023-07-14T19:16:59+00:00

Use the 'constant' indicator '%' in the examples for the
Return: values syntax. This can help encourage people to use it.

Signed-off-by: Randy Dunlap 
Suggested-by: Steven Rostedt 
Cc: Jonathan Corbet 
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/lkml/20221121154358.36856ca6@gandalf.local.home/
Acked-by: Steven Rostedt (Google) 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/20230703232030.8223-1-rdunlap@infradead.org

docs/doc-guide: Clarify how to write tables

2023-06-09T07:57:56+00:00

Prior to this commit, the kernel docs writing guide spent over a page
describing exactly how *not* to write tables into the kernel docs,
without providing a example about the desired format.

This patch provides a positive example first in the guide so that it's
harder to miss, then leaves the existing less desirable approach below
for contributors to follow if they have some stronger justification for
why to use that approach.

Signed-off-by: Joe Stringer 
Reviewed-by: Randy Dunlap 
Link: https://lore.kernel.org/r/20230424171850.3612317-1-joe@isovalent.com
Signed-off-by: Jonathan Corbet

Merge branch 'alabaster-rb' into docs-mw

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

For a long time we have rejoiced that our HTML output from Sphinx is far
better than what we got from the old DocBook toolchain.  But it still
leaves a lot to be desired; the following is an attempt to improve the
situation somewhat.

Sphinx has a theming mechanism for HTML rendering.  Since the kernel's
adoption of Sphinx, we have been using the "Read The Docs" theme — a choice
made in a bit of a hurry to have *something* while figuring out the rest.
RTD is OK, but it is not hugely attractive, requires the installation of an
extra package, and does not observe all of the Sphinx configuration
parameters.  Among other things, that makes it hard to put reasonable
contents into the left column in the HTML output.

The Alabaster theme is the default for Sphinx installations, and is bundled
with Sphinx itself.  It has (IMO) nicer output and gives us the control
that we need.

So: switch to Alabaster.  Additional patches adjust the documentation and
remove the RTD references from scripts/sphinx-pre-install.

The penultimate patch changes the way that kerneldoc declarations are
rendered to (IMO) improve readability.  That requires some changes to
kernel-doc to output a new container block and some CSS tweaks to improve
things overall.

It should be noted that I have a long history of inflicting ugly web
designs on the net; this work is a start, but I think we could do far
better yet.  It would be great if somebody who actually enjoys working with
CSS and such would help to improve what we have.