Skip to content

Don't generate netlink .rst files inside $(srctree)

Mauro Carvalho Chehab linux-doc linux-kernel-mentees lkml lkmm netdev 10 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v10 Latest14 patches 5 repliesIn review
  2. v913 patches 7 repliesSuperseded
  3. v813 patches 13 repliesSuperseded
Earlier versions · 7
VersionPostedPatchesRepliesStatus
v717 patches8 repliesSuperseded
v615 patches6 repliesSuperseded
v515 patches26 repliesSuperseded
v414 patches14 repliesSuperseded
v316 patches2 repliesSuperseded
v212 patches19 repliesSuperseded
v14 patches10 repliesSuperseded

Changes in v10 from the cover letter

- added a R-B from Donald on patch 5;
- added an extra patch fixing issues with line numbers. I opted to make it a separate patch, as this was not a trivial fix, and I wanted to have it documented why the original way doesn't work, as this information can be useful in the future.

Patches in v10 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/14docs: netlink: netlink-raw.rst: use :ref: instead of :doc:Documentation/userspace-api/netlink/netlink-raw.rst tools/net/ynl/pyynl/ynl_gen_rst.py+6 -50 replies
2/14tools: ynl_gen_rst.py: Split library from command line tooltools/net/ynl/pyynl/lib/__init__.py tools/net/ynl/pyynl/lib/doc_generator.py tools/net/ynl/pyynl/ynl_gen_rst.py+400 -3590 replies
3/14docs: netlink: index.rst: add a netlink index fileDocumentation/netlink/specs/index.rst+13 -00 replies
4/14tools: ynl_gen_rst.py: cleanup coding styletools/net/ynl/pyynl/lib/doc_generator.py+25 -470 replies
5/14docs: sphinx: add a parser for yaml files for Netlink specsDocumentation/sphinx/parser_yaml.py+104 -00 replies
6/14docs: use parser_yaml extension to handle Netlink specsDocumentation/Makefile Documentation/conf.py Documentation/networking/index.rst +1 more+16 -272 replies
7/14docs: uapi: netlink: update netlink specs linkDocumentation/userspace-api/netlink/index.rst Documentation/userspace-api/netlink/specs.rst+2 -20 replies
8/14tools: ynl_gen_rst.py: drop support for generating index filestools/net/ynl/pyynl/ynl_gen_rst.py+0 -280 replies
9/14docs: netlink: remove obsolete .gitignore from unused directoryDocumentation/networking/netlink_spec/.gitignore+0 -10 replies
10/14MAINTAINERS: add netlink_yml_parser.py to linux-docMAINTAINERS+1 -00 replies
11/14tools: netlink_yml_parser.py: add line numbers to parsed datatools/net/ynl/pyynl/lib/doc_generator.py+32 -20 replies
12/14docs: parser_yaml.py: add support for line numbers from the parserDocumentation/sphinx/parser_yaml.py tools/net/ynl/pyynl/lib/doc_generator.py+22 -60 replies
13/14docs: parser_yaml.py: fix backward compatibility with old docutilsDocumentation/sphinx/parser_yaml.py+4 -00 replies
14/14sphinx: parser_yaml.py: fix line numbers informationDocumentation/sphinx/parser_yaml.py+14 -70 replies

Reviews trailers per patch

10 of 14 patches have a Reviewed-by or Acked-by.

PatchDonald HunterAkira YokosawaBreno Leitao
1/14R-b
2/14R-b
3/14R-b
4/14R-b R-b
5/14R-b
6/14R-b
7/14R-b
8/14R-b
9/14R-b
10/14R-b R-b
11/14
12/14
13/14T-b
14/14

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes. Scroll the table sideways for all 3 reviewers.

Read the v10 thread

Cover letter [PATCH v10 00/14] Don't generate netlink .rst files inside $(srctree)

Hi Jon,

That's the v10 version of the parser-yaml series, addressing a couple of issues raised by Donald.

It should apply cleanly on the top of docs-next, as I just rebased on the top of docs/docs-next.

Please merge it via your tree, as I have another patch series that will depend on this one.

-

As discussed at:
https://lore.kernel.org/all/[email protected]/

changeset f061c9f7d058 ("Documentation: Document each netlink family") added a logic which generates *.rst files inside $(srctree). This is bad when O=<BUILDDIR> is used.

A recent change renamed the yaml files used by Netlink, revealing a bad side effect: as "make cleandocs" don't clean the produced files and symbols appear duplicated for people that don't build the kernel from scratch.

