From 9aa00831193573958bf3da4657537167a2d0bcea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ole=20Sch=C3=BCtt?= Date: Thu, 30 Nov 2023 22:58:40 +0100 Subject: [PATCH] Manual: Add keyword mentions --- docs/generate_input_reference.py | 38 +++++++++++++++++++++++++++----- 1 file changed, 33 insertions(+), 5 deletions(-) diff --git a/docs/generate_input_reference.py b/docs/generate_input_reference.py index bf9d84b67a..55ec156deb 100755 --- a/docs/generate_input_reference.py +++ b/docs/generate_input_reference.py @@ -2,12 +2,15 @@ # author: Ole Schuett -from typing import Dict, Tuple, List, Optional +from typing import Dict, Tuple, List, Set, Optional import lxml.etree as ET import lxml from pathlib import Path import re import sys +from collections import defaultdict +from functools import cache + SectionPath = Tuple[str, ...] @@ -138,7 +141,8 @@ def process_section( for keyword in keywords: keyword_name = get_name(keyword) keyword_xref = f"{section_xref}.{sanitize_name(keyword_name)}" - output += [f"* [{escape_markdown(keyword_name)}](#{keyword_xref})"] + em = "**" if lookup_mentions(keyword_xref) else "" # emphasize if mentioned + output += [f"* {em}[{escape_markdown(keyword_name)}](#{keyword_xref}){em}"] output += [""] # Render keywords output += ["## Keyword descriptions", ""] @@ -266,6 +270,8 @@ def render_keyword( keyword_names = [get_text(name) for name in keyword.findall("NAME")] assert keyword_names canonical_name = sanitize_name(keyword_names[0]) + keyword_xref = f"{section_xref}.{canonical_name}" if section_xref else None + mentions = lookup_mentions(keyword_xref) # Find more keyword fields. default_value = get_text(keyword.find("DEFAULT_VALUE")) @@ -330,20 +336,42 @@ def render_keyword( if references: citations = ", ".join([f"{{ref}}`{r}`" for r in references]) output += [f"**References:** {citations}", ""] + if mentions: + mentions_list = ", ".join([f"⭐[](project:{m})" for m in mentions]) + output += [f"**Mentions:** {mentions_list}", ""] output += [escape_markdown(description)] if github: output += [github_link(location)] output += ["", "```", ""] # Close py:data directive. if deprecation_notice: - output += ["```{warning}", "The keyword"] - output += [f"[{canonical_name}](#{section_xref}.{canonical_name})"] - output += [" is deprecated and may be removed in a future version.", ""] + output += ["```{warning}", f"The keyword [{canonical_name}](#{keyword_xref})"] + output += ["is deprecated and may be removed in a future version.", ""] output += [escape_markdown(deprecation_notice), "", "```", ""] return output +# ====================================================================================== +@cache +def find_all_mentions() -> Dict[str, Set[Path]]: + root_dir = Path(__file__).resolve().parent + mentions = defaultdict(set) + for fn in (root_dir / "methods").glob("**/*.md"): + for xref in re.findall(r"\(#(CP2K_INPUT\..*)\)", fn.read_text()): + mentions[xref].add(fn.relative_to(root_dir)) + return mentions + + +# ====================================================================================== +def lookup_mentions(xref: Optional[str]) -> List[str]: + if not xref: + return [] + mentions = find_all_mentions() + n = xref.count(".") - 1 + return [("../" * n) + str(path) for path in sorted(mentions[xref])] + + # ====================================================================================== def get_name(element: lxml.etree._Element) -> str: return get_text(element.find("NAME"))