From 42e70836846f2b08c76c39337e2a6e83afe98cb8 Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Wed, 3 Dec 2025 19:12:03 -0800 Subject: [PATCH 1/3] docs cleanup --- docs/README.md | 2 +- docs/assets/logo.png | Bin 1466 -> 0 bytes 2 files changed, 1 insertion(+), 1 deletion(-) delete mode 100644 docs/assets/logo.png diff --git a/docs/README.md b/docs/README.md index d1801a276..3925aa501 100644 --- a/docs/README.md +++ b/docs/README.md @@ -20,5 +20,5 @@ cd docs; uv run mkdocs build To serve the docs locally ``` -cd docs; uv run mkdocs serve +cd docs; uv run mkdocs serve --verbose --livereload ``` diff --git a/docs/assets/logo.png b/docs/assets/logo.png deleted file mode 100644 index 84759d575bb698d5e9e87c1805545f6ab192523a..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 1466 zcmV;r1x5OaP)TH$BBrIVK&`f^p+?YD65EINp{Wp3B1*&G2!+E5=9}V3D$@Y7=#*0Btq^mMSZ9oL480He$MRP!2x&N-QMnDzsdLR_I7vn zGqb<>?aU5?KC*Dh>UG8!2uie{QCIM&T9^xjA9^)?MmJvaDz+KP| z?#tbXKt+rIUvC=>kPJ0$DMEHY$GcGi<6GUA#WiygrffjO!F3C%{{y_{O5|<GC+|v>ygR6K z#{$9IjE28l$;euz!k6SRa(-i?tfyHhW!U|}%SM7f@-XPVCW+p%N@U&+YPU0*A2-pt zLMha;L?~H&Rp5qE@EK1sx^h;c*4It+#9l^szc4BAo;#tzb`Lc3YJCR`(916{EE7Xw z0q4SM|pQoX>4v9OEjxbb^&0ylq(D}hKuAE~ydzx)H z#(s_P*=>RWl0^k%Xpjh*ssafEcL&XUn&?wo-h2Je8G|QE_o`xYrpH6=>BPK0p7(4d6U2QeNIECEjf|o92*NXTh%T zNc7;rg9@y-Mn^{}IXPL`clGKUN+oos!uBL4()9H7nwBpwe}&9uGc`0c(BZ>}^@d+F!MBG~n0W9E4-c<^PfkuM z(5a~@)ZE;xXUJ>_A5U%+VdQ|H$#Nidc6Oq&vJ#7ni)e3e!~OezVs>^GlEiTHW)BRK zm{K|=_l8Kq*PuZ>qbTq^_K}g10iGfe7Z=BK{gjdLH{fG+N3?!OZ{(`0tCf)H>grN* zdq>AR)Z5!j2?+^CgpAM5yI%HS3psM+d77J>ql$_OWn1KSVS~X5o4nZaDBuKN40Q(w z2PrKrP1!zv{1|0rJr@ah2ZE4{O+qP=r^`#1>WIhr%6|rBne`6(<*rbvzk&`N*dGa4 zUk-V-#*VE4^<_IW$_{|=fWmtuZrxTb@|8j-$%w$hhnL4;(4w~;FcjPc9YQ9MWaz(^ z-~rb(7Sk#jYK(^SW_t)>f(JKK4=fq#OJeb!HQl`}d+nchTg3K^`@0Wb3lv)QANC+x Ut~Zh|4gdfE07*qoM6N<$f(bCH8vp Date: Wed, 3 Dec 2025 19:12:35 -0800 Subject: [PATCH 2/3] Add current file path and commit sha env --- .github/workflows/docs-action.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/docs-action.yml b/.github/workflows/docs-action.yml index fd5011f60..6568b137e 100644 --- a/.github/workflows/docs-action.yml +++ b/.github/workflows/docs-action.yml @@ -5,6 +5,7 @@ on: branches: - main paths: + - ".github/workflows/docs-action.yml" - "docs/**.md" - "docs/mkdocs.yml" - "examples/python/**" @@ -114,6 +115,7 @@ jobs: DOCSBRANCH: "gh-pages" DOCSREMOTE: "origin" GITHUB_TOKEN: "${{ secrets.GH_PAGES_PAT }}" + DOCS_COMMIT_SHA: ${{ github.sha }} run: | mkdir -p ${GITHUB_WORKSPACE}/site/ cd docs From ad2e12bfb68dfc6da11a8974eda0468b57845548 Mon Sep 17 00:00:00 2001 From: ShahanaFarooqui Date: Wed, 3 Dec 2025 19:11:45 -0800 Subject: [PATCH 3/3] Add `commit shasums` and `last updated` date on documentation site Note: Some plugins, such as mkdocs-macros-plugin, can retrieve Git details, but they offer limited flexibility in terms of information placement, styling, and formatting. A better approach was to create a custom hook and override the header. --- docs/hooks/git-info.py | 40 +++++++++++ docs/mkdocs.yml | 19 +++--- docs/overrides/partials/header.html | 85 ++++++++++++++++++++++++ docs/src/assets/stylesheets/git-info.css | 34 ++++++++++ 4 files changed, 169 insertions(+), 9 deletions(-) create mode 100644 docs/hooks/git-info.py create mode 100644 docs/overrides/partials/header.html create mode 100644 docs/src/assets/stylesheets/git-info.css diff --git a/docs/hooks/git-info.py b/docs/hooks/git-info.py new file mode 100644 index 000000000..7572bd390 --- /dev/null +++ b/docs/hooks/git-info.py @@ -0,0 +1,40 @@ +import subprocess +import os + +def on_config(config): + """ + Hook to add git commit information. This runs once when MkDocs loads the config. + """ + try: + repo_root = os.path.dirname(os.path.abspath(config.config_file_path)) + commit_hash = os.environ.get('DOCS_COMMIT_SHA') + + if commit_hash: + print(f"Using commit from DOCS_COMMIT_SHA env: {commit_hash[:7]}") + short_hash = commit_hash[:7] + commit_date = subprocess.check_output( + ['git', 'log', '-1', '--format=%cd', '--date=short', commit_hash], + cwd=repo_root, + stderr=subprocess.STDOUT + ).decode('utf-8').strip() + print(f"Git hook: Loaded commit info {short_hash} • {commit_date}") + else: + # No commit details in not provided via env + print("DOCS_COMMIT_SHA not set") + + # Add to extra context (available in templates if needed) + if 'extra' not in config: + config['extra'] = {} + + config['extra']['git'] = { + 'commit': commit_hash, + 'short_commit': short_hash, + 'date': commit_date, + } + + except subprocess.CalledProcessError as e: + print(f"Warning: Could not get git information: {e}") + except Exception as e: + print(f"Warning: Error in git hook: {e}") + + return config diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e2440d2e6..c4e1fe1d8 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -4,13 +4,10 @@ docs_dir: src repo_url: https://github.com/Blockstream/greenlight edit_uri: tree/main/docs/src -plugins: - - search - - social - - redirects: - redirect_maps: - 'reference/partner-certs.md': 'getting-started/certs.md' - +hooks: + - hooks/git-info.py +extra_css: + - assets/stylesheets/git-info.css markdown_extensions: - admonition - attr_list @@ -33,6 +30,7 @@ markdown_extensions: base_path: ["../examples/rust/snippets", "../examples/python/snippets"] theme: name: material + custom_dir: overrides logo: assets/logo.png favicon: assets/logo.png palette: @@ -53,14 +51,13 @@ theme: toggle: icon: material/weather-sunny name: Switch to light mode - features: - navigation.tabs - - content.code.annotate - navigation.instant - navigation.tabs.sticky - navigation.sections - navigation.indexes + - content.code.annotate - content.tabs.link - content.code.copy @@ -93,3 +90,7 @@ nav: - About: about/index.md - Frequently Asked Questions: about/faq.md - Changelog: about/changelog.md +extra: + generator: false +copyright: | + © 2024 Greenlight All rights reserved. \ No newline at end of file diff --git a/docs/overrides/partials/header.html b/docs/overrides/partials/header.html new file mode 100644 index 000000000..3abbb742d --- /dev/null +++ b/docs/overrides/partials/header.html @@ -0,0 +1,85 @@ +{%- set class = "md-header" -%} +{%- if "navigation.tabs.sticky" in features -%} + {%- set class = class ~ " md-header--shadow md-header--lifted" -%} +{%- elif "navigation.tabs" not in features -%} + {%- set class = class ~ " md-header--shadow" -%} +{%- endif -%} +
+ + {% if "navigation.tabs.sticky" in features %} + {% if "navigation.tabs" in features %} + {% include "partials/tabs.html" %} + {% endif %} + {% endif %} +
+{% if "navigation.tabs" in features %} + {% if "navigation.tabs.sticky" not in features %} + {% include "partials/tabs.html" %} + {% endif %} +{% endif %} \ No newline at end of file diff --git a/docs/src/assets/stylesheets/git-info.css b/docs/src/assets/stylesheets/git-info.css new file mode 100644 index 000000000..9642e085c --- /dev/null +++ b/docs/src/assets/stylesheets/git-info.css @@ -0,0 +1,34 @@ +.git-info-bar { + font-size: 0.5rem; +} + +.git-info-bar .md-grid { + display: flex; + justify-content: center; + align-items: center; + opacity: .75; +} + +.git-info-item { + display: flex; + align-items: center; + gap: 0.2rem; + padding-right: 0.3rem; +} + +.git-info-item:last-child { + padding-right: 1rem; +} + +.git-info-item svg { + width: 0.5rem; + height: 0.5rem; +} + +.git-info-item a { + text-decoration: none; +} + +.git-info-item a:hover { + text-decoration: none; +}