linux-kernel - Re: [PATCH 02/13] docs: enable Sphinx autodoc extension to allow documenting python

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: <20260115135726.035fbdc8@foz.lan>
Date: Thu, 15 Jan 2026 13:57:26 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jani Nikula <jani.nikula@...ux.intel.com>
Cc: Jonathan Corbet <corbet@....net>, Linux Doc Mailing List
 <linux-doc@...r.kernel.org>, linux-kernel@...r.kernel.org, Mauro Carvalho
 Chehab <mchehab@...nel.org>, Shuah Khan <skhan@...uxfoundation.org>
Subject: Re: [PATCH 02/13] docs: enable Sphinx autodoc extension to allow
 documenting python

Em Thu, 15 Jan 2026 14:18:45 +0200
Jani Nikula <jani.nikula@...ux.intel.com> escreveu:

> On Thu, 15 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:
> > On Thu, Jan 15, 2026 at 12:19:48PM +0200, Jani Nikula wrote:  
> >> On Wed, 14 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@...nel.org> wrote:  
> >> > Adding python documentation is simple with Sphinx: all we need
> >> > is to include the ext.autodoc extension and add the directories
> >> > where the Python code sits at the sys.path.
> >> >
> >> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> >> > ---
> >> >  Documentation/conf.py | 11 ++++++++---
> >> >  1 file changed, 8 insertions(+), 3 deletions(-)
> >> >
> >> > diff --git a/Documentation/conf.py b/Documentation/conf.py
> >> > index 1ea2ae5c6276..429fcc9fd7f7 100644
> >> > --- a/Documentation/conf.py
> >> > +++ b/Documentation/conf.py
> >> > @@ -13,11 +13,18 @@ from  textwrap import dedent
> >> >  
> >> >  import sphinx
> >> >  
> >> > +# Location of Documentation/ directory
> >> > +doctree = os.path.abspath(".")  
> >> 
> >> Looking this up based on __file__ would be more robust than cwd.  
> >
> > Agreed.
> >  
> >> Calling this doctree is misleading because doctree is a specific Sphinx
> >> term that means something else. The doctree directory is where the
> >> parsed and pickled documents are cached.  
> >
> > Yeah, you're right: better use a different name.
> >  
> >> 
> >> Oh, I see that you're just moving this, but this is something that
> >> should be fixed first.  
> >
> > It can also be changed afterwards. Anyway, this should be on another
> > series, as such changes don't have anything to do with sphinx.ext.autodoc.
> >  
> >>   
> >> > +
> >> >  # If extensions (or modules to document with autodoc) are in another directory,
> >> >  # add these directories to sys.path here. If the directory is relative to the
> >> >  # documentation root, use os.path.abspath to make it absolute, like shown here.
> >> >  sys.path.insert(0, os.path.abspath("sphinx"))
> >> >  
> >> > +# Allow sphinx.ext.autodoc to document from tools and scripts
> >> > +sys.path.append(f"{doctree}/../tools")
> >> > +sys.path.append(f"{doctree}/../scripts")  
> >> 
> >> These would be much nicer with pathlib.Path.  
> >
> > I guess we agree to disagree here: patchlib basically overrides math divison 
> > operator to work on patches like[1]
> >
> >     p = Path('/etc')
> >     q = p / 'init.d' / 'reboot'
> >
> > This looks really weird on my eyes. I can't see why this would be better
> > than:
> >
> >     q = "/etc/init.d/reboot"
> >
> > And yeah, I've seen examples in c++ that does similar things overriding 
> > math operators to do something else. Never liked this kind of math operator
> > abuse.  
> 
> Resistance is futile, you will be assimilated. ;)

Yeah, one day I might be forced to move to it. There were much more 
assimilation attempts with regards to IPv6... So, far, I've been
resisting  ;-)

> The upside is everything's a Path object rather than a string, giving
> you methods that you'd expect paths but not strings to have, avoiding
> the tedious string manipulation all over the place.

This could make sense if this were supposed to work outside Linux 
(or Unix). As this is not the case, we don't need class abstraction
to handle directory deliminator, which is mainly the reason why 
someone writes methods and classes like os.path and pathlib.

Also, os.path has methods already to handle them in a portable way.

In this specific case, it could be using it like:

	sys.path.append(os.path.join(doctree, "/../scripts"))

to do patch contactenation, or, to be portable on other OSes:

	sys.path.append(os.path.join(doctree, "..", "scripts"))

IMO, both are easier to read, and IMHO more direct than:

	from pathlib import Path

	script_path = Path(doctree) / ".." / "scripts"
	sys.path.append(str(script_path))

Also, pathlib is more error prone, as if one does:

	>>> doctree="/tmp"
	>>> import sys
	>>> from pathlib import Path
	>>> script_path = Path(doctree) / ".." / "scripts"
	>>> sys.path.append(script_path)

It ends placing PosixPath() at the list:

	>>> sys.path
	['', '/usr/lib64/python314.zip', '/usr/lib64/python3.14', '/usr/lib64/python3.14/lib-dynload', '/usr/lib/python3.14/site-packages', PosixPath('/tmp/../scripts')]

which I don't thing it would do the right thing to do.

Regards,
Mauro