Refactor to handle custom locations properly

Author: dannyadair

examples/custom_locations/other_pages/custom_page.yaml

@@ -1,3 +1,6 @@
 title: "Custom Location Example"
 description: "This page uses custom directory structure"
-template: "../other_templates/custom_page.svg.j2"
+template:
+  # If you just wrote this directly it would be relative to the templates directory
+  # We want it to be relative to the config file:
+  path: "../other_templates/custom_page.svg.j2"

examples/custom_locations/your_directory/config.yaml

@@ -1,9 +1,9 @@
-title: "Custom Locations Example"
-filename: "custom_locations_custom"
+title: Custom Locations Example
+filename: custom_locations_custom
 pages:
   # Simple notation - uses conventional location (pages/standard_page.yaml)
-  - "standard_page"
+  - standard_page
   # Path notation - uses custom location
-  - "../other_pages/custom_page.yaml"
+  - path: ../other_pages/custom_page.yaml
 # Custom images directory name and location
-images_dir: "../your_images"
+images_dir: ../your_images

src/pdfbaker/baker.py

@@ -19,14 +19,13 @@
 __all__ = ["PDFBaker", "PDFBakerOptions"]
 
 
-DEFAULT_CONFIG = {
+DEFAULT_BAKER_CONFIG = {
     # Default to directories relative to the config file
-    "documents_dir": ".",
-    "pages_dir": "pages",
-    "templates_dir": "templates",
-    "images_dir": "images",
-    "build_dir": "build",
-    "dist_dir": "dist",
+    "directories": {
+        "documents": ".",
+        "build": "build",
+        "dist": "dist",
+    },
 }
 
 
@@ -58,15 +57,16 @@ def __init__(
         ) -> None:
             """Initialize baker configuration (needs documents)."""
             self.baker = baker
-            self.baker.log_debug_section("Loading main configuration: %s", config_file)
             super().__init__(base_config, config_file)
+            self.baker.log_trace_section("Main configuration: %s", config_file)
             self.baker.log_trace(self.pretty())
             if "documents" not in self:
                 raise ConfigurationError(
                     'Key "documents" missing - is this the main configuration file?'
                 )
             self.documents = [
-                self.resolve_path(doc_spec) for doc_spec in self["documents"]
+                self.resolve_path(doc_spec, directory=self["directories"]["documents"])
+                for doc_spec in self["documents"]
             ]
 
     def __init__(
@@ -93,9 +93,11 @@ def __init__(
         else:
             logging.getLogger().setLevel(logging.INFO)
         self.keep_build = options.keep_build
+        base_config = DEFAULT_BAKER_CONFIG.copy()
+        base_config["directories"]["config"] = config_file.parent.resolve()
         self.config = self.Configuration(
             baker=self,
-            base_config=DEFAULT_CONFIG,
+            base_config=base_config,
             config_file=config_file,
         )
 
@@ -110,7 +112,7 @@ def bake(self) -> None:
             doc = PDFBakerDocument(
                 baker=self,
                 base_config=self.config,
-                config=doc_config,
+                config_path=doc_config,
             )
             pdf_files, error_message = doc.process_document()
             if pdf_files is None:

src/pdfbaker/config.py

@@ -11,7 +11,7 @@
 from .errors import ConfigurationError
 from .types import PathSpec
 
-__all__ = ["PDFBakerConfiguration"]
+__all__ = ["PDFBakerConfiguration", "deep_merge", "render_config"]
 
 logger = logging.getLogger(__name__)
 
@@ -51,25 +51,44 @@ class PDFBakerConfiguration(dict):
     def __init__(
         self,
         base_config: dict[str, Any],
-        config: Path,
+        config_file: Path,
     ) -> None:
         """Initialize configuration from a file.
 
         Args:
             base_config: Existing base configuration
             config: Path to YAML file to merge with base_config
         """
-        self.directory = config.parent
-        super().__init__(deep_merge(base_config, self._load_config(config)))
-
-    def _load_config(self, config_file: Path) -> dict[str, Any]:
-        """Load configuration from a file."""
         try:
             with open(config_file, encoding="utf-8") as f:
-                return yaml.safe_load(f)
+                config = yaml.safe_load(f)
         except Exception as exc:
             raise ConfigurationError(f"Failed to load config file: {exc}") from exc
 
+        # Determine all relevant directories
+        directories = {"config": config_file.parent.resolve()}
+        for directory in (
+            "documents",
+            "pages",
+            "templates",
+            "images",
+            "build",
+            "dist",
+        ):
+            if directory in config.get("directories", {}):
+                # Set in this config file
+                directories[directory] = self.resolve_path(
+                    config["directories"][directory]
+                )
+            elif directory in base_config.get("directories", {}):
+                # Inherited or not yet relevant/mentioned
+                directories[directory] = self.resolve_path(
+                    str(base_config["directories"][directory]),
+                    directory=base_config["directories"]["config"],
+                )
+        super().__init__(deep_merge(base_config, config))
+        self["directories"] = directories
+
     def resolve_path(self, spec: PathSpec, directory: Path | None = None) -> Path:
         """Resolve a possibly relative path specification.
 
@@ -79,7 +98,7 @@ def resolve_path(self, spec: PathSpec, directory: Path | None = None) -> Path:
         Returns:
             Resolved Path object
         """
-        directory = directory or self.directory
+        directory = directory or self["directories"]["config"]
         if isinstance(spec, str):
             return directory / spec
 
@@ -91,35 +110,63 @@ def resolve_path(self, spec: PathSpec, directory: Path | None = None) -> Path:
 
         return directory / spec["name"]
 
-    def render(self) -> dict[str, Any]:
-        """Resolve all template strings in config using its own values.
-
-        This allows the use of "{{ variant }}" in the "filename" etc.
-
-        Returns:
-            Resolved configuration dictionary
-
-        Raises:
-            ConfigurationError: If maximum number of iterations is reached
-                (circular references)
-        """
-        max_iterations = 10
-        config = self
-        for _ in range(max_iterations):
-            config_yaml = Template(yaml.dump(config))
-            resolved_yaml = config_yaml.render(**config)
-            new_config = yaml.safe_load(resolved_yaml)
-
-            if new_config == config:  # No more changes
-                return new_config
-            config = new_config
-
-        raise ConfigurationError(
-            "Maximum number of iterations reached. "
-            "Check for circular references in your configuration."
-        )
-
     def pretty(self, max_string=60) -> str:
         """Return readable presentation (for debugging)."""
         truncated = _truncate_strings(self, max_string)
         return pprint.pformat(truncated, indent=2)
+
+
+def _convert_paths_to_strings(config: dict[str, Any]) -> dict[str, Any]:
+    """Convert all Path objects in config to strings."""
+    result = {}
+    for key, value in config.items():
+        if isinstance(value, Path):
+            result[key] = str(value)
+        elif isinstance(value, dict):
+            result[key] = _convert_paths_to_strings(value)
+        elif isinstance(value, list):
+            result[key] = [
+                _convert_paths_to_strings(item)
+                if isinstance(item, dict)
+                else str(item)
+                if isinstance(item, Path)
+                else item
+                for item in value
+            ]
+        else:
+            result[key] = value
+    return result
+
+
+def render_config(config: dict[str, Any]) -> dict[str, Any]:
+    """Resolve all template strings in config using its own values.
+
+    This allows the use of "{{ variant }}" in the "filename" etc.
+
+    Args:
+        config: Configuration dictionary to render
+
+    Returns:
+        Resolved configuration dictionary
+
+    Raises:
+        ConfigurationError: If maximum number of iterations is reached
+            (circular references)
+    """
+    max_iterations = 10
+    current_config = dict(config)
+    current_config = _convert_paths_to_strings(current_config)
+
+    for _ in range(max_iterations):
+        config_yaml = Template(yaml.dump(current_config))
+        resolved_yaml = config_yaml.render(**current_config)
+        new_config = yaml.safe_load(resolved_yaml)
+
+        if new_config == current_config:  # No more changes
+            return new_config
+        current_config = new_config
+
+    raise ConfigurationError(
+        "Maximum number of iterations reached. "
+        "Check for circular references in your configuration."
+    )