Add pre/post render hooks to ModPlugin

Author: object-Object

CHANGELOG.md

@@ -4,6 +4,12 @@ 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).
 
+## `1!0.1.0a34`
+
+### Added
+
+* Added several new hooks to `ModPlugin` for running code before/after the web book is generated.
+
 ## `1!0.1.0a33`
 
 ### Fixed

src/hexdoc/cli/app.py

@@ -254,6 +254,10 @@ def build(
         env = create_jinja_env(pm, props.template.include, props_file)
 
         logger.info(f"Rendering book for {len(books)} language(s).")
+
+        site_dir.mkdir(parents=True, exist_ok=True)
+        pm.pre_render_site(books, env, site_dir, props.template.include)
+
         for book_info in books:
             try:
                 templates = get_templates(
@@ -312,6 +316,8 @@ def build(
                     raise
                 logger.exception(f"Failed to render book for {book_info.language}")
 
+        pm.post_render_site(books, env, site_dir, props.template.include)
+
     logger.info("Done.")
     return site_dir
 

src/hexdoc/jinja/render.py

@@ -88,7 +88,7 @@ def create_jinja_env(pm: PluginManager, include: Sequence[str], props_file: Path
         )
     )
 
-    return pm.update_jinja_env(env, include)
+    return pm.update_jinja_env(include, env)
 
 
 def create_jinja_env_with_loader(loader: BaseLoader):
@@ -235,6 +235,8 @@ def render_book(
     }
     pm.update_template_args(template_args)
 
+    pm.pre_render_book(template_args, output_dir, props.template.include)
+
     for filename, (template, extra_args) in templates.items():
         file = template.render(template_args | dict(extra_args))
         stripped_file = strip_empty_lines(file)
@@ -286,6 +288,8 @@ def render_book(
 
     (output_dir / MARKER_NAME).write_text(marker.model_dump_json(), "utf-8")
 
+    pm.post_render_book(template_args, output_dir, props.template.include)
+
 
 def strip_empty_lines(text: str) -> str:
     return "\n".join(s for s in text.splitlines() if s.strip())

src/hexdoc/plugin/manager.py

@@ -28,6 +28,7 @@
 from hexdoc.utils import ContextSource, ValidationContext
 
 if TYPE_CHECKING:
+    from hexdoc.cli.app import LoadedBookInfo
     from hexdoc.core import Properties, ResourceLocation
     from hexdoc.minecraft import I18n
     from hexdoc.patchouli import FormatTree
@@ -212,17 +213,55 @@ def update_context(self, context: dict[str, Any]) -> Iterator[ValidationContext]
         if returns := caller.try_call(context=context):
             yield from flatten(returns)
 
-    def update_jinja_env(self, env: SandboxedEnvironment, modids: Sequence[str]):
+    def update_jinja_env(self, modids: Sequence[str], env: SandboxedEnvironment):
         for modid in modids:
             plugin = self.mod_plugin(modid)
             plugin.update_jinja_env(env)
         return env
 
+    def pre_render_site(
+        self,
+        books: list[LoadedBookInfo],
+        env: SandboxedEnvironment,
+        output_dir: Path,
+        modids: Sequence[str],
+    ):
+        for modid in modids:
+            self.mod_plugin(modid).pre_render_site(self.props, books, env, output_dir)
+
+    def post_render_site(
+        self,
+        books: list[LoadedBookInfo],
+        env: SandboxedEnvironment,
+        output_dir: Path,
+        modids: Sequence[str],
+    ):
+        for modid in modids:
+            self.mod_plugin(modid).post_render_site(self.props, books, env, output_dir)
+
     def update_template_args(self, template_args: dict[str, Any]):
         caller = self._hook_caller(PluginSpec.hexdoc_update_template_args)
         caller.try_call(template_args=template_args)
         return template_args
 
+    def pre_render_book(
+        self,
+        template_args: dict[str, Any],
+        output_dir: Path,
+        modids: Sequence[str],
+    ):
+        for modid in modids:
+            self.mod_plugin(modid).pre_render_book(template_args, output_dir)
+
+    def post_render_book(
+        self,
+        template_args: dict[str, Any],
+        output_dir: Path,
+        modids: Sequence[str],
+    ):
+        for modid in modids:
+            self.mod_plugin(modid).post_render_book(template_args, output_dir)
+
     def load_resources(self, modid: str) -> Iterator[ModuleType]:
         plugin = self.mod_plugin(modid)
         for package in flatten([plugin.resource_dirs()]):

src/hexdoc/plugin/mod_plugin.py

@@ -15,6 +15,7 @@
 from .types import HookReturn
 
 if TYPE_CHECKING:
+    from hexdoc.cli.app import LoadedBookInfo
     from hexdoc.core import ModResourceLoader, Properties
     from hexdoc.minecraft.assets import HexdocAssetLoader
 
@@ -140,6 +141,33 @@ def update_jinja_env(self, env: SandboxedEnvironment) -> None:
         rendering the book.
         """
 
+    def pre_render_site(
+        self,
+        props: Properties,
+        books: list[LoadedBookInfo],
+        env: SandboxedEnvironment,
+        output_dir: Path,
+    ) -> None:
+        """Called once, after hexdoc is done setting up the Jinja environment but before
+        rendering the book."""
+
+    def post_render_site(
+        self,
+        props: Properties,
+        books: list[LoadedBookInfo],
+        env: SandboxedEnvironment,
+        output_dir: Path,
+    ) -> None:
+        """Called once, at the end of `hexdoc build`."""
+
+    def pre_render_book(self, template_args: dict[str, Any], output_dir: Path) -> None:
+        """Called once per language, just before rendering the book for that
+        language."""
+
+    def post_render_book(self, template_args: dict[str, Any], output_dir: Path) -> None:
+        """Called once per language, after all book files for that language are
+        rendered."""
+
     # utils
 
     def site_path(self, versioned: bool):