From 8556c087462a53e35e44b5d353fd126924be0434 Mon Sep 17 00:00:00 2001
From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com>
Date: Mon, 6 Nov 2023 19:27:26 +0100
Subject: [PATCH] Move methods into class pages for docs (#1290)

### Summary
Moved all the methods and attributes into class pages to speed up the
building process of the documentation with the new ecosystem sphinx
theme.

This PR continues the work done by @Eric-Arellano in
https://github.com/Qiskit-Extensions/qiskit-experiments/pull/1231.

See https://github.com/Qiskit/qiskit/pull/10455 for more information.

---------

Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com>
---
 docs/_templates/autosummary/analysis.rst      | 10 +--
 docs/_templates/autosummary/class.rst         | 61 ++++++-------------
 .../class_no_inherited_members.rst            | 52 ++++++++++++++++
 docs/_templates/autosummary/drawer.rst        | 10 +--
 docs/_templates/autosummary/experiment.rst    | 10 +--
 docs/_templates/autosummary/plotter.rst       | 11 +---
 6 files changed, 84 insertions(+), 70 deletions(-)
 create mode 100644 docs/_templates/autosummary/class_no_inherited_members.rst

diff --git a/docs/_templates/autosummary/analysis.rst b/docs/_templates/autosummary/analysis.rst
index 222df215af..d8811523ac 100644
--- a/docs/_templates/autosummary/analysis.rst
+++ b/docs/_templates/autosummary/analysis.rst
@@ -17,11 +17,9 @@
 
    .. rubric:: Attributes
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_attributes %}
       {%- if not item.startswith('_') %}
