aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/sphinx/kerneldoc.py
Commit message (Collapse)AuthorAgeFilesLines
* docs: kdoc: Remove a Python 2 commentJonathan Corbet2025-07-081-2/+0
| | | | | | | | | | | | We no longer support Python 2 in the docs build chain at all, so we certainly do not need to admonish folks to keep this file working with it. Cc: Jani Nikula <[email protected]> Reviewed-by: Mauro Carvalho Chehab <[email protected]> Acked-by: Jani Nikula <[email protected]> Tested-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* docs: sphinx: add missing SPDX tagsMauro Carvalho Chehab2025-06-251-0/+1
| | | | | | | | | Several Sphinx extensions and tools are missing SPDX tags. Add them. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/1a62226c5fe524eb87bdb80b33bc7ec880a68880.1750585188.git.mchehab+huawei@kernel.org
* docs: kerneldoc.py: simplify exception handling logicMauro Carvalho Chehab2025-05-211-63/+45
| | | | | | | | | | | | | | | Get rid of logger.verbose() which is causing the logger to not work. Also, instead of having try/except everywhere, place them on a common place. While here, get rid of some bogus logs. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Acked-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <a2cc32d5d519ed343158a915c39e8dc536a8ddb7.1747817887.git.mchehab+huawei@kernel.org>
* docs: Sphinx: kerneldoc: only initialize kernel-doc classes onceMauro Carvalho Chehab2025-04-281-12/+11
| | | | | | | | | | | Instead of re-creating the objects every time, initialize it just once. This allows caching previously parsed objects. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Message-ID: <b00788f26e161512858a6e01a673c34743c954df.1745564565.git.mchehab+huawei@kernel.org>
* docs: sphinx: kerneldoc: Use python class if availableMauro Carvalho Chehab2025-04-211-8/+130
| | | | | | | | | | | | Better integrate with the new kernel-doc tool by calling the Python classes directly if KERNELDOC=scripts/kernel-doc.py. This way, warnings won't be duplicated anymore, as files will be parsed only once. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/1556a6c005d8e0fafa951f74725e984e1c7459bf.1744685912.git.mchehab+huawei@kernel.org
* docs: sphinx: kerneldoc: ignore "\" characters from optionsMauro Carvalho Chehab2025-04-091-0/+12
| | | | | | | | | | | | | | | | | | | | | | | | | | | Documentation/driver-api/infiniband.rst has a kernel-doc tag with "\" characters at the end: .. kernel-doc:: drivers/infiniband/ulp/iser/iscsi_iser.c :functions: iscsi_iser_pdu_alloc iser_initialize_task_headers \ iscsi_iser_task_init iscsi_iser_mtask_xmit iscsi_iser_task_xmit \ iscsi_iser_cleanup_task iscsi_iser_check_protection \ iscsi_iser_conn_create iscsi_iser_conn_bind \ iscsi_iser_conn_start iscsi_iser_conn_stop \ iscsi_iser_session_destroy iscsi_iser_session_create \ iscsi_iser_set_param iscsi_iser_ep_connect iscsi_iser_ep_poll \ iscsi_iser_ep_disconnect This is not handled well, as the "\" strings will be just stored inside Sphinx options. While the actual problem deserves being fixed, better to relax the keneldoc.py extension to silently strip "\" from the end of strings, as otherwise this may cause troubles when preparing arguments to be executed by kernel-doc. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/4c652d6c57b20500c135b95294e554d9e9a97f42.1744106242.git.mchehab+huawei@kernel.org
* docs: sphinx: kerneldoc: verbose kernel-doc command if V=1Mauro Carvalho Chehab2025-04-091-0/+34
| | | | | | | | | | It is useful to know what kernel-doc command was used during document build time, as it allows one to check the output the same way as Sphinx extension does. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/a2f01590814b111e138f278e8a721024fdf2d445.1744106242.git.mchehab+huawei@kernel.org
* scripts/kernel-doc: drop Sphinx version checkMauro Carvalho Chehab2025-02-131-5/+0
| | | | | | | | | | As the current minimal supported Sphinx version is 3.4.3, drop support for older versions. 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/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org
* docs: sphinx: remove kernellog.py fileMauro Carvalho Chehab2025-02-101-7/+7
| | | | | | | | | | | In the past, there was a need for a wrapper due to different Sphinx versions support (before Sphinx 1.6). This is long gone, and now it is just a wrapper. Get rig of it to simplify the code. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/48bf16f199250d7048ca164d1b90773861915157.1739182025.git.mchehab+huawei@kernel.org
* doc: kerneldoc.py: fix indentationVegard Nossum2024-02-211-3/+3
| | | | | | | | | | | | | | kerneldoc.py is mostly indented with 4 spaces (like PEP8 suggests); replace the last remaining tabs for consistency. No functional change. Cc: Jani Nikula <[email protected]> Cc: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Vegard Nossum <[email protected]> Reviewed-by: Randy Dunlap <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* docs/sphinx: Explicitly convert Sphinx paths to strOliver Faso2023-10-101-1/+1
| | | | | | | | | | | | | 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 <[email protected]> Tested-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/[email protected]
* Documentation/sphinx: fix Python string escapesBenjamin Gray2023-09-121-1/+1
| | | | | | | | | | | | 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 <[email protected]> Message-ID: <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
* scripts/kernel-doc: change the line number meta infoMauro Carvalho Chehab2022-03-281-1/+1
| | | | | | | | | | | | | | | | 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 <[email protected]> Link: https://lore.kernel.org/r/40725032b5a4a33db740bf1de397523af958ff8a.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <[email protected]>
* Move our minimum Sphinx version to 1.7Jonathan Corbet2021-02-011-23/+3
| | | | | | | 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 <[email protected]>
* docs: kerneldoc.py: add support for kerneldoc -nosymbolMauro Carvalho Chehab2020-10-151-0/+7
| | | | | | | Currently, there's no way to exclude identifiers from a kernel-doc markup. Add support for it. Signed-off-by: Mauro Carvalho Chehab <[email protected]>
* docs: kerneldoc.py: append the name of the parsed doc fileMauro Carvalho Chehab2020-10-151-1/+2
| | | | | | | | | | | | | 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 <[email protected]>
* scripts: kernel-doc: allow passing desired Sphinx C domain dialectMauro Carvalho Chehab2020-10-151-0/+5
| | | | | | | | | | | | | | | | | | | | | | 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 <patch> argument. Thanks-to: Joe Perches <[email protected]> Suggested-by: Jonathan Corbet <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]>
* kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'Changbin Du2019-11-071-6/+11
| | | | | | | | | | | 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 <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
* doc: Cope with the deprecation of AutoReporterJonathan Corbet2019-05-231-8/+26
| | | | | | | | | | | | | | 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: [email protected] Signed-off-by: Jonathan Corbet <[email protected]>
* doc: Cope with Sphinx logging deprecationsJonathan Corbet2019-05-231-4/+8
| | | | | | | | | | | | | | | 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: [email protected] Signed-off-by: Jonathan Corbet <[email protected]>
* Documentation/sphinx: allow "functions" with no parametersMike Rapoport2018-06-301-3/+7
| | | | | | | | | | | | | | | | | | When kernel-doc:: specified in .rst document without explicit directives, it outputs both comment and DOC: sections. If a DOC: section was explicitly included in the same document it will be duplicated. For example, the output generated for Documentation/core-api/idr.rst [1] has "IDA description" in the "IDA usage" section and in the middle of the API reference. This patch enables using "functions" directive without parameters to output all the documentation excluding DOC: sections. [1] https://www.kernel.org/doc/html/v4.17/core-api/idr.html Signed-off-by: Mike Rapoport <[email protected]> Acked-by: Matthew Wilcox <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
* Documentation/sphinx: Fix Directive import errorMatthew Wilcox2018-03-091-2/+1
| | | | | | | | | | | | | | Sphinx 1.7 removed sphinx.util.compat.Directive so people who have upgraded cannot build the documentation. Switch to docutils.parsers.rst.Directive which has been available since docutils 0.5 released in 2009. Bugzilla: https://bugzilla.opensuse.org/show_bug.cgi?id=1083694 Co-developed-by: Takashi Iwai <[email protected]> Acked-by: Jani Nikula <[email protected]> Cc: [email protected] Signed-off-by: Matthew Wilcox <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
* Documentation/sphinx: fix kernel-doc decode for non-utf-8 localeJani Nikula2017-08-311-5/+3
| | | | | | | | | | | | | | | | | | | | | | On python3, Popen() universal_newlines=True converts the subprocess stdout to unicode text using a codec based on user preferences. Given LANG indicating ascii and utf-8 stdout from the subprocess, you'd get: WARNING: kernel-doc '../scripts/kernel-doc -rst -enable-lineno ../drivers/media/dvb-core/demux.h' processing failed with: 'ascii' codec can't decode byte 0xe2 in position 6368: ordinal not in range(128) Fix this by dropping universal_newlines=True and replacing the implicit LANG specific decode with an explicit utf-8 decode. This also gets rid of the annoying conditional code for python 2 vs. 3. Fixes: ba3501859354 ("Documentation/sphinx: fix kernel-doc extension on python3") Reference: http://mid.mail-archive.com/[email protected] Reported-and-tested-by: Randy Dunlap <[email protected]> Cc: Jonathan Corbet <[email protected]> Cc: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jani Nikula <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
* Documentation/sphinx: rename kernel-doc.py to kerneldoc.pyJani Nikula2016-10-191-0/+149
Python module names should not have hyphens per [PEP 8]. Drop the hyphen from kernel-doc.py. The extension directive remains unchanged. [PEP 8] https://www.python.org/dev/peps/pep-0008/#package-and-module-names Reported-by: Markus Heiser <[email protected]> Signed-off-by: Jani Nikula <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]>
generated by cgit (git 2.51.2) at 2025-12-01 11:00:32 +0000