linux-kernel - Re: [PATCH RFC] docs: add python module documentation

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [day] [month] [year] [list]

Message-ID: <20260114094328.28f1a157@foz.lan>
Date: Wed, 14 Jan 2026 09:43:28 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>,
 linux-kernel@...r.kernel.org, Mauro Carvalho Chehab <mchehab@...nel.org>,
 Randy Dunlap <rdunlap@...radead.org>, Shuah Khan
 <skhan@...uxfoundation.org>
Subject: Re: [PATCH RFC] docs: add python module documentation

Em Tue, 13 Jan 2026 13:46:35 -0700
Jonathan Corbet <corbet@....net> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:
> 
> > Hi Jon,
> >
> > While checking/improving docstrings inside kernel-doc, I noticed
> > that some changes there aren't Sphinx-compatible. Also, there are
> > several functions and some classes that miss documentation.
> >
> > Being responsible for doing some documentation work, I felt blamed
> > on not having a good documentation of our own dog food :-)
> >
> > So, I'm adding kdoc documentation to the Kernel documentation. The basic
> > change is just a couple of extra lines at conf.py, plus a few *.rst files
> > pointing to the files we want to document:  
> 
> At a first glance, this looks like a worthy task.
> 
> I've never really played with autodoc. 

once enabled, it is easy to add documentation. To document an entire
module, all we need is to add:

	.. automodule:: kdoc.kdoc_files
	   :members:
	   :show-inheritance:
	   :undoc-members:

undoc-members mean to show functions and vars that don't have
any comments. IMHO we want that, as it will help checking what parts
are missing docs. There are ways to exclude parts of the document from
the docs (I'm not planning to use them).

So, at the ReST, we need to add an automodule for each new file there.

> Sure you don't want to fix up kernel-doc to read Python code too? :) 

:-D

> Seriously, though, I worry that
> it could end up cluttering the code with a bunch of sphinxstuff, but the
> only way to really see is to try it.

Most of the documentation is extracted from standard python docstrings,
which will be handled as ReST. If you look at the patch, you'll see
that most of the changes are related to the lack of docstrings
(which also satifies linters, like pylint):

     def get(self, key, default = None):
+        """Get a value from optional keys"""
         return self.other_stuff.get(key, default)

Sphinx has the special "#:" syntax for comments that we want to
be at the documentation. So:

     # output mode.
-    OUTPUT_ALL          = 0 # output all symbols and doc sections
-    OUTPUT_INCLUDE      = 1 # output only specified symbols
-    OUTPUT_EXPORTED     = 2 # output exported symbols
-    OUTPUT_INTERNAL     = 3 # output non-exported symbols
+    OUTPUT_ALL          = 0 #: output all symbols and doc sections
+    OUTPUT_INCLUDE      = 1 #: output only specified symbols
+    OUTPUT_EXPORTED     = 2 #: output exported symbols
+    OUTPUT_INTERNAL     = 3 #: output non-exported symbols

and:

+    #: Highlights to be used in ReST format
     highlights = [

Add documentation to variables. Sphinx is smart enough to preserve
such comments on inherited classes, so, no need to document the same
functions 3 times for base, man and rest at kdoc_output.py.

So far, IMHO, all such changes will ensure that we'll have a good
documentation for python scripts.

Going further:

Documenting class instances will use the default representation,
which may not be the best. Adding a  __repr__() allows adjusting
it (*):

+    def __repr__(self):
+        return f're.compile("{self.regex.pattern}")'
+

With that, all documentation for KernRe() will use it. For instance,
sphinx_cblock is documented as:

	sphinx_cblock = re.compile("^\.\.\ +code-block::")

	    Sphinx code block regex

(*) I opted to use re.compile() instead of KernRe() because it
    was simpler and more intuitive for people just looking at the
    docs. We may, instead use KernRe() and then check if:

	- flags != 0
	- cache != True

    and then output it as:

		KernRe("pattern")
		KernRe("pattern", cache=False)
		KernRe("pattern", flags=Re.I)

    but IMO just printing the pattern is enough for doc purpose.

On this patch, the only sphinxstuff are the usage of "#:" 
and one Sphinx-specific notation here:

	-!!! Caution !!!
	+.. caution::

Thanks,
Mauro