tools: ynl_gen_rst.py: cleanup coding style (3a3b8a14) · Commits · git / linux-net

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

+25 −47

Original line number	Diff line number	Diff line
		@@ -18,17 +18,12 @@
		"""

		from typing import Any, Dict, List
		import os.path
		import sys
		import argparse
		import logging
		import yaml


		# ==============
		# RST Formatters
		# ==============
		class RstFormatters:
		"""RST Formatters"""

		SPACE_PER_LEVEL = 4

		@staticmethod
		@@ -36,81 +31,67 @@ class RstFormatters:
		"""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


		def rst_bullet(self, item: str, level: int = 0) -> str:
		"""Return a formatted a bullet"""
		return self.headroom(level) + f"- {item}"


		@staticmethod
		def rst_subsection(title: str) -> str:
		"""Add a sub-section to the document"""
		return f"{title}\n" + "-" * len(title)


		@staticmethod
		def rst_subsubsection(title: str) -> str:
		"""Add a sub-sub-section to the document"""
		return f"{title}\n" + "~" * len(title)


		@staticmethod
		def rst_section(namespace: str, prefix: str, title: str) -> str:
		"""Add a section to the document"""
		return f".. _{namespace}-{prefix}-{title}:\n\n{title}\n" + "=" * len(title)


		@staticmethod
		def rst_subtitle(title: str) -> str:
		"""Add a subtitle to the document"""
		return "\n" + "-" * len(title) + f"\n{title}\n" + "-" * len(title) + "\n\n"


		@staticmethod
		def rst_title(title: str) -> str:
		"""Add a title to the document"""
		return "=" * len(title) + f"\n{title}\n" + "=" * len(title) + "\n\n"


		def rst_list_inline(self, list_: List[str], level: int = 0) -> str:
		"""Format a list using inlines"""
		return self.headroom(level) + "[" + ", ".join(self.inline(i) for i in list_) + "]"


		@staticmethod
		def rst_ref(namespace: str, prefix: str, name: str) -> str:
		"""Add a hyperlink to the document"""
		@@ -122,7 +103,6 @@ class RstFormatters:
		prefix = mappings[prefix]
		return f":ref:`{namespace}-{prefix}-{name}`"


		def rst_header(self) -> str:
		"""The headers for all the auto generated RST files"""
		lines = []
		@@ -132,7 +112,6 @@ class RstFormatters:

		return "\n".join(lines)


		@staticmethod
		def rst_toctree(maxdepth: int = 2) -> str:
		"""Generate a toctree RST primitive"""
		@@ -143,16 +122,13 @@ class RstFormatters:

		return "\n".join(lines)


		@staticmethod
		def rst_label(title: str) -> str:
		"""Return a formatted label"""
		return f".. _{title}:\n\n"

		# =======
		# Parsers
		# =======
		class YnlDocGenerator:
		"""YAML Netlink specs Parser"""

		fmt = RstFormatters()

		@@ -164,7 +140,6 @@ class YnlDocGenerator:

		return "\n".join(lines)


		def parse_do(self, do_dict: Dict[str, Any], level: int = 0) -> str:
		"""Parse 'do' section and return a formatted string"""
		lines = []
		@@ -177,16 +152,16 @@ class YnlDocGenerator:

		return "\n".join(lines)


		def parse_do_attributes(self, attrs: Dict[str, Any], level: int = 0) -> str:
		"""Parse 'attributes' section"""
		if "attributes" not in attrs:
		return ""
		lines = [self.fmt.rst_fields("attributes", self.fmt.rst_list_inline(attrs["attributes"]), level + 1)]
		lines = [self.fmt.rst_fields("attributes",
		self.fmt.rst_list_inline(attrs["attributes"]),
		level + 1)]

		return "\n".join(lines)


		def parse_operations(self, operations: List[Dict[str, Any]], namespace: str) -> str:
		"""Parse operations block"""
		preprocessed = ["name", "doc", "title", "do", "dump", "flags"]
		@@ -194,7 +169,8 @@ class YnlDocGenerator:
		lines = []

		for operation in operations:
		lines.append(self.fmt.rst_section(namespace, 'operation', operation["name"]))
		lines.append(self.fmt.rst_section(namespace, 'operation',
		operation["name"]))
		lines.append(self.fmt.rst_paragraph(operation["doc"]) + "\n")

		for key in operation.keys():
		@@ -206,7 +182,8 @@ class YnlDocGenerator:
		value = self.fmt.rst_ref(namespace, key, value)
		lines.append(self.fmt.rst_fields(key, value, 0))
		if 'flags' in operation:
		lines.append(self.fmt.rst_fields('flags', self.fmt.rst_list_inline(operation['flags'])))
		lines.append(self.fmt.rst_fields('flags',
		self.fmt.rst_list_inline(operation['flags'])))

		if "do" in operation:
		lines.append(self.fmt.rst_paragraph(":do:", 0))
		@@ -220,7 +197,6 @@ class YnlDocGenerator:

		return "\n".join(lines)


		def parse_entries(self, entries: List[Dict[str, Any]], level: int) -> str:
		"""Parse a list of entries"""
		ignored = ["pad"]
		@@ -235,17 +211,19 @@ class YnlDocGenerator:
		if type_:
		field_name += f" ({self.fmt.inline(type_)})"
		lines.append(
		self.fmt.rst_fields(field_name, self.fmt.sanitize(entry.get("doc", "")), level)
		self.fmt.rst_fields(field_name,
		self.fmt.sanitize(entry.get("doc", "")),
		level)
		)
		elif isinstance(entry, list):
		lines.append(self.fmt.rst_list_inline(entry, level))
		else:
		lines.append(self.fmt.rst_bullet(self.fmt.inline(self.fmt.sanitize(entry)), level))
		lines.append(self.fmt.rst_bullet(self.fmt.inline(self.fmt.sanitize(entry)),
		level))

		lines.append("\n")
		return "\n".join(lines)


		def parse_definitions(self, defs: Dict[str, Any], namespace: str) -> str:
		"""Parse definitions section"""
		preprocessed = ["name", "entries", "members"]
		@@ -270,7 +248,6 @@ class YnlDocGenerator:

		return "\n".join(lines)


		def parse_attr_sets(self, entries: List[Dict[str, Any]], namespace: str) -> str:
		"""Parse attribute from attribute-set"""
		preprocessed = ["name", "type"]
		@@ -279,7 +256,8 @@ class YnlDocGenerator:
		lines = []

		for entry in entries:
		lines.append(self.fmt.rst_section(namespace, 'attribute-set', entry["name"]))
		lines.append(self.fmt.rst_section(namespace, 'attribute-set',
		entry["name"]))
		for attr in entry["attributes"]:
		type_ = attr.get("type")
		attr_line = attr["name"]
		@@ -301,13 +279,13 @@ class YnlDocGenerator:

		return "\n".join(lines)


		def parse_sub_messages(self, entries: List[Dict[str, Any]], namespace: str) -> str:
		"""Parse sub-message definitions"""
		lines = []

		for entry in entries:
		lines.append(self.fmt.rst_section(namespace, 'sub-message', entry["name"]))
		lines.append(self.fmt.rst_section(namespace, 'sub-message',
		entry["name"]))
		for fmt in entry["formats"]:
		value = fmt["value"]

		@@ -315,13 +293,14 @@ class YnlDocGenerator:
		for attr in ['fixed-header', 'attribute-set']:
		if attr in fmt:
		lines.append(self.fmt.rst_fields(attr,
		self.fmt.rst_ref(namespace, attr, fmt[attr]),
		self.fmt.rst_ref(namespace,
		attr,
		fmt[attr]),
		1))
		lines.append("\n")

		return "\n".join(lines)


		def parse_yaml(self, obj: Dict[str, Any]) -> str:
		"""Format the whole YAML into a RST string"""
		lines = []
		@@ -344,7 +323,8 @@ class YnlDocGenerator:
		# Operations
		if "operations" in obj:
		lines.append(self.fmt.rst_subtitle("Operations"))
		lines.append(self.parse_operations(obj["operations"]["list"], family))
		lines.append(self.parse_operations(obj["operations"]["list"],
		family))

		# Multicast groups
		if "mcast-groups" in obj:
		@@ -368,11 +348,9 @@ class YnlDocGenerator:

		return "\n".join(lines)


		# Main functions
		# ==============


		def parse_yaml_file(self, filename: str) -> str:
		"""Transform the YAML specified by filename into an RST-formatted string"""
		with open(filename, "r", encoding="utf-8") as spec_file: