linux.git/Documentation/sphinx, branch v6.15

docs: automarkup: drop legacy support

2025-02-18T20:42:46+00:00

Python 2 is already EOL for quite some time. Drop support for
it.

Also, the minimal Sphinx version is now 3.4.3. So, we can drop
support for Sphinx < 3.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/5cb57d158e42957d4bff06db38be141d849ac13b.1739254867.git.mchehab+huawei@kernel.org

docs: media: Allow creating cross-references for RC ABI

2025-02-18T20:42:46+00:00

Now that Documentation/ABI is processed by automarkup, let it
generate cross-references for RC sysfs devnodes.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/7c2f9a9970a15df8b5e3a6ecd21bcedcc8881ce1.1739254867.git.mchehab+huawei@kernel.org

scripts/kernel-doc: drop Sphinx version check

2025-02-13T18:33:33+00:00

As the current minimal supported Sphinx version is 3.4.3, drop
support for older versions.

Signed-off-by: Mauro Carvalho Chehab 
Reviewed-by: Kees Cook 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/0d002e7550476a68547ee53ad06cfd8fdcaf7c3a.1739254187.git.mchehab+huawei@kernel.org

docs: extensions: don't use utf-8 syntax for descriptions

2025-02-13T18:33:32+00:00

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 
Reviewed-by: Kees Cook 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/8a42f6be53464af4b866492a7e9ddf29c0429997.1739254187.git.mchehab+huawei@kernel.org

docs: sphinx/kernel_abi: avoid warnings during Sphinx module init

2025-02-10T18:19:57+00:00

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 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/b0e79dc60d556e3b39fa6774d3b7bf734b73f352.1739182025.git.mchehab+huawei@kernel.org

docs: sphinx/automarkup: add cross-references for ABI

2025-02-10T18:19:57+00:00

Now that all ABI files are handled together, we can add a feature
at automarkup for it to generate cross-references for ABI symbols.

The cross-reference logic can produce references for all existing
files, except for README (as this is not parsed).

For symbols, they need to be an exact match of what it is
described at the docs, which is not always true due to wildcards.

If symbols at /sys /proc and /config are identical, a cross-reference
will be used.

Signed-off-by: Mauro Carvalho Chehab 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/0b97a51b68b1c20127ad4a6a55658557fe0848d0.1739182025.git.mchehab+huawei@kernel.org

docs: sphinx/kernel_abi: parse ABI files only once

2025-02-10T18:19:57+00:00

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 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/5205c53838b6ea25f4cdd4cc1e3d17c0141e75a6.1739182025.git.mchehab+huawei@kernel.org

docs: sphinx/kernel_abi: properly split lines

2025-02-10T18:19:57+00:00

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 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/d4ad5b977799616544376210364d5cec686119ef.1739182025.git.mchehab+huawei@kernel.org

docs: sphinx/kernel_abi: reduce buffer usage for ABI messages

2025-02-10T18:19:57+00:00

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 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/15be22955e3c6df49d7256c8fd24f62b397ad0ff.1739182025.git.mchehab+huawei@kernel.org

docs: sphinx/kernel_abi: use AbiParser directly

2025-02-10T18:19:57+00:00

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 
Signed-off-by: Jonathan Corbet 
Link: https://lore.kernel.org/r/8dbc244dcda97112c1b694e2512a5d600e62873b.1739182025.git.mchehab+huawei@kernel.org