| Age | Commit message (Collapse) | Author |
|---|
|
The kerneldoc parsing phase gathers all of the information about the
declarations of interest, then passes it through to the output phase as a
dict that is an unstructured blob of information; this organization has its
origins in the Perl version of the program. It results in an interface
that is difficult to reason about, dozen-parameter function calls, and
other ills.
Introduce a new class (KdocItem) to carry this information between the
parser and the output modules, and, step by step, modify the system to use
this class in a more structured way. This could be taken further by
creating a subclass of KdocItem for each declaration type (function,
struct, ...), but that is probably more structure than we need.
The result is (I hope) clearer code, the removal of a bunch of boilerplate,
and no changes to the generated output.
|
|
Versions of Python prior to 3.7 do not guarantee to remember the insertion
order of dicts; since kernel-doc depends on that guarantee, running with
such older versions could result in output with reordered sections.
Python 3.9 is the minimum for the kernel as a whole, so this should not be
a problem, but put in a warning just in case somebody tries to use
something older.
Suggested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
entry.sectcheck is just a duplicate of our list of sections that is only
passed to check_sections(); its main purpose seems to be to avoid checking
the special named sections. Rework check_sections() to not use that field
(which is then deleted), tocheck for the known sections directly, and
tighten up the logic in general.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
They are part of the interface, so use them directly. This allows the
removal of the transitional __dict__ hack in KdocItem.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Get rid of the excess "return" statements in dump_declaration(), along with
a line of never-executed dead code.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Each declaration type passes through the name in a unique field of the
"args" blob - even though we have always just passed the name separately.
Get rid of all the weird names and just use the common version.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Callers to output_declaration() always pass the parameter information from
self.entry; remove all of the boilerplate arguments and just get at that
information directly. Formalize its placement in the KdocItem class.
It would be nice to get rid of parameterlist as well, but that has the
effect of reordering the output of function parameters and struct fields to
match the order in the kerneldoc comment rather than in the declaration.
One could argue about which is more correct, but the ordering has been left
unchanged for now.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Callers of check_sections() join parameterlist into a single string, which
is then immediately split back into the original list. Rather than do all
that, just use parameterlist directly in check_sections().
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The code goes out of its way to create a special list of parameters in
entry.struct_actual that is just like entry.parameterlist, but with extra
junk. The only use of that information, in check_sections(), promptly
strips all the extra junk back out. Drop all that extra work and just use
parameterlist.
No output changes.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The section list always comes directly from the under-construction entry
and is used uniformly. Formalize section handling in the KdocItem class,
and have output_declaration() load the sections directly from the entry,
eliminating a lot of duplicated, verbose parameters.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Python dicts (as of 3.7) are guaranteed to remember the insertion order of
items, so we do not need a separate list for that purpose. Drop the
per-entry sectionlist variable and just rely on native dict ordering.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Add some comments to dump_enum to help the next person who has to figure
out what it is actually doing.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-8-corbet@lwn.net
|
|
Add a set of comments to process_proto_function and reorganize the logic
slightly; no functional change.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-6-corbet@lwn.net
|
|
process_proto_type() is using a complex regex and a "while True" loop to
split a declaration into chunks and, in the end, count brackets. Switch to
using a simpler regex to just do the split directly, and handle each chunk
as it comes. The result is, IMO, easier to understand and reason about.
The old algorithm would occasionally elide the space between function
parameters; see struct rng_alg->generate(), foe example. The only output
difference is to not elide that space, which is more correct.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-5-corbet@lwn.net
|
|
Putting the floor under brcount does not change the output in any way, just
remove it.
Change the termination test from ==0 to <=0 to prevent infinite loops in
case somebody does something truly wacko in the code.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-4-corbet@lwn.net
|
|
Rework _add_regex() to avoid doing the lookup twice for the (hopefully
common) cache-hit case.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-3-corbet@lwn.net
|
|
process_proto_type() and process_proto_function() reinventing the strip()
string method with a whole series of separate regexes; take all that out
and just use strip().
The previous implementation also (in process_proto_type()) removed C++
comments *after* the above dance, leaving trailing whitespace in that case;
now we do the stripping afterward. This results in exactly one output
change: the removal of a spurious space in the definition of
BACKLIGHT_POWER_REDUCED - see
https://docs.kernel.org/gpu/backlight.html#c.backlight_properties.
I note that we are putting semicolons after #define lines that really
shouldn't be there - a task for another day.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Tested-by: Akira Yokosawa <akiyks@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250703184403.274408-2-corbet@lwn.net
|
|
Since our output items contain their name, we don't need to pass it
separately.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
This class is intended to replace the unstructured dict used to accumulate
an entry to pass to an output module. For now, it remains unstructured,
but it works well enough that the output classes don't notice the
difference.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Add some comments to dump_enum to help the next person who has to figure
out what it is actually doing.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Add a set of comments to process_proto_function and reorganize the logic
slightly; no functional change.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
process_proto_type() is using a complex regex and a "while True" loop to
split a declaration into chunks and, in the end, count brackets. Switch to
using a simpler regex to just do the split directly, and handle each chunk
as it comes. The result is, IMO, easier to understand and reason about.
The old algorithm would occasionally elide the space between function
parameters; see struct rng_alg->generate(), foe example. The only output
difference is to not elide that space, which is more correct.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Now that "inline_*" are just ordinary parser states, split them into two
separate functions, getting rid of some nested conditional logic.
The original process_inline() would simply ignore lines that didn't match
any of the regexes (those lacking the initial " * " marker). I have
preserved that behavior, but we should perhaps emit a warning instead.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627184000.132291-9-corbet@lwn.net
|
|
The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
substate logic and make the inline states normal ones like the rest.
INLINE_ERROR was never actually used for anything, so just take it out.
No changes to the generated output.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627184000.132291-8-corbet@lwn.net
|
|
It is never used, so just get rid of it.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627184000.132291-7-corbet@lwn.net
|
|
Reorganize process_export() to eliminate duplicated code, don't look for
exports in states where we don't expect them, and don't bother with normal
state-machine processing if an export declaration has been found.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627184000.132291-6-corbet@lwn.net
|
|
This member is unused, to take it out.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627184000.132291-5-corbet@lwn.net
|
|
The type_param regex matches "@..." just fine, so the special-case branch
for that in dump_section() is never executed. Just remove it.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627184000.132291-4-corbet@lwn.net
|
|
Rather than having other code mucking around with this bit of internal
state, encapsulate it internally. Accumulate the description as a list of
strings, joining them at the end, which is a more efficient way of building
the text.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627184000.132291-3-corbet@lwn.net
|
|
This field is not used for anything, just get rid of it.
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250627184000.132291-2-corbet@lwn.net
|
|
Putting the floor under brcount does not change the output in any way, just
remove it.
Change the termination test from ==0 to <=0 to prevent infinite loops in
case somebody does something truly wacko in the code.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Switch KernRe::add_regex() to a try..except block to avoid looking up each
regex twice.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
process_proto_type() and process_proto_function() reinventing the strip()
string method with a whole series of separate regexes; take all that out
and just use strip().
The previous implementation also (in process_proto_type()) removed C++
comments *after* the above dance, leaving trailing whitespace in that case;
now we do the stripping afterward. This results in exactly one output
change: the removal of a spurious space in the definition of
BACKLIGHT_POWER_REDUCED - see
https://docs.kernel.org/gpu/backlight.html#c.backlight_properties.
I note that we are putting semicolons after #define lines that really
shouldn't be there - a task for another day.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Now that "inline_*" are just ordinary parser states, split them into two
separate functions, getting rid of some nested conditional logic.
The original process_inline() would simply ignore lines that didn't match
any of the regexes (those lacking the initial " * " marker). I have
preserved that behavior, but we should perhaps emit a warning instead.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The processing of inline kerneldoc comments is a state like the rest, but
it was implemented as a set of separate substates. Just remove the
substate logic and make the inline states normal ones like the rest.
INLINE_ERROR was never actually used for anything, so just take it out.
No changes to the generated output.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
It is never used, so just get rid of it.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Reorganize process_export() to eliminate duplicated code, don't look for
exports in states where we don't expect them, and don't bother with normal
state-machine processing if an export declaration has been found.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
This member is unused, to take it out.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The type_param regex matches "@..." just fine, so the special-case branch
for that in dump_section() is never executed. Just remove it.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Rather than having other code mucking around with this bit of internal
state, encapsulate it internally. Accumulate the description as a list of
strings, joining them at the end, which is a more efficient way of building
the text.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
This field is not used for anything, just get rid of it.
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The script now have lots or arguments. Better organize and
name them, for it to be a little bit more intuitive.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/acf5e1db38ca6a713c44ceca9db5cdd7d3079c92.1750571906.git.mchehab+huawei@kernel.org
|
|
Fedora distros are now identified as:
Fedora Linux 42
Fix the way script detects it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/c2a34860bd986cc5f81fc25554ed91629736e995.1750571906.git.mchehab+huawei@kernel.org
|
|
Currently, the script ignores SPHINXBUILD, making it useless.
As we're about to use on another script, fix support for it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/b0217df871a5e563646d386327bdd7a393c58ac2.1750571906.git.mchehab+huawei@kernel.org
|
|
Most of the time, testing the full range of supported Sphinx
version is a waste of time and resources. Instead, the best is
to focus at the versions that are actually shipped by major
distros.
For it to work properly, we need to adjust the requirements for
them to start from first patch for each distro after the
minimal supported one. The requirements were re-adjusted to
avoid build breakages related to version incompatibilities.
Such builds were tested with:
./scripts/test_doc_build.py -m -a "SPHINXOPTS=-j8" "SPHINXDIRS=networking netlink/specs" --full
Change the logic to pick by default only such versions, adding
another parameter to do a comprehensive test.
While here, improve the script documentation to make it easier
to be used.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/a2b9b7775a185766643ea4b82b558de25b61d6c7.1750571906.git.mchehab+huawei@kernel.org
|
|
Simplify the logic which handles with new lines.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/2436f37ab7945673f26bcfc94c10e6e76b93c2d8.1750571906.git.mchehab+huawei@kernel.org
|
|
Change the dependency list to ensure that:
- all docutils versions are covered;
- provide an explanation about the dependencies;
- set a better minimal requirement for 3.4.3.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/433aeefb4ac9edbd62494334ac07bc1307387d40.1750571906.git.mchehab+huawei@kernel.org
|
|
Very old versions of Sphinx require older versions of python.
The original script assumes that a python3.9 exec exists,
but this may not be the case.
Relax python requirements.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/32cb41c543293bbbab5fcb15f8a0aefac040e3a9.1750571906.git.mchehab+huawei@kernel.org
|
|
Now that asyncio is supported, allow userspace to adjust
verbosity level and direct the script output to a file.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/76c3a64a87a7493ae607d5c7784b3b829affcaf0.1750571906.git.mchehab+huawei@kernel.org
|
|
Prepare the tool to allow writing the output into log files.
For such purpose, receive stdin/stdout messages asynchronously.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/9b0a60b5047137b5ba764701268da992767b128c.1750571906.git.mchehab+huawei@kernel.org
|
