From 14fc4ceddc3fe2708e71dbd51829e15fda176683 Mon Sep 17 00:00:00 2001 From: object-Object Date: Fri, 5 Jul 2024 14:08:27 -0400 Subject: [PATCH] Add hexdoc_smart_var, generate GitHub repo link in navbar if no custom links are configured (close #26) --- CHANGELOG.md | 11 +++ noxfile.py | 1 + .../_templates/macros/formatting.html.jinja | 8 +- src/hexdoc/core/properties.py | 12 ++- src/hexdoc/jinja/__init__.py | 9 +- src/hexdoc/jinja/filters.py | 20 +++++ src/hexdoc/jinja/render.py | 8 ++ ...test_index[vlatestmainen_usindex.html].raw | 10 +++ ...test_files[vlatestmainen_usindex.html].raw | 10 +++ ...test_files[vlatestmainen_usindex.html].raw | 10 +++ .../docs/03-guides/03-template/index.md | 84 +++++++++++++++++- .../03-guides/03-template/navbar_default.png | Bin 0 -> 3333 bytes .../{example.png => navbar_example.png} | Bin 13 files changed, 175 insertions(+), 8 deletions(-) create mode 100644 web/docusaurus/docs/03-guides/03-template/navbar_default.png rename web/docusaurus/docs/03-guides/03-template/{example.png => navbar_example.png} (100%) diff --git a/CHANGELOG.md b/CHANGELOG.md index d55811ec..3849f5b6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Pydantic's HISTORY.md](https://github.com/pydantic/pydantic/blob/main/HISTORY.md), and this project *mostly* adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [UNRELEASED] + +### Added + +* New Jinja template filter: `hexdoc_smart_var` + * Can be used to allow runtime variable lookups based on values in `props.template.args`. This is currently used by the [custom navbar links](https://hexdoc.hexxy.media/docs/guides/template/#navbar) feature. + +### Changed + +* A GitHub link is now added to the navbar by default (fixes [#26](https://github.com/hexdoc-dev/hexdoc/issues/26)). See the [docs](https://hexdoc.hexxy.media/docs/guides/template/#navbar) for more info. + ## `1!0.1.0a19` ### Added diff --git a/noxfile.py b/noxfile.py index 0b2d3642..e0d06d72 100644 --- a/noxfile.py +++ b/noxfile.py @@ -518,6 +518,7 @@ def dummy_setup(session: nox.Session): ] right = [ { text="Right", href="https://google.ca", icon="box-arrow-up-left" }, + { text="GitHub", href.variable="source_url" }, ] """ ), diff --git a/src/hexdoc/_templates/macros/formatting.html.jinja b/src/hexdoc/_templates/macros/formatting.html.jinja index 36c926c6..e580e6ed 100644 --- a/src/hexdoc/_templates/macros/formatting.html.jinja +++ b/src/hexdoc/_templates/macros/formatting.html.jinja @@ -64,11 +64,11 @@ {%- endmacro %} {% defaultmacro navbar_link(data) -%} - {% set external = data.external|default(true) %} - {% set icon = data.icon|default("box-arrow-up-right" if external else false) %} + {% set external = data.external|default(true)|hexdoc_smart_var %} + {% set icon = data.icon|default("box-arrow-up-right" if external else false)|hexdoc_smart_var %}
  • + >{{ data.text|hexdoc_smart_var|safe }}{% if icon %} {% endif %}
    • {%- enddefaultmacro %} diff --git a/src/hexdoc/core/properties.py b/src/hexdoc/core/properties.py index 01fa757f..694edb24 100644 --- a/src/hexdoc/core/properties.py +++ b/src/hexdoc/core/properties.py @@ -60,8 +60,16 @@ def asset_url(self) -> URL: return ( URL("https://raw.githubusercontent.com") - / self.repo_owner - / self.repo_name + / self.github_repository + / self.github_sha + ) + + @property + def source_url(self) -> URL: + return ( + URL("https://github.com") + / self.github_repository + / "tree" / self.github_sha ) diff --git a/src/hexdoc/jinja/__init__.py b/src/hexdoc/jinja/__init__.py index df5d87bb..b7399019 100644 --- a/src/hexdoc/jinja/__init__.py +++ b/src/hexdoc/jinja/__init__.py @@ -2,9 +2,16 @@ "IncludeRawExtension", "hexdoc_item", "hexdoc_localize", + "hexdoc_smart_var", "hexdoc_texture", "hexdoc_wrap", ] from .extensions import IncludeRawExtension -from .filters import hexdoc_item, hexdoc_localize, hexdoc_texture, hexdoc_wrap +from .filters import ( + hexdoc_item, + hexdoc_localize, + hexdoc_smart_var, + hexdoc_texture, + hexdoc_wrap, +) diff --git a/src/hexdoc/jinja/filters.py b/src/hexdoc/jinja/filters.py index 89491006..e0afd8b7 100644 --- a/src/hexdoc/jinja/filters.py +++ b/src/hexdoc/jinja/filters.py @@ -103,3 +103,23 @@ def hexdoc_item( id, context=cast(dict[str, Any], context), # lie ) + + +@pass_context +@make_jinja_exceptions_suck_a_bit_less +def hexdoc_smart_var(context: Context, value: Any): + """Smart template argument filter. + + If `value` is of the form `{"!Variable": str(ref)}`, returns the value of the + template variable called `ref`. + + Otherwise, returns `value` unchanged. + """ + + match value: + case {**items} if len(items) != 1: + return value + case {"variable": str(ref)}: + return context.resolve(ref) + case _: + return value diff --git a/src/hexdoc/jinja/render.py b/src/hexdoc/jinja/render.py index a218b696..c394768d 100644 --- a/src/hexdoc/jinja/render.py +++ b/src/hexdoc/jinja/render.py @@ -29,6 +29,7 @@ from .filters import ( hexdoc_item, hexdoc_localize, + hexdoc_smart_var, hexdoc_texture, hexdoc_wrap, ) @@ -108,6 +109,7 @@ def create_jinja_env_with_loader(loader: BaseLoader): "hexdoc_localize": hexdoc_localize, "hexdoc_texture": hexdoc_texture, "hexdoc_item": hexdoc_item, + "hexdoc_smart_var": hexdoc_smart_var, } return env @@ -194,6 +196,7 @@ def render_book( "site_url": str(props.env.github_pages_url), "relative_site_url": relative_site_url, "page_url": str(page_url), + "source_url": str(props.env.source_url), "version": version, "lang": lang, "lang_name": lang_name, @@ -205,6 +208,11 @@ def render_book( "safari_pinned_tab_color": "#332233", "minecraft_version": minecraft_version or "???", "full_version": plugin.full_version, + "navbar": { # default navbar links (ignored if set in props) + "center": [ + {"text": "GitHub", "href": {"variable": "source_url"}}, + ], + }, "_": lambda key: hexdoc_localize( # i18n helper key, do_format=False, diff --git a/test/integration/__snapshots__/test_copier/test_index[vlatestmainen_usindex.html].raw b/test/integration/__snapshots__/test_copier/test_index[vlatestmainen_usindex.html].raw index 731560a3..08011367 100644 --- a/test/integration/__snapshots__/test_copier/test_index[vlatestmainen_usindex.html].raw +++ b/test/integration/__snapshots__/test_copier/test_index[vlatestmainen_usindex.html].raw @@ -75,6 +75,16 @@