Cleanup for PR: docs, version bump, and pre-compile regex

Author: thetianshuhuang

docs/config.md

@@ -3,38 +3,77 @@ that the handler name should be `python_xref` instead of `python`. Because
 this handler extends the standard [mkdocstrings-python][] handler, the same options are
 available.
 
-Additional options are added by this extension. Currently, there are two:
+Additional options are added by this extension. Currently, there are three:
 
-* **relative_crossrefs** - if set to true enables use of relative path syntax in
+* **relative_crossrefs**: `bool` - if set to true enables use of relative path syntax in
     cross-references.
 
-* **check_crossrefs** - enables early checking of all cross-references. Note that
+* **check_crossrefs**: `bool` - enables early checking of all cross-references. Note that
     this option only takes affect if **relative_crossrefs** is also true. This option is
     true by default, so this option is used to disable checking. Checking can
     also be disabled on a per-case basis by prefixing the reference with '?', e.g.
     `[something][?dontcheckme]`.
 
-!!! Example "mkdocs.yml plugins specification using this handler"
-
-```yaml
-plugins:
-- search
-- mkdocstrings:
-    default_handler: python_xref
-    handlers:
-      python_xref:
-        import:
-        - https://docs.python.org/3/objects.inv
-        options:
-          docstring_style: google
-          docstring_options:
-            ignore_init_summary: yes
-          merge_init_into_class: yes
-          relative_crossrefs: yes
-          check_crossrefs: no
-          separate_signature: yes
-          show_source: no
-          show_root_full_path: no
-```
+* **check_crossrefs_exclude**: `list[str]` - exclude cross-references matching any of these
+    regex patterns from crossref checking. This option can be used disabling checking on
+    libraries which are very expensive to import without having to disable checking for all
+    cross-references.
+
+!!! Example "mkdocs.yml plugins specifications using this handler"
+
+    === "Always check"
+
+        !!! warning
+
+            Crossrefs to libraries which are expensive to import (e.g., machine learning
+            frameworks) can cause very slow build times when checked!
+
+        ```yaml
+        plugins:
+        - mkdocstrings:
+            default_handler: python_xref
+            handlers:
+              python_xref:
+                import:
+                - https://docs.python.org/3/objects.inv
+                - https://pytorch.org/docs/stable/objects.inv
+                options:
+                  relative_crossrefs: yes
+        ```
+
+    === "Check all but listed exclusions"
+
+        ```yaml
+        plugins:
+        - mkdocstrings:
+            default_handler: python_xref
+            handlers:
+              python_xref:
+                import:
+                - https://docs.python.org/3/objects.inv
+                - https://pytorch.org/docs/stable/objects.inv
+                options:
+                  relative_crossrefs: yes
+                  check_crossrefs_exclude:
+                  - "^torch\\.(.*)"
+        ```
+
+    === "Never check"
+
+        ```yaml
+        plugins:
+        - mkdocstrings:
+            default_handler: python_xref
+            handlers:
+              python_xref:
+                import:
+                - https://docs.python.org/3/objects.inv
+                - https://pytorch.org/docs/stable/objects.inv
+                options:
+                  relative_crossrefs: yes
+                  check_crossrefs: no
+        ```
+
+
 
 [mkdocstrings-python]: https://mkdocstrings.github.io/python/

docs/index.md

@@ -105,7 +105,7 @@ but has not yet been accepted.
 
 If `relative_crossrefs` and `check_crossrefs` are both enabled (the latter is true by default),
 then all cross-reference expressions will be checked to ensure that they exist and failures
-will be reported with the source location. Otherwise, missing cross-references will be reported
+will be reported with the source location (with the exception of any crossrefs which match a pattern in `check_crossrefs_exclude`). Otherwise, missing cross-references will be reported
 by mkdocstrings without the source location, in which case it is often difficult to locate the source
 of the error. Note that the errors generated by this feature are in addition to the errors
 from mkdocstrings.
@@ -121,5 +121,3 @@ This function returns a [Path][?pathlib.] instance.
 [mkdocstrings]: https://mkdocstrings.github.io/
 [mkdocstrings_python]: https://mkdocstrings.github.io/python/
 [relative-crossref-issue]: https://github.com/mkdocstrings/python/issues/27
-
-

src/mkdocstrings_handlers/python_xref/VERSION

@@ -1 +1 @@
-1.16.2
+1.16.3

src/mkdocstrings_handlers/python_xref/handler.py

@@ -45,7 +45,7 @@
 @dataclass(**_dataclass_options)
 class PythonRelXRefOptions(PythonOptions):
     check_crossrefs: bool = True
-    check_crossrefs_exclude: list[str] = field(default_factory=list)
+    check_crossrefs_exclude: list[str | re.Pattern] = field(default_factory=list)
 
 class PythonRelXRefHandler(PythonHandler):
     """Extended version of mkdocstrings Python handler
@@ -66,8 +66,8 @@ def __init__(self, config: PythonConfig, base_dir: Path, **kwargs: Any) -> None:
             **kwargs: Arguments passed to the parent constructor.
         """
         self.check_crossrefs = config.options.pop('check_crossrefs', None)
-        self.check_crossrefs_exclude = config.options.pop(
-            'check_crossrefs_exclude', [])
+        exclude = config.options.pop('check_crossrefs_exclude', [])
+        self.check_crossrefs_exclude = [re.compile(p) for p in exclude]
         super().__init__(config, base_dir, **kwargs)
 
     def get_options(self, local_options: Mapping[str, Any]) -> PythonRelXRefOptions:
@@ -105,7 +105,7 @@ def get_templates_dir(self, handler: Optional[str] = None) -> Path:
             handler = 'python'
         return super().get_templates_dir(handler)
 
-    def _check_ref(self, ref : str, exclude: list[str] = []) -> bool:
+    def _check_ref(self, ref : str, exclude: list[str | re.Pattern] = []) -> bool:
         """Check for existence of reference"""
         for ex in exclude:
             if re.match(ex, ref):