linux-kernel - Re: [PATCH v2 10/12] docs: sphinx: parser

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20250613142752.01ae67d4@foz.lan>
Date: Fri, 13 Jun 2025 14:27:52 +0200
From: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
To: Donald Hunter <donald.hunter@...il.com>
Cc: Linux Doc Mailing List <linux-doc@...r.kernel.org>, Jonathan Corbet
 <corbet@....net>, "Akira Yokosawa" <akiyks@...il.com>, "Breno Leitao"
 <leitao@...ian.org>, "David S. Miller" <davem@...emloft.net>, "Eric
 Dumazet" <edumazet@...gle.com>, "Ignacio Encinas Rubio"
 <ignacio@...cinas.com>, "Jan Stancek" <jstancek@...hat.com>, "Marco Elver"
 <elver@...gle.com>, "Paolo Abeni" <pabeni@...hat.com>, "Ruben Wauters"
 <rubenru09@....com>, "Shuah Khan" <skhan@...uxfoundation.org>,
 joel@...lfernandes.org, linux-kernel-mentees@...ts.linux.dev,
 linux-kernel@...r.kernel.org, lkmm@...ts.linux.dev, netdev@...r.kernel.org,
 peterz@...radead.org, stern@...land.harvard.edu
Subject: Re: [PATCH v2 10/12] docs: sphinx: parser_yaml.py: add Netlink
 specs parser

Em Fri, 13 Jun 2025 12:45:10 +0100
Donald Hunter <donald.hunter@...il.com> escreveu:

> Mauro Carvalho Chehab <mchehab+huawei@...nel.org> writes:
> 
> > Place the code at parser_yaml.py to handle Netlink specs. All
> > other yaml files are ignored.
> >
> > Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@...nel.org>
> > ---
> >  .pylintrc                           |  2 +-
> >  Documentation/sphinx/parser_yaml.py | 39 +++++++++++++++++++++--------
> >  2 files changed, 29 insertions(+), 12 deletions(-)
> >
> > diff --git a/.pylintrc b/.pylintrc
> > index 30b8ae1659f8..f1d21379254b 100644
> > --- a/.pylintrc
> > +++ b/.pylintrc
> > @@ -1,2 +1,2 @@
> >  [MASTER]
> > -init-hook='import sys; sys.path += ["scripts/lib/kdoc", "scripts/lib/abi"]'
> > +init-hook='import sys; sys.path += ["scripts/lib", "scripts/lib/kdoc", "scripts/lib/abi"]'
> > diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
> > index b3cde9cf7aac..eb32e3249274 100755
> > --- a/Documentation/sphinx/parser_yaml.py
> > +++ b/Documentation/sphinx/parser_yaml.py
> > @@ -3,6 +3,10 @@ Sphinx extension for processing YAML files
> >  """
> >  
> >  import os
> > +import re
> > +import sys
> > +
> > +from pprint import pformat
> >  
> >  from docutils.parsers.rst import Parser as RSTParser
> >  from docutils.statemachine import ViewList
> > @@ -10,7 +14,10 @@ from docutils.statemachine import ViewList
> >  from sphinx.util import logging
> >  from sphinx.parsers import Parser
> >  
> > -from pprint import pformat
> > +srctree = os.path.abspath(os.environ["srctree"])
> > +sys.path.insert(0, os.path.join(srctree, "scripts/lib"))
> > +
> > +from netlink_yml_parser import NetlinkYamlParser      # pylint: disable=C0413
> >  
> >  logger = logging.getLogger(__name__)
> >  
> > @@ -19,8 +26,9 @@ class YamlParser(Parser):
> >  
> >      supported = ('yaml', 'yml')
> >  
> > -    # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser
> > -    def parse(self, inputstring, document):
> > +    netlink_parser = NetlinkYamlParser()
> > +
> > +    def do_parse(self, inputstring, document, msg):
> >          """Parse YAML and generate a document tree."""
> >  
> >          self.setup_parse(inputstring, document)
> > @@ -28,14 +36,6 @@ class YamlParser(Parser):
> >          result = ViewList()
> >  
> >          try:
> > -            # FIXME: Test logic to generate some ReST content
> > -            basename = os.path.basename(document.current_source)
> > -            title = os.path.splitext(basename)[0].replace('_', ' ').title()
> > -
> > -            msg = f"{title}\n"
> > -            msg += "=" * len(title) + "\n\n"
> > -            msg += "Something\n"
> > -
> >              # Parse message with RSTParser
> >              for i, line in enumerate(msg.split('\n')):
> >                  result.append(line, document.current_source, i)
> > @@ -48,6 +48,23 @@ class YamlParser(Parser):
> >  
> >          self.finish_parse()
> >  
> > +    # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser
> > +    def parse(self, inputstring, document):
> > +        """Check if a YAML is meant to be parsed."""
> > +
> > +        fname = document.current_source
> > +
> > +        # Handle netlink yaml specs
> > +        if re.search("/netlink/specs/", fname):  
> 
> The re.search is overkill since it is not a regexp. You can instead say:
> 
>     if '/netlink/specs/' in fname:

OK.

> > +            if fname.endswith("index.yaml"):
> > +                msg = self.netlink_parser.generate_main_index_rst(fname, None)
> > +            else:  
> 
> I'm guessing we can drop these lines if the static index.rst approach works.

Agreed. Will test and drop it if it works.

> 
> > +                msg = self.netlink_parser.parse_yaml_file(fname)
> > +
> > +            self.do_parse(inputstring, document, msg)
> > +
> > +        # All other yaml files are ignored
> > +
> >  def setup(app):
> >      """Setup function for the Sphinx extension."""  

Thanks,
Mauro