Add enabled option (#11)

CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing
+
+Editable install (run in root of repository):
+
+```shell
+pip install -e .
+```
+
+Setup pre-commit:
+
+```shell
+pip install pre-commit
+pre-commit install
+```
+
+Setup unit testing:
+
+```shell
+pip install --upgrade nox pytest pytest-cov
+nox
+```

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2020 Andrzej Klajnert
+Copyright (c) 2020-2022 Andrzej Klajnert
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -31,7 +31,7 @@ a separate plugin package.
 
 Just define a function and register it as a hook in the `mkdocs.yml`. The function shall
 have the same API as the desired hook. To see available hooks and their API, see the
-events chapter in the [documentation][mkdocs-hooks].
+events chapter in the [mkdocs documentation][mkdocs-hooks].
 
 ## Example
 
@@ -57,5 +57,24 @@ plugins:
 That's all - the `copy_readme()` function will run every time, before building the documentation.  
 
 
+## Disabling the plugin
+
+You can use the `enabled` option to optionally disable this plugin. A possible use case is local development where you might want faster build times. It's recommended to use this option with an environment variable together with a default fallback (introduced in `mkdocs` v1.2.1, see [docs](https://www.mkdocs.org/user-guide/configuration/#environment-variables)). Example:
+
+```yaml
+plugins:
+  - mkdocs-simple-hooks:
+      enabled: !ENV [ENABLE_MKDOCS_SIMPLE_HOOKS, True]
+      hooks:
+        on_pre_build: "docs.hooks:copy_readme"
+```
+
+Which enables you to disable the plugin locally using:
+
+```bash
+export ENABLE_MKDOCS_SIMPLE_HOOKS=false
+mkdocs serve
+```
+
 [mkdocs-plugins]: http://www.mkdocs.org/user-guide/plugins/
 [mkdocs-hooks]: https://www.mkdocs.org/user-guide/plugins/#events

mkdocs_simple_hooks/__init__.py

@@ -1,23 +1,31 @@
-import mkdocs
+import importlib
 import os
 import sys
 from functools import partial
-import importlib
 from pathlib import Path
 
+import mkdocs
+
 try:
     ModuleNotFoundError
 except NameError:  # pragma: no cover
     ModuleNotFoundError = ImportError
 
 
 class SimpleHooksPlugin(mkdocs.plugins.BasePlugin):
-    config_scheme = (("hooks", mkdocs.config.config_options.Type(dict, default={})),)
+    config_scheme = (
+        ("hooks", mkdocs.config.config_options.Type(dict, default={})),
+        ("enabled", mkdocs.config.config_options.Type(bool, default=True)),
+    )
 
     def load_config(self, options, config_file_path=None):
         errs, warns = super(SimpleHooksPlugin, self).load_config(
             options, config_file_path
         )
+
+        if not self.config.get("enabled"):
+            return errs, warns
+
         hooks = self.config.get("hooks", {})
         if not hooks:
             warns.append(

setup.py

@@ -15,7 +15,7 @@
     url="https://github.com/aklajnert/mkdocs-simple-hooks",
     license="MIT",
     packages=find_packages(),
-    install_requires=["mkdocs>=1"],
+    install_requires=["mkdocs>=1.2"],
     extras_require={"test": ["pytest>=4.0", "pytest-cov"]},
     include_package_data=True,
     zip_safe=False,

tests.py

@@ -1,9 +1,10 @@
+import pytest
 import yaml
 from click.testing import CliRunner
 from mkdocs.__main__ import build_command
 
 
-def setup_mkdocs(plugin_config, monkeypatch, tmpdir):
+def setup_mkdocs(plugin_config, monkeypatch, tmpdir, enabled=True):
     monkeypatch.chdir(tmpdir)
     monkeypatch.syspath_prepend(tmpdir)
     (tmpdir / "docs").mkdir()
@@ -15,7 +16,14 @@ def setup_mkdocs(plugin_config, monkeypatch, tmpdir):
                 "site_name": "test",
                 "docs_dir": "docs",
                 "site_dir": "site",
-                "plugins": [{"mkdocs-simple-hooks": {"hooks": plugin_config}}],
+                "plugins": [
+                    {
+                        "mkdocs-simple-hooks": {
+                            "hooks": plugin_config,
+                            "enabled": enabled,
+                        }
+                    }
+                ],
             },
             f,
         )
@@ -196,3 +204,21 @@ def test_valid_hook_module(tmpdir, monkeypatch):
     output = result.output.splitlines()
     assert output[0] == "from on_pre_build"
     assert output[-1] == "from on_post_build"
+
+
+@pytest.mark.parametrize(
+    "enabled", [True, False],
+)
+def test_disabling_plugin(tmpdir, monkeypatch, enabled):
+    with open(str(tmpdir / "hooks.py"), "w") as f:
+        f.write(
+            "def on_pre_build(*args, **kwargs):\n" '    print("from on_pre_build")\n'
+        )
+
+    runner = setup_mkdocs(
+        {"on_pre_build": "hooks:on_pre_build",}, monkeypatch, tmpdir, enabled=enabled,
+    )
+
+    result = runner.invoke(build_command)
+    assert result.exit_code == 0
+    assert ("from on_pre_build" in result.output) == enabled