refactor: Move writing extra files to an earlier stage in the build

oprypin · web-flow · commit 3890ab597692 · 2021-05-08T21:04:03.000+02:00
This step does not depend on anything that happens the HTML-rendering steps, only on the Markdown-rendering steps, so it's fine to move earlier. An example of why it's bad that the files do not exist during the HTML-rendering steps can be seen in a hypothetical commit oprypin/mkdocs@a677dd7 - basing the HTML content on the content of those files fails. PR #275: #275
diff --git a/src/mkdocstrings/plugin.py b/src/mkdocstrings/plugin.py
@@ -197,6 +197,20 @@ def inventory_enabled(self) -> bool:
             inventory_enabled = any(handler.enable_inventory for handler in self.handlers.seen_handlers)
         return inventory_enabled
 
+    def on_env(self, env, config: Config, **kwargs):
+        """Write mkdocstrings' extra files into the site dir.
+
+        This is done in `on_env` because it's the only event that happens right after all Markdown rendering.
+        """
+        if self._handlers:
+            css_content = "\n".join(handler.renderer.extra_css for handler in self.handlers.seen_handlers)
+            write_file(css_content.encode("utf-8"), os.path.join(config["site_dir"], self.css_filename))
+
+            if self.inventory_enabled:
+                log.debug("Creating inventory file objects.inv")
+                inv_contents = self.handlers.inventory.format_sphinx()
+                write_file(inv_contents, os.path.join(config["site_dir"], "objects.inv"))
+
     def on_post_build(self, config: Config, **kwargs) -> None:  # noqa: W0613,R0201 (unused arguments, cannot be static)
         """Teardown the handlers.
 
@@ -213,15 +227,7 @@ def on_post_build(self, config: Config, **kwargs) -> None:  # noqa: W0613,R0201
             config: The MkDocs config object.
             kwargs: Additional arguments passed by MkDocs.
         """
-        if self.handlers:
-            css_content = "\n".join(handler.renderer.extra_css for handler in self.handlers.seen_handlers)
-            write_file(css_content.encode("utf-8"), os.path.join(config["site_dir"], self.css_filename))
-
-            if self.inventory_enabled:
-                log.debug("Creating inventory file objects.inv")
-                inv_contents = self.handlers.inventory.format_sphinx()
-                write_file(inv_contents, os.path.join(config["site_dir"], "objects.inv"))
-
+        if self._handlers:
             log.debug("Tearing handlers down")
             self.handlers.teardown()
 
