PyCharm settings

 - Check compatability for Python 3.8 through 3.12
 - Added project icon

Author: analog-cbarber

CHANGELOG.md

@@ -1,6 +1,6 @@
 # mkdocstring-python-xref changes
 
-## 1.6.2
+## 1.5.3
 
 First public release
 

README.md

@@ -10,6 +10,36 @@ Python handler for [mkdocstrings] supporting relative cross-references.
 [![CI](https://github.com/analog-garage/mkdocstrings-python-xref/actions/workflows/main.yml/badge.svg)](https://github.com/analog-garage/mkdocstrings-python-xref/actions/workflows/main.yml)
 ![GitHub issues](https://img.shields.io/github/issues/analog-garage/mkdocstrings-python-xref)
 
+[mkdocstrings] is an awesome plugin for [MkDocs] that can generate Markdown API documentation
+from comments in code. The standard [python handler][mkdocstrings-python] allows you to
+create cross-reference links using the syntax `[<title>][<path>]` where the path must
+either be the fully qualified name of the referent or is empty, in which case the path
+is taken from the title. This works well when the names are short, but can be burdensome
+in larger codebases with deeply nested package structures.
 
+This package extends [mkdocstrings-python] to support a relative cross-reference syntax,
+that allows you to write doc-strings with cross-references like:
+
+```python
+class MyClass:
+    def this_method(self):
+        """
+        See [other_method][..] from [MyClass][(c)]
+        """
+```
+rather than:
+
+```python
+class MyClass:
+    def this_method(self):
+        """
+        See [other_method][mypkg.mymod.MyClass.other_method] 
+        from [MyClass][mypkg.mymod.Myclass]
+        """
+```
+
+For further details, please see the [Documentation](https://analog-garage.github.io/mkdocstrings-python-xref/)
+
+[MkDocs]: https://mkdocs.readthedocs.io/
 [mkdocstrings]: https://github.com/mkdocstrings/mkdocstrings
-[mkdocstrings_python]: https://github.com/mkdocstrings/python
+[mkdocstrings-python]: https://github.com/mkdocstrings/python

docs/install.md

@@ -3,6 +3,9 @@
 ```
 pip install mkdocstrings-python-xref
 ```
+### Using conda
+
+*coming soon...*
 
 
 

docs/relative-crossref.md

@@ -15,7 +15,7 @@ will support more compact relative syntax:
     class MyClass:
         def this_method(self):
             """
-            See [other_function][mypkg.mymod.MyClass.other_function] 
+            See [other_method][mypkg.mymod.MyClass.other_method] 
             from [MyClass][mypkg.mymod.Myclass]
             """
     ```
@@ -26,7 +26,7 @@ will support more compact relative syntax:
     class MyClass:
         def this_method(self):
             """
-            See [other_function][.] from [MyClass][^]
+            See [other_method][..] from [MyClass][(c)]
             """
     ```
 
@@ -38,11 +38,6 @@ The relative path specifier has the following form:
 * If the path begins with a single `.` then it will be expanded relative to the path
     of the doc-string in which it occurs. 
 
-    As a deprecated special case, if the current
-    doc-string is for a function or method, then `.` will instead be
-    expanded relative to the function's parent (i.e. the same as `^.`).
-    This will turn into an error in a future version.
-
 * If the path begins with `(c)`, that will be replaced by the path of the
     class that contains the doc-string
 
@@ -53,10 +48,17 @@ The relative path specifier has the following form:
     package that contains the doc-string. If there is only one module in the 
     system it will be treated as a package.
 
-* If the path begins with one or more `^` characters, then that will go
-   up one level in the path of the current doc string for each `^`. Additionally,
-   if the path begins with two or more `.` characters, then that will go
-   up on level for each `.` after the first.
+* If the path begins with one or more `^` characters, then will be replaced
+    by the path of the parent element. For example, when used in a doc-string
+    for a method, `^` would get replaced with the class and `^^` would get
+    replaced with the module.
+
+* Similarly, if the path begins with two or more `.` characters, then all but
+    the last `.` will be replaced by the parent element, and if nothing follows
+    the last `.`, the title text will be appended according to the first rule.
+   
+    *NOTE: When using either `^` or `..` we have found that going up more than one
+    or two levels makes cross-references difficult to read and should be avoided*
 
 These are demonstrated here:
 
@@ -66,7 +68,10 @@ These are demonstrated here:
     class MyClass:
         def this_method(self):
             """
-            [`that_method`][.]
+            [MyClass][^]
+            Also [MyClass][(c)]
+            [`that_method`][^.]
+            Also [`that_method`][..]
             [init method][(c).__init__]
             [this module][(m)]
             [this package][(p)]
@@ -81,7 +86,10 @@ These are demonstrated here:
     class MyClass:
         def this_method(self):
             """
+            [MyClass][mypkg.mymod.MyClass]
+            Also [MyClass][mypkg.mymod.MyClass]
             [`that_method`][mypkg.mymod.MyClass.that_method]
+            Also [`that_method`][mypkg.mymod.MyClass.that_method]
             [init method][mypkg.mymod.MyClass.__init__]
             [this module][mypkg.mymod]
             [this package][mypkg]

docs/support.md

@@ -1,2 +1,4 @@
 You can file bug reports or feature requests 
-[on GitHub](https://github.com/analog-garage/mkdocstrings-python-xref/issues).
+[on GitHub](https://github.com/analog-garage/mkdocstrings-python-xref/issues) or if you just want to ask
+a question on the [project's discussions board](https://github.com/analog-garage/mkdocstrings-python-xref/discussions)
+

mkdocs.yml

@@ -11,9 +11,7 @@ watch:
   - src/mkdocstrings_handlers
 
 nav:
-- User Guide:
-    - Overview: index.md
-    - Relative cross-references: relative-crossref.md
+- User Guide: relative-crossref.md
 - Setup:
     - Installation: install.md
     - Configuration: config.md