Docs: Add Github links

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
 

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

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

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

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.
 #