Merge tag 'docs-7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux

Pull documentation updates from Jonathan Corbet:
"A busier cycle than I had expected for docs, including:

- Tran

Merge tag 'docs-7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux

Pull documentation updates from Jonathan Corbet:
"A busier cycle than I had expected for docs, including:

- Translations: some overdue updates to the Japanese translations,
Chinese translations for some of the Rust documentation, and the
beginnings of a Portuguese translation.

- New documents covering CPU isolation, managed interrupts, debugging
Python gbb scripts, and more.

- More tooling work from Mauro, reducing docs-build warnings, adding
self tests, improving man-page output, bringing in a proper C
tokenizer to replace (some of) the mess of kernel-doc regexes, and
more.

- Update and synchronize changes.rst and scripts/ver_linux, and put
both into alphabetical order.

... and a long list of documentation updates, typo fixes, and general
improvements"

* tag 'docs-7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (162 commits)
Documentation: core-api: real-time: correct spelling
doc: Add CPU Isolation documentation
Documentation: Add managed interrupts
Documentation: seq_file: drop 2.6 reference
docs/zh_CN: update rust/index.rst translation
docs/zh_CN: update rust/quick-start.rst translation
docs/zh_CN: update rust/coding-guidelines.rst translation
docs/zh_CN: update rust/arch-support.rst translation
docs/zh_CN: sync process/2.Process.rst with English version
docs/zh_CN: fix an inconsistent statement in dev-tools/testing-overview
tracing: Documentation: Update histogram-design.rst for fn() handling
docs: sysctl: Add documentation for /proc/sys/xen/
Docs: hid: intel-ish-hid: make long URL usable
Documentation/kernel-parameters: fix architecture alignment for pt, nopt, and nobypass
sched/doc: Update yield_task description in sched-design-CFS
Documentation/rtla: Convert links to RST format
docs: fix typos and duplicated words across documentation
docs: fix typo in zoran driver documentation
docs: add an Assisted-by mention to submitting-patches.rst
Revert "scripts/checkpatch: add Assisted-by: tag validation"
...

show more ...

docs: kdoc: better handle source when producing YAML output

The current logic was storing symbols source code on a list,
not linked to the actual KdocItem. While this works fine when
kernel-doc mark

docs: kdoc: better handle source when producing YAML output

The current logic was storing symbols source code on a list,
not linked to the actual KdocItem. While this works fine when
kernel-doc markups are OK, on places where there is a "/**"
without a valid kernel-doc markup, it ends that the 1:1 match
between source code and KdocItem doesn't happen, causing
problems to generate the YAML output.

Fix it by storing the source code directly into the KdocItem
structure.

This shouldn't affect performance or memory footprint, except
when --yaml option is used.

While here, add a __repr__() function for KdocItem, as it
helps debugging it.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <77902dafabb5c3250486aa2dc1568d5fafa95c5b.1774256269.git.mchehab+huawei@kernel.org>

show more ...

unittests: test_kdoc_parser: add command line arg to read a YAML file

The test_kdoc_parser.py already supports loading dynamic tests
when running unit tests.

Add support to read from a different fi

unittests: test_kdoc_parser: add command line arg to read a YAML file

The test_kdoc_parser.py already supports loading dynamic tests
when running unit tests.

Add support to read from a different file. This is useful for:
- regression tests before/afer some changes;
- preparing new unit tests;
- test a different yaml before adding its contents at
tools/unittests/kdoc-test.yaml.

It should be noticed that passing an argument to a unit test
is not too trivial, as unittest core will load itself the
runner with a separate environment. The best (only?) way to
do it is by setting the system environment. This way, when
the class is called by the unit test loader, it can pick
the var from the environment without relying on a global
variable.

The unittest_helper has already provision for it, so let's
use its support.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <1d1a56de012c43756f9ca87aa9bf6c285674f113.1774256269.git.mchehab+huawei@kernel.org>

show more ...

Merge branch 'mauro' into docs-mw

This series comes after:
https://lore.kernel.org/linux-doc/cover.1773770483.git.mchehab+huawei@kernel.org/

It basically contains patches I submitted before on

Merge branch 'mauro' into docs-mw

This series comes after:
https://lore.kernel.org/linux-doc/cover.1773770483.git.mchehab+huawei@kernel.org/

It basically contains patches I submitted before on a 40+ patch series,
but were less relevant, plus a couple of other minor fixes:

- patch 1 improves one of the CTokenizer unit test, fixing some
potential issues on it;
- patches 2 and 3 contain some improvement/fixes for Sphinx
Python autodoc extension. They basically document c_lex.py;

- The remaining patches:
- create a new class for kernel-doc config;
- fix some internal representations of KdocItem;
- add unit tests for KernelDoc() parser class;
- add support to output KdocItem in YAML, which is a
machine-readable output for all documented kAPI.

None of the patches should affect man or html output.

show more ...

docs: test_kdoc_parser: add support for dynamic test creation

Use the content of kdoc-test.yaml to generate unittests to
verify that kernel-doc internal methods are parsing C code
and generating out

docs: test_kdoc_parser: add support for dynamic test creation

Use the content of kdoc-test.yaml to generate unittests to
verify that kernel-doc internal methods are parsing C code
and generating output the expected way.

Depending on what is written at the parser file at
kdoc-test.yaml, up to 5 tests can be generated from a single
test entry inside the YAML file:

1. from source to kdoc_item: test KernelDoc class;
2. from kdoc_item to man: test ManOutput class;
3. from kdoc_item to rst: test RestOutput class;
4. from source to man without checking expected KdocItem;
5. from source to rst without checking expected KdocItem.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <7ec2593c5b19de3e3b1d8de92675f6b751d3fa21.1773823995.git.mchehab+huawei@kernel.org>

show more ...

docs: unittests: add a parser to test kernel-doc parser logic

Validating that kernel-doc is parsing data properly is tricky.

Add an unittest skeleton that alllows passing a source code
and check if

docs: unittests: add a parser to test kernel-doc parser logic

Validating that kernel-doc is parsing data properly is tricky.

Add an unittest skeleton that alllows passing a source code
and check if the corresponding values of export_table and
entries returned by the parser are properly filled.

It works by mocking a file input with the contents of a source
string, an comparing if:

- exports set matches;
- expected KernelItem entries match.

Create a new TestSelfValidate meant to check if the logic
inside KdocParser.run_test() does its job of checking for
differences inside KdocItem.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <8d91bfabd69de7aa44a0f5080ccb01aa41957e6d.1773823995.git.mchehab+huawei@kernel.org>

show more ...