Move mkdocstrings-macros integration to a library #349
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
the
part:template
llucax
added
type:enhancement
This module is basically documentation, but there is some relationship to macros as we'll provide the `CODE_ANNOTATION_MARKER` as a macro variable, so we take the opportunity to unify the documentation in one place. Signed-off-by: Leandro Lucarella <[email protected]>
This module provides the required hooking, so macros can be used inside docstrings properly when using `mkdocstrings`. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
This commit adds a new utility function to retrieve version information from the repository and expose it as a couple of macro variables. This function is also called from the convenience `define_env()` function, so the variables are provided by default. Signed-off-by: Leandro Lucarella <[email protected]>
The new function `hook_env_with_everything()` will do all the default hooking, so it is easier to define a custom `define_env()` where only a few macros are added, but still gets all the variables macros and filters provided by this module. Signed-off-by: Leandro Lucarella <[email protected]>
For the basic usage we can actually use the module itself as a *pluglet*: https://mkdocs-macros-plugin.readthedocs.io/en/latest/pluglets/ Signed-off-by: Leandro Lucarella <[email protected]>
With this, there is no need for customization unless you want to define your own macros. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
The macros plugin already offer easy access to git info, so we can do a last resort try of getting the current sha from there. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
This completely removes the macros script. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
We now use the *pluglet* for templates too. Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
Signed-off-by: Leandro Lucarella <[email protected]>
shsms
reviewed
Feb 7, 2025
Contributor
shsms
left a comment
shsms
left a comment
There was a problem hiding this comment.
Perfect sleepy time PR for friday afternoon.
| ``` | ||
|
|
||
| Then you need to add the `path/to/macros.py` file. The contents will vary depending on | ||
| if you want to use use the convenience default hooking or not. |
Contributor
There was a problem hiding this comment.
Suggested change
| if you want to use use the convenience default hooking or not. | |
| whether you want to use the convenience default hooking or not. |
Contributor
Author
There was a problem hiding this comment.
That text is not present in the latest code, I wouldn't go through the trouble of fixing up the commit, but I can do it if you think it is important.
Contributor
There was a problem hiding this comment.
No, I wasn't aware it wasn't the latest code, it doesn't have to be fixed.
shsms
approved these changes
Feb 10, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR moves the documentation macros functionality from individual template repositories into a central location, making it available as a
macrospluglet. Key improvements include:macrospluglet with common functionalityThe PR also bumps template dependencies and repository configuration versions in preparation for the 0.12 release.
Fixes #179.