Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx> writes:
> Add a simple sphinx.Parser class meant to handle yaml files.
>
> For now, it just replaces a yaml file by a simple ReST
> code. I opted to do this way, as this patch can be used as
> basis for new file format parsers. We may use this as an
> example to parse other types of files.
>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@xxxxxxxxxx>
> ---
> Documentation/sphinx/parser_yaml.py | 63 +++++++++++++++++++++++++++++
> 1 file changed, 63 insertions(+)
> create mode 100755 Documentation/sphinx/parser_yaml.py
It's not a generic yaml parser so the file should be
netlink_doc_generator.py or something.
>
> diff --git a/Documentation/sphinx/parser_yaml.py b/Documentation/sphinx/parser_yaml.py
> new file mode 100755
> index 000000000000..b3cde9cf7aac
> --- /dev/null
> +++ b/Documentation/sphinx/parser_yaml.py
> @@ -0,0 +1,63 @@
> +"""
> +Sphinx extension for processing YAML files
> +"""
> +
> +import os
> +
> +from docutils.parsers.rst import Parser as RSTParser
> +from docutils.statemachine import ViewList
> +
> +from sphinx.util import logging
> +from sphinx.parsers import Parser
> +
> +from pprint import pformat
> +
> +logger = logging.getLogger(__name__)
> +
> +class YamlParser(Parser):
> + """Custom parser for YAML files."""
The class is only intended to be a netlink doc generator so I sugget
calling it NetlinkDocGenerator
> +
> + supported = ('yaml', 'yml')
I don't think we need to support the .yml extension.
> +
> + # Overrides docutils.parsers.Parser. See sphinx.parsers.RSTParser
> + def parse(self, inputstring, document):
> + """Parse YAML and generate a document tree."""
> +
> + self.setup_parse(inputstring, document)
> +
> + 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)
> +
> + rst_parser = RSTParser()
> + rst_parser.parse('\n'.join(result), document)
> +
> + except Exception as e:
> + document.reporter.error("YAML parsing error: %s" % pformat(e))
> +
> + self.finish_parse()
> +
> +def setup(app):
> + """Setup function for the Sphinx extension."""
> +
> + # Add YAML parser
> + app.add_source_parser(YamlParser)
> + app.add_source_suffix('.yaml', 'yaml')
> + app.add_source_suffix('.yml', 'yaml')
No need to support the .yml extension.
> +
> + return {
> + 'version': '1.0',
> + 'parallel_read_safe': True,
> + 'parallel_write_safe': True,
> + }