-      {{ name }}.{{ item }}
+   .. autoattribute:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% endif %}
@@ -32,16 +30,14 @@
 
    .. rubric:: Methods
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_methods %}
       {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% for item in inherited_members %}
       {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
 
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
index f6e8a53f58..fd25d5706e 100644
--- a/docs/_templates/autosummary/class.rst
+++ b/docs/_templates/autosummary/class.rst
@@ -12,58 +12,37 @@
    :no-inherited-members:
    :no-special-members:
 
-   {% block attributes_summary %}
-   {% if attributes %}
+{% block attributes_summary %}
 
-   {# This counter lets us only render the heading if there's at least
-   one valid entry. #}
-   {% set count = namespace(value=0) %}
+   {% set wanted_attributes = [] %}
+   {% for item in attributes%}
+      {%- if not item.startswith('_') %}
+         {% set _ = wanted_attributes.append(item)%}
+      {%- endif -%}
+   {%- endfor %}
 
-   {% for item in attributes %}
-      {% if not item.startswith('_') %}
-      {% set count.value = count.value + 1 %}
-         {% if count.value == 1 %}
+   {% if wanted_attributes %}
    .. rubric:: Attributes
-
-   .. autosummary::
-      :toctree: ../stubs/
-         {% endif %}
-      
-      {{ name }}.{{ item }}
-      {% endif %}
-   {% endfor %}
+      {% for item in wanted_attributes %}
+   .. autoattribute:: {{ name }}.{{ item }}
+      {%- endfor %}
    {% endif %}
-   {% endblock %}
+{% endblock %}
 
-   {% block methods_summary %}
-   {% if methods %}
+{% block methods_summary %}
 
-   {% set count = namespace(value=0) %}
+   {% set wanted_methods = [] %}
    {% for item in all_methods %}
-
       {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-   {% set count.value = count.value + 1 %}
-   {% if count.value == 1 %}
-   .. rubric:: Methods
-
-   .. autosummary::
-      :toctree: ../stubs/
-   {% endif %}
-      {{ name }}.{{ item }}
+         {% set _ = wanted_methods.append(item)%}
       {%- endif -%}
    {%- endfor %}
-   {% for item in inherited_members %}
-      {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-   {% set count.value = count.value + 1 %}
-   {% if count.value == 1 %}
-   .. rubric:: Methods
 
-   .. autosummary::
-      :toctree: ../stubs/
-   {% endif %}
-      {{ name }}.{{ item }}
-      {%- endif -%}
+   {% if wanted_methods%}
+   .. rubric:: Methods
+   {% for item in wanted_methods %}
+   .. automethod:: {{ name }}.{{ item }}
    {%- endfor %}
 
    {% endif %}
-   {% endblock %}
+{% endblock %}
\ No newline at end of file
diff --git a/docs/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst
new file mode 100644
index 0000000000..9e3b9339c9
--- /dev/null
+++ b/docs/_templates/autosummary/class_no_inherited_members.rst
@@ -0,0 +1,52 @@
+{# This is identical to class.rst, except for the filtering of the inherited_members. -#}
+
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :no-members:
+   :no-inherited-members:
+   :no-special-members:
+
+{% block attributes_summary %}
+
+   {% set wanted_attributes = [] %}
+   {% for item in attributes%}
+      {%- if not item.startswith('_') %}
+         {% set _ = wanted_attributes.append(item)%}
+      {%- endif -%}
+   {%- endfor %}
+
+   {% if wanted_attributes%}
+   .. rubric:: Attributes
+      {% for item in wanted_attributes %}
+   .. autoattribute:: {{ name }}.{{ item }}
+      {%- endfor %}
+   {% endif %}
+{% endblock %}
+
+{% block methods_summary %}
+
+   {% set wanted_methods = [] %}
+   {% for item in all_methods %}
+      {%- if item not in inherited_members %}
+         {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
+            {% set _ = wanted_methods.append(item)%}
+         {%- endif -%}
+      {%- endif -%}
+   {%- endfor %}
+
+   {% if wanted_methods %}
+   .. rubric:: Methods
+   {% for item in wanted_methods %}
+   .. automethod:: {{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+{% endblock %}
\ No newline at end of file
diff --git a/docs/_templates/autosummary/drawer.rst b/docs/_templates/autosummary/drawer.rst
index a17d57f6da..03501a5cd0 100644
--- a/docs/_templates/autosummary/drawer.rst
+++ b/docs/_templates/autosummary/drawer.rst
@@ -17,11 +17,9 @@
 
    .. rubric:: Attributes
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_attributes %}
       {%- if not item.startswith('_') %}
-      {{ name }}.{{ item }}
+   .. autoattribute:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% endif %}
@@ -32,16 +30,14 @@
 
    .. rubric:: Methods
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_methods %}
       {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% for item in inherited_members %}
       {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
 
diff --git a/docs/_templates/autosummary/experiment.rst b/docs/_templates/autosummary/experiment.rst
index 01800ea10b..0de1a1c3c3 100644
--- a/docs/_templates/autosummary/experiment.rst
+++ b/docs/_templates/autosummary/experiment.rst
@@ -17,11 +17,9 @@
 
    .. rubric:: Attributes
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_attributes %}
       {%- if not item.startswith('_') %}
-      {{ name }}.{{ item }}
+   .. autoattribute:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% endif %}
@@ -32,16 +30,14 @@
 
    .. rubric:: Methods
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_methods %}
       {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% for item in inherited_members %}
       {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
 
diff --git a/docs/_templates/autosummary/plotter.rst b/docs/_templates/autosummary/plotter.rst
index 83e19addbe..0b5cdeefaa 100644
--- a/docs/_templates/autosummary/plotter.rst
+++ b/docs/_templates/autosummary/plotter.rst
@@ -17,11 +17,9 @@
 
    .. rubric:: Attributes
 
-   .. autosummary::
-      :toctree: ../stubs/
    {% for item in all_attributes %}
       {%- if not item.startswith('_') %}
-      {{ name }}.{{ item }}
+   .. autoattribute:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% endif %}
@@ -32,17 +30,14 @@
 
    .. rubric:: Methods
 
-   .. autosummary::
-      :toctree: ../stubs/
-
    {% for item in all_methods %}
       {%- if not item.startswith('_') or item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}
    {% for item in inherited_members %}
       {%- if item in ['__call__', '__mul__', '__getitem__', '__len__'] %}
-      {{ name }}.{{ item }}
+   .. automethod:: {{ name }}.{{ item }}
       {%- endif -%}
    {%- endfor %}