Comments (5)
Hi @kcgthb, thanks for opening this issue :)
I have read the discussion in Material for MkDocs' repository, and to me it would make sense to let users decide whether to emit info or warning messages for plugin configs using the Deprecated
API, just like pytest users can decide whether to treat actual warnings as info messages or errors.
I recently added a breaking change in mkdocstrings-python, with a deprecation period where users will first get info logs (not breaking their strict builds), then warnings (now breaking them).
Back to this issue, I wonder though if we should allow setting info level globally, or per deprecation message.
from mkdocs.
I π― agree that allowing users to choose the message level (INFO
or WARNING
) for each Deprecated object would be even better!
from mkdocs.
@tomchristie π in my view, this issue is a great start for improving MkDocs, as it touches many users. Basically, when you're using --strict
mode, your build will fail if you run into a plugin deprecation, but not when you use something that was deprecated in MkDocs. That sounds like an inconsistency, also see squidfunk/mkdocs-material#7146 (comment).
It would be great if you could share your view
from mkdocs.
but not when you use something that was deprecated in MkDocs
Could you expand on that?
The first part "when you're using --strict mode, your build will fail if you run into a plugin deprecation" seems right, sounds like it's the inconsistency that needs addressing?
from mkdocs.
I did expand on it in the comment I linked: squidfunk/mkdocs-material#7146 (comment)
IMHO, the most sensical thing would be that the
Deprecated
helper emits something like the following, which are deprecation warnings we fixed when upgrading to 1.6, as was reported in squidfunk/mkdocs-material#7119 (comment):INFO - DeprecationWarning: Do not access Theme._vars, instead access the keys of Theme directly. File "/opt/homebrew/lib/python3.10/site-packages/mkdocs_git_revision_date_localized_plugin/plugin.py", line 82, in on_config theme_locale = custom_theme._vars.get("locale") File "/opt/homebrew/lib/python3.10/site-packages/mkdocs/theme.py", line 87, in _vars warnings.warn( INFO - DeprecationWarning: To replace an existing file, call `remove` before `append`. File "<snip>/mkdocs-material/material/plugins/privacy/plugin.py", line 445, in _queue self.assets.append(file) File "/opt/homebrew/lib/python3.10/site-packages/mkdocs/structure/files.py", line 100, in append warnings.warn(
MkDocs uses this approach itself for their internal APIs, e.g., the
Files
collections, see an example, but emit warnings for plugin configurations. IMHO, this is inconsistent, so before we act here, we should discuss this with the maintainers of MkDocs. Interestingly, the aforementionedDeprecationWarnings
were formerly also raised with level WARNING and de-escalated to INFO in a subsequent release.
from mkdocs.
Related Issues (20)
- plugin autorefs installed but not found HOT 1
- Organizing chapters on toolbar using mkdocs
- Anchor validation false positives after upgrading to 1.6 HOT 1
- Uncaught DOMException: Element.querySelectorAll: '> .dropdown-submenu > a' is not a valid selector HOT 5
- Substring search does not work
- Improve performance and authoring experience of `mkdocs serve` HOT 14
- Break search plugin out into separate package HOT 8
- Empty mkdocs_theme.yml breaks build
- Generate nav with links to headers HOT 1
- ModuleNotFoundError: No module named 'mkdocs.tests' HOT 1
- FR: Anchor validation warning should remind the user it's case sensitive, especially if there are case-insensitive matches. HOT 3
- Anchor validation and special characters. HOT 2
- How to specify the port in MkDocs HOT 1
- AttributeError: 'EntryPoints' object has no attribute 'get' in xarray.backends HOT 1
- Should the markdown renderer treat a single line break as <br>? HOT 2
- Feature Request: Extend the `on_page_context` event with the reference to the Jinja2 Environment HOT 1
- Mkdocs no longer respecting set display text for same .md files. HOT 3
- Cannot get mkdocs to recognize the caseinsensitive plugin HOT 1
- Table display βflickersβ when refreshing the page HOT 2
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. πππ
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google β€οΈ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from mkdocs.