From c6cf50e0664fcbfc970303d389eae35ce0d289d6 Mon Sep 17 00:00:00 2001 From: Arnau Casau Date: Mon, 9 Oct 2023 18:47:27 +0200 Subject: [PATCH 1/6] Move methods into class pages for docs Co-authored-by: Eric Arellano <14852634+Eric-Arellano@users.noreply.github.com> --- docs/_templates/autosummary/class.rst | 59 ++++++++---------- .../class_no_inherited_members.rst | 61 +++++++------------ docs/conf.py | 1 + 3 files changed, 46 insertions(+), 75 deletions(-) diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index a63062a73..ebe590363 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -1,45 +1,34 @@ -{% if referencefile %} -.. include:: {{ referencefile }} -{% endif %} +{# + We show all the class's methods and attributes on the same page. By default, we document + all methods, including those defined by parent classes. +-#} -{{ objname }} -{{ underline }} +{{ objname | escape | underline }} .. currentmodule:: {{ module }} .. autoclass:: {{ objname }} - :show-inheritance: :no-members: - :no-inherited-members: :no-special-members: + :show-inheritance: - {% block attributes_summary %} - {% if attributes %} - +{% block attributes_summary %} + {% if attributes %} .. rubric:: Attributes - - .. autosummary:: - :toctree: ../stubs/ - {% for item in all_attributes %} - {%- if not item.startswith('_') %} - ~{{ name }}.{{ item }} - {%- endif -%} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block methods_summary %} - {% if methods %} - + {% for item in attributes %} + .. autoattribute:: {{ item }} + :noindex: + {%- endfor %} + {% endif %} +{% endblock -%} + +{% block methods_summary %} + {% set wanted_methods = (methods | reject('==', '__init__') | list) %} + {% if wanted_methods %} .. rubric:: Methods - - .. autosummary:: - :toctree: ../stubs/ - {% for item in all_methods %} - {%- if not item.startswith('_') %} - ~{{ name }}.{{ item }} - {%- endif -%} - {%- endfor %} - - {% endif %} - {% endblock %} + {% for item in wanted_methods %} + .. automethod:: {{ item }} + :noindex: + {%- endfor %} + {% endif %} +{% endblock %} diff --git a/docs/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst index 0e83ca902..de40c6dbb 100644 --- a/docs/_templates/autosummary/class_no_inherited_members.rst +++ b/docs/_templates/autosummary/class_no_inherited_members.rst @@ -1,49 +1,30 @@ -{% if referencefile %} -.. include:: {{ referencefile }} -{% endif %} +{# This is identical to class.rst, except for the filtering in `set wanted_methods`. -#} -{{ objname }} -{{ underline }} +{{ objname | escape | underline }} .. currentmodule:: {{ module }} .. autoclass:: {{ objname }} - :show-inheritance: :no-members: - :no-inherited-members: - :no-special-members: - - {% block attributes_summary %} - {% if attributes %} + :show-inheritance: +{% block attributes_summary %} + {% if attributes %} .. rubric:: Attributes - - .. autosummary:: - :toctree: ../stubs/ - {% for item in all_attributes %} - {%- if item not in inherited_members %} - {%- if not item.startswith('_') %} - ~{{ name }}.{{ item }} - {%- endif -%} - {%- endif %} - {%- endfor %} - {% endif %} - {% endblock %} - - {% block methods_summary %} - {% if methods %} - + {% for item in attributes %} + .. autoattribute:: {{ item }} + :noindex: + {%- endfor %} + {% endif %} +{% endblock -%} + +{% block methods_summary %} + {% set wanted_methods = (methods | reject('in', inherited_members) | reject('==', '__init__') | list) %} + {% if wanted_methods %} .. rubric:: Methods - - .. autosummary:: - :toctree: ../stubs/ - {% for item in all_methods %} - {%- if item not in inherited_members %} - {%- if not item.startswith('_') %} - ~{{ name }}.{{ item }} - {%- endif -%} - {%- endif %} - {%- endfor %} - - {% endif %} - {% endblock %} + {% for item in wanted_methods %} + .. automethod:: {{ item }} + :noindex: + {%- endfor %} + {% endif %} +{% endblock %} diff --git a/docs/conf.py b/docs/conf.py index c245e130c..7da6309e7 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -93,6 +93,7 @@ "nbsphinx", "sphinx.ext.intersphinx", "qiskit_sphinx_theme", + 'matplotlib.sphinxext.plot_directive', ] html_static_path = ["_static"] templates_path = ["_templates"] From 7ed9a85e0690b27eb9043e7795c5efc2f57282ef Mon Sep 17 00:00:00 2001 From: Arnau Casau Date: Tue, 10 Oct 2023 15:09:13 +0200 Subject: [PATCH 2/6] :no-index: removed --- docs/_templates/autosummary/class.rst | 2 -- docs/_templates/autosummary/class_no_inherited_members.rst | 2 -- 2 files changed, 4 deletions(-) diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index ebe590363..76b45f4c8 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -17,7 +17,6 @@ .. rubric:: Attributes {% for item in attributes %} .. autoattribute:: {{ item }} - :noindex: {%- endfor %} {% endif %} {% endblock -%} @@ -28,7 +27,6 @@ .. rubric:: Methods {% for item in wanted_methods %} .. automethod:: {{ item }} - :noindex: {%- endfor %} {% endif %} {% endblock %} diff --git a/docs/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst index de40c6dbb..269a89b70 100644 --- a/docs/_templates/autosummary/class_no_inherited_members.rst +++ b/docs/_templates/autosummary/class_no_inherited_members.rst @@ -13,7 +13,6 @@ .. rubric:: Attributes {% for item in attributes %} .. autoattribute:: {{ item }} - :noindex: {%- endfor %} {% endif %} {% endblock -%} @@ -24,7 +23,6 @@ .. rubric:: Methods {% for item in wanted_methods %} .. automethod:: {{ item }} - :noindex: {%- endfor %} {% endif %} {% endblock %} From 9a363aa83adbf36cbfe9d0c716db1f5427c177d9 Mon Sep 17 00:00:00 2001 From: Arnau Casau Date: Tue, 10 Oct 2023 19:25:12 +0200 Subject: [PATCH 3/6] fix the templates --- docs/_templates/autosummary/class.rst | 5 +++++ docs/_templates/autosummary/class_no_inherited_members.rst | 6 ++++++ 2 files changed, 11 insertions(+) diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index 76b45f4c8..dcfde8d87 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -3,12 +3,17 @@ all methods, including those defined by parent classes. -#} +{% if referencefile %} +.. include:: {{ referencefile }} +{% endif %} + {{ objname | escape | underline }} .. currentmodule:: {{ module }} .. autoclass:: {{ objname }} :no-members: + :no-inherited-members: :no-special-members: :show-inheritance: diff --git a/docs/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst index 269a89b70..d88ef81af 100644 --- a/docs/_templates/autosummary/class_no_inherited_members.rst +++ b/docs/_templates/autosummary/class_no_inherited_members.rst @@ -1,11 +1,17 @@ {# This is identical to class.rst, except for the filtering in `set wanted_methods`. -#} +{% if referencefile %} +.. include:: {{ referencefile }} +{% endif %} + {{ objname | escape | underline }} .. currentmodule:: {{ module }} .. autoclass:: {{ objname }} :no-members: + :no-inherited-members: + :no-special-members: :show-inheritance: {% block attributes_summary %} From 086950305cc65078957404074930a00817c0c418 Mon Sep 17 00:00:00 2001 From: Arnau Casau Date: Tue, 10 Oct 2023 19:37:19 +0200 Subject: [PATCH 4/6] modifying the templates and lint test --- docs/_templates/autosummary/class.rst | 7 ++++--- docs/_templates/autosummary/class_no_inherited_members.rst | 7 ++++--- docs/conf.py | 2 +- 3 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index dcfde8d87..0b3e1b397 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -7,7 +7,8 @@ .. include:: {{ referencefile }} {% endif %} -{{ objname | escape | underline }} +{{ objname }} +{{ underline }} .. currentmodule:: {{ module }} @@ -21,7 +22,7 @@ {% if attributes %} .. rubric:: Attributes {% for item in attributes %} - .. autoattribute:: {{ item }} + .. autoattribute:: {{ name }}.{{ item }} {%- endfor %} {% endif %} {% endblock -%} @@ -31,7 +32,7 @@ {% if wanted_methods %} .. rubric:: Methods {% for item in wanted_methods %} - .. automethod:: {{ item }} + .. automethod:: {{ name }}.{{ item }} {%- endfor %} {% endif %} {% endblock %} diff --git a/docs/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst index d88ef81af..8ef41d200 100644 --- a/docs/_templates/autosummary/class_no_inherited_members.rst +++ b/docs/_templates/autosummary/class_no_inherited_members.rst @@ -4,7 +4,8 @@ .. include:: {{ referencefile }} {% endif %} -{{ objname | escape | underline }} +{{ objname }} +{{ underline }} .. currentmodule:: {{ module }} @@ -18,7 +19,7 @@ {% if attributes %} .. rubric:: Attributes {% for item in attributes %} - .. autoattribute:: {{ item }} + .. autoattribute:: {{ name }}.{{ item }} {%- endfor %} {% endif %} {% endblock -%} @@ -28,7 +29,7 @@ {% if wanted_methods %} .. rubric:: Methods {% for item in wanted_methods %} - .. automethod:: {{ item }} + .. automethod:: {{ name }}.{{ item }} {%- endfor %} {% endif %} {% endblock %} diff --git a/docs/conf.py b/docs/conf.py index 7da6309e7..91066b217 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -93,7 +93,7 @@ "nbsphinx", "sphinx.ext.intersphinx", "qiskit_sphinx_theme", - 'matplotlib.sphinxext.plot_directive', + "matplotlib.sphinxext.plot_directive", ] html_static_path = ["_static"] templates_path = ["_templates"] From d89627a84cff48dda65901b54c1c43e53432fd81 Mon Sep 17 00:00:00 2001 From: Arnau Casau Date: Tue, 10 Oct 2023 21:21:19 +0200 Subject: [PATCH 5/6] adding conditions old templates --- docs/_templates/autosummary/class.rst | 36 ++++++++-------- .../class_no_inherited_members.rst | 41 ++++++++++--------- 2 files changed, 38 insertions(+), 39 deletions(-) diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index 0b3e1b397..26837c0a4 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -1,8 +1,3 @@ -{# - We show all the class's methods and attributes on the same page. By default, we document - all methods, including those defined by parent classes. --#} - {% if referencefile %} .. include:: {{ referencefile }} {% endif %} @@ -13,26 +8,29 @@ .. currentmodule:: {{ module }} .. autoclass:: {{ objname }} + :show-inheritance: :no-members: :no-inherited-members: :no-special-members: - :show-inheritance: -{% block attributes_summary %} - {% if attributes %} + {% block attributes_summary %} + {% if attributes %} .. rubric:: Attributes - {% for item in attributes %} + {% for item in all_attributes %} + {%- if not item.startswith('_') %} .. autoattribute:: {{ name }}.{{ item }} - {%- endfor %} - {% endif %} -{% endblock -%} + {%- endif -%} + {%- endfor %} + {% endif %} + {% endblock %} -{% block methods_summary %} - {% set wanted_methods = (methods | reject('==', '__init__') | list) %} - {% if wanted_methods %} + {% block methods_summary %} + {% if methods %} .. rubric:: Methods - {% for item in wanted_methods %} + {% for item in all_methods %} + {%- if not item.startswith('_') %} .. automethod:: {{ name }}.{{ item }} - {%- endfor %} - {% endif %} -{% endblock %} + {%- endif -%} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst index 8ef41d200..2836baba3 100644 --- a/docs/_templates/autosummary/class_no_inherited_members.rst +++ b/docs/_templates/autosummary/class_no_inherited_members.rst @@ -1,35 +1,36 @@ -{# This is identical to class.rst, except for the filtering in `set wanted_methods`. -#} - -{% if referencefile %} -.. include:: {{ referencefile }} -{% endif %} - {{ objname }} {{ underline }} .. currentmodule:: {{ module }} .. autoclass:: {{ objname }} + :show-inheritance: :no-members: :no-inherited-members: :no-special-members: - :show-inheritance: -{% block attributes_summary %} - {% if attributes %} + {% block attributes_summary %} + {% if attributes %} .. rubric:: Attributes - {% for item in attributes %} + {% for item in all_attributes %} + {%- if item not in inherited_members %} + {%- if not item.startswith('_') %} .. autoattribute:: {{ name }}.{{ item }} - {%- endfor %} - {% endif %} -{% endblock -%} + {%- endif -%} + {%- endif %} + {%- endfor %} + {% endif %} + {% endblock %} -{% block methods_summary %} - {% set wanted_methods = (methods | reject('in', inherited_members) | reject('==', '__init__') | list) %} - {% if wanted_methods %} + {% block methods_summary %} + {% if methods %} .. rubric:: Methods - {% for item in wanted_methods %} + {% for item in all_methods %} + {%- if item not in inherited_members %} + {%- if not item.startswith('_') %} .. automethod:: {{ name }}.{{ item }} - {%- endfor %} - {% endif %} -{% endblock %} + {%- endif -%} + {%- endif %} + {%- endfor %} + {% endif %} + {% endblock %} From accc4ba986c47545f7dcd5bbf97e196e546716bb Mon Sep 17 00:00:00 2001 From: Arnau Casau <47946624+arnaucasau@users.noreply.github.com> Date: Tue, 10 Oct 2023 21:28:26 +0200 Subject: [PATCH 6/6] Update class_no_inherited_members.rst --- docs/_templates/autosummary/class_no_inherited_members.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/_templates/autosummary/class_no_inherited_members.rst b/docs/_templates/autosummary/class_no_inherited_members.rst index 2836baba3..58df844b8 100644 --- a/docs/_templates/autosummary/class_no_inherited_members.rst +++ b/docs/_templates/autosummary/class_no_inherited_members.rst @@ -1,3 +1,7 @@ +{% if referencefile %} +.. include:: {{ referencefile }} +{% endif %} + {{ objname }} {{ underline }}