docs: mkdocs edit and view on github (#5114)

Author: cwhite911

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) $@
 

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
 

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 %}
+            <a href="{{ custom_edit_url }}" title="{{ lang.t('action.edit') }}" class="md-content__button md-icon">
+                {% set icon = config.theme.icon.edit or "material/file-edit-outline" %}
+                {% include ".icons/" ~ icon ~ ".svg" %}
+            </a>
+        {% endif %}
+
+        {% if "content.action.view" in features %}
+            {% if "/blob/" in custom_edit_url %}
+                {% set part = "blob" %}
+            {% else %}
+                {% set part = "edit" %}
+            {% endif %}
+                <a href="{{ custom_edit_url | replace(part, 'tree') }}" title="{{ lang.t('action.view') }}" class="md-content__button md-icon">
+                    {% set icon = config.theme.icon.view or "material/file-eye-outline" %}
+                    {% include ".icons/" ~ icon ~ ".svg" %}
+                </a>
+        {% endif %}
+    {% endif %}
+{% endif %}

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<text>.*?)\]\(https://github\.com/OSGeo/grass/tree/main/(?P<gh_path>.*?)\)"
+    )
+
+    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