tools/net/ynl/pyynl/lib/doc_generator.py

Source file repositories/reference/linux-study-clean/tools/net/ynl/pyynl/lib/doc_generator.py

File Facts

System
Linux kernel
Corpus path
tools/net/ynl/pyynl/lib/doc_generator.py
Extension
.py
Size
15325 bytes
Lines
405
Domain
Support Tooling And Documentation
Bucket
tools
Inferred role
Support Tooling And Documentation: tools
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

#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0
# -*- coding: utf-8; mode: python -*-

"""
    Class to auto generate the documentation for Netlink specifications.

    :copyright:  Copyright (C) 2023  Breno Leitao <leitao@debian.org>
    :license:    GPL Version 2, June 1991 see linux/COPYING for details.

    This class performs extensive parsing to the Linux kernel's netlink YAML
    spec files, in an effort to avoid needing to heavily mark up the original
    YAML file.

    This code is split in two classes:
        1) RST formatters: Use to convert a string to a RST output
        2) YAML Netlink (YNL) doc generator: Generate docs from YAML data
"""

from typing import Any, Dict, List
import yaml

LINE_STR = '__lineno__'

class NumberedSafeLoader(yaml.SafeLoader):              # pylint: disable=R0901
    """Override the SafeLoader class to add line number to parsed data"""

    def construct_mapping(self, node, *args, **kwargs):
        mapping = super().construct_mapping(node, *args, **kwargs)
        mapping[LINE_STR] = node.start_mark.line

        return mapping

class RstFormatters:
    """RST Formatters"""

    SPACE_PER_LEVEL = 4

    @staticmethod
    def headroom(level: int) -> str:
        """Return space to format"""
        return " " * (level * RstFormatters.SPACE_PER_LEVEL)

    @staticmethod
    def bold(text: str) -> str:
        """Format bold text"""
        return f"**{text}**"

    @staticmethod
    def inline(text: str) -> str:
        """Format inline text"""
        return f"``{text}``"

    @staticmethod
    def sanitize(text: str) -> str:
        """Remove newlines and multiple spaces"""
        # This is useful for some fields that are spread across multiple lines
        return str(text).replace("\n", " ").strip()

    def rst_fields(self, key: str, value: str, level: int = 0) -> str:
        """Return a RST formatted field"""
        return self.headroom(level) + f":{key}: {value}"

    def rst_definition(self, key: str, value: Any, level: int = 0) -> str:
        """Format a single rst definition"""
        return self.headroom(level) + key + "\n" + self.headroom(level + 1) + str(value)

    def rst_paragraph(self, paragraph: str, level: int = 0) -> str:
        """Return a formatted paragraph"""
        return self.headroom(level) + paragraph

Annotation

Implementation Notes