adding links to first references of the vocabulary items

.gitignore

@@ -12,3 +12,23 @@ makelog.txt
 # Unknown
 /python/
 __github_creds__.txt
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST

MANIFEST.in

@@ -0,0 +1,4 @@
+recursive-include applications/ *.nxdl.xml
+recursive-include contributed_definitions/ *.nxdl.xml
+recursive-include base_classes/ *.nxdl.xml
+include ./ *.xsd

dev_tools/docs/nxdl.py

@@ -12,6 +12,7 @@
 from ..globals.errors import NXDLParseError
 from ..globals.nxdl import NXDL_NAMESPACE
 from ..globals.urls import REPO_URL
+from ..utils import nexus as pynxtools_nxlib
 from ..utils.types import PathLike
 from .anchor_list import AnchorRegistry
 
@@ -506,7 +507,7 @@ def _print_attribute(self, ns, kind, node, optional, indent, parent_path):
         )
         self._print(f"{indent}.. index:: {index_name} ({kind} attribute)\n")
         self._print(
-            f"{indent}**@{name}**: {optional}{self._format_type(node)}{self._format_units(node)}\n"
+            f"{indent}**@{name}**: {optional}{self._format_type(node)}{self._format_units(node)} {self.get_first_parent_ref(f'{parent_path}/{name}', 'attribute')}\n"
         )
         self._print_doc(indent + self._INDENTATION_UNIT, ns, node)
         node_list = node.xpath("nx:enumeration", namespaces=ns)
@@ -549,6 +550,7 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path):
                 f"{self._format_type(node)}"
                 f"{dims}"
                 f"{self._format_units(node)}"
+                f" {self.get_first_parent_ref(f'{parent_path}/{name}', 'field')}"
                 "\n"
             )
 
@@ -585,7 +587,9 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path):
             # target = hTarget.replace(".. _", "").replace(":\n", "")
             # TODO: https://github.com/nexusformat/definitions/issues/1057
             self._print(f"{indent}{hTarget}")
-            self._print(f"{indent}**{name}**: {optional_text}{typ}\n")
+            self._print(
+                f"{indent}**{name}**: {optional_text}{typ} {self.get_first_parent_ref(f'{parent_path}/{name}', 'group')}\n"
+            )
 
             self._print_if_deprecated(ns, node, indent + self._INDENTATION_UNIT)
             self._print_doc(indent + self._INDENTATION_UNIT, ns, node)
@@ -624,3 +628,47 @@ def _print_full_tree(self, ns, parent, name, indent, parent_path):
     def _print(self, *args, end="\n"):
         # TODO: change instances of \t to proper indentation
         self._rst_lines.append(" ".join(args) + end)
+
+    def get_first_parent_ref(self, path, tag):
+        nx_name = path[1 : path.find("/", 1)]
+        path = path[path.find("/", 1) :]
+
+        try:
+            parents = pynxtools_nxlib.get_inherited_nodes(path, nx_name)[2]
+        except FileNotFoundError:
+            return ""
+        if len(parents) > 1:
+            parent = parents[1]
+            parent_path = parent_display_name = parent.attrib["nxdlpath"]
+            parent_path_segments = parent_path[1:].split("/")
+            parent_def_name = parent.attrib["nxdlbase"][
+                parent.attrib["nxdlbase"]
+                .rfind("/") : parent.attrib["nxdlbase"]
+                .rfind(".nxdl")
+            ]
+
+            # Case where the first parent is a base_class
+            if parent_path_segments[0] == "":
+                return ""
+
+            # special treatment for NXnote@type
+            if (
+                tag == "attribute"
+                and parent_def_name == "/NXnote"
+                and parent_path == "/type"
+            ):
+                return ""
+
+            if tag == "attribute":
+                pos_of_right_slash = parent_path.rfind("/")
+                parent_path = (
+                    parent_path[:pos_of_right_slash]
+                    + "@"
+                    + parent_path[pos_of_right_slash + 1 :]
+                )
+            parent_display_name = f"{parent_def_name[1:]}{parent_path}"
+            return (
+                f":abbr:`... (override: {parent_display_name})"
+                + f"`:ref:`🔗 </{parent_display_name}-{tag}>`"
+            )
+        return ""