Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: kernel_include.py: document all supported parameters
As we're actually a fork of Sphinx Include, update its
docstring to contain the documentation for the actual
implemented parameters.
Let's use :param: for parameters, as defined at:
https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/f193160889a2dc296b4df2cc7ebc9934d717ccef.1755872208.git.mchehab+huawei@kernel.org
authored by
Mauro Carvalho Chehab
and committed by
Jonathan Corbet
a49adfab
428c1d35
+58
-30
+58
-30
Documentation/sphinx/kernel_include.py
+58
-30
Documentation/sphinx/kernel_include.py
···
2
2
# SPDX-License-Identifier: GPL-2.0
3
3
# pylint: disable=R0903, R0912, R0914, R0915, C0209,W0707
4
4
5
+
5
6
"""
6
-
kernel-include
7
-
~~~~~~~~~~~~~~
7
+
Implementation of the ``kernel-include`` reST-directive.
8
8
9
-
Implementation of the ``kernel-include`` reST-directive.
9
+
:copyright: Copyright (C) 2016 Markus Heiser
10
+
:license: GPL Version 2, June 1991 see linux/COPYING for details.
10
11
11
-
:copyright: Copyright (C) 2016 Markus Heiser
12
-
:license: GPL Version 2, June 1991 see linux/COPYING for details.
12
+
The ``kernel-include`` reST-directive is a replacement for the ``include``
13
+
directive. The ``kernel-include`` directive expand environment variables in
14
+
the path name and allows to include files from arbitrary locations.
13
15
14
-
The ``kernel-include`` reST-directive is a replacement for the ``include``
15
-
directive. The ``kernel-include`` directive expand environment variables in
16
-
the path name and allows to include files from arbitrary locations.
16
+
.. hint::
17
17
18
-
.. hint::
18
+
Including files from arbitrary locations (e.g. from ``/etc``) is a
19
+
security risk for builders. This is why the ``include`` directive from
20
+
docutils *prohibit* pathnames pointing to locations *above* the filesystem
21
+
tree where the reST document with the include directive is placed.
19
22
20
-
Including files from arbitrary locations (e.g. from ``/etc``) is a
21
-
security risk for builders. This is why the ``include`` directive from
22
-
docutils *prohibit* pathnames pointing to locations *above* the filesystem
23
-
tree where the reST document with the include directive is placed.
23
+
Substrings of the form $name or ${name} are replaced by the value of
24
+
environment variable name. Malformed variable names and references to
25
+
non-existing variables are left unchanged.
24
26
25
-
Substrings of the form $name or ${name} are replaced by the value of
26
-
environment variable name. Malformed variable names and references to
27
-
non-existing variables are left unchanged.
27
+
**Supported Sphinx Include Options**:
28
28
29
-
This extension overrides Sphinx include directory, adding some extra
30
-
arguments:
29
+
:param literal:
30
+
If present, the included file is inserted as a literal block.
31
31
32
-
1. :generate-cross-refs:
32
+
:param code:
33
+
Specify the language for syntax highlighting (e.g., 'c', 'python').
33
34
34
-
If present, instead of reading the file, it calls ParseDataStructs()
35
-
class, which converts C data structures into cross-references to
36
-
be linked to ReST files containing a more comprehensive documentation;
35
+
:param encoding:
36
+
Specify the encoding of the included file (default: 'utf-8').
37
37
38
-
2. :exception-file:
38
+
:param tab-width:
39
+
Specify the number of spaces that a tab represents.
39
40
40
-
Used together with :generate-cross-refs
41
+
:param start-line:
42
+
Line number at which to start including the file (1-based).
41
43
42
-
Points to a file containing rules to ignore C data structs or to
43
-
use a different reference name, optionally using a different
44
-
reference type.
44
+
:param end-line:
45
+
Line number at which to stop including the file (inclusive).
45
46
46
-
3. :warn-broken:
47
+
:param start-after:
48
+
Include lines after the first line matching this text.
47
49
48
-
Used together with :generate-cross-refs:
50
+
:param end-before:
51
+
Include lines before the first line matching this text.
49
52
50
-
Detect if the auto-generated cross references doesn't exist.
53
+
:param number-lines:
54
+
Number the included lines (integer specifies start number).
55
+
Only effective with 'literal' or 'code' options.
51
56
57
+
:param class:
58
+
Specify HTML class attribute for the included content.
59
+
60
+
**Kernel-specific Extensions**:
61
+
62
+
:param generate-cross-refs:
63
+
If present, instead of directly including the file, it calls
64
+
ParseDataStructs() to convert C data structures into cross-references
65
+
that link to comprehensive documentation in other ReST files.
66
+
67
+
:param exception-file:
68
+
(Used with generate-cross-refs)
69
+
70
+
Path to a file containing rules for handling special cases:
71
+
- Ignore specific C data structures
72
+
- Use alternative reference names
73
+
- Specify different reference types
74
+
75
+
:param warn-broken:
76
+
(Used with generate-cross-refs)
77
+
78
+
Enables warnings when auto-generated cross-references don't point to
79
+
existing documentation targets.
52
80
"""
53
81
54
82
# ==============================================================================