aboutsummaryrefslogtreecommitdiffstats
path: root/Documentation/sphinx/kernel_abi.py
Commit message (Collapse)AuthorAgeFilesLines
* sphinx: kernel_abi: fix performance regression with O=<dir>Mauro Carvalho Chehab2025-07-241-2/+4
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | The logic there which adds a dependency note to Sphinx cache is not taking into account that the build dir may not be the source dir. This causes a performance regression: $ time make O=/tmp/foo SPHINXDIRS=admin-guide htmldocs [OUTDATED] Added: set() Changed: {'abi-obsolete', 'abi-removed', 'abi-stable-files', 'abi-obsolete-files', 'abi-stable', 'abi', 'abi-removed-files', 'abi-testing-files', 'abi-testing', 'gpio/index', 'gpio/obsolete'} Removed: set() All docs count: 385 Found docs count: 385 real 0m11,324s user 0m15,783s sys 0m1,164s To get the root cause of the problem (ABI files reported as changed), I used this changeset: diff --git a/Documentation/conf.py b/Documentation/conf.py index e8766e689c1b..ab486623bd8b 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -571,3 +571,16 @@ def setup(app): """Patterns need to be updated at init time on older Sphinx versions""" app.connect('config-inited', update_patterns) + app.connect('env-get-outdated', on_outdated) + +def on_outdated(app, env, added, changed, removed): + """Track cache outdated due to added/changed/removed files""" + print("\n[OUTDATED]") + print(f"Added: {added}") + print(f"Changed: {changed}") + print(f"Removed: {removed}") + print(f"All docs count: {len(env.all_docs)}") + print(f"Found docs count: {len(env.found_docs)}") + + # Just return what we have + return added | changed | removed Reported-by: Akira Yokosawa <[email protected]> Closes: https://lore.kernel.org/linux-doc/[email protected]/ Signed-off-by: Mauro Carvalho Chehab <[email protected]> Tested-by: Akira Yokosawa <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/e25673d87357457bc54ee863e97ff8f75956580d.1752752211.git.mchehab+huawei@kernel.org
* docs: extensions: don't use utf-8 syntax for descriptionsMauro Carvalho Chehab2025-02-131-3/+3
| | | | | | | | | | | | | | | | | | None of the descriptions at the Sphinx extensions are using non-ascii characters, so no need to place them under u""" notation. Also, according with: https://docs.python.org/3/deprecations/pending-removal-in-3.16.html the 'u' format code is scheduled to be removed in Python 3.16. So, let's just use """. 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/8a42f6be53464af4b866492a7e9ddf29c0429997.1739254187.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: avoid warnings during Sphinx module initMauro Carvalho Chehab2025-02-101-4/+19
| | | | | | | | | | | | | | | | Sphinx logging system doesn't like warnings during module load, as it understands that such logs are produced at the wrong time: WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cpuX/topology/physical_package_id is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:27; /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70 WARNING: while setting up extension automarkup: /sys/devices/system/cpu/cpuX/topology/ppin is defined 2 times: /new_devel/v4l/docs/Documentation/ABI/stable/sysfs-devices-system-cpu:89; /new_devel/v4l/docs/Documentation/ABI/testing/sysfs-devices-system-cpu:70 So, use a function to allocate/process ABI files and use it to be called at kernel_abi.py, as automarkup also needs it to produce the right cross-references. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/b0e79dc60d556e3b39fa6774d3b7bf734b73f352.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: parse ABI files only onceMauro Carvalho Chehab2025-02-101-45/+58
| | | | | | | | | | | | | Right now, the logic parses ABI files on 4 steps, one for each directory. While this is fine in principle, by doing that, not all symbol cross-references will be created. Change the logic to do the parsing only once in order to get a global dictionary to be used when creating ABI cross-references. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/5205c53838b6ea25f4cdd4cc1e3d17c0141e75a6.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: properly split linesMauro Carvalho Chehab2025-02-101-2/+3
| | | | | | | | | | | Sphinx doesn't like to have lines split with str.split("\n"). Instead, it uses its own splitter, with handles line breaks the way Spinx expects. Not using it cause issues at the output files. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/d4ad5b977799616544376210364d5cec686119ef.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: reduce buffer usage for ABI messagesMauro Carvalho Chehab2025-02-101-37/+39
| | | | | | | | | | | | Instead of producing a big message with all ABI contents and then parse as a whole, simplify the code by handling each ABI symbol in separate. As an additional benefit, there's no need to place file/line nubers inlined at the data and use a regex to convert them. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/15be22955e3c6df49d7256c8fd24f62b397ad0ff.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: use AbiParser directlyMauro Carvalho Chehab2025-02-101-13/+16
| | | | | | | | | | | Instead of running get_abi.py script, import AbiParser class and handle messages directly there using an interactor. This shold save some memory, as there's no need to exec python inside the Sphinx python extension. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/8dbc244dcda97112c1b694e2512a5d600e62873b.1739182025.git.mchehab+huawei@kernel.org
* docs: use get_abi.py for ABI generationMauro Carvalho Chehab2025-02-101-7/+3
| | | | | | | | | | | Use the new script instead of the old one when generating ABI docs. For now, execute it via exec. Future changes will better integrate it by using the class defined there directly. Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/e7fcb121c0612c94f6f54f0d742cd3a26a46cd7d.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx/kernel_abi: adjust coding styleMauro Carvalho Chehab2025-02-101-13/+12
| | | | | | | | Make pylint and flake8 happier with this module's coding style Signed-off-by: Mauro Carvalho Chehab <[email protected]> Signed-off-by: Jonathan Corbet <[email protected]> Link: https://lore.kernel.org/r/02a9ec0fab61e4c94b9c2ff555bc0e9d93f59100.1739182025.git.mchehab+huawei@kernel.org
* docs: sphinx: remove kernellog.py fileMauro Carvalho Chehab2025-02-101-2/+3
| | | | | | | | | | | 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
* docs: kernel_abi.py: fix command injectionVegard Nossum2024-01-031-46/+10
| | | | | | | | | | | | | | | | | The kernel-abi directive passes its argument straight to the shell. This is unfortunate and unnecessary. Let's always use paths relative to $srctree/Documentation/ and use subprocess.check_call() instead of subprocess.Popen(shell=True). This also makes the code shorter. Link: https://fosstodon.org/@jani/111676532203641247 Reported-by: Jani Nikula <[email protected]> Cc: [email protected] Signed-off-by: Vegard Nossum <[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/get_abi: change the file/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/125ffd31fbc77ad9eee4d6906e1830b8162fa6ca.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <[email protected]>
* docs: kernel_abi.py: add sphinx build dependenciesMauro Carvalho Chehab2022-03-281-0/+4
| | | | | | | | | | | Ensure that Sphinx-build will handle the files parsed by get_abi.pl as dependencies. This way, if they are touched, the ABI output will be regenerated. Reported-by: Hans de Goede <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/10bc3d3bc74f514a539cd3b48b9d287d2b6f99e2.1648290305.git.mchehab@kernel.org Signed-off-by: Jonathan Corbet <[email protected]>
* Documentation/sphinx: fix typos of "its"Randy Dunlap2021-12-231-1/+1
| | | | | | | | | | Use "its" for possessive form instead of the contraction "it's". Signed-off-by: Randy Dunlap <[email protected]> Cc: Jonathan Corbet <[email protected]> Cc: [email protected] Link: https://lore.kernel.org/r/[email protected] Signed-off-by: Jonathan Corbet <[email protected]>
* Move our minimum Sphinx version to 1.7Jonathan Corbet2021-02-011-24/+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: ABI: make it parse ABI/stable as ReST-compatible filesMauro Carvalho Chehab2020-10-301-2/+6
| | | | | | | | | | | | | | Now that the stable ABI files are compatible with ReST, parse them without converting complex descriptions as literal blocks nor escaping special characters. Please notice that escaping special characters will probably be needed at descriptions, at least for the asterisk character. Acked-by: Jonathan Corbet <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/59ccbaa75ff05f23e701dd9a0bbe118e9343a553.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <[email protected]>
* docs: kernel_abi.py: Handle with a lazy Sphinx parserMauro Carvalho Chehab2020-10-301-13/+26
| | | | | | | | | | | | | | The Sphinx docutils parser is lazy: if the content is bigger than a certain number of lines, it silenlty stops parsing it, producing an incomplete content. This seems to be worse on newer Sphinx versions, like 2.0. So, change the logic to parse the contents per input file. Acked-by: Jonathan Corbet <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/4659b60795739308e34d2d00c57ee0742a9cd2ab.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <[email protected]>
* docs: kernel_abi.py: use --enable-lineno for get_abi.plMauro Carvalho Chehab2020-10-301-4/+14
| | | | | | | | | | | | | | | | | | | Just like kernel-doc extension, we need to be able to identify what part of an imported document has issues, as reporting them as: get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation. Makes a lot harder for someone to fix. It should be noticed that it the line which will be reported is the line where the "What:" definition is, and not the line with actually has an error. Acked-by: Jonathan Corbet <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/d6155ab16fb7631f2fa8e7a770eae72f24bf7cc5.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <[email protected]>
* docs: kernel_abi.py: make it compatible with Sphinx 1.7+Mauro Carvalho Chehab2020-10-301-12/+27
| | | | | | | | | | | | The same way kerneldoc.py needed changes to work with newer Sphinx, this script needs the same changes. While here, reorganize the include order to match kerneldoc.py. Acked-by: Jonathan Corbet <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/f2b25caef5db7738629773a03463908d3b39b83a.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <[email protected]>
* docs: kernel_abi.py: fix UTF-8 supportMauro Carvalho Chehab2020-10-301-12/+7
| | | | | | | | | The parser breaks with UTF-8 characters with Sphinx 1.4. Acked-by: Jonathan Corbet <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/9e7c8e3b0efaa1ae0536da6493ab438bd3f9fe58.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <[email protected]>
* docs: kernel_abi.py: add a script to parse ABI documentationMauro Carvalho Chehab2020-10-301-0/+157
The ABI documentation is special: it is not plain text files, but, instead, files with an strict format, as specified by Documentation/ABI/README. Add a parser for it. Acked-by: Jonathan Corbet <[email protected]> Signed-off-by: Mauro Carvalho Chehab <[email protected]> Link: https://lore.kernel.org/r/48abf1a410237e63f85354a8cd7027fdf25657bf.1604042072.git.mchehab+huawei@kernel.org Signed-off-by: Greg Kroah-Hartman <[email protected]>
generated by cgit (git 2.51.2) at 2025-12-02 06:07:41 +0000