👌 Allow names starting ~ in autodoc2-summary (#12)

sphinx-extensions2 · Feb 28, 2023 · 13933a5 · 13933a5
1 parent 58be3fe
commit 13933a5
Show file tree

Hide file tree

Showing 5 changed files with 14 additions and 6 deletions.
diff --git a/docs/apidocs/autodoc2/autodoc2.rst b/docs/apidocs/autodoc2/autodoc2.rst
@@ -61,7 +61,7 @@ API
 
 .. py:data:: __version__
    :canonical: autodoc2.__version__
-   :value: '0.3.0'
+   :value: '0.4.2'
 
    .. autodoc2-docstring:: autodoc2.__version__
 

diff --git a/docs/summary.md b/docs/summary.md
@@ -10,6 +10,7 @@ For example, the following:
     :renderer: myst
 
     aiida.orm.Node
+    ~aiida.orm.Dict
     autodoc2.sphinx.docstring._example my example
 ````
 
@@ -19,13 +20,15 @@ creates:
 :renderer: myst
 
 aiida.orm.Node
+~aiida.orm.Dict
 autodoc2.sphinx.docstring._example my example
 ```
 
 Note that fully qualified names can be used to refer to objects in other packages,
 and they will also resolve against public API names, i.e. if the object is specified in an `__all__` variable.
 
-Any text after the fully qualified name will be used as the title for the object.
+Any text after the fully qualified name will be used as the title for the object,
+or alternatively, if the name begins with `~` then the last component will be used as the title.
 
 The `:renderer:` option can also be used to specify the renderer to use for the summary.
 

diff --git a/src/autodoc2/__init__.py b/src/autodoc2/__init__.py
@@ -1,6 +1,6 @@
 """Analyse a python project and create documentation for it."""
 
-__version__ = "0.4.1"
+__version__ = "0.4.2"
 
 
 def setup(app):  # type: ignore

diff --git a/src/autodoc2/sphinx/summary.py b/src/autodoc2/sphinx/summary.py
@@ -50,6 +50,9 @@ def run(self) -> list[nodes.Node]:
                 continue
             full_name = parts[0]
             alias: str | None = None
+            if full_name.startswith("~"):
+                full_name = full_name[1:]
+                alias = full_name.split(".")[-1]
             if len(parts) > 1:
                 alias = parts[1]
             if (item := db.get_item(full_name)) is None and (
@@ -63,7 +66,9 @@ def run(self) -> list[nodes.Node]:
                             self.env.note_dependency(file_path)
                         break
                 if alias:
-                    aliases[full_name] = alias
+                    aliases[item["full_name"]] = alias
+                elif full_name != item["full_name"]:
+                    aliases[item["full_name"]] = full_name
                 objects.append(item)
             else:
                 warn_sphinx(

diff --git a/tests/test_render/test_sphinx_build_directives.xml b/tests/test_render/test_sphinx_build_directives.xml
@@ -69,9 +69,9 @@
                     <row>
                         <entry>
                             <paragraph>
-                                <pending_xref py:class="True" py:module="True" refdoc="index" refdomain="py" refexplicit="False" reftarget="package.a.a1" reftype="obj" refwarn="False">
+                                <pending_xref py:class="True" py:module="True" refdoc="index" refdomain="py" refexplicit="True" reftarget="package.a.a1" reftype="obj" refwarn="False">
                                     <literal classes="xref py py-obj">
-                                        package.a.a1
+                                        package.a1
                         <entry>
                             <paragraph>
                                 a1 can be documented here.