Remove auto-install of missing pluglet (#262)

fralau · fralau · commit 4ec687e81b6c · 2025-09-21T16:52:40.000-04:00
- Change documentation to reflect this
  - Bump version number
  - Changelog for Pypi release
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,12 @@ All notable changes to this project are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.4.0, 2025-09-21
+* Removed: auto-install of missing pluglet (meaningful error message #262)
+* Fixed: error with yaml dumps (#258)
+* Fixed: detection of Jinja2, to allow title rendering (#266)
+* Small improvements to documentation
+  
 ## 1.3.7, 2024-10-18
 * Fixed: incompatibility with the d2 module (#249)
 
diff --git a/mkdocs_macros/plugin.py b/mkdocs_macros/plugin.py
@@ -568,8 +568,8 @@ def _load_modules(self):
                 module = importlib.import_module(module_name)
             except ModuleNotFoundError:
                 if is_on_pypi(source_name, fail_silently=True):
-                    err_msg = (f"Pluglet '{source_name}' exists on PyPI. "
-                                f"Please install it:\n\n    pip install {source_name}")
+                    err_msg = (f"Counld not import pluglet '{source_name}'. "
+                                f"Please install it from Pypi:\n\n    pip install {source_name}")
                     raise ModuleNotFoundError(err_msg, name=module_name)
                 else:
                     raise ModuleNotFoundError(f"Could not import "
diff --git a/pyproject.toml b/pyproject.toml
@@ -3,7 +3,7 @@ name = "mkdocs-macros-plugin"
 
 # This version number is the REFERENCE for the rest of the project,
 # particularly for update_pypi.sh
-version = "1.3.9"
+version = "1.4.0"
 
 description = "Unleash the power of MkDocs with macros and variables"
 readme = "README.md"
@@ -44,6 +44,9 @@ test = [
     "mkdocs-d2-plugin",
 ]
 
+# for the MkDocs documentation (webdoc/)
+doc = ["mkdocs-mermaid2-plugin"]
+
 [project.entry-points."mkdocs.plugins"]
 macros = "mkdocs_macros.plugin:MacrosPlugin"
 
diff --git a/test/missing_macros/test_site.py b/test/missing_macros/test_site.py
@@ -23,7 +23,7 @@ def test_build():
     print("Result:", result)
     # fails, declaring that the pluglet exists and must be installed.
     assert build_result.returncode != 0 # failure 
-    assert "Pluglet" in result
+    assert "pluglet" in result
     assert "pip install" in result
 
     
diff --git a/webdoc/docs/pluglets.md b/webdoc/docs/pluglets.md
@@ -85,23 +85,28 @@ plugins:
       modules: [mkdocs_macros_foo, mkdocs_macros_bar]
 ```
 
-### Auto-installable pluglets
+### Finding pluglets
 
-**Every pluglet specified in the `modules`list should be available.**
+**Every pluglet specified in the `modules`list should be already installed.**
 
-However, if the pluglet cannot be found, mkdocs will attempt to install it
-(with `pip3 install`) from the standard repositories ([Pypi](https://pypi.org/) and others [defined locally](https://pip.pypa.io/en/stable/topics/configuration/#configuration-files)). If not, mkdocs will fail and exit.
+*As of 1.4.0*
 
-!!! Tip "Make installations easier!"
-    The purpose of this feature is to facilitate the management of environments with several mkdocs websites, typically when a pluglet is designed for a whole
-    company, project, etc.
+!!! Tip "No more auto-install of pluglets"
+    However, if a pluglet cannot be found, mkdocs will no longer attempt to install it
+    (with `pip3 install`) from the standard repositories ([Pypi](https://pypi.org/) and others [defined locally](https://pip.pypa.io/en/stable/topics/configuration/#configuration-files)). 
 
-    In this way, the macros and filters declared in the pluglet will work out
-    of the box, as long as the pluglet is properly defined in the config file
-    (and the pluglet is auto-installable).
+If a plugin is available on Pypi and it was not installed, `mkdocs serve` and `mkdocs build` will fail
+with a ModuleNotFound exception and a meaningful message, making debugging easier on a new install:
 
+```
+Could not import pluglet 'mkdocs_macros_foo'. Please install it from Pypi:
+
+    pip install mkdocs_macros_foo
+```
 
-In some cases, the name of the source package i:
+If the plugin name is different from the Python import name, you _should_ specify it
+in the `modules` parameter so that MkDocs-Macros can check for its existence on Pypi,
+in case it is not installed.
 
 ``` {.yaml}
 plugins:
@@ -113,7 +118,7 @@ plugins:
 In the example above `mkdocs-macros-test` is the package source, and
 `mkdocs_macros_test` is the package name for the `import` statement.
 
-If those names are correct everything should fall into place when you type the `mkdocs serve` or `mkdocs build` commands.
+If those names are correct, the `mkdocs serve` or `mkdocs build` will give the correct error message.
 
 ## Implementing a new pluglet
 
