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

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

On Thu, Jan 15, 2026 at 12:19:48PM +0200, Jani Nikula wrote:
> On Wed, 14 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.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@kernel.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