This series adds an yaml parser extension and uses an index file with glob for *. We opted to write such extension in a way that no actual yaml conversion code is inside it. This makes it flexible enough to handle other types of yaml files in the future. The actual yaml conversion logic were placed at netlink_yml_parser.py.

As requested by YNL maintainers, this version has netlink_yml_parser.py inside tools/net/ynl/pyynl/ directory. I don't like mixing libraries with binaries, nor to have Python libraries spread all over the Kernel. IMO, the best is to put all of them on a common place (scripts/lib, python/lib, lib/python, ...) but, as this can be solved later, for now let's keep it this way.

---

v10:
- added a R-B from Donald on patch 5;
- added an extra patch fixing issues with line numbers. I opted to make it a separate patch, as this was not a trivial fix, and I wanted to have it documented why the original way doesn't work, as this information can be useful in the future.

v9:
- did some cleanups due to changes caused by rebases;
- added some reviewed-by/reported-by/tested-by tags;
- addressed some pylint problems at the line numbering patch.

v8:
- minor fixes based on Donald's feedback;
- removed unrelated patches.

v7:
- Added a patch to cleanup conf.py and address coding style issues;
- Added a docutils version check logic to detect known issues when building the docs with too old or too new docutils version. The actuall min/max vesion depends on Sphinx version.

v6:
- YNL doc parser is now at tools/net/ynl/pyynl/lib/doc_generator.py;
- two patches got merged;
- added instructions to test docs with Sphinx 3.4.3 (minimal supported version);
- minor fixes.

v5:
- some patch reorg;
- netlink_yml_parser.py is now together with ynl tools;
- minor fixes.

v4:
- Renamed the YNL parser class;
- some minor patch cleanups and merges;
- added an extra patch to fix a insert_pattern/exclude_pattern logic when SPHINXDIRS is used.

v3:
- Two series got merged altogether:
- https://lore.kernel.org/linux-doc/[email protected]/T/#t
- https://lore.kernel.org/linux-doc/[email protected]

- Added an extra patch to update MAINTAINERS to point to YNL library
- Added a (somewhat unrelated) patch that remove warnings check when running "make cleandocs".

Mauro Carvalho Chehab (14):
docs: netlink: netlink-raw.rst: use :ref: instead of :doc:
tools: ynl_gen_rst.py: Split library from command line tool
docs: netlink: index.rst: add a netlink index file
tools: ynl_gen_rst.py: cleanup coding style
docs: sphinx: add a parser for yaml files for Netlink specs
docs: use parser_yaml extension to handle Netlink specs
docs: uapi: netlink: update netlink specs link
tools: ynl_gen_rst.py: drop support for generating index files
docs: netlink: remove obsolete .gitignore from unused directory
MAINTAINERS: add netlink_yml_parser.py to linux-doc
tools: netlink_yml_parser.py: add line numbers to parsed data
docs: parser_yaml.py: add support for line numbers from the parser
docs: parser_yaml.py: fix backward compatibility with old docutils
sphinx: parser_yaml.py: fix line numbers information

 Documentation/Makefile                        |  17 -
 Documentation/conf.py                         |  20 +-
 Documentation/netlink/specs/index.rst         |  13 +
 Documentation/networking/index.rst            |   2 +-
 .../networking/netlink_spec/.gitignore        |   1 -
 .../networking/netlink_spec/readme.txt        |   4 -
 Documentation/sphinx/parser_yaml.py           | 123 ++++++
 Documentation/userspace-api/netlink/index.rst |   2 +-
 .../userspace-api/netlink/netlink-raw.rst     |   6 +-
 Documentation/userspace-api/netlink/specs.rst |   2 +-
 MAINTAINERS                                   |   1 +
 tools/net/ynl/pyynl/lib/__init__.py           |   2 +
 tools/net/ynl/pyynl/lib/doc_generator.py      | 398 ++++++++++++++++++
 tools/net/ynl/pyynl/ynl_gen_rst.py            | 384 +----------------
 14 files changed, 565 insertions(+), 410 deletions(-)
 create mode 100644 Documentation/netlink/specs/index.rst
 delete mode 100644 Documentation/networking/netlink_spec/.gitignore
 delete mode 100644 Documentation/networking/netlink_spec/readme.txt
 create mode 100755 Documentation/sphinx/parser_yaml.py
 create mode 100644 tools/net/ynl/pyynl/lib/doc_generator.py
Signature · 1 line
2.49.0