Re: [PATCH 0/3] Some kernel-doc fixes

[Mauro Carvalho Chehab <mchehab+huawei@kernel.org>]

Hi Jon,

On Mon, 02 Feb 2026 10:01:14 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > Hi Jon,
> >
> > This small series contain 3 patches:
> > - patch 1 fixes PDF docs build, as reported by Akira;
> >   (I'm resending this one as-is from its v2)
> > - patch 2 addresses a complain from Jani about not being able
> >   of disabling "-q" flag when building docs with V=0;
> > - patch 3 addresses an issue indirectly reported by Jani that
> >   it the env vars that affects the wrapper aren't documented.
> >
> > With regards to patch 2, docs build honours V=0 by adding a
> > "-q" flag.
> >
> > When V=1 is set, there are two effects in place:
> >
> > 1. sphix-build will be called without "-q";
> > 2. Sphinx extensions will increase their verbosity levels.
> >
> > Sometimes, it is desired to just remove "-q" without increasing
> > extensions verbosity. That's what patch 2 does.
> >
> > IMO, at least patch 1 should be merged during Kernel v6.21
> > development cycle.
> >
> > Mauro Carvalho Chehab (3):
> >   docs: kdoc: Fix pdfdocs build for tools
> >   docs: sphinx-build-wrapper: allow -v override -q
> >   tools: sphinx-build-wrapper: improve its help message
> >
> >  tools/docs/sphinx-build-wrapper  | 42 +++++++++++++++++++++++++++-----
> >  tools/lib/python/kdoc/kdoc_re.py | 10 +++++---
> >  2 files changed, 43 insertions(+), 9 deletions(-)  
> 
> I've applied this set, thanks.

Thanks!

-

Jon,

I ended placing this series near the end of the /41 one mainly because
the first patch conflicts there.

The conflict is trivial, to solve though, if you opt to merge
from it.

IMO, it is worth merging this series before the merge window,
as it will solve some troubles that will appear after Linus
picks stuff from -next, related to some annotations Peter
Zijlstra added on his tree, but it is up to you.

Yeah, it is a lot more complex than I would expect for a late
-rc, so we could end just postpone it.

---

As a heads up, I'm working on a separate set of patches that, if 
things go well, we may end having a regression test for kernel-doc.
When done, I'll be submitting in separate.

The idea is to have a YAML file with source code, KdocItem,
man output and rst output, and a dynamic unit test to run
them. I finished today to write a skeleton, but still requires
polishing (*).

I'm thinking on modifying kernel-doc executable to be able
to generate the content for such YAML file.

If things go well, we could have something like:

	$ tools/docs/kernel-doc --gen-yaml all_kdoc_tests.yaml .

To place all tests there. As we modify kernel-doc, we can
run the code I'm currently writing. It would identify the
differences for both ReST and man and report.
	
(*) I started working on it today.

The unittest generation part from YAML already works:

	$ tools/unittests/test_kdoc_from_yaml.py 
	Ran 3 tests in 0.004s

	FAILED (failures=1)
	test_kdoc_from_yaml:
	    KernelDocParser:
	        test_gen_function3:  FAIL
	    KernelManOutput:
	        test_man_function3:  OK
	    KernelRestOutput:
	        test_rst_function3:  OK

Those 3 classes were auto-populated from yaml. Right now,
only KernelDocParser test exectution was implemented.

Those three classes contain just the test functions (two are just
stubs):

	class KernelDocParser(KdocParser):
	    def run_parser_test(self, source, kdoc_item, exports, fname):
	        if isinstance(kdoc_item, dict):
	            kdoc_item = [kdoc_item]

        	if isinstance(exports, str):
        	    exports=set([exports])
        	elif isinstance(exports, list):
        	    exports=set(exports)

		# For now, it is using here a function I wrote on a non-dynamic unit test
	        self.run_test(source, kdoc_item, exports=exports, fname=fname)

	class KernelManOutput(unittest.TestCase):
	    # TODO: for now, this is just a stub
	    def run_out_test(self, kdoc_item, out_type, data):
	        pass

	class KernelRestOutput(unittest.TestCase):
	    # TODO: for now, this is just a stub
	    def run_out_test(self, kdoc_item, out_type, data):
	        pass

And It contains a separate class to add dynamic tests on those.

The only issue I need to handle on its current implementation for
KernelDocParser (with the simple YAML test) is to solve whitespace
issues:

	FAIL: test_gen_function3 (test_kdoc_from_yaml.KernelDocParser.test_gen_function3)
	Lambda-like function to run tests with provided vars
	----------------------------------------------------------------------
	Traceback (most recent call last):
	  File "/new_devel/docs/tools/unittests/test_kdoc_from_yaml.py", line 79, in test_method
	    self.run_parser_test(source, kdoc_item, exports, fname)
	    ~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	  File "/new_devel/docs/tools/unittests/test_kdoc_from_yaml.py", line 54, in run_parser_test
	    self.run_test(source, kdoc_item, exports=exports, fname=fname)
	    ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	  File "/new_devel/docs/tools/unittests/test_kdoc_parser.py", line 84, in run_test
	    self.assertEqual(d[key], value, msg=f"at {key}")
	    ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
	AssertionError: {'Description': 'Does nothing\n\n', 'Return': '\nalways return 0.\n'} != {'Description': 'Does nothing\n', 'Return': 'always return 0.\n'}
	- {'Description': 'Does nothing\n\n', 'Return': '\nalways return 0.\n'}
	?                                --              --
	
	+ {'Description': 'Does nothing\n', 'Return': 'always return 0.\n'} : at sections

I'll probably add a regex to replace all whitespaces/new lines by a
single one.

For man pages, I need to handle timestamps, but except for that and
whitespace differences, both rst and man page functions should be
straight forward: just call the output class passing the list of
KdocItem objects.

I guess tomorrow I may have this fixed and the test functions for
rst and man implemented.

Thanks,
Mauro

---

If you're curious enough, this is the test YAML file it is using to
generate the 3 dynamic unit tests:

tests:
  - name: function3
    fname: function3.c
    description: Just a simple example

    source: |
      /**
      * function3: Exported function
      * @arg1: @arg1 does nothing
      *
      * Does nothing
      *
      * return:
      *    always return 0.
      */
      int function3(char *arg1) { return 0; };
      EXPORT_SYMBOL(function3);

    exports: function3
    expected:
      - kdoc_item:
          name: function3
          type: function
          declaration_start_line: 1

          sections:
            Description: |
              Does nothing

            Return: |
              always return 0.

          parameterdescs:
            arg1: |
              @arg1 does nothing
          parameterlist:
            - arg1
          parameterdesc_start_lines:
            arg1: 2
          parametertypes:
            arg1: char *arg1

          other_stuff:
            func_macro: false
            functiontype: int
            purpose: Exported function
            typedef: false

        rst: |
          .. c:function:: int function3 (char *arg1)

            Exported function

          .. container:: kernelindent

            **Parameters**

            ``char *arg1``
              **arg1** does nothing

            **Description**

            Does nothing

            **Return**

            always return 0.

        man: |
          .TH "function3" 9 "February 2026"  "" "Kernel API Manual"
          .SH NAME
          function3 \- Exported function
          .SH SYNOPSIS
          .B "int" function3
          .BI "(char *arg1 "  ");"
          .SH ARGUMENTS
          .IP "arg1" 12
          \fIarg1\fP does nothing
          .SH "DESCRIPTION"
          Does nothing
          .SH "RETURN"
          always return 0.
          .SH "SEE ALSO"
          .PP
          Kernel file \fBtest.c\fR