Documentation/sphinx/parser_yaml.py

Source file repositories/reference/linux-study-clean/Documentation/sphinx/parser_yaml.py

File Facts

System
Linux kernel
Corpus path
Documentation/sphinx/parser_yaml.py
Extension
.py
Size
3560 bytes
Lines
124
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: Documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

# SPDX-License-Identifier: GPL-2.0
# Copyright 2025 Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

"""
Sphinx extension for processing YAML files
"""

import os
import re
import sys

from pprint import pformat

from docutils import statemachine
from docutils.parsers.rst import Parser as RSTParser
from docutils.parsers.rst import states
from docutils.statemachine import ViewList

from sphinx.util import logging
from sphinx.parsers import Parser

srctree = os.path.abspath(os.environ["srctree"])
sys.path.insert(0, os.path.join(srctree, "tools/net/ynl/pyynl/lib"))

from doc_generator import YnlDocGenerator        # pylint: disable=C0413

logger = logging.getLogger(__name__)

class YamlParser(Parser):
    """
    Kernel parser for YAML files.

    This is a simple sphinx.Parser to handle yaml files inside the
    Kernel tree that will be part of the built documentation.

    The actual parser function is not contained here: the code was
    written in a way that parsing yaml for different subsystems
    can be done from a single dispatcher.

    All it takes to have parse YAML patches is to have an import line:

            from some_parser_code import NewYamlGenerator

    To this module. Then add an instance of the parser with:

            new_parser = NewYamlGenerator()

    and add a logic inside parse() to handle it based on the path,
    like this:

            if "/foo" in fname:
                msg = self.new_parser.parse_yaml_file(fname)
    """

    supported = ('yaml', )

    netlink_parser = YnlDocGenerator()

    re_lineno = re.compile(r"\.\. LINENO ([0-9]+)$")

    tab_width = 8

    def rst_parse(self, inputstring, document, msg):
        """
        Receives a ReST content that was previously converted by the
        YAML parser, adding it to the document tree.
        """

        self.setup_parse(inputstring, document)

Annotation

Implementation Notes