use custom templates for autosummary (#219)

This lets us tell autosummary to do :members: also remove docs/reference/stubs from version control, because sphinx rebuilds it automatically
scikit-tda · Mar 4, 2021 · ac0c50e · ac0c50e
1 parent 571b577
commit ac0c50e
Show file tree

Hide file tree

Showing 13 changed files with 102 additions and 161 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -11,4 +11,5 @@ venv/
 backup_docs
 dist/
 test/
-generated
+generated
+reference/stubs
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.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/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst
@@ -0,0 +1,64 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: Module Attributes
+
+   .. autosummary::
+      :toctree:
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+   {% 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:
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/conf.py b/docs/conf.py
@@ -14,6 +14,9 @@
 
 html_static_path = ["../examples/output"]
 
+templates_path = ['_templates']
+exclude_patterns.append('_templates')
+
 # extensions.append('sphinx_gallery.gen_gallery')
 
 import pathlib
@@ -35,4 +38,4 @@
 })
 
 html_short_title = project
-htmlhelp_basename = 'KeplerMapperdoc'
+htmlhelp_basename = 'KeplerMapperdoc'
diff --git a/docs/reference/stubs/kmapper.Cover.rst b/docs/reference/stubs/kmapper.Cover.rst
diff --git a/docs/reference/stubs/kmapper.GraphNerve.rst b/docs/reference/stubs/kmapper.GraphNerve.rst
diff --git a/docs/reference/stubs/kmapper.KeplerMapper.rst b/docs/reference/stubs/kmapper.KeplerMapper.rst
diff --git a/docs/reference/stubs/kmapper.adapter.rst b/docs/reference/stubs/kmapper.adapter.rst
diff --git a/docs/reference/stubs/kmapper.draw_matplotlib.rst b/docs/reference/stubs/kmapper.draw_matplotlib.rst
diff --git a/docs/reference/stubs/kmapper.jupyter.rst b/docs/reference/stubs/kmapper.jupyter.rst
diff --git a/docs/reference/stubs/kmapper.plotlyviz.mpl_to_plotly.rst b/docs/reference/stubs/kmapper.plotlyviz.mpl_to_plotly.rst
diff --git a/docs/reference/stubs/kmapper.plotlyviz.plotlyviz.rst b/docs/reference/stubs/kmapper.plotlyviz.plotlyviz.rst
diff --git a/docs/reference/stubs/kmapper.visuals.colorscale_from_matplotlib_cmap.rst b/docs/reference/stubs/kmapper.visuals.colorscale_from_matplotlib_cmap.rst