1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
|
#!/usr/bin/env python3
# SPDX-License-Identifier: GPL-2.0
# -*- coding: utf-8; mode: python -*-
"""
Script 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 script 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. It uses the library code from scripts/lib.
"""
import os.path
import pathlib
import sys
import argparse
import logging
sys.path.append(pathlib.Path(__file__).resolve().parent.as_posix())
from lib import YnlDocGenerator # pylint: disable=C0413
def parse_arguments() -> argparse.Namespace:
"""Parse arguments from user"""
parser = argparse.ArgumentParser(description="Netlink RST generator")
parser.add_argument("-v", "--verbose", action="store_true")
parser.add_argument("-o", "--output", help="Output file name")
# Index and input are mutually exclusive
group = parser.add_mutually_exclusive_group()
group.add_argument(
"-x", "--index", action="store_true", help="Generate the index page"
)
group.add_argument("-i", "--input", help="YAML file name")
args = parser.parse_args()
if args.verbose:
logging.basicConfig(level=logging.DEBUG)
if args.input and not os.path.isfile(args.input):
logging.warning("%s is not a valid file.", args.input)
sys.exit(-1)
if not args.output:
logging.error("No output file specified.")
sys.exit(-1)
if os.path.isfile(args.output):
logging.debug("%s already exists. Overwriting it.", args.output)
return args
def write_to_rstfile(content: str, filename: str) -> None:
"""Write the generated content into an RST file"""
logging.debug("Saving RST file to %s", filename)
with open(filename, "w", encoding="utf-8") as rst_file:
rst_file.write(content)
def generate_main_index_rst(parser: YnlDocGenerator, output: str) -> None:
"""Generate the `networking_spec/index` content and write to the file"""
lines = []
lines.append(parser.fmt.rst_header())
lines.append(parser.fmt.rst_label("specs"))
lines.append(parser.fmt.rst_title("Netlink Family Specifications"))
lines.append(parser.fmt.rst_toctree(1))
index_dir = os.path.dirname(output)
logging.debug("Looking for .rst files in %s", index_dir)
for filename in sorted(os.listdir(index_dir)):
base, ext = os.path.splitext(filename)
if filename == "index.rst" or ext not in [".rst", ".yaml"]:
continue
lines.append(f" {base}\n")
logging.debug("Writing an index file at %s", output)
write_to_rstfile("".join(lines), output)
def main() -> None:
"""Main function that reads the YAML files and generates the RST files"""
args = parse_arguments()
parser = YnlDocGenerator()
if args.input:
logging.debug("Parsing %s", args.input)
try:
content = parser.parse_yaml_file(os.path.join(args.input))
except Exception as exception:
logging.warning("Failed to parse %s.", args.input)
logging.warning(exception)
sys.exit(-1)
write_to_rstfile(content, args.output)
if args.index:
# Generate the index RST file
generate_main_index_rst(parser, args.output)
if __name__ == "__main__":
main()
|
