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] [thread-next>] [day] [month] [year] [list]

Message-ID: <aWjRdFNJ_FMVnypU@foz.lan>
Date: Thu, 15 Jan 2026 12:50:26 +0100
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Jani Nikula <jani.nikula@...ux.intel.com>
Cc: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>, 
	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

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.

[1] got from textbook example at https://docs.python.org/3/library/pathlib.html

-- 
Thanks,
Mauro