lwn.git/Documentation/sphinx/kerneldoc.py, branch docs-6.8-2

docs/sphinx: Explicitly convert Sphinx paths to str

2023-10-10T19:35:54+00:00

Sphinx 7.2+ is switching to using pathlib.Path instead of str to represent paths. This fixes the current deprecation warnings and eventual breakage. This conversion will be a no-op when using older Sphinx versions. Signed-off-by: Oliver Faso Tested-by: Akira Yokosawa Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20230910040811.53046-1-erer1243@gmail.com

Documentation/sphinx: fix Python string escapes

2023-09-12T20:27:45+00:00

Python 3.6 introduced a DeprecationWarning for invalid escape sequences. This is upgraded to a SyntaxWarning in Python 3.12, and will eventually be a syntax error. Fix these now to get ahead of it before it's an error. Signed-off-by: Benjamin Gray Message-ID: <20230912060801.95533-3-bgray@linux.ibm.com> Signed-off-by: Jonathan Corbet

scripts/kernel-doc: change the line number meta info

2022-03-28T19:53:46+00:00

In order to make it more standard and ReST compatible, change the meta-tag used with --enable-lineno from: #define LINENO to .. LINENO In practice, no functional changes. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet

Move our minimum Sphinx version to 1.7

2021-02-01T23:29:12+00:00

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

docs: kerneldoc.py: add support for kerneldoc -nosymbol

2020-10-15T05:49:38+00:00

Currently, there's no way to exclude identifiers from a kernel-doc markup. Add support for it. Signed-off-by: Mauro Carvalho Chehab

docs: kerneldoc.py: append the name of the parsed doc file

2020-10-15T05:49:37+00:00

Finding where an error like this was generated: ../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'. Can take some time, as there's no glue about what kernel-doc tag generated it. It is a way better to display it as: .../Documentation/core-api/kernel-api:171: ../lib/math/div64.c:73: WARNING: Duplicate C declaration, also defined in 'kernel-api'. Declaration is 'div_s64_rem'. Signed-off-by: Mauro Carvalho Chehab

scripts: kernel-doc: allow passing desired Sphinx C domain dialect

2020-10-15T05:49:36+00:00

When kernel-doc is called via kerneldoc.py, there's no need to auto-detect the Sphinx version, as the Sphinx module already knows it. So, add an optional parameter to allow changing the Sphinx dialect. As kernel-doc can also be manually called, keep the auto-detection logic if the parameter was not specified. On such case, emit a warning if sphinx-build can't be found at PATH. I ended using a suggestion from Joe for using a more readable regex, instead of using a complex one with a hidden group like: m/^(\d+)\.(\d+)(?:\.?(\d+)?)/ in order to get the optional argument. Thanks-to: Joe Perches Suggested-by: Jonathan Corbet Signed-off-by: Mauro Carvalho Chehab

kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'

2019-11-07T20:17:25+00:00

The 'functions' directive is not only for functions, but also works for structs/unions. So the name is misleading. This patch renames it to 'identifiers', which specific the functions/types to be included in documentation. We keep the old name as an alias of the new one before all documentation are updated. Signed-off-by: Changbin Du Signed-off-by: Jonathan Corbet

doc: Cope with the deprecation of AutoReporter

2019-05-23T15:23:11+00:00

AutoReporter is going away; recent versions of sphinx emit a warning like: Documentation/sphinx/kerneldoc.py:125: RemovedInSphinx20Warning: AutodocReporter is now deprecated. Use sphinx.util.docutils.switch_source_input() instead. Make the switch. But switch_source_input() only showed up in 1.7, so we have to do ugly version checks to keep things working in older versions. Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet

doc: Cope with Sphinx logging deprecations

2019-05-23T15:22:00+00:00

Recent versions of sphinx will emit messages like: Documentation/sphinx/kerneldoc.py:103: RemovedInSphinx20Warning: app.warning() is now deprecated. Use sphinx.util.logging instead. Switch to sphinx.util.logging to make this unsightly message go away. Alas, that interface was only added in version 1.6, so we have to add a version check to keep things working with older sphinxes. Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet