[PATCH v2 0/2] Some extra patches for netlink doc generation

[PATCH v2 0/2] Some extra patches for netlink doc generation

[Mauro Carvalho Chehab]

This patch series comes after:
	https://lore.kernel.org/linux-doc/cover.1749723671.git.mchehab+huawei@kernel.org/T/#t	
The first patch is meant to speedup glob time by not adding all yaml to the parser.

The second one adjusts the location of netlink/specs/index.rst.

With that, on my AMD Ryzen 9 7900 machine, the time to do a full build after a
cleanup is:

real    7m29,196s
user    14m21,893s
sys     2m28,510s

Mauro Carvalho Chehab (2):
  docs: conf.py: add include_pattern to speedup
  docs: uapi: netlink: update netlink specs link

 Documentation/conf.py                         | 7 +++++--
 Documentation/userspace-api/netlink/index.rst | 2 +-
 Documentation/userspace-api/netlink/specs.rst | 2 +-
 3 files changed, 7 insertions(+), 4 deletions(-)

-- 
2.49.0

[PATCH v2 1/2] docs: conf.py: add include_pattern to speedup

[Mauro Carvalho Chehab]

Now that we have a parser for yaml, use include_pattern, adding
just yaml files from the only directory we currently process.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/conf.py | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/Documentation/conf.py b/Documentation/conf.py
index b8668bcaf090..60e6998e49e1 100644
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -222,10 +222,13 @@ language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
+include_patterns = [
+	'**.rst',
+	'netlink/specs/*.yaml',
+]
+
 exclude_patterns = [
 	'output',
-	'devicetree/bindings/**.yaml',
-	'netlink/*.yaml',
 ]
 
 # The reST default role (used for this markup: `text`) to use for all
-- 
2.49.0

[PATCH v2 2/2] docs: uapi: netlink: update netlink specs link

[Mauro Carvalho Chehab]

With the recent parser_yaml extension, and the removal of the
auto-generated ReST source files, the location of netlink
specs changed.

Update uAPI accordingly.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
 Documentation/userspace-api/netlink/index.rst | 2 +-
 Documentation/userspace-api/netlink/specs.rst | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/userspace-api/netlink/index.rst b/Documentation/userspace-api/netlink/index.rst
index c1b6765cc963..83ae25066591 100644
--- a/Documentation/userspace-api/netlink/index.rst
+++ b/Documentation/userspace-api/netlink/index.rst
@@ -18,4 +18,4 @@ Netlink documentation for users.
 
 See also:
  - :ref:`Documentation/core-api/netlink.rst <kernel_netlink>`
- - :ref:`Documentation/networking/netlink_spec/index.rst <specs>`
+ - :ref:`Documentation/netlink/specs/index.rst <specs>`
diff --git a/Documentation/userspace-api/netlink/specs.rst b/Documentation/userspace-api/netlink/specs.rst
index 1b50d97d8d7c..debb4bfca5c4 100644
--- a/Documentation/userspace-api/netlink/specs.rst
+++ b/Documentation/userspace-api/netlink/specs.rst
@@ -15,7 +15,7 @@ kernel headers directly.
 Internally kernel uses the YAML specs to generate:
 
  - the C uAPI header
- - documentation of the protocol as a ReST file - see :ref:`Documentation/networking/netlink_spec/index.rst <specs>`
+ - documentation of the protocol as a ReST file - see :ref:`Documentation/netlink/specs/index.rst <specs>`
  - policy tables for input attribute validation
  - operation tables
 
-- 
2.49.0

Re: [PATCH v2 0/2] Some extra patches for netlink doc generation

[Mauro Carvalho Chehab]

Em Thu, 12 Jun 2025 15:41:29 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> This patch series comes after:
> 	https://lore.kernel.org/linux-doc/cover.1749723671.git.mchehab+huawei@kernel.org/T/#t	
> The first patch is meant to speedup glob time by not adding all yaml to the parser.
> 
> The second one adjusts the location of netlink/specs/index.rst.
> 
> With that, on my AMD Ryzen 9 7900 machine, the time to do a full build after a
> cleanup is:
> 
> real    7m29,196s
> user    14m21,893s
> sys     2m28,510s

Heh, funny enough, my laptop with i5-10210U CPU @ 1.60GHz builds it faster:

real	6m2,075s
user	18m47,334s
sys	1m24,931s

Both are running Sphinx version 8.1.3 with standard Fedora package. At my
laptop, this is a bit slower than no using the extension:

real	5m13,334s
user	15m56,441s
sys	1m4,072s

but it is a lot cleaner, as, with the original way, there are several
warnings after make cleandocs:

	Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`rt-link<../../networking/netlink_spec/rt-link>`
	Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>`
	Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>`
	Warning: Documentation/userspace-api/netlink/index.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst
	Warning: Documentation/userspace-api/netlink/specs.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst
	Warning: MAINTAINERS references a file that doesn't exist: Documentation/devicetree/bindings/firmware/intel,stratix10-svc.txt

Because they refer to the temp .rst source files generated inside
the source directory by the yaml conversion script.

Regards,
Mauro

Re: [PATCH v2 0/2] Some extra patches for netlink doc generation

[Mauro Carvalho Chehab]

Em Thu, 12 Jun 2025 15:41:29 +0200
Mauro Carvalho Chehab <mchehab+huawei@kernel.org> escreveu:

> This patch series comes after:
> 	https://lore.kernel.org/linux-doc/cover.1749723671.git.mchehab+huawei@kernel.org/T/#t	
> The first patch is meant to speedup glob time by not adding all yaml to the parser.
> 
> The second one adjusts the location of netlink/specs/index.rst.
> 
> With that, on my AMD Ryzen 9 7900 machine, the time to do a full build after a
> cleanup is:
> 
> real    7m29,196s
> user    14m21,893s
> sys     2m28,510s

Heh, funny enough, my laptop with i5-10210U CPU @ 1.60GHz builds it faster:

real	6m2,075s
user	18m47,334s
sys	1m24,931s

Both are running Sphinx version 8.1.3 with standard Fedora package. At my
laptop, this is a bit slower than no using the extension:

real	5m13,334s
user	15m56,441s
sys	1m4,072s

but it is a lot cleaner, as, with the original way, there are several
warnings after make cleandocs:

	Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`rt-link<../../networking/netlink_spec/rt-link>`
	Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>`
	Documentation/userspace-api/netlink/netlink-raw.rst: :doc:`tc<../../networking/netlink_spec/tc>`
	Warning: Documentation/userspace-api/netlink/index.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst
	Warning: Documentation/userspace-api/netlink/specs.rst references a file that doesn't exist: Documentation/networking/netlink_spec/index.rst

Because they refer to the temp .rst source files generated inside
the source directory by the yaml conversion script.

Regards,
Mauro

Re: [PATCH v2 0/2] Some extra patches for netlink doc generation

[Donald Hunter]

Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:

> This patch series comes after:
> 	https://lore.kernel.org/linux-doc/cover.1749723671.git.mchehab+huawei@kernel.org/T/#t

Can you please incorporate this series into a v3 of the other patch set.

Re: [PATCH v2 0/2] Some extra patches for netlink doc generation

[Mauro Carvalho Chehab]

Em Fri, 13 Jun 2025 09:24:43 +0100
Donald Hunter <donald.hunter@gmail.com> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@kernel.org> writes:
> 
> > This patch series comes after:
> > 	https://lore.kernel.org/linux-doc/cover.1749723671.git.mchehab+huawei@kernel.org/T/#t  
> 
> Can you please incorporate this series into a v3 of the other patch set.

Sure. Will send it in a few.

Thanks,
Mauro