From c1da5fd9c2770c95eb0691e037ff8762849fa13e Mon Sep 17 00:00:00 2001 From: Corey White Date: Wed, 19 Feb 2025 09:36:08 -0500 Subject: [PATCH] docs: mkdocs edit and view on github (#5114) --- man/Makefile | 13 ++++- man/mkdocs/mkdocs.yml | 13 +++-- man/mkdocs/overrides/partials/actions.html | 27 +++++++++++ man/mkdocs/scripts/hook_list_scripts.py | 55 ++++++++++++++++++++++ 4 files changed, 103 insertions(+), 5 deletions(-) create mode 100644 man/mkdocs/overrides/partials/actions.html create mode 100644 man/mkdocs/scripts/hook_list_scripts.py diff --git a/man/Makefile b/man/Makefile index 45573de1f02..f29d5681f9d 100644 --- a/man/Makefile +++ b/man/Makefile @@ -16,7 +16,9 @@ DSTFILES := \ $(MDDIR)/mkdocs.yml \ $(MDDIR)/source/grass_logo.png \ $(MDDIR)/source/grassdocs.css \ - $(MDDIR)/overrides/partials/footer.html + $(MDDIR)/scripts/hook_list_scripts.py \ + $(MDDIR)/overrides/partials/footer.html \ + $(MDDIR)/overrides/partials/actions.html categories = \ d:display \ @@ -248,9 +250,18 @@ $(MDDIR)/mkdocs.yml: mkdocs/mkdocs.yml $(MDDIR)/source/grassdocs.css: mkdocs/grassdocs.css $(INSTALL_DATA) $< $@ +$(MDDIR)/scripts/hook_list_scripts.py: mkdocs/scripts/hook_list_scripts.py | $(MDDIR)/scripts + $(INSTALL_DATA) $< $@ + +$(MDDIR)/scripts: + $(MKDIR) $@ + $(MDDIR)/overrides/partials/footer.html: mkdocs/overrides/partials/footer.html | $(MDDIR)/overrides/partials $(INSTALL_DATA) $< $@ +$(MDDIR)/overrides/partials/actions.html: mkdocs/overrides/partials/actions.html | $(MDDIR)/overrides/partials + $(INSTALL_DATA) $< $@ + $(MDDIR)/overrides/partials: $(MKDIR) $@ diff --git a/man/mkdocs/mkdocs.yml b/man/mkdocs/mkdocs.yml index d750eadeeb5..e1be07d7a10 100644 --- a/man/mkdocs/mkdocs.yml +++ b/man/mkdocs/mkdocs.yml @@ -6,7 +6,7 @@ site_url: https://grass.osgeo.org/grass-stable/manuals/ # Repository information repo_name: GitHub repo_url: https://github.com/OSGeo/grass -# edit_uri_template: edit/main/{path} +edit_uri_template: edit/main/{path!q} # Project Configuration docs_dir: source @@ -33,20 +33,25 @@ theme: # - navigation.expand - navigation.tabs - navigation.tabs.sticky - - # - content.action.edit # Edit on GitHub + - content.action.view + - content.action.edit # Edit on GitHub palette: primary: custom # accent: custom icon: repo: fontawesome/brands/github - # edit: material/pencil + edit: material/pencil view: material/eye # Customization extra: homepage: ./index.html +# Hooks +hooks: + - scripts/hook_list_scripts.py + +# Custom CSS extra_css: - grassdocs.css diff --git a/man/mkdocs/overrides/partials/actions.html b/man/mkdocs/overrides/partials/actions.html new file mode 100644 index 00000000000..0c89301ab52 --- /dev/null +++ b/man/mkdocs/overrides/partials/actions.html @@ -0,0 +1,27 @@ +{% if page.edit_url %} + + {% set toolname = page.file.src_path.split("/")[-1] | replace(".md", "") %} + {# Default to the normal edit URL #} + {% set ghpath = github_path(toolname, config.extra.source_docs) %} + {% if ghpath %} + {% set custom_edit_url = page.edit_url | replace(toolname, ghpath ~ "/" ~ toolname) %} + {% if "content.action.edit" in features %} + + {% set icon = config.theme.icon.edit or "material/file-edit-outline" %} + {% include ".icons/" ~ icon ~ ".svg" %} + + {% endif %} + + {% if "content.action.view" in features %} + {% if "/blob/" in custom_edit_url %} + {% set part = "blob" %} + {% else %} + {% set part = "edit" %} + {% endif %} + + {% set icon = config.theme.icon.view or "material/file-eye-outline" %} + {% include ".icons/" ~ icon ~ ".svg" %} + + {% endif %} + {% endif %} +{% endif %} diff --git a/man/mkdocs/scripts/hook_list_scripts.py b/man/mkdocs/scripts/hook_list_scripts.py new file mode 100644 index 00000000000..1cb75eb4d9e --- /dev/null +++ b/man/mkdocs/scripts/hook_list_scripts.py @@ -0,0 +1,55 @@ +from pathlib import Path +import re +from jinja2 import Environment + + +def github_path(toolname: str, source_docs: dict[str, str]): + """Return the GitHub path for the given toolname""" + try: + return source_docs[toolname] + except KeyError: + return None + + +def on_env(env: Environment, config, files): + """Enable loopcontrols extension in Jinja2""" + env.add_extension("jinja2.ext.loopcontrols") + env.globals["github_path"] = github_path + return env + + +def on_config(config): + """ + Read the list of tools from the source directory and + store it in MkDocs extra config. These are used to generate + the correct links to the documentation in GitHub. + """ + source_dir = Path("source") + + # Dict to store the documentation path for each tool in GitHub + # the key is the doc name and the value is the path in the GitHub repository + source_docs = {} + + # Read the source files and extract the GitHub path from the Available at link at the bottom of the page + pattern = re.compile( + r"Available at:\s*\[(?P.*?)\]\(https://github\.com/OSGeo/grass/tree/main/(?P.*?)\)" + ) + + for file in source_dir.glob("*.md"): + with file.open() as f: + for line in f: + match = pattern.search(line) + if match: + # Extract the entire link text and the GitHub path. + text = match.group("text") + gh_path = match.group("gh_path").strip() + + # Remove the trailing "source code" from the text to get the tool name. + toolname = re.sub( + r"\s*source\s+code\s*$", "", text, flags=re.IGNORECASE + ).strip() + source_docs[toolname] = gh_path + + # Store in MkDocs extra config + config["extra"]["source_docs"] = source_docs + return config