Skip to content

Commit 370a61d

Browse files
authored
fix: Make custom_templates relative to the config file
Issue #477: #477 PR #627: #627
1 parent f4a94f7 commit 370a61d

4 files changed

Lines changed: 44 additions & 6 deletions

File tree

‎docs/usage/index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ The above is equivalent to:
108108

109109
- `default_handler`: The handler that is used by default when no handler is specified.
110110
- `custom_templates`: The path to a directory containing custom templates.
111-
The path is relative to the current working directory.
111+
The path is relative to the MkDocs configuration file.
112112
See [Theming](theming.md).
113113
- `handlers`: The handlers' global configuration.
114114
- `enable_inventory`: Whether to enable inventory file generation.

‎docs/usage/theming.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,9 @@ so you can tweak the look and feel with extra CSS rules.
1717

1818
### Templates
1919

20-
To use custom templates and override the theme ones,
21-
specify the relative path to your templates directory
22-
with the `custom_templates` global configuration option:
20+
To use custom templates and override the theme ones, specify the relative path from your
21+
configuration file to your templates directory with the `custom_templates` global
22+
configuration option:
2323

2424
```yaml title="mkdocs.yml"
2525
plugins:

‎src/mkdocstrings/plugin.py‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,7 @@
2323
from urllib import request
2424

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

‎tests/test_plugin.py‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66

77
from mkdocs.commands.build import build
88
from mkdocs.config import load_config
9+
from mkdocstrings.plugin import MkdocstringsPlugin
910

1011
if TYPE_CHECKING:
1112
from pathlib import Path
@@ -31,3 +32,38 @@ def test_disabling_plugin(tmp_path: Path) -> None:
3132

3233
# make sure the instruction was not processed
3334
assert "::: mkdocstrings" in site_dir.joinpath("index.html").read_text()
35+
36+
37+
def test_plugin_default_config(tmp_path: Path) -> None:
38+
"""Test default config options are set for Plugin."""
39+
config_file_path = tmp_path / "mkdocs.yml"
40+
plugin = MkdocstringsPlugin()
41+
errors, warnings = plugin.load_config({}, config_file_path=str(config_file_path))
42+
assert errors == []
43+
assert warnings == []
44+
assert plugin.config == {
45+
"handlers": {},
46+
"default_handler": "python",
47+
"custom_templates": None,
48+
"enable_inventory": None,
49+
"enabled": True,
50+
}
51+
52+
def test_plugin_config_custom_templates(tmp_path: Path) -> None:
53+
"""Test custom_templates option is relative to config file."""
54+
config_file_path = tmp_path / "mkdocs.yml"
55+
options = {"custom_templates": "docs/templates"}
56+
template_dir = tmp_path / options["custom_templates"]
57+
# Path must exist or config validation will fail.
58+
template_dir.mkdir(parents=True)
59+
plugin = MkdocstringsPlugin()
60+
errors, warnings = plugin.load_config(options, config_file_path=str(config_file_path))
61+
assert errors == []
62+
assert warnings == []
63+
assert plugin.config == {
64+
"handlers": {},
65+
"default_handler": "python",
66+
"custom_templates": str(template_dir),
67+
"enable_inventory": None,
68+
"enabled": True,
69+
}

0 commit comments

Comments
 (0)