-
Notifications
You must be signed in to change notification settings - Fork 51
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
all issues should be printed at WARN level during mkdocs serve/build #226
Comments
Welcome to this project and thank you!' first issue |
Thank you for your observation. The question of proper processing of warnings and errors becomes increasingly important, now that Mkdocs-Macros is being more used more and more in automated deployment contexts. The fact that messages signaling a Jinja2 error were passed as INFO instead had escaped my notice. The point that if WARNING was used instead, it would (virtuously) make the build fail on Concerning the processing of errors, I gave attention to that issue by allowing the person who configures the project to regulate how they want errors to be processed. There is a certain logic behind the rendering of variables, which is connected to Jinja2. The fact that unknown variables could be not rendered, is documented here. However, it should not happen: I used Finally, you are correct: |
- Generated a warning so as to make the build fail in strict mode (`mkdocs build --strict`) - Updated documentation of Advanced usage and Troubleshooting to clarify this. - Bumped revision number.
- Generated a warning so as to make the build fail in strict mode (`mkdocs build --strict`) - Updated documentation of Advanced usage and Troubleshooting to clarify this. - Bumped revision number.
This issue has been fixed (on Github). Can you check whether it works for you? |
Sorry for the misunderstanding; when I said there is not output at all for undefined variables by default, I meant in the logs, not in the generated site source. As far as I can tell, the site generation features work as intended, and my only suggestion is changing how logging works. For my workflow, I prefer to build my project locally with strict at least once before pushing and letting CI deploy the site. That way I never check in something that will not properly render and fail the deployment step in CI. I think the error configuration logic for variables that you have implemented is thoughtful and perfectly fine. I just want potential issues to be logged as warnings, since that's where I'm already looking for any potential issues on my site. As it currently stands, if I follow the basic configuration in this repository's README and simply add |
Oh you fixed it already :D That was fast! I'll pull and test |
Hmm, I wasn't able to get it working 🤔 I changed my dependency to Then if I put this in main.py: def define_env(env):
"Defines macros for Mkdocs-Macros"
@env.macro
def foo(file_name):
1/0 Then use the
Unless I'm also not getting any logs at all when I use an undefined variable and don't have |
@garfieldnate Try now? |
Okay, an error raised in main.py does indeed now print at the WARNING level, so building/serving with However, if I use a variable that's not defined, I still don't get any warnings. |
Thanks for your confirmation! Your issue helped make MkDocs-Macro's behavior more logical in case of warning. If you want to catch an undefined variable, see how you can alter the behavior of Mkdocs-Macros. |
No problem, thank you for creating the plugin!
This requires hand-checking the pages that use variables, which a user won't necessarily do if it builds cleanly with
That is a good point and is actually really annoying 😆 I guess the fix would be to put the variables into a namespace, e.g. So I guess perhaps my one and only suggestion at this point would be to mention this bit of configuration in the |
Thanks for your PR. In that way, users will know what to do. |
When you serve a site that triggers errors in the Macro plugin, the errors are printed at the INFO level instead of at the WARN level. A simple example would be:
If you use
{{my_var}}
somewhere, the output frommkdocs serve
will have an INFO message that looks like this:In addition, if you use an undefined variable, unless you've set
on_undefined
tostrict
, you don't get any output at all!In my opinion, every issue that the
macros
package knows about should be printed at the WARNING level by default. Authors can then see them and act on them, and can also choose to fail themkdocs serve
andmkdocs build
commands with the-s
(strict) flag, which we use in CI.I do see the documentation on how to use
on_error_fail
to fail the build for errors (which doesn't apply to undefined variables unlesson_undefined
is also set tostrict
!), but MkDocs already has some built-in functionality for letting authors inspect issues and fail builds with warnings, so I would find the macros plugin easier to use if it took advantage of this functionality directly. It would be less configuration and a lower likelihood of accidentally deploying a broken site.The text was updated successfully, but these errors were encountered: