scripts/lib was always a bit of an awkward place for Python libraries; give
them a proper home under tools/lib/python.  Put the modules from
tools/docs/lib there for good measure.

The second patch ties them into a single package namespace.  It would be
more aesthetically pleasing to add a kernel layer, so we could say:

  from kernel.kdoc import kdoc_parser

...and have the kernel-specific stuff clearly marked, but that means adding
an empty directory in the hierarchy, which isn't as pleasing.

There are some other "Python library" directories hidden in the kernel
tree; we may eventually want to encourage them to move as well.

Jonathan Corbet (2):
  docs: Move the python libraries to tools/lib/python
  docs: bring some order to our Python module hierarchy

 .pylintrc                                              |  2 +-
 Documentation/Makefile                                 |  2 +-
 Documentation/sphinx/kernel_abi.py                     |  4 ++--
 Documentation/sphinx/kernel_include.py                 |  4 ++--
 Documentation/sphinx/kerneldoc.py                      |  6 +++---
 MAINTAINERS                                            |  3 +--
 scripts/jobserver-exec                                 |  2 +-
 scripts/kernel-doc.py                                  |  6 +++---
 tools/docs/check-variable-fonts.py                     |  8 ++++++--
 tools/docs/get_abi.py                                  | 10 +++++-----
 tools/docs/parse-headers.py                            |  9 ++++++---
 tools/docs/sphinx-build-wrapper                        |  6 +++---
 tools/docs/sphinx-pre-install                          |  5 ++++-
 tools/{docs/lib => lib/python}/__init__.py             |  0
 tools/lib/python/abi/__init__.py                       |  0
 {scripts/lib => tools/lib/python}/abi/abi_parser.py    |  2 +-
 {scripts/lib => tools/lib/python}/abi/abi_regex.py     |  4 ++--
 {scripts/lib => tools/lib/python}/abi/helpers.py       |  0
 .../lib => tools/lib/python}/abi/system_symbols.py     |  2 +-
 {scripts/lib => tools/lib/python}/jobserver.py         |  0
 tools/lib/python/kdoc/__init__.py                      |  0
 .../{docs/lib => lib/python/kdoc}/enrich_formatter.py  |  0
 {scripts/lib => tools/lib/python}/kdoc/kdoc_files.py   |  4 ++--
 {scripts/lib => tools/lib/python}/kdoc/kdoc_item.py    |  0
 {scripts/lib => tools/lib/python}/kdoc/kdoc_output.py  |  4 ++--
 {scripts/lib => tools/lib/python}/kdoc/kdoc_parser.py  |  4 ++--
 {scripts/lib => tools/lib/python}/kdoc/kdoc_re.py      |  0
 tools/{docs/lib => lib/python/kdoc}/latex_fonts.py     |  0
 .../lib => lib/python/kdoc}/parse_data_structs.py      |  0
 tools/{docs/lib => lib/python/kdoc}/python_version.py  |  0
 30 files changed, 48 insertions(+), 39 deletions(-)
 rename tools/{docs/lib => lib/python}/__init__.py (100%)
 create mode 100644 tools/lib/python/abi/__init__.py
 rename {scripts/lib => tools/lib/python}/abi/abi_parser.py (99%)
 rename {scripts/lib => tools/lib/python}/abi/abi_regex.py (99%)
 rename {scripts/lib => tools/lib/python}/abi/helpers.py (100%)
 rename {scripts/lib => tools/lib/python}/abi/system_symbols.py (99%)
 rename {scripts/lib => tools/lib/python}/jobserver.py (100%)
 create mode 100644 tools/lib/python/kdoc/__init__.py
 rename tools/{docs/lib => lib/python/kdoc}/enrich_formatter.py (100%)
 rename {scripts/lib => tools/lib/python}/kdoc/kdoc_files.py (99%)
 rename {scripts/lib => tools/lib/python}/kdoc/kdoc_item.py (100%)
 rename {scripts/lib => tools/lib/python}/kdoc/kdoc_output.py (99%)
 rename {scripts/lib => tools/lib/python}/kdoc/kdoc_parser.py (99%)
 rename {scripts/lib => tools/lib/python}/kdoc/kdoc_re.py (100%)
 rename tools/{docs/lib => lib/python/kdoc}/latex_fonts.py (100%)
 rename tools/{docs/lib => lib/python/kdoc}/parse_data_structs.py (100%)
 rename tools/{docs/lib => lib/python/kdoc}/python_version.py (100%)

-- 
2.51.0

Hi,

On 11/10/25 23:04, Jonathan Corbet wrote:
> scripts/lib was always a bit of an awkward place for Python libraries; give
> them a proper home under tools/lib/python.  Put the modules from
> tools/docs/lib there for good measure.
> 
> The second patch ties them into a single package namespace.  It would be
> more aesthetically pleasing to add a kernel layer, so we could say:
> 
>    from kernel.kdoc import kdoc_parser

This is great, the code looks so much cleaner! However, it would've been 
even nicer if the redundant `kdoc_` was done away with.

So instead of:
* `import kdoc.kdoc_files` -> `import kdoc.files`
* `kdoc/kdoc_files.py` -> `kdoc/kdoc_files.py`
* `abi/abi_parser.py` -> `abi/parser.py`

etc.

Will you consider this?

Bence

Bence Csókás <bence.csokas@arm.com> writes:

> Hi,
>
> On 11/10/25 23:04, Jonathan Corbet wrote:
>> scripts/lib was always a bit of an awkward place for Python libraries; give
>> them a proper home under tools/lib/python.  Put the modules from
>> tools/docs/lib there for good measure.
>> 
>> The second patch ties them into a single package namespace.  It would be
>> more aesthetically pleasing to add a kernel layer, so we could say:
>> 
>>    from kernel.kdoc import kdoc_parser
>
> This is great, the code looks so much cleaner! However, it would've been 
> even nicer if the redundant `kdoc_` was done away with.
>
> So instead of:
> * `import kdoc.kdoc_files` -> `import kdoc.files`
> * `kdoc/kdoc_files.py` -> `kdoc/kdoc_files.py`
> * `abi/abi_parser.py` -> `abi/parser.py`
>
> etc.
>
> Will you consider this?

We can certainly consider it...that's a relatively small detail, though,
in the big organizational picture, so I wasn't concerned about it at
this point.

Thanks,

jon

Jonathan Corbet <corbet@lwn.net> writes:

> scripts/lib was always a bit of an awkward place for Python libraries; give
> them a proper home under tools/lib/python.  Put the modules from
> tools/docs/lib there for good measure.
>
> The second patch ties them into a single package namespace.  It would be
> more aesthetically pleasing to add a kernel layer, so we could say:
>
>   from kernel.kdoc import kdoc_parser
>
> ...and have the kernel-specific stuff clearly marked, but that means adding
> an empty directory in the hierarchy, which isn't as pleasing.
>
> There are some other "Python library" directories hidden in the kernel
> tree; we may eventually want to encourage them to move as well.
>
> Jonathan Corbet (2):
>   docs: Move the python libraries to tools/lib/python
>   docs: bring some order to our Python module hierarchy

In the absence of complaints, I have applied these.

Thanks,

jon

Em Tue, 18 Nov 2025 09:27:05 -0700
Jonathan Corbet <corbet@lwn.net> escreveu:

> Jonathan Corbet <corbet@lwn.net> writes:
> 
> > scripts/lib was always a bit of an awkward place for Python libraries; give
> > them a proper home under tools/lib/python.  Put the modules from
> > tools/docs/lib there for good measure.
> >
> > The second patch ties them into a single package namespace.  It would be
> > more aesthetically pleasing to add a kernel layer, so we could say:
> >
> >   from kernel.kdoc import kdoc_parser
> >
> > ...and have the kernel-specific stuff clearly marked, but that means adding
> > an empty directory in the hierarchy, which isn't as pleasing.
> >
> > There are some other "Python library" directories hidden in the kernel
> > tree; we may eventually want to encourage them to move as well.
> >
> > Jonathan Corbet (2):
> >   docs: Move the python libraries to tools/lib/python
> >   docs: bring some order to our Python module hierarchy  
> 
> In the absence of complaints, I have applied these.

Sorry, I ended missing it. Looking at the changes, looks good to 
to me.

I also tested building it and everything seems fine.

Thanks,
Mauro