From f783b2805872f50728a22fc57012f3576a08b2de Mon Sep 17 00:00:00 2001 From: Matthias Krack Date: Sun, 6 Aug 2023 12:11:38 +0200 Subject: [PATCH] Sort keywords in new manual and "ruff" script --- docs/generate_input_reference.py | 61 +++++++++++++++++++++----------- 1 file changed, 41 insertions(+), 20 deletions(-) diff --git a/docs/generate_input_reference.py b/docs/generate_input_reference.py index a83f904575..fefd7f920c 100755 --- a/docs/generate_input_reference.py +++ b/docs/generate_input_reference.py @@ -12,7 +12,7 @@ import sys SectionPath = Tuple[str, ...] -# ======================================================================================= +# ====================================================================================== def main() -> None: if len(sys.argv) != 3: print("generate_input_reference.py ") @@ -25,17 +25,20 @@ def main() -> None: build_input_reference(cp2k_input_xml_fn, output_dir) -# ======================================================================================= +# ====================================================================================== def build_bibliography(references_html_fn: str, output_dir: Path) -> None: content = Path(references_html_fn).read_text() entries = re.findall(".*?", content, re.DOTALL) output = [] output += ["%", "% This file was created by generate_input_reference.py", "%"] - output += [f"# Bibliography", ""] + output += ["# Bibliography", ""] for entry in entries: - pattern = '\[(.*?)\]\n (.*?)
(.*?)' + pattern = ( + '\[(.*?)\]\n (.*?)
' + "(.*?)" + ) parts = re.search(pattern, entry, re.DOTALL) assert parts key = parts.group(1) @@ -66,7 +69,7 @@ def build_bibliography(references_html_fn: str, output_dir: Path) -> None: print(f"Wrote {filename}") -# ======================================================================================= +# ====================================================================================== def build_input_reference(cp2k_input_xml_fn: str, output_dir: Path) -> None: tree = ET.parse(cp2k_input_xml_fn) root = tree.getroot() @@ -80,7 +83,7 @@ def build_input_reference(cp2k_input_xml_fn: str, output_dir: Path) -> None: output = [] output += ["%", "% This file was created by generate_input_reference.py", "%"] - output += [f"# Input reference", ""] + output += ["# Input reference", ""] assert compile_revision.startswith("git:") github_url = f"https://github.com/cp2k/cp2k/tree/{compile_revision[4:]}" @@ -99,7 +102,7 @@ def build_input_reference(cp2k_input_xml_fn: str, output_dir: Path) -> None: print(f"Wrote markdown files for {num_files_written} input sections.") -# ======================================================================================= +# ====================================================================================== def process_section( section: lxml.etree._Element, section_path: SectionPath, output_dir: Path ) -> int: @@ -116,7 +119,7 @@ def process_section( output += ["%", "% This file was created by generate_input_reference.py", "%"] output += [f"# {section_name}", ""] if repeats: - output += [f"**Section can be repeated.**", ""] + output += ["**Section can be repeated.**", ""] if references: citations = ", ".join([f"{{ref}}`{r}`" for r in references]) output += [ @@ -125,7 +128,7 @@ def process_section( ] output += [f"{escape_markdown(description)} {github_link(location)}", ""] - # Render TOC + # Render TOC for subsections if section.findall("SECTION"): output += ["```{toctree}"] output += [":maxdepth: 1"] @@ -135,14 +138,26 @@ def process_section( output += [f"{section_name}/*"] # TODO maybe list subsection explicitly. output += ["```", ""] - # Render keywords + # Collect keywords + keywords = section.findall("KEYWORD") + # Sort keywords + keywords[:] = sorted(keywords, key=get_name) + # Prepend special keywords keywords = ( section.findall("SECTION_PARAMETERS") + section.findall("DEFAULT_KEYWORD") - + section.findall("KEYWORD") + + keywords ) + if keywords: - output += [f"## Keywords", ""] + # Render TOC for keywords + output += ["## Keywords", ""] + for keyword in keywords: + keyword_name = get_name(keyword) + output += [f"* {keyword_name}"] # TODO cross-links with description + output += [""] + # Render keywords + output += ["## Keyword descriptions", ""] for keyword in keywords: output += render_keyword(keyword, section_path) @@ -155,7 +170,7 @@ def process_section( # Process subsections for subsection in section.findall("SECTION"): - subsection_name_element = subsection.find("NAME") + subsection.find("NAME") subsection_name = get_text(subsection.find("NAME")) subsection_path = (*section_path, subsection_name) num_files_written += process_section(subsection, subsection_path, output_dir) @@ -163,7 +178,13 @@ def process_section( return num_files_written -# ======================================================================================= +# ====================================================================================== +def get_name(keyword: lxml.etree._Element) -> str: + name = get_text(keyword.find("NAME")) + return name + + +# ====================================================================================== def render_keyword( keyword: lxml.etree._Element, section_path: SectionPath ) -> List[str]: @@ -218,7 +239,7 @@ def render_keyword( output += [f":value: '{default_value}'"] output += [""] if repeats: - output += [f"**Keyword can be repeated.**", ""] + output += ["**Keyword can be repeated.**", ""] if len(keyword_names) > 1: aliases = " ,".join(keyword_names[1:]) output += [f"**Aliase:** {aliases}", ""] @@ -227,7 +248,7 @@ def render_keyword( if usage: output += [f"**Usage:** _{escape_markdown(usage)}_", ""] if data_type == "enum": - output += [f"**Valid values:**"] + output += ["**Valid values:**"] for item in keyword.findall("DATA_TYPE/ENUMERATION/ITEM"): item_name = get_text(item.find("NAME")) item_description = get_text(item.find("DESCRIPTION")) @@ -243,7 +264,7 @@ def render_keyword( return output -# ======================================================================================= +# ====================================================================================== def get_text(element: Optional[lxml.etree._Element]) -> str: if element is not None: if element.text is not None: @@ -251,14 +272,14 @@ def get_text(element: Optional[lxml.etree._Element]) -> str: return "" -# ======================================================================================= +# ====================================================================================== def escape_markdown(text: str) -> str: text = text.replace("__", "\_\_") text = text.replace("#", "\#") return text -# ======================================================================================= +# ====================================================================================== def github_link(location: str) -> str: if not location: return "" @@ -267,7 +288,7 @@ def github_link(location: str) -> str: return f"[[Edit on GitHub]({github_url})]" -# ======================================================================================= +# ====================================================================================== main()