Bump version to 2.1.0, update CHANGELOG and docs

- Update VERSION to 2.1.0
- Add CHANGELOG entry for compatibility_check and compatibility_patch features
- Document new options in docs/config.md with examples
- Add migration section to docs/index.md

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: analog-cbarber

CHANGELOG.md

@@ -3,6 +3,13 @@
 *Note that versions roughly correspond to the version of mkdocstrings-python that they 
 are compatible with.*
 
+## 2.1.0
+
+* Added `compatibility_check` option to warn or error on cross-reference syntax that
+  is not supported by the standard mkdocstrings-python handler (#60)
+* Added `compatibility_patch` option to generate a patch file converting incompatible
+  cross-references to standard form (#60)
+
 ## 2.0.1
 
 * Fix extended template configuration (#56)

docs/config.md

@@ -3,7 +3,7 @@ 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 three:
+Additional options are added by this extension:
 
 * **relative_crossrefs**: `bool` - if set to true enables use of relative path syntax in
     cross-references.
@@ -19,6 +19,18 @@ Additional options are added by this extension. Currently, there are three:
     libraries which are very expensive to import without having to disable checking for all
     cross-references.
 
+* **compatibility_check**: `false`, `"warn"`, or `"error"` - when set, reports cross-references
+    that use syntax not supported by the standard [mkdocstrings-python][] handler. This is
+    useful when planning to migrate away from this extension. The incompatible syntax elements
+    are: leading `^`, `(c)`, `(m)`, `(p)` specifiers; trailing `.` after a name (which
+    appends the title); and leading `?` (which suppresses reference checking).
+
+* **compatibility_patch**: `false` or a file path string - when set to a file path, generates
+    a unified diff patch file that converts incompatible cross-references to the standard
+    dot-prefix form. The patch file is overwritten on each build. If no incompatibilities are
+    found, any existing patch file is removed. The generated patch can be applied with
+    `git apply` or `patch -p0`.
+
 !!! Example "mkdocs.yml plugins specifications using this handler"
 
     === "Always check"
@@ -80,6 +92,56 @@ Additional options are added by this extension. Currently, there are three:
                   check_crossrefs: no
         ```
 
+!!! Example "Compatibility checking for migration"
+
+    To check for incompatible syntax before migrating to the standard handler:
+
+    === "Warn on incompatibilities"
+
+        ```yaml
+        plugins:
+        - mkdocstrings:
+            default_handler: python_xref
+            handlers:
+              python_xref:
+                options:
+                  relative_crossrefs: yes
+                  compatibility_check: warn
+        ```
+
+    === "Error on incompatibilities"
+
+        ```yaml
+        plugins:
+        - mkdocstrings:
+            default_handler: python_xref
+            handlers:
+              python_xref:
+                options:
+                  relative_crossrefs: yes
+                  compatibility_check: error
+        ```
+
+    === "Generate a patch file"
+
+        ```yaml
+        plugins:
+        - mkdocstrings:
+            default_handler: python_xref
+            handlers:
+              python_xref:
+                options:
+                  relative_crossrefs: yes
+                  compatibility_check: warn
+                  compatibility_patch: xref-compat.patch
+        ```
+
+        Then apply the patch:
+
+        ```bash
+        git apply xref-compat.patch
+        ```
+
 
 
 [mkdocstrings-python]: https://mkdocstrings.github.io/python/

docs/index.md

@@ -126,6 +126,29 @@ reference expression with a `?`, for example:
 This function returns a [Path][?pathlib.] instance.
 ```
 
+## Migrating to standard mkdocstrings-python
+
+If you want to migrate from this extension to the standard [mkdocstrings-python][mkdocstrings_python]
+handler, you can use the `compatibility_check` and `compatibility_patch` options to help
+identify and convert incompatible cross-reference syntax.
+
+The following syntax elements are specific to this extension and not supported by the
+standard handler:
+
+| Syntax | Description | Standard equivalent |
+|--------|-------------|-------------------|
+| `^`, `^^`, ... | Caret parent specifier | `..`, `...`, ... (dot prefix) |
+| `(c)` | Class specifier | Equivalent number of leading dots |
+| `(m)` | Module specifier | Equivalent number of leading dots |
+| `(p)` | Package specifier | Equivalent number of leading dots |
+| Trailing `.` after a name | Append title to reference | Expand title inline, e.g. `[foo][bar.]` → `[foo][bar.foo]` |
+| Leading `?` | Suppress reference checking | Remove the `?` |
+
+To check for incompatibilities, set `compatibility_check` to `"warn"` or `"error"` in your
+handler options. To generate a patch file that converts all incompatible references to
+standard form, set `compatibility_patch` to a file path. See the [configuration](config.md)
+page for examples.
+
 [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 @@
-2.0.1
+2.1.0