Closed CrispyDrone closed 3 years ago
@CrispyDrone Thanks a lot for bringing up this issue, and I understand your point.
This has been a design decision in 0.5.10, as documented in the changelog.
You should now use:
fix_url = env.macros.fix_url # make relative urls point to root
If you want to have code that works in any case you could write something like:
try:
fix_url = env.macros.fix_url # make relative urls point to root
except AttributeError:
# mkdocs-macros version < 5.10
fix_url = env.variables.fix_url # make relative urls point to root
Addition: I don't think I would like to create a fallback in mkdocs-macros as proposed in pull request #92.
For the background, I had thought (intuitively) that treating variables and macros the same was a sound decision, but under jinja2 they are very different entities, which determine different behaviors. Then it created a weird situation, where macros and variables were together, but not filters.
mkdocs-macros has been changed to align with jinja2: now variables, macros, and filters have their own list, which is very clear (better than adding "ifs" and "buts").
I realise that it may break some pre-existing code, but the fix should be easy to make?
Hello @fralau
Thanks for your prompt replies.
Sure, it's not a big problem as it was easy to fix.
However, I think from the perspective of semantic versioning, this is a breaking change. So in the future, I recommend incrementing the major version.
As a consumer, I like to lock-in to particular major versions so I have the opportunity to adapt to breaking changes at my own leisure. It seems this is possible with pip with pip install mkdocs-macros-plugin==0.*
or pip install mkdocs-macros-plugin~=0.0.0
. Of course, I don't know how common of a practice this is in the python ecosystem.
Also, I indeed had a look at the changelog, but I must admit I interpreted it differently. When I see deprecated (or even obsolete), I assume I should not use this api any more as it can be removed in a next major version, but I still expect it to work in the version in which it was deprecated or obsoleted. (I see javascript for example denotes an api as obsolete if it has been removed from that version, whereas in dotnet you have an attribute called Obsolete
that takes the role of "deprecating" it so people know it might be removed in a next major version. I don't know what approach python takes.)
In any case, feel free to close this issue.
@CrispyDrone Both points are taken:
The version numbering cannot be changed any longer, but the changelog has been corrected in c676fa5 .
I will do it better next time 🙂
@fralau
Thanks.
I do think it should be 1.0.0 (major version increment) though and not 0.6.0 (minor version).
Hello,
My build pipeline suddenly started failing. It seems to be related to the
fix_url
macro not being found in thevariables
property of the plugin.This is for version
0.5.12
ofmkdocs-macros-plugin
. Reverting to0.5.5
fixes the issue.Next, I went through the code and it seems the
fix_url
function is now part of amacros
property instead ofvariables
? Is this not a breaking change? Upgrading once more to0.5.12
and usingenv.macros.fix_url
is working.This is (was) my full
main.py
:Log output from my build server: