fix: Do minimum work when falling back to re-collecting an object to get its anchor

pawamoy · web-flow · commit f6cf570255df · 2021-10-10T13:07:30.000+02:00
This change introduces a new attribute on collectors: `fallback_config`. It is used by the `Handlers.get_anchor` method when collecting an object to find its anchor. It allows to pass specific options to the collector to avoid collecting the object members or, for example, parsing Python docstrings, as it is not useful, since we only care about the anchor. Issue #329: #329 PR #330: #330
diff --git a/pyproject.toml b/pyproject.toml
@@ -24,7 +24,7 @@ dependencies = [
     "mkdocs~=1.2",
     "mkdocs-autorefs>=0.1,<0.4",
     "pymdown-extensions>=6.3,<10.0",
-    "pytkdocs>=0.2.0,<0.13.0",
+    "pytkdocs~=0.14.0",
 ]
 
 [project.urls]
diff --git a/src/mkdocstrings/handlers/base.py b/src/mkdocstrings/handlers/base.py
@@ -339,8 +339,9 @@ def get_anchor(self, identifier: str) -> Optional[str]:
             A string - anchor without '#', or None if there isn't any identifier familiar with it.
         """
         for handler in self._handlers.values():
+            fallback_config = getattr(handler.collector, "fallback_config", {})
             try:
-                anchor = handler.renderer.get_anchor(handler.collector.collect(identifier, {}))
+                anchor = handler.renderer.get_anchor(handler.collector.collect(identifier, fallback_config))
             except CollectionError:
                 continue
             if anchor is not None:
diff --git a/src/mkdocstrings/handlers/python.py b/src/mkdocstrings/handlers/python.py
@@ -141,6 +141,21 @@ class PythonCollector(BaseCollector):
     Obviously one could use a single filter instead: `"!^_[^_]"`, which is the default.
     """
 
+    fallback_config = {"docstring_style": "markdown", "filters": ["!.*"]}
+    """The configuration used when falling back to re-collecting an object to get its anchor.
+
+    This configuration is used in [`Handlers.get_anchor`][mkdocstrings.handlers.base.Handlers.get_anchor].
+
+    When trying to fix (optional) cross-references, the autorefs plugin will try to collect
+    an object with every configured handler until one succeeds. It will then try to get
+    an anchor for it. It's because objects can have multiple identifiers (aliases),
+    for example their definition path and multiple import paths in Python.
+
+    When re-collecting the object, we have no use for its members, or for its docstring being parsed.
+    This is why the fallback configuration filters every member out, and uses the Markdown style,
+    which we know will not generate any warnings.
+    """
+
     def __init__(self, setup_commands: Optional[List[str]] = None) -> None:
         """Initialize the object.
 

Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,7 @@ dependencies = [`
`24`	`24`	`"mkdocs~=1.2",`
`25`	`25`	`"mkdocs-autorefs>=0.1,<0.4",`
`26`	`26`	`"pymdown-extensions>=6.3,<10.0",`
`27`		`- "pytkdocs>=0.2.0,<0.13.0",`
	`27`	`+ "pytkdocs~=0.14.0",`
`28`	`28`	`]`
`29`	`29`
`30`	`30`	`[project.urls]`