From d9c66bf77fcfec77871dad69c1a509ab9a1cb3a1 Mon Sep 17 00:00:00 2001
From: Alexander Hampel <ahampel@flatironinstitute.org>
Date: Wed, 16 Feb 2022 09:16:49 -0500
Subject: [PATCH] enable autosummary in sphinx

---
 doc/CMakeLists.txt                            |  2 +-
 doc/_templates/autosummary_class_template.rst | 32 +++++++++
 .../autosummary_module_template.rst           | 68 +++++++++++++++++++
 doc/conf.py.in                                |  7 ++
 doc/documentation.rst                         | 11 ++-
 5 files changed, 113 insertions(+), 7 deletions(-)
 create mode 100644 doc/_templates/autosummary_class_template.rst
 create mode 100644 doc/_templates/autosummary_module_template.rst

diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
index 01d96c39..04d1ad06 100644
--- a/doc/CMakeLists.txt
+++ b/doc/CMakeLists.txt
@@ -56,7 +56,7 @@ endif()
 add_custom_target(${PROJECT_NAME}_docs_sphinx ALL)
 add_custom_command(
   TARGET ${PROJECT_NAME}_docs_sphinx
-  COMMAND PYTHONPATH=${PROJECT_BINARY_DIR}/python:$ENV{PYTHONPATH} ${SPHINXBUILD_EXECUTABLE} -c . -j8 -b html ${CMAKE_CURRENT_SOURCE_DIR} html
+  COMMAND PYTHONPATH=${PROJECT_BINARY_DIR}/python/${PROJECT_NAME}:${PROJECT_BINARY_DIR}/python:$ENV{PYTHONPATH} ${SPHINXBUILD_EXECUTABLE} -c . -b html ${CMAKE_CURRENT_SOURCE_DIR} html
 )
 
 option(Sphinx_Only "When building the documentation, skip the Python Modules and the generation of C++ Api and example outputs" OFF)
diff --git a/doc/_templates/autosummary_class_template.rst b/doc/_templates/autosummary_class_template.rst
new file mode 100644
index 00000000..e74d21b5
--- /dev/null
+++ b/doc/_templates/autosummary_class_template.rst
@@ -0,0 +1,32 @@
+{{ 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 %}
diff --git a/doc/_templates/autosummary_module_template.rst b/doc/_templates/autosummary_module_template.rst
new file mode 100644
index 00000000..737206f8
--- /dev/null
+++ b/doc/_templates/autosummary_module_template.rst
@@ -0,0 +1,68 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+{% block functions %}
+{% if functions %}
+.. rubric:: Functions
+
+.. autosummary::
+    :toctree:                             
+    {% for item in functions %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block attributes %}
+{% if attributes %}
+.. rubric:: Module Attributes
+
+.. autosummary::
+    :toctree:                             
+    {% for item in attributes %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block classes %}
+{% if classes %}
+.. rubric:: {{ _('Classes') }}
+
+.. autosummary::
+    :toctree:                                         
+    :template: autosummary_class_template.rst
+    {% for item in classes %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block exceptions %}
+{% if exceptions %}
+.. rubric:: {{ _('Exceptions') }}
+
+.. autosummary::
+    :toctree:                                       
+    {% for item in exceptions %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+    :toctree:
+    :template: autosummary_module_template.rst 
+    :recursive:
+
+    {% for item in modules %}
+    {{ item }}
+    {%- endfor %}
+{% endif %}
+{% endblock %}
+
diff --git a/doc/conf.py.in b/doc/conf.py.in
index 31e575f3..230762e6 100644
--- a/doc/conf.py.in
+++ b/doc/conf.py.in
@@ -6,6 +6,9 @@ import sys
 sys.path.insert(0, "@CMAKE_CURRENT_SOURCE_DIR@/sphinxext")
 sys.path.insert(0, "@CMAKE_CURRENT_SOURCE_DIR@/sphinxext/numpydoc")
 
+# exclude these folders from scanning by sphinx
+exclude_patterns = ['_templates']
+
 extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.mathjax',
               'sphinx.ext.intersphinx',
@@ -39,6 +42,10 @@ pygments_style = 'sphinx'
 
 source_suffix = '.rst'
 
+# Turn on sphinx.ext.autosummary
+autosummary_generate = True
+autosummary_imported_members=False
+
 project = '@PROJECT_NAME@'
 version = '@PROJECT_VERSION@'
 
diff --git a/doc/documentation.rst b/doc/documentation.rst
index d68686ca..c82a0b5b 100644
--- a/doc/documentation.rst
+++ b/doc/documentation.rst
@@ -21,10 +21,9 @@ C++ reference manual
 Python reference manual
 =======================
 
-.. automodule:: app4triqs 
-   :members:
+.. autosummary::
+   :toctree: _autosummary
+   :template: autosummary_module_template.rst
+   :recursive:
 
-.. autoclass:: app4triqs.app4triqs_module.Toto
-   :members:
-
-.. autofunction:: app4triqs.app4triqs_module.chain
+    app4triqs_module