mkdocs-spellcheck 1.1.2__tar.gz → 1.2.0__tar.gz

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/CHANGELOG.md

@@ -5,6 +5,14 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [1.2.0](https://github.com/pawamoy/mkdocs-spellcheck/releases/tag/1.2.0) - 2025-12-01
+
+<small>[Compare with 1.1.2](https://github.com/pawamoy/mkdocs-spellcheck/compare/1.1.2...1.2.0)</small>
+
+### Features
+
+- Allow disabling spellcheck in specific regions thanks to HTML comments ([17e4ff3](https://github.com/pawamoy/mkdocs-spellcheck/commit/17e4ff307c9b9c71db8462b3d46463c02185235f) by Tobias Langer). [Issue #33](https://github.com/pawamoy/mkdocs-spellcheck/issues/33), [PR-34](https://github.com/pawamoy/mkdocs-spellcheck/pull/34)
+
 ## [1.1.2](https://github.com/pawamoy/mkdocs-spellcheck/releases/tag/1.1.2) - 2025-08-05
 
 <small>[Compare with 1.1.1](https://github.com/pawamoy/mkdocs-spellcheck/compare/1.1.1...1.1.2)</small>

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocs-spellcheck
-Version: 1.1.2
+Version: 1.2.0
 Summary: A spell checker plugin for MkDocs.
 Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
 License-Expression: ISC
@@ -10,7 +10,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -29,7 +28,7 @@ Project-URL: Issues, https://github.com/pawamoy/mkdocs-spellcheck/issues
 Project-URL: Discussions, https://github.com/pawamoy/mkdocs-spellcheck/discussions
 Project-URL: Gitter, https://gitter.im/mkdocs-spellcheck/community
 Project-URL: Funding, https://github.com/sponsors/pawamoy
-Requires-Python: >=3.9
+Requires-Python: >=3.10
 Requires-Dist: mkdocs>=1.5
 Provides-Extra: all
 Requires-Dist: mkdocs-spellcheck[codespell,symspellpy]; extra == "all"
@@ -42,10 +41,13 @@ Description-Content-Type: text/markdown
 
 # MkDocs SpellCheck
 
+> [!WARNING]
+> This project is in maintenance mode. I'm now dedicating my time to [Zensical](https://zensical.org/). Feel free to reach out for a responsible transfer of maintainership.
+
 [![ci](https://github.com/pawamoy/mkdocs-spellcheck/workflows/ci/badge.svg)](https://github.com/pawamoy/mkdocs-spellcheck/actions?query=workflow%3Aci)
 [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://pawamoy.github.io/mkdocs-spellcheck/)
 [![pypi version](https://img.shields.io/pypi/v/mkdocs-spellcheck.svg)](https://pypi.org/project/mkdocs-spellcheck/)
-[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#mkdocs-spellcheck:gitter.im)
+[![gitter](https://img.shields.io/badge/matrix-chat-4DB798.svg?style=flat)](https://app.gitter.im/#/room/#mkdocs-spellcheck:gitter.im)
 
 A spell checker plugin for MkDocs.
 
@@ -120,3 +122,24 @@ The builtin dictionaries are:
     to be typos in other contexts (such as `uint`)
 - `names` for valid proper names that might be typos
 - `en-GB_to_en-US` for corrections from `en-GB` to `en-US`
+
+### On-off regions
+
+In some situations it can be useful to temporarily disable spell checking for a document.
+To this end, MkDocs SpellCheck recognizes special guards `mkdocs-spellcheck-{on,off}`:
+
+```md
+Here MkDocs SpellCheck checks for correct spelling.
+
+<!-- mkdocs-spellcheck-off -->
+In this block it doesn't.
+<!-- mkdocs-spellcheck-on -->
+
+Here spelling checks are performed again.
+```
+
+## Sponsors
+
+<!-- sponsors-start -->
+<!-- sponsors-end -->
+

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/README.md

@@ -1,9 +1,12 @@
 # MkDocs SpellCheck
 
+> [!WARNING]
+> This project is in maintenance mode. I'm now dedicating my time to [Zensical](https://zensical.org/). Feel free to reach out for a responsible transfer of maintainership.
+
 [![ci](https://github.com/pawamoy/mkdocs-spellcheck/workflows/ci/badge.svg)](https://github.com/pawamoy/mkdocs-spellcheck/actions?query=workflow%3Aci)
 [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://pawamoy.github.io/mkdocs-spellcheck/)
 [![pypi version](https://img.shields.io/pypi/v/mkdocs-spellcheck.svg)](https://pypi.org/project/mkdocs-spellcheck/)
-[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#mkdocs-spellcheck:gitter.im)
+[![gitter](https://img.shields.io/badge/matrix-chat-4DB798.svg?style=flat)](https://app.gitter.im/#/room/#mkdocs-spellcheck:gitter.im)
 
 A spell checker plugin for MkDocs.
 
@@ -78,3 +81,24 @@ The builtin dictionaries are:
     to be typos in other contexts (such as `uint`)
 - `names` for valid proper names that might be typos
 - `en-GB_to_en-US` for corrections from `en-GB` to `en-US`
+
+### On-off regions
+
+In some situations it can be useful to temporarily disable spell checking for a document.
+To this end, MkDocs SpellCheck recognizes special guards `mkdocs-spellcheck-{on,off}`:
+
+```md
+Here MkDocs SpellCheck checks for correct spelling.
+
+<!-- mkdocs-spellcheck-off -->
+In this block it doesn't.
+<!-- mkdocs-spellcheck-on -->
+
+Here spelling checks are performed again.
+```
+
+## Sponsors
+
+<!-- sponsors-start -->
+<!-- sponsors-end -->
+

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/config/pytest.ini

@@ -10,5 +10,7 @@ testpaths =
 # action:message_regex:warning_class:module_regex:line
 filterwarnings =
   error
+  default::EncodingWarning
+  error::EncodingWarning:mkdocs_spellcheck
   # TODO: remove once pytest-xdist 4 is released
   ignore:.*rsyncdir:DeprecationWarning:xdist

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/duties.py

@@ -5,16 +5,12 @@ from __future__ import annotations
 import os
 import re
 import sys
-from contextlib import contextmanager
-from importlib.metadata import version as pkgversion
 from pathlib import Path
 from typing import TYPE_CHECKING
 
 from duty import duty, tools
 
 if TYPE_CHECKING:
-    from collections.abc import Iterator
-
     from duty.context import Context
 
 
@@ -25,6 +21,8 @@ CI = os.environ.get("CI", "0") in {"1", "true", "yes", ""}
 WINDOWS = os.name == "nt"
 PTY = not WINDOWS and not CI
 MULTIRUN = os.environ.get("MULTIRUN", "0") == "1"
+PY_VERSION = f"{sys.version_info.major}{sys.version_info.minor}"
+PY_DEV = "314"
 
 
 def pyprefix(title: str) -> str:
@@ -34,18 +32,6 @@ def pyprefix(title: str) -> str:
     return title
 
 
-@contextmanager
-def material_insiders() -> Iterator[bool]:
-    if "+insiders" in pkgversion("mkdocs-material"):
-        os.environ["MATERIAL_INSIDERS"] = "true"
-        try:
-            yield True
-        finally:
-            os.environ.pop("MATERIAL_INSIDERS")
-    else:
-        yield False
-
-
 def _get_changelog_version() -> str:
     changelog_version_re = re.compile(r"^## \[(\d+\.\d+\.\d+)\].*$")
     with Path(__file__).parent.joinpath("CHANGELOG.md").open("r", encoding="utf8") as file:
@@ -68,7 +54,7 @@ def check(ctx: Context) -> None:
     """Check it all!"""
 
 
-@duty
+@duty(nofail=PY_VERSION == PY_DEV)
 def check_quality(ctx: Context) -> None:
     """Check the code quality."""
     ctx.run(
@@ -77,19 +63,18 @@ def check_quality(ctx: Context) -> None:
     )
 
 
-@duty
+@duty(nofail=PY_VERSION == PY_DEV)
 def check_docs(ctx: Context) -> None:
     """Check if the documentation builds correctly."""
     Path("htmlcov").mkdir(parents=True, exist_ok=True)
     Path("htmlcov/index.html").touch(exist_ok=True)
-    with material_insiders():
-        ctx.run(
-            tools.mkdocs.build(strict=True, verbose=True),
-            title=pyprefix("Building documentation"),
-        )
+    ctx.run(
+        tools.mkdocs.build(strict=True, verbose=True),
+        title=pyprefix("Building documentation"),
+    )
 
 
-@duty
+@duty(nofail=PY_VERSION == PY_DEV)
 def check_types(ctx: Context) -> None:
     """Check that the code is correctly typed."""
     os.environ["FORCE_COLOR"] = "1"
@@ -99,7 +84,7 @@ def check_types(ctx: Context) -> None:
     )
 
 
-@duty
+@duty(nofail=PY_VERSION == PY_DEV)
 def check_api(ctx: Context, *cli_args: str) -> None:
     """Check for API breaking changes."""
     ctx.run(
@@ -117,22 +102,18 @@ def docs(ctx: Context, *cli_args: str, host: str = "127.0.0.1", port: int = 8000
         host: The host to serve the docs from.
         port: The port to serve the docs on.
     """
-    with material_insiders():
-        ctx.run(
-            tools.mkdocs.serve(dev_addr=f"{host}:{port}").add_args(*cli_args),
-            title="Serving documentation",
-            capture=False,
-        )
+    ctx.run(
+        tools.mkdocs.serve(dev_addr=f"{host}:{port}").add_args(*cli_args),
+        title="Serving documentation",
+        capture=False,
+    )
 
 
 @duty
 def docs_deploy(ctx: Context) -> None:
     """Deploy the documentation to GitHub pages."""
     os.environ["DEPLOY"] = "true"
-    with material_insiders() as insiders:
-        if not insiders:
-            ctx.run(lambda: False, title="Not deploying docs without Material for MkDocs Insiders!")
-        ctx.run(tools.mkdocs.gh_deploy(), title="Deploying documentation")
+    ctx.run(tools.mkdocs.gh_deploy(force=True), title="Deploying documentation")
 
 
 @duty
@@ -179,7 +160,7 @@ def release(ctx: Context, version: str = "") -> None:
         ctx.run("false", title="A version must be provided")
     ctx.run("git add pyproject.toml CHANGELOG.md", title="Staging files", pty=PTY)
     ctx.run(["git", "commit", "-m", f"chore: Prepare release {version}"], title="Committing changes", pty=PTY)
-    ctx.run(f"git tag {version}", title="Tagging commit", pty=PTY)
+    ctx.run(f"git tag -m '' -a {version}", title="Tagging commit", pty=PTY)
     ctx.run("git push", title="Pushing commits", pty=False)
     ctx.run("git push --tags", title="Pushing tags", pty=False)
 
@@ -192,20 +173,15 @@ def coverage(ctx: Context) -> None:
     ctx.run(tools.coverage.html(rcfile="config/coverage.ini"))
 
 
-@duty
-def test(ctx: Context, *cli_args: str, match: str = "") -> None:  # noqa: PT028
-    """Run the test suite.
-
-    Parameters:
-        match: A pytest expression to filter selected tests.
-    """
-    py_version = f"{sys.version_info.major}{sys.version_info.minor}"
-    os.environ["COVERAGE_FILE"] = f".coverage.{py_version}"
+@duty(nofail=PY_VERSION == PY_DEV)
+def test(ctx: Context, *cli_args: str) -> None:
+    """Run the test suite."""
+    os.environ["COVERAGE_FILE"] = f".coverage.{PY_VERSION}"
+    os.environ["PYTHONWARNDEFAULTENCODING"] = "1"
     ctx.run(
         tools.pytest(
             "tests",
             config_file="config/pytest.ini",
-            select=match,
             color="yes",
         ).add_args("-n", "auto", *cli_args),
         title=pyprefix("Running tests"),

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/mkdocs.yml

@@ -153,10 +153,7 @@ plugins:
     type: timeago
 - minify:
     minify_html: !ENV [DEPLOY, false]
-- group:
-    enabled: !ENV [MATERIAL_INSIDERS, false]
-    plugins:
-    - typeset
+- typeset
 
 extra:
   social:

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/pyproject.toml

@@ -15,7 +15,7 @@ license-files = [
     "LICENSE",
 ]
 readme = "README.md"
-requires-python = ">=3.9"
+requires-python = ">=3.10"
 keywords = []
 dynamic = []
 classifiers = [
@@ -24,7 +24,6 @@ classifiers = [
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3 :: Only",
-    "Programming Language :: Python :: 3.9",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
@@ -39,7 +38,7 @@ classifiers = [
 dependencies = [
     "mkdocs>=1.5",
 ]
-version = "1.1.2"
+version = "1.2.0"
 
 [project.optional-dependencies]
 all = [

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/scripts/make.py

@@ -14,7 +14,8 @@ if TYPE_CHECKING:
     from collections.abc import Iterator
 
 
-PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.9 3.10 3.11 3.12 3.13 3.14").split()
+PYTHON_VERSIONS = os.getenv("PYTHON_VERSIONS", "3.10 3.11 3.12 3.13 3.14 3.15").split()
+PYTHON_DEV = "3.15"
 
 
 def shell(cmd: str, *, capture_output: bool = False, **kwargs: Any) -> str | None:
@@ -67,16 +68,31 @@ def setup() -> None:
                 uv_install(venv_path)
 
 
+class _RunError(subprocess.CalledProcessError):
+    def __init__(self, *args: Any, python_version: str, **kwargs: Any):
+        super().__init__(*args, **kwargs)
+        self.python_version = python_version
+
+
 def run(version: str, cmd: str, *args: str, **kwargs: Any) -> None:
     """Run a command in a virtual environment."""
     kwargs = {"check": True, **kwargs}
     uv_run = ["uv", "run", "--no-sync"]
-    if version == "default":
-        with environ(UV_PROJECT_ENVIRONMENT=".venv"):
-            subprocess.run([*uv_run, cmd, *args], **kwargs)  # noqa: S603, PLW1510
-    else:
-        with environ(UV_PROJECT_ENVIRONMENT=f".venvs/{version}", MULTIRUN="1"):
-            subprocess.run([*uv_run, cmd, *args], **kwargs)  # noqa: S603, PLW1510
+    try:
+        if version == "default":
+            with environ(UV_PROJECT_ENVIRONMENT=".venv"):
+                subprocess.run([*uv_run, cmd, *args], **kwargs)  # noqa: S603, PLW1510
+        else:
+            with environ(UV_PROJECT_ENVIRONMENT=f".venvs/{version}", MULTIRUN="1"):
+                subprocess.run([*uv_run, cmd, *args], **kwargs)  # noqa: S603, PLW1510
+    except subprocess.CalledProcessError as process:
+        raise _RunError(
+            returncode=process.returncode,
+            python_version=version,
+            cmd=process.cmd,
+            output=process.output,
+            stderr=process.stderr,
+        ) from process
 
 
 def multirun(cmd: str, *args: str, **kwargs: Any) -> None:
@@ -195,7 +211,14 @@ def main() -> int:
 if __name__ == "__main__":
     try:
         sys.exit(main())
-    except subprocess.CalledProcessError as process:
+    except _RunError as process:
         if process.output:
             print(process.output, file=sys.stderr)
-        sys.exit(process.returncode)
+        if (code := process.returncode) == 139:  # noqa: PLR2004
+            print(
+                f"✗ (python{process.python_version})  '{' '.join(process.cmd)}' failed with return code {code} (segfault)",
+                file=sys.stderr,
+            )
+            if process.python_version == PYTHON_DEV:
+                code = 0
+        sys.exit(code)

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/src/mkdocs_spellcheck/_internal/words.py

@@ -8,6 +8,9 @@ from functools import partial
 from html.parser import HTMLParser
 from io import StringIO
 
+_spell_check_guard_on = "mkdocs-spellcheck-on"
+_spell_check_guard_off = "mkdocs-spellcheck-off"
+
 
 class _MLStripper(HTMLParser):
     def __init__(self, ignore_code: bool = True) -> None:  # noqa: FBT001,FBT002
@@ -18,6 +21,7 @@ class _MLStripper(HTMLParser):
         self.text = StringIO()
         self.ignore_code = ignore_code
         self.in_code_tag = False
+        self.in_guard = False
 
     def handle_starttag(self, tag: str, attrs: list[tuple[str, str | None]]) -> None:  # noqa: ARG002
         if tag == "code":
@@ -28,15 +32,29 @@ class _MLStripper(HTMLParser):
         if tag == "code":
             self.in_code_tag = False
 
+    def handle_comment(self, data: str) -> None:
+        data = data.strip()
+
+        if not self.in_code_tag:
+            if data == _spell_check_guard_off:
+                self.in_guard = True
+            elif data == _spell_check_guard_on:
+                self.in_guard = False
+
     def handle_data(self, data: str) -> None:
-        if not (self.ignore_code and self.in_code_tag):
-            self.text.write(data)
+        if self.ignore_code and self.in_code_tag:
+            return
+
+        if self.in_guard:
+            return
+
+        self.text.write(data)
 
     def get_data(self) -> str:
         return self.text.getvalue()
 
 
-def _strip_tags(html: str, ignore_code: bool) -> str:  # noqa: FBT001
+def _strip(html: str, ignore_code: bool) -> str:  # noqa: FBT001
     stripper = _MLStripper(ignore_code)
     stripper.feed(html)
     return stripper.get_data()
@@ -94,6 +112,6 @@ def get_words(
     """
     known_words = known_words or set()
     keep = partial(_keep_word, min_length=min_length, max_capital=max_capital)
-    filtered = filter(keep, _normalize(_strip_tags(html, ignore_code), allow_unicode).split("-"))
+    filtered = filter(keep, _normalize(_strip(html, ignore_code), allow_unicode).split("-"))
     words = {word.lower() for word in filtered}
     return sorted(words - known_words)

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/tests/test_api.py

@@ -137,7 +137,9 @@ def test_api_matches_inventory(inventory: Inventory, public_objects: list[griffe
     """All public objects are added to the inventory."""
     ignore_names = {"__getattr__", "__init__", "__repr__", "__str__", "__post_init__"}
     not_in_inventory = [
-        obj.path for obj in public_objects if obj.name not in ignore_names and obj.path not in inventory
+        f"{obj.relative_filepath}:{obj.lineno}: {obj.path}"
+        for obj in public_objects
+        if obj.name not in ignore_names and obj.path not in inventory
     ]
     msg = "Objects not in the inventory (try running `make run mkdocs build`):\n{paths}"
     assert not not_in_inventory, msg.format(paths="\n".join(sorted(not_in_inventory)))

{mkdocs_spellcheck-1.1.2 → mkdocs_spellcheck-1.2.0}/tests/test_words.py

@@ -27,6 +27,43 @@ def test_remove_single_tags() -> None:
     assert "img" not in words
 
 
+def test_remove_guarded_blocks() -> None:
+    """Assert guarded text blocks are removed from HTML text."""
+    html = """\
+before
+<!-- mkdocs-spellcheck-off -->
+between
+<!-- mkdocs-spellcheck-on -->
+after
+"""
+    words = get_words(html, min_length=1)
+    assert "before" in words
+    assert "between" not in words
+    assert "after" in words
+
+
+@pytest.mark.parametrize(
+    ("ignore_code", "expected"),
+    [
+        (True, {"before", "after"}),
+        (False, {"before", "some", "guarded", "text", "after"}),
+    ],
+)
+def test_guarded_blocks_disabled_in_code_blocks(ignore_code: bool, expected: set[str]) -> None:
+    """Assert guarded blocks are disabled in code blocks."""
+    html = """\
+before
+<code>
+<!-- mkdocs-spellcheck-off -->
+some guarded text
+<!-- mkdocs-spellcheck-on -->
+</code>
+after
+"""
+    words = get_words(html, ignore_code=ignore_code)
+    assert set(words) == expected
+
+
 @pytest.mark.parametrize(
     ("text", "known_words", "expected"),
     [

mkdocs_spellcheck-1.1.2/docs/.overrides/main.html

@@ -1,14 +0,0 @@
-{% extends "base.html" %}
-
-{% block announce %}
-  
-  Follow
-  <strong>@pawamoy</strong> on
-  <a rel="me" href="https://fosstodon.org/@pawamoy">
-    <span class="twemoji mastodon">
-      {% include ".icons/fontawesome/brands/mastodon.svg" %}
-    </span>
-    <strong>Fosstodon</strong>
-  </a>
-  for updates
-{% endblock %}