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(".")
+
# 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")
+
# Minimal supported version
needs_sphinx = "3.4.3"
@@ -32,9 +39,6 @@ else:
# Include patterns that don't contain directory names, in glob format
include_patterns = ["**.rst"]
-# Location of Documentation/ directory
-doctree = os.path.abspath(".")
-
# Exclude of patterns that don't contain directory names, in glob format.
exclude_patterns = []
@@ -151,6 +155,7 @@ extensions = [
"maintainers_include",
"parser_yaml",
"rstFlatTable",
+ "sphinx.ext.autodoc",
"sphinx.ext.autosectionlabel",
"sphinx.ext.ifconfig",
"translations",
--
2.52.0On 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.
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.
Oh, I see that you're just moving this, but this is something that
should be fixed first.
> +
> # 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.
> +
> # Minimal supported version
> needs_sphinx = "3.4.3"
>
> @@ -32,9 +39,6 @@ else:
> # Include patterns that don't contain directory names, in glob format
> include_patterns = ["**.rst"]
>
> -# Location of Documentation/ directory
> -doctree = os.path.abspath(".")
> -
> # Exclude of patterns that don't contain directory names, in glob format.
> exclude_patterns = []
>
> @@ -151,6 +155,7 @@ extensions = [
> "maintainers_include",
> "parser_yaml",
> "rstFlatTable",
> + "sphinx.ext.autodoc",
> "sphinx.ext.autosectionlabel",
> "sphinx.ext.ifconfig",
> "translations",
--
Jani Nikula, Intel
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
On Thu, 15 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.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@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.
Resistance is futile, you will be assimilated. ;)
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.
BR,
Jani.
>
> [1] got from textbook example at https://docs.python.org/3/library/pathlib.html
--
Jani Nikula, Intel
Em Thu, 15 Jan 2026 14:18:45 +0200
Jani Nikula <jani.nikula@linux.intel.com> escreveu:
> On Thu, 15 Jan 2026, Mauro Carvalho Chehab <mchehab+huawei@kernel.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@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.
>
> 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
© 2016 - 2026 Red Hat, Inc.