summaryrefslogtreecommitdiff
AgeCommit message (Collapse)Author
2025-11-03MAINTAINERS: extend DOCUMENTATION SCRIPTS to the full directoriesLukas Bulwahn
Due to commit abd61d1ff8f0 ("scripts: sphinx-pre-install: move it to tools/docs"), checkpatch.pl --self-test=patterns reported a non-matching file entry in DOCUMENTATION SCRIPTS. Clearly, there are now multiple documentation scripts, all located in Documentation/sphinx/ and tools/docs/ and Mauro is the maintainer of those. Update the DOCUMENTATION SCRIPTS section to cover these directories. While at it, also make the DOCUMENTATION section cover the subdirectories of tools/docs/. Signed-off-by: Lukas Bulwahn <lukas.bulwahn@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251103075948.26026-1-lukas.bulwahn@redhat.com>
2025-11-03Merge branch 'tools-final2' into docs-mwJonathan Corbet
Our documentation-related tools are spread out over various directories; several are buried in the scripts/ dumping ground. That makes them harder to discover and harder to maintain. Recent work has started accumulating our documentation-related tools in /tools/docs. This series nearly completes that task, moving most of the rest of our various utilities there, hopefully fixing up all of the relevant references in the process. The one exception is scripts/kernel-doc; that move turned up some other problems, so I have dropped it until those are ironed out. At the end, rather than move the old, Perl kernel-doc, I simply removed it.
2025-11-03Documentation: treewide: Replace marc.info links with loreBagas Sanjaya
In the past, people would link to third-party mailing list archives (like marc.info) for any kernel-related discussions. Now that there is lore archive under kernel.org infrastructure, replace these marc links Note that the only remaining marc link is "Re: Memory mapping on Cirrus EP9315" [1] since that thread is not available at lore [2]. [1]: https://marc.info/?l=linux-arm-kernel&m=110061245502000&w=2 [2]: https://lore.kernel.org/linux-arm-kernel/?q=b%3A%22Re%3A+Memory+mapping+on+Cirrus+EP9315%22 Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Lance Yang <lance.yang@linux.dev> Acked-by: SeongJae Park <sj@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251031043358.23709-1-bagasdotme@gmail.com>
2025-11-03Merge tag 'Chinese-docs-6.18' of ↵Jonathan Corbet
gitolite.kernel.org:pub/scm/linux/kernel/git/alexs/linux into alex Chinese translation docs for 6.18 This is the Chinese translation subtree for 6.18. It includes the following changes: - docs/zh_CN: Add rust Chinese translations - docs/zh_CN: Add scsi Chinese translations - docs/zh_CN: Add gfs2 Chinese translations - Add some other Chinese translations and fixes Above patches are tested by 'make htmldocs'
2025-11-03coding-style: fix verb typoGabriele Ricciardi
In the Identation section there is a list of instructions in second-person. The offending line uses third-person singular. Signed-off-by: Gabriele Ricciardi <gricciardi-coding@pm.me> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251101223027.171874-1-gricciardi-coding@pm.me>
2025-10-31Revert "Docs/zh_CN: Translate skbuff.rst to Simplified Chinese"Alex Shi
This reverts commit d3e7609c6e5ec92587ed1043a985749d22cc78d1. The commit cause a warning: Documentation/networking/skbuff.rst:34: WARNING: duplicate label crc, other instance in Documentation/translations/zh_CN/networking/skbuff.rst And there's no simple way to keep the meaningful doc context and avoid the warning, so, let's remove the doc. Signed-off-by: Alex Shi <alexs@kernel.org>
2025-10-30docs: kdoc: fix duplicate section warning messageJacob Keller
The python version of the kernel-doc parser emits some strange warnings with just a line number in certain cases: $ ./scripts/kernel-doc -Wall -none 'include/linux/virtio_config.h' Warning: 174 Warning: 184 Warning: 190 Warning: include/linux/virtio_config.h:226 No description found for return value of '__virtio_test_bit' Warning: include/linux/virtio_config.h:259 No description found for return value of 'virtio_has_feature' Warning: include/linux/virtio_config.h:283 No description found for return value of 'virtio_has_dma_quirk' Warning: include/linux/virtio_config.h:392 No description found for return value of 'virtqueue_set_affinity' I eventually tracked this down to the lone call of emit_msg() in the KernelEntry class, which looks like: self.emit_msg(self.new_start_line, f"duplicate section name '{name}'\n") This looks like all the other emit_msg calls. Unfortunately, the definition within the KernelEntry class takes only a message parameter and not a line number. The intended message is passed as the warning! Pass the filename to the KernelEntry class, and use this to build the log message in the same way as the KernelDoc class does. To avoid future errors, mark the warning parameter for both emit_msg definitions as a keyword-only argument. This will prevent accidentally passing a string as the warning parameter in the future. Also fix the call in dump_section to avoid an unnecessary additional newline. Fixes: e3b42e94cf10 ("scripts/lib/kdoc/kdoc_parser.py: move kernel entry to a class") Signed-off-by: Jacob Keller <jacob.e.keller@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251030-jk-fix-kernel-doc-duplicate-return-warning-v2-1-ec4b5c662881@intel.com>
2025-10-29Documentation: fix reference to PR_SPEC_L1D_FLUSHBrendan Jackman
PR_SET_L1D_FLUSH does not exist. Signed-off-by: Brendan Jackman <jackmanb@google.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251015-l1d-flush-doc-v1-2-f8cefea3f2f2@google.com>
2025-10-29Documentation: clarify PR_SPEC_L1D_FLUSHBrendan Jackman
For PR_SPEC_STORE_BYPASS and PR_SPEC_INDIRECT_BRANCH, PR_SPEC_DISABLE means "disable the speculation bug" i.e. "enable the mitigation". For PR_SPEC_L1D_FLUSH, PR_SPEC_DISABLE means "disable the mitigation". This is not obvious, so document it. Signed-off-by: Brendan Jackman <jackmanb@google.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251015-l1d-flush-doc-v1-1-f8cefea3f2f2@google.com>
2025-10-29Documentation: process: Also mention Sasha Levin as stable tree maintainerBagas Sanjaya
Sasha has also maintaining stable branch in conjunction with Greg since cb5d21946d2a2f ("MAINTAINERS: Add Sasha as a stable branch maintainer"). Mention him in 2.Process.rst. Cc: stable@vger.kernel.org Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251022034336.22839-1-bagasdotme@gmail.com>
2025-10-29docs: replace broken links in ramfs-rootfs-initramfs docsNadav Tasher
http://www.uwsg.iu.edu/ doesn't seem to exist anymore. I managed to find backups on archive.org, which helped me find the right links on https://lore.kernel.org/. http://freecode.com/projects/afio was also down, so I figured it could be replaced with https://linux.die.net/man/1/afio. Replace broken links to mailing list and aifo tool. Signed-off-by: Nadav Tasher <tashernadav@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251025171625.33197-1-tashernadav@gmail.com>
2025-10-29tools/docs/sphinx-build-wrapper: Emit $SPHINXOPTS later in args listAkira Yokosawa
The option list to sphinx-build via SPHINXOPTS should have higher priority than those the wrapper comes up with. sphinx-build will choose the latest one if there are duplicates. To restore the behavior of Makefile era, when the documentation builds at https://www.kernel.org/doc/html/next/ had been depending on it, reorder the flag list. Reported-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org> Closes: https://lore.kernel.org/20251007-awesome-guan-of-greatness-e6ec75@lemur/ Reported-by: Akira Yokosawa <akiyks@gmail.com> Closes: https://lore.kernel.org/c35e690f-0579-49cb-850c-07af98e5253a@gmail.com/ Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <eaf4bfd8-fb80-45d0-b3ec-4047692ebbed@gmail.com>
2025-10-28docs: remove kernel-doc.plJonathan Corbet
We've been using the Python version and nobody has missed this one. All credit goes to Mauro Carvalho Chehab for creating the replacement. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move find-unused-docs.sh to tools/docsJonathan Corbet
...and update references accordingly. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move test_doc_build.py to tools/docsJonathan Corbet
Add this tool to tools/docs. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move get_abi.py to tools/docsJonathan Corbet
Move this tool out of scripts/ to join the other documentation tools; fix up a couple of erroneous references in the process. It's worth noting that this script will fail badly unless one has a PYTHONPATH referencing scripts/lib/abi. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move scripts/documentation-file-ref-check to tools/docsJonathan Corbet
Add this script to the growing collection of documentation tools. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: move checktransupdate.py to tools/docsJonathan Corbet
The checktranslate.py tool currently languishes in scripts/; move it to tools/docs and update references accordingly. Cc: Alex Shi <alexs@kernel.org> Cc: Yanteng Si <si.yanteng@linux.dev> Cc: Dongliang Mu <dzm91@hust.edu.cn> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-28docs: Move the "features" tools to tools/docsJonathan Corbet
The scripts for managing the features docs are found in three different directories; unite them all under tools/docs and update references as needed. Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Acked-by: Jani Nikula <jani.nikula@intel.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2025-10-21docs: checkpatch: Drop networking comment styleBrian Norris
Networking no longer has their own comment style, and checkpatch no longer checks for this. Signed-off-by: Brian Norris <briannorris@chromium.org> Suggested-by: Randy Dunlap <rdunlap@infradead.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251017203719.1554224-2-briannorris@chromium.org>
2025-10-21docs: checkpatch: Align block comment styleBrian Norris
Ironically, the block style comments in the checkpatch documentation are not aligned properly. Correct that. Signed-off-by: Brian Norris <briannorris@chromium.org> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251017203719.1554224-1-briannorris@chromium.org>
2025-10-21Documentation: fix dev-tools broken links in translationsAlly Heev
gdb and kgdb debugging documentation were moved to Documentation/process/debugging/ as a part of Commit d5af79c05e9382d38b8546dc5362381ce07ba3d1 ("Documentation: move dev-tools debugging files to process/debugging/"), but translations/ were not updated. Fix them Signed-off-by: Ally Heev <allyheev@gmail.com> Fixes: d5af79c05e938 ("Documentation: move dev-tools debugging files to process/debugging/") Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251020-aheev-fix-docs-dev-tools-broken-links-v2-1-7db64bf0405a@gmail.com>
2025-10-18docs/zh_CN: Add translation of rust/testing.rstBen Guo
Complete the translation of rust/testing.rst and add the testing TOC entry to rust/index.rst. Add the translation based on commit a3b2347343e0 ("Documentation: rust: testing: add docs on the new KUnit `#[test]` tests"). Signed-off-by: Ben Guo <benx.guo@gmail.com> Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cm> Signed-off-by: Alex Shi <alexs@kernel.org>
2025-10-18docs/zh_CN: Add secrets coco Chinese translationShuo Zhao
Translate .../security/secrets/coco.rst into Chinese. Update the translation through commit d56b699d76d1 ("Documentation: Fix typos"). Signed-off-by: Shuo Zhao <zhaoshuo@cqsoftware.com.cn> Reviewed-by: Yanteng Si <siyanteng@cqsoftware.com.cn> Signed-off-by: Alex Shi <alexs@kernel.org>
2025-10-17Documentation/rtla: rename common_xxx.rst files to common_xxx.txtGopi Krishna Menon
Sphinx reports htmldocs errors: Documentation/tools/rtla/common_options.rst:58: ERROR: Undefined substitution referenced: "threshold". Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "tool". Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "thresharg". Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "tracer". Documentation/tools/rtla/common_options.rst:92: ERROR: Undefined substitution referenced: "tracer". Documentation/tools/rtla/common_options.rst:98: ERROR: Undefined substitution referenced: "actionsperf". Documentation/tools/rtla/common_options.rst:113: ERROR: Undefined substitution referenced: "tool". common_*.rst files are snippets that are intended to be included by rtla docs (rtla*.rst). common_options.rst in particular contains substitutions which depend on other common_* includes, so building it independently as reST source results in above errors. Rename all common_*.rst files to common_*.txt to prevent Sphinx from building these snippets as standalone reST source and update all include references accordingly. Link: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions Suggested-by: Tomas Glozar <tglozar@redhat.com> Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Gopi Krishna Menon <krishnagopi487@gmail.com> Reviewed-by: Tomas Glozar <tglozar@redhat.com> Fixes: 05b7e10687c6 ("tools/rtla: Add remaining support for osnoise actions") Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> Link: https://lore.kernel.org/r/20251008184522.13201-1-krishnagopi487@gmail.com [Bagas: massage commit message and apply trailers] Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251013092719.30780-2-bagasdotme@gmail.com>
2025-10-17Documentation: assoc_array: Format internal tree layout tablesBagas Sanjaya
Format tables in "Basic internal tree layout" as reST tables. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251013095630.34235-4-bagasdotme@gmail.com>
2025-10-17Documentation: assoc_array: Indent function explanation textBagas Sanjaya
Paragraphs of function explanation are currently not indented following their appropriate numbered list item, which causes only the first paragraph and function prototype code blocks to be indented in the numbered list in htmldocs output. Indent the explanation. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> Tested-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20251013095630.34235-3-bagasdotme@gmail.com>
2025-10-17docs: admin-guide: Fix a typo in kernel-parameters.txtYohei Kojima
Fix a typo in the stacktrace parameter description in kernel-parameters.txt Signed-off-by: Yohei Kojima <Yohei.Kojima@sony.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <edda15e3fcae13265278d3c3bd93ab077345d78f.1760498951.git.Yohei.Kojima@sony.com>
2025-10-17Merge branch 'build-script' into docs-mwJonathan Corbet
Quoth Mauro: This series should probably be called: "Move the trick-or-treat build hacks accumulated over time into a single place and document them." as this reflects its main goal. As such: - it places the jobserver logic on a library; - it removes sphinx/parallel-wrapper.sh; - the code now properly implements a jobserver-aware logic to do the parallelism when called via GNU make, failing back to "-j" when there's no jobserver; - converts check-variable-fonts.sh to Python and uses it via function call; - drops an extra script to generate man pages, adding a makefile target for it; - ensures that return code is 0 when PDF successfully builds; - about half of the script is comments and documentation. I tried to do my best to document all tricks that are inside the script. This way, the docs build steps is now documented. It should be noticed that it is out of the scope of this series to change the implementation. Surely the process can be improved, but first let's consolidate and document everything on a single place. Such script was written in a way that it can be called either directly or via a Makefile. Running outside Makefile is interesting specially when debug is needed. The command line interface replaces the need of having lots of env vars before calling sphinx-build: $ ./tools/docs/sphinx-build-wrapper --help usage: sphinx-build-wrapper [-h] [--sphinxdirs SPHINXDIRS [SPHINXDIRS ...]] [--conf CONF] [--builddir BUILDDIR] [--theme THEME] [--css CSS] [--paper {,a4,letter}] [-v] [-j JOBS] [-i] [-V [VENV]] {cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs} Kernel documentation builder positional arguments: {cleandocs,linkcheckdocs,htmldocs,epubdocs,texinfodocs,infodocs,mandocs,latexdocs,pdfdocs,xmldocs} Documentation target to build options: -h, --help show this help message and exit --sphinxdirs SPHINXDIRS [SPHINXDIRS ...] Specific directories to build --conf CONF Sphinx configuration file --builddir BUILDDIR Sphinx configuration file --theme THEME Sphinx theme to use --css CSS Custom CSS file for HTML/EPUB --paper {,a4,letter} Paper size for LaTeX/PDF output -v, --verbose place build in verbose mode -j, --jobs JOBS Sets number of jobs to use with sphinx-build -i, --interactive Change latex default to run in interactive mode -V, --venv [VENV] If used, run Sphinx from a venv dir (default dir: sphinx_latest) the only mandatory argument is the target, which is identical with "make" targets. The call inside Makefile doesn't use the last four arguments. They're there to help identifying problems at the build: -v makes the output verbose; -j helps to test parallelism; -i runs latexmk in interactive mode, allowing to debug PDF build issues; -V is useful when testing it with different venvs. When used with GNU make (or some other make which implements jobserver), a call like: make -j <targets> htmldocs will make the wrapper to automatically use POSIX jobserver to claim the number of available job slots, calling sphinx-build with a "-j" parameter reflecting it. ON such case, the default can be overriden via SPHINXDIRS argument. Visiable changes when compared with the old behavior: When V=0, the only visible difference is that: - pdfdocs target now returns 0 on success, 1 on failures. This addresses an issue over the current process where we it always return success even on failures; - it will now print the name of PDF files that failed to build, if any. In verbose mode, sphinx-build-wrapper and sphinx-build command lines are now displayed.
2025-10-17Merge branch 'media-uapi' into docs-mwJonathan Corbet
Mauro says: In the past, media used Docbook to generate documentation, together with some logic to ensure that cross-references would match the actual defined uAPI. The rationale is that we wanted to automatically check for uAPI documentation gaps. The same logic was migrated to Sphinx. Back then, broken links were reported. However, recent versions of it and/or changes at conf.py disabled such checks. The result is that several symbols are now not cross-referenced, and we don't get warnings anymore when something breaks. This series consist on 2 parts: Part 1: extra patches to parse_data_structs.py and kernel_include.py; Part 2: media documentation fixes.
2025-10-17docs: media: dvb: fix dmx.h.rst.exceptionsMauro Carvalho Chehab
There are lots of broken links on dmx. Those are mostly linked to namespace handling. Yet, some symbols were pointed to the wrong locations, and there are some definitions that aren't needed. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <b2acf243771529daa925afddd2b68d07d7bbb164.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: dvb: headers: warn about broken cross referencesMauro Carvalho Chehab
Enable cross-reference warnings for demux header. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8f98dde399df8b937dadf09168194bacce682c7d.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: dmx_types: place kerneldoc at the right namespaceMauro Carvalho Chehab
The DVB documentation is using DTV.dmx for all demux symbols. Use such domain for kernel-doc documentation. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <27fcc036fb5c80bda8116029e1964ad229208095.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: cec: show broken xrefs and show TOC instead of cec.h contentMauro Carvalho Chehab
Enable xref broken warnings. While here, change the output to only show cross-references, as there's no need to show the entire cec.h header at the docs. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <c587872ca3685213d9f8e88277404c9e253633df.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: cec: cec.h.rst.exceptions: fix broken references from cec.hMauro Carvalho Chehab
All references there belong to CEC namespace. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <dd1270dd5d91538cdfb0b087127c53a9f4ba7885.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17media: docs: add some C domain missing referencesMauro Carvalho Chehab
Some enum/struct fields don't contain C domain references. Add them to avoid broken xrefs. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <c9b036938197f1dd5bc93f5c5be0245bd9e5d1ee.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17media: docs: videodev2.h.rst.exceptions: ignore struct __kernel_v4l2_timevalMauro Carvalho Chehab
This is an ancillary struct used for year-2038 compat logic. It is not meant to be used directly on userspace. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <a6a0dc7366b1a5d7184b8f7d4ba27689051a1f6a.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17media: docs: add a missing reference for VIDIOC_QUERY_CTRLMauro Carvalho Chehab
This one is missing its c:macro definition. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <46f86be6ace28abe83ea9ce6fa6138e40185a23a.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: videodev2.h.rst.exceptions: fix namespace on refsMauro Carvalho Chehab
Media uses V4L domain, but the replace rules are not considering it. Fix them. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <927f9c19d90b62ffda950cdac9bba23c2ca09f53.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: add missing c namespace to V4L headersMauro Carvalho Chehab
Media references belong to V4L namespace. Fix a lot of broken links when including videodev2.h and probably fixing several other broken cross-references between different files inside media docs. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <b69fc5bd43da7d326b9f4720df59388088c64065.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: kernel_include.py: use get_close_matches() to propose alternativesMauro Carvalho Chehab
Improve the suggestions algorithm by using get_close_matches() if no suggestions with the same name are found. As we're now building a dict, when the name is identical, but on a different domain, the search is O(1), making it a lot faster. The get_close_matches is also fast, as there is just one loop, instead of 3. This can be useful to detect typos on references, with could be the base of a futuere extension that will handle ref unmatches for the entire build, allowing someone to find typos and fix them. As difflib and get_close_matches are there since the early Python 3.x days, we don't need to handle any extra dependencies to use it. We're keeping the default values for the search, e.g. n=3, cutoff=0.6. With that, we now have things like: $ make SPHINXDIRS="userspace-api/media" htmldocs ... include/uapi/linux/videodev2.h:199: WARNING: Invalid xref: c:type:`v4l2_memory`. Possible alternatives: c:type:`v4l2_meta_format` (from v4l/dev-meta) c:type:`v4l2_rect` (from v4l/dev-overlay) c:type:`v4l2_area` (from v4l/ext-ctrls-image-source) [ref.missing] ... include/uapi/linux/videodev2.h:1985: WARNING: Invalid xref: c:type:`V4L.v4l2_queryctrl`. Possible alternatives: std:label:`v4l2-queryctrl` (from v4l/vidioc-queryctrl) std:label:`v4l2-query-ext-ctrl` (from v4l/vidioc-queryctrl) At the first example, it was not a typo, but a symbol that doesn't seem to be properly documented. The second example points to v4l2-queryctrl, which is a close match for the symbol. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <7365feb74cbdd6b982c87baf5863360ab98cf727.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: mediactl: use TOC instead of file contentsMauro Carvalho Chehab
All we wanted were to have a way to link the comprehensive documentation with the actual symbols parsed from the header file, as this helps to identify any broken references. Use the new :toc: flag for media controller and enable warnings. Here, we need to adjust the exceptions file to setup the C namespace accordingly. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <5c8a87be712397563fc8ca914c3d92fe675e4071.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: rc: use TOC instead of file contents for LIRC headerMauro Carvalho Chehab
All we wanted were to have a way to link the comprehensive documentation with the actual symbols parsed from the header file, as this helps to identify any broken references. Use the new :toc: flag for LIRC and enable warnings. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <94dc601b4777ca544489ffc6cef9a2da5fe28e0e.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: dvb: enable warnings for most headersMauro Carvalho Chehab
Except for two exception rules and dmx.h, the other files are already handling properly cross references. Fix the two exception rules for frontend.h, as those are false-positives: include/uapi/linux/dvb/frontend.h:959: WARNING: can't link to: c:type:: FE_GET_PROPERTY include/uapi/linux/dvb/frontend.h:933: WARNING: can't link to: c:func:: FE_SET_FRONTEND_TUNE_MODE The dmx.h are actual issues that will require an extra patch to fill gaps. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <9ae6556ebd47de4f066a149ab0bbe7ce27acf2c4.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: media: dvb: use TOC instead of file contents at headersMauro Carvalho Chehab
All we wanted were to have a way to link the comprehensive documentation with the actual symbols parsed from the header file, as this helps to identify any broken references. Use the new :toc: flag for DVB. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <dbe95d83ae2117ed532fda423fd1c1d9906b7a19.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: accept more reftypesMauro Carvalho Chehab
Current regex is limited to only some c-domain reftypes. There are several others. Change the code to pick the name specified there. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <5c146923d1e3183893f290216fb1378954e2e540.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: add namespace supportMauro Carvalho Chehab
C domain supports a ".. c:namespace::" tag that allows setting a symbol namespace. This is used within the kernel to avoid warnings about duplicated symbols. This is specially important for syscalls, as each subsystem may have their own documentation for them. This is specially true for ioctl. When such tag is used, all C domain symbols have c++ style, e.g. they'll become "{namespace}.{reference}". Allow specifying C namespace at the exception files, avoiding the need of override rules for every symbol. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <cc27ec60ceb3bdac4197fb7266d2df8155edacda.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs.py: get rid of process_exceptions()Mauro Carvalho Chehab
Add an extra parameter to parse_file to make it handle exceptions internally, cleaning up the API. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <8575bbc94ff706aa7e7cc3a188399ca17a3169e6.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17tools: docs: parse_data_structs: make process_exceptions two stagesMauro Carvalho Chehab
Split the logic which parses exceptions on two stages, preparing the exceptions file to have rules that will affect xref generation. For now, preserve the original API. Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <da9ca5f2ce1ffcfb355e32e676ff013607c227e0.1759329363.git.mchehab+huawei@kernel.org>
2025-10-17docs: kernel_include.py: propose alternativesMauro Carvalho Chehab
Specially when using c::namespace, it is not hard to break a reference by forgetting to add a domain. Also, different cases and using "-"/"_" the wrong way are typical cases that people often gets wrong. We might use a more complex logic here to also check for typos, but let's keep it plain, simple. This is enough to get thos exeptions from media controller: .../include/uapi/linux/media.h:26: WARNING: Invalid xref: c:type:`media_device_info`. Possible alternatives: c:type:`MC.media_device_info` (from mediactl/media-ioc-device-info) .../include/uapi/linux/media.h:149: WARNING: Invalid xref: c:type:`media_entity_desc`. Possible alternatives: c:type:`MC.media_entity_desc` (from mediactl/media-ioc-enum-entities) .../include/uapi/linux/media.h:228: WARNING: Invalid xref: c:type:`media_link_desc`. Possible alternatives: c:type:`MC.media_link_desc` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:235: WARNING: Invalid xref: c:type:`media_links_enum`. Possible alternatives: c:type:`MC.media_links_enum` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:212: WARNING: Invalid xref: c:type:`media_pad_desc`. Possible alternatives: c:type:`MC.media_pad_desc` (from mediactl/media-ioc-enum-links) .../include/uapi/linux/media.h:298: WARNING: Invalid xref: c:type:`media_v2_entity`. Possible alternatives: c:type:`MC.media_v2_entity` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:312: WARNING: Invalid xref: c:type:`media_v2_interface`. Possible alternatives: c:type:`MC.media_v2_interface` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:307: WARNING: Invalid xref: c:type:`media_v2_intf_devnode`. Possible alternatives: c:type:`MC.media_v2_intf_devnode` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:341: WARNING: Invalid xref: c:type:`media_v2_link`. Possible alternatives: c:type:`MC.media_v2_link` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:333: WARNING: Invalid xref: c:type:`media_v2_pad`. Possible alternatives: c:type:`MC.media_v2_pad` (from mediactl/media-ioc-g-topology) .../include/uapi/linux/media.h:349: WARNING: Invalid xref: c:type:`media_v2_topology`. Possible alternatives: c:type:`MC.media_v2_topology` (from mediactl/media-ioc-g-topology) Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <4c75d277e950e619ea00ba2dea336853a4aac976.1759329363.git.mchehab+huawei@kernel.org>
generated by cgit v1.2.3 (git 2.0.4) at 2026-01-06 21:52:50 +0000