From 04733487439f7707bd3aa034d082d3f14da973d7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ole=20Sch=C3=BCtt?= <ole.schuett@cp2k.org>
Date: Sun, 10 Sep 2023 16:32:04 +0200
Subject: [PATCH] Docs: Add Github links

---
 docs/Makefile                       |  1 +
 docs/conf.py                        |  8 +++++
 docs/fix_github_links.py            | 53 +++++++++++++++++++++++++++++
 tools/docker/scripts/test_manual.sh |  1 +
 tools/docker/scripts/test_misc.sh   |  1 +
 5 files changed, 64 insertions(+)
 create mode 100755 docs/fix_github_links.py

diff --git a/docs/Makefile b/docs/Makefile
index 491d141215..6ea48e54b6 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -11,6 +11,7 @@ BUILDDIR      = _build
 # Put it first so that "make" without argument is like "make help".
 help:
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	./fix_github_links.py "$(BUILDDIR)"
 
 .PHONY: help Makefile
 
diff --git a/docs/conf.py b/docs/conf.py
index 3a6df47d79..f0f139e328 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -31,4 +31,12 @@ add_module_names = False
 
 # https://myst-parser.readthedocs.io/en/v0.16.1/syntax/optional.html#syntax-header-anchors
 
+html_context = {
+    "display_github": True,
+    "github_user": "cp2k",
+    "github_repo": "cp2k",
+    "github_version": "master",
+    "conf_py_path": "/docs/",
+}
+
 # EOF
diff --git a/docs/fix_github_links.py b/docs/fix_github_links.py
new file mode 100755
index 0000000000..d8a4842ca7
--- /dev/null
+++ b/docs/fix_github_links.py
@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+
+# author: Ole Schuett
+
+import sys
+from pathlib import Path
+import re
+
+LINK_PATTERN = re.compile('<a .*? class="fa fa-github"> Edit on GitHub</a>')
+
+
+# ======================================================================================
+def main() -> None:
+    if len(sys.argv) != 2:
+        print("fix_github_links.py <build_dir>")
+        sys.exit(1)
+
+    print("Fixing GitHub links...")
+    build_dir = Path(sys.argv[1])
+
+    replace(build_dir / "bibliography.html", newlink("src/common/bibliography.F"))
+    replace(build_dir / "units.html", newlink("src/common/cp_units.F"))
+
+    message = "This page was generated. Please use the smaller [Edit on GitHub] links to see the original location of each string."
+    replace(build_dir / "CP2K_INPUT.html", alert(message))
+    cp2k_input_dir = build_dir / "CP2K_INPUT"
+    for fn in cp2k_input_dir.rglob("*.html"):
+        replace(fn, alert(message))
+
+
+# ======================================================================================
+def replace(filename: Path, replacement: str) -> None:
+    orig_content = filename.read_text()
+    new_content, count = LINK_PATTERN.subn(replacement, orig_content)
+    assert count == 1
+    filename.write_text(new_content)
+
+
+# ======================================================================================
+def newlink(src_file: str) -> str:
+    github_url = f"https://github.com/cp2k/cp2k/blob/master/{src_file}"
+    return f'<a href="{github_url}" class="fa fa-github"> Edit on GitHub</a>'
+
+
+# ======================================================================================
+def alert(message: str) -> str:
+    return f'<a onclick="alert(\'{message}\')" class="fa fa-github"> Edit on GitHub</a>'
+
+
+# ======================================================================================
+main()
+
+# EOF
diff --git a/tools/docker/scripts/test_manual.sh b/tools/docker/scripts/test_manual.sh
index 28661a866b..0f7b89bab2 100755
--- a/tools/docker/scripts/test_manual.sh
+++ b/tools/docker/scripts/test_manual.sh
@@ -43,6 +43,7 @@ set +e # disable error trapping for remainder of script
   /opt/cp2k/docs/generate_input_reference.py ./cp2k_input.xml ./references.html
   echo ""
   sphinx-build /opt/cp2k/docs/ /workspace/artifacts/manual -W -n --keep-going --jobs 16
+  /opt/cp2k/docs/fix_github_links.py /workspace/artifacts/manual
 )
 EXIT_CODE=$?
 if ((EXIT_CODE)); then
diff --git a/tools/docker/scripts/test_misc.sh b/tools/docker/scripts/test_misc.sh
index 9355210dbb..4fc9ad5075 100755
--- a/tools/docker/scripts/test_misc.sh
+++ b/tools/docker/scripts/test_misc.sh
@@ -43,6 +43,7 @@ run_test mypy --strict ./tools/docker/generate_dockerfiles.py
 run_test mypy --strict ./tools/apptainer/generate_apptainer_def_files.py
 run_test mypy --strict ./tools/conventions/analyze_gfortran_ast.py
 run_test mypy --strict ./docs/generate_input_reference.py
+run_test mypy --strict ./docs/fix_github_links.py
 
 # TODO: Find a way to test generate_dashboard.py without git repository.
 #