Skip to content

feat: Allow extensions to add templates#569

Merged
pawamoy merged 2 commits intomasterfrom
extended-templates
May 24, 2023
Merged

feat: Allow extensions to add templates#569
pawamoy merged 2 commits intomasterfrom
extended-templates

Conversation

@pawamoy
Copy link
Member

@pawamoy pawamoy commented May 12, 2023

An extension here is simply a Python package that defines an entry-point for a specific handler.

For example, an extension can add templates to the Python handler thanks to this entry-point:

[project.entry-points."mkdocstrings.python.templates"]
extension-name = "extension_package:get_templates_path"

This entry-point assumes that the extension provides a get_templates_path function directly under the extension_package package. This function doesn't accept any argument and returns the path to a directory containing templates. The directory must contain one subfolder for each supported theme, for example:

templates/
    material/
    readthedocs/
    mkdocs/

mkdocstrings will add the folders corresponding to the user-selected theme, and to the handler's defined fallback theme, as usual.

The names of the extension templates must not overlap with the handler's original templates.

The extension is then responsible, in collaboration with its target handler, for mutating the collected data in order to instruct the handler to use one of the extension template when rendering particular objects.

For example, the Python handler will look for a template attribute on objects, and use it to render the object. This template attribute will be set by Griffe extensions (Griffe is the tool used by the Python handler to collect data).
See related PR: mkdocstrings/python#70


TODO

  • docs
  • tests

pawamoy added 2 commits May 12, 2023 16:49
An extension here is simply a Python package
that defines an entry-point for a specific handler.

For example, an extension can add templates to the Python handler
thanks to this entry-point:

```toml
[project.entry-points."mkdocstrings.python.templates"]
extension-name = "extension_package:get_templates_path"
```

This entry-point assumes that the extension provides
a `get_templates_path` function directly under
the `extension_package` package. This function doesn't
accept any argument and returns the path to a directory
containing templates. The directory must contain one
subfolder for each supported theme, for example:

```
templates/
    material/
    readthedocs/
    mkdocs/
```

mkdocstrings will add the folders corresponding
to the user-selected theme, and to the handler's defined
fallback theme, as usual, to the Jinja loader.

The names of the extension templates must not
overlap with the handler's original templates.

The extension is then responsible, in collaboration
with its target handler, for mutating the collected
data in order to instruct the handler to use one of
the extension template when rendering particular objects.

For example, the Python handler will look for a `template`
attribute on objects, and use it to render the object.
This `template` attribute will be set by Griffe extensions
(Griffe is the tool used by the Python handler to collect data).
@pawamoy
Copy link
Member Author

pawamoy commented May 23, 2023

@oprypin I've added docs and tests, will merge in one or two days 🙂

@oprypin
Copy link
Member

oprypin commented May 23, 2023

Thanks.
No comments from me 🙂
Generally you don't need to wait for my review. Or let's say... if I haven't commented on something in the first 2 days, I probably won't.

@pawamoy pawamoy merged commit cf0af05 into master May 24, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants