From 04acff8e2ebfbe39b91d68485c711f07b77a050d Mon Sep 17 00:00:00 2001
From: IanCa <ianrcallanan@gmail.com>
Date: Fri, 20 Oct 2023 18:42:56 -0500
Subject: [PATCH] Improve toctree in documentation

---
 docs/source/_templates/autosummary/class.rst  | 34 ----------
 .../_templates/custom-class-template.rst      | 68 +++++++++++--------
 .../_templates/custom-module-template.rst     | 27 +++++---
 docs/source/index.rst                         |  4 +-
 4 files changed, 58 insertions(+), 75 deletions(-)
 delete mode 100644 docs/source/_templates/autosummary/class.rst

diff --git a/docs/source/_templates/autosummary/class.rst b/docs/source/_templates/autosummary/class.rst
deleted file mode 100644
index 50efd957f..000000000
--- a/docs/source/_templates/autosummary/class.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-{{ fullname | escape | underline}}
-
-.. currentmodule:: {{ module }}
-
-.. autoclass:: {{ module }}.{{ objname }}
-   {% block methods %}
-   .. automethod:: __init__
-
-   {% if methods %}
-   .. rubric:: {{ _('Methods') }}
-
-   .. autosummary::
-   {% for item in methods %}
-      ~{{ name }}.{{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block attributes %}
-   {% if attributes %}
-   .. rubric:: {{ _('Attributes') }}
-
-   .. autosummary::
-   {% for item in attributes %}
-      ~{{ name }}.{{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-.. autoclass:: {{ module }}.{{ objname }}
-   :members:
-   :undoc-members:
-   :show-inheritance:
-   :inherited-members:
diff --git a/docs/source/_templates/custom-class-template.rst b/docs/source/_templates/custom-class-template.rst
index 16ebb2f33..490f83ee2 100644
--- a/docs/source/_templates/custom-class-template.rst
+++ b/docs/source/_templates/custom-class-template.rst
@@ -1,32 +1,42 @@
-{{ fullname | escape | underline}}
+{{ fullname | escape | underline }}
 
 .. currentmodule:: {{ module }}
 
-.. autoclass:: {{ objname }}
-   :members:
-   :show-inheritance:
-   :inherited-members:
-
-   {% block methods %}
-   .. automethod:: __init__
-
-   {% if methods %}
-   .. rubric:: {{ _('Methods') }}
-
-   .. autosummary::
-   {% for item in methods %}
-      ~{{ name }}.{{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block attributes %}
-   {% if attributes %}
-   .. rubric:: {{ _('Attributes') }}
-
-   .. autosummary::
-   {% for item in attributes %}
-      ~{{ name }}.{{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
\ No newline at end of file
+.. autoclass:: {{ module }}.{{ objname }}
+   :noindex:
+
+.. rubric:: {{ _('Methods') }}
+
+.. autosummary::
+{% for item in methods %}
+   {{ module }}.{{ objname }}.{{ item }}
+{%- endfor %}
+
+.. rubric:: {{ _('Attributes') }}
+
+.. autosummary::
+{% for item in attributes %}
+   {{ module }}.{{ objname }}.{{ item }}
+{%- endfor %}
+
+.. toctree::
+   :hidden:
+
+{% for item in methods %}
+   {{ fullname }}#method-{{ item }}
+{%- endfor %}
+{% for item in attributes %}
+   {{ fullname }}#attribute-{{ item }}
+{%- endfor %}
+
+{% for item in methods %}
+.. _method-{{ item }}:
+
+.. automethod:: {{ module }}.{{ objname }}.{{ item }}
+{%- endfor %}
+
+{% for item in attributes %}
+.. _attribute-{{ item }}:
+
+.. autoattribute:: {{ module }}.{{ objname }}.{{ item }}
+{%- endfor %}
diff --git a/docs/source/_templates/custom-module-template.rst b/docs/source/_templates/custom-module-template.rst
index 74078355f..7fec9f9c4 100644
--- a/docs/source/_templates/custom-module-template.rst
+++ b/docs/source/_templates/custom-module-template.rst
@@ -1,5 +1,7 @@
 {{ fullname | escape | underline}}
 
+.. currentmodule:: {{ module }}
+
 .. automodule:: {{ fullname }}
 
    {% block attributes %}
@@ -14,17 +16,22 @@
    {% endif %}
    {% endblock %}
 
-   {% block functions %}
-   {% if functions %}
-   .. rubric:: {{ _('Functions') }}
+    {% block functions %}
+    {% if functions %}
+    .. rubric:: {{ _('Functions') }}
 
-   .. autosummary::
-      :toctree:
-   {% for item in functions %}
-      {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
+    .. autosummary::
+    {% for item in functions %}
+       {{ item }}
+    {% endfor %}
+
+    {% for item in functions %}
+    .. _{{ item }}:
+
+    .. autofunction:: {{ item }}
+    {% endfor %}
+    {% endif %}
+    {% endblock %}
 
    {% block classes %}
    {% if classes %}
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 924fb2b7e..3b82987d3 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -14,14 +14,14 @@ Hierarchical Event Descriptor (HED) Python Tools
 Note:  this is a work in progress. More information is coming.
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 6
    :caption: Contents:
 
    introduction.md
    user_guide.rst
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 6
    :caption: HED Python API:
 
    api2.rst