fix: Make custom_templates relative to the config file

Issue #477: #477
PR #627: #627

docs/usage/index.md

@@ -108,7 +108,7 @@ The above is equivalent to:
 
 - `default_handler`: The handler that is used by default when no handler is specified.
 - `custom_templates`: The path to a directory containing custom templates.
-  The path is relative to the current working directory.
+  The path is relative to the MkDocs configuration file.
   See [Theming](theming.md).
 - `handlers`: The handlers' global configuration.
 - `enable_inventory`: Whether to enable inventory file generation.

docs/usage/theming.md

@@ -17,9 +17,9 @@ so you can tweak the look and feel with extra CSS rules.
 
 ### Templates
 
-To use custom templates and override the theme ones,
-specify the relative path to your templates directory
-with the `custom_templates` global configuration option:
+To use custom templates and override the theme ones, specify the relative path from your
+configuration file to your templates directory with the `custom_templates` global
+configuration option:
 
 ```yaml title="mkdocs.yml"
 plugins:

src/mkdocstrings/plugin.py

@@ -23,6 +23,7 @@
 from urllib import request
 
 from mkdocs.config.config_options import Type as MkType
+from mkdocs.config.config_options import Dir, Optional
 from mkdocs.plugins import BasePlugin
 from mkdocs.utils import write_file
 from mkdocs_autorefs.plugin import AutorefsPlugin
@@ -78,7 +79,7 @@ class MkdocstringsPlugin(BasePlugin):
     config_scheme: tuple[tuple[str, MkType]] = (  # type: ignore[assignment]
         ("handlers", MkType(dict, default={})),
         ("default_handler", MkType(str, default="python")),
-        ("custom_templates", MkType(str, default=None)),
+        ("custom_templates", Optional(Dir(exists=True))),
         ("enable_inventory", MkType(bool, default=None)),
         ("enabled", MkType(bool, default=True)),
     )
@@ -90,7 +91,8 @@ class MkdocstringsPlugin(BasePlugin):
     - **`handlers`**: Global configuration of handlers. You can set global configuration per handler, applied everywhere,
       but overridable in each "autodoc" instruction. Example:
     - **`default_handler`**: The default handler to use. The value is the name of the handler module. Default is "python".
-    - **`custom_templates`**: Custom templates to use when rendering API objects.
+    - **`custom_templates`**: Location of custom templates to use when rendering API objects. Value should be the path of 
+      a directory relative to the MkDocs configuration file.
     - **`enable_inventory`**: Whether to enable object inventory creation.
     - **`enabled`**: Whether to enable the plugin. Default is true. If false, *mkdocstrings* will not collect or render anything.
 

tests/test_plugin.py

@@ -6,6 +6,7 @@
 
 from mkdocs.commands.build import build
 from mkdocs.config import load_config
+from mkdocstrings.plugin import MkdocstringsPlugin
 
 if TYPE_CHECKING:
     from pathlib import Path
@@ -31,3 +32,38 @@ def test_disabling_plugin(tmp_path: Path) -> None:
 
     # make sure the instruction was not processed
     assert "::: mkdocstrings" in site_dir.joinpath("index.html").read_text()
+
+
+def test_plugin_default_config(tmp_path: Path) -> None:
+    """Test default config options are set for Plugin."""
+    config_file_path = tmp_path / "mkdocs.yml"
+    plugin = MkdocstringsPlugin()
+    errors, warnings = plugin.load_config({}, config_file_path=str(config_file_path))
+    assert errors == []
+    assert warnings == []
+    assert plugin.config == {
+        "handlers": {},
+        "default_handler": "python",
+        "custom_templates": None,
+        "enable_inventory": None,
+        "enabled": True,
+    }
+
+def test_plugin_config_custom_templates(tmp_path: Path) -> None:
+    """Test custom_templates option is relative to config file."""
+    config_file_path = tmp_path / "mkdocs.yml"
+    options = {"custom_templates": "docs/templates"}
+    template_dir = tmp_path / options["custom_templates"]
+    # Path must exist or config validation will fail.
+    template_dir.mkdir(parents=True)
+    plugin = MkdocstringsPlugin()
+    errors, warnings = plugin.load_config(options, config_file_path=str(config_file_path))
+    assert errors == []
+    assert warnings == []
+    assert plugin.config == {
+        "handlers": {},
+        "default_handler": "python",
+        "custom_templates": str(template_dir),
+        "enable_inventory": None,
+        "enabled": True,
+    }