Add AutoAutoSummary extension

.nengobones.yml

@@ -67,6 +67,7 @@ docs_conf_py:
     - examples/test-example.ipynb
   extensions:
     - nengo_sphinx_theme.ext.resolvedefaults
+    - nengo_sphinx_theme.ext.autoautosummary
   analytics_id: UA-41658423-2
 
 pre_commit_config_yaml: {}

.travis.yml

@@ -54,8 +54,11 @@ jobs:
           condition: $TRAVIS_TAG =~ ^v[0-9]*
 
 before_install:
-  # export travis_terminate for use in scripts
+  # export travis_terminate for use in scripts, from here:
+  # https://github.com/travis-ci/travis-build/blob/master/lib/travis/build/bash/travis_terminate.bash
   - export -f travis_terminate
+    _travis_terminate_agent
+    _travis_terminate_freebsd
     _travis_terminate_linux
     _travis_terminate_osx
     _travis_terminate_unix
@@ -77,9 +80,6 @@ install:
   - .ci/$SCRIPT.sh install
   - pip freeze
 
-after_install:
-  - .ci/$SCRIPT.sh after_install
-
 before_script:
   - .ci/$SCRIPT.sh before_script
 

CHANGES.rst

@@ -19,14 +19,20 @@ Release History
    - Removed
    - Fixed
 
-1.0.4 (unreleased)
+1.1.0 (unreleased)
 ==================
 
+**Added**
 
+- Added an extension with the ``AutoAutoSummary`` directive, which will
+  automatically generate Sphinx AutoSummaries for modules and classes.
+  (`#45 <https://github.com/nengo/nengo-sphinx-theme/pull/45>`__)
 
 1.0.3 (September 13, 2019)
 ==========================
 
+**Changed**
+
 - Updated header and footer to match changes to nengo.ai.
   (`#41 <https://github.com/nengo/nengo-sphinx-theme/pull/41>`__)
 

docs/conf.py

@@ -18,6 +18,7 @@
     "nengo_sphinx_theme",
     "numpydoc",
     "nengo_sphinx_theme.ext.resolvedefaults",
+    "nengo_sphinx_theme.ext.autoautosummary",
 ]
 
 # -- sphinx.ext.autodoc
@@ -43,7 +44,11 @@
 
 # -- sphinx
 nitpicky = True
-exclude_patterns = ["_build", "**/.ipynb_checkpoints", "examples/test-example.ipynb"]
+exclude_patterns = [
+    "_build",
+    "**/.ipynb_checkpoints",
+    "examples/test-example.ipynb",
+]
 linkcheck_timeout = 30
 source_suffix = ".rst"
 source_encoding = "utf-8"

docs/extensions.rst

@@ -23,3 +23,19 @@ to the ``extensions`` list in ``conf.py``.
 Autodoc with default resolution:
 
 .. autoclass:: nengo_sphinx_theme.ext.resolvedefaults.TestClass
+
+AutoAutoSummary
+===============
+
+.. automodule:: nengo_sphinx_theme.ext.autoautosummary
+
+   .. autoautosummary:: nengo_sphinx_theme.ext.autoautosummary
+      :exclude-members: setup
+
+.. autoclass:: nengo_sphinx_theme.ext.autoautosummary.TestClass
+   :private-members:
+
+   .. autoautosummary:: nengo_sphinx_theme.ext.autoautosummary.TestClass
+      :nosignatures:
+
+      nengo_sphinx_theme.ext.autoautosummary.TestClass._another_private_method

nengo_sphinx_theme/ext/autoautosummary.py

@@ -0,0 +1,130 @@
+"""
+This extension automatically generates AutoSummaries for modules/classes.
+"""
+
+import inspect
+
+from docutils.parsers.rst import directives
+import sphinx.ext.autosummary as autosummary
+
+# We import nengo_sphinx_theme here to test the issue that
+# `patch_autosummary_import_by_name` fixes.
+
+import nengo_sphinx_theme  # pylint: disable=unused-import
+
+
+# should be ignored
+a_test_attribute = None
+
+
+def a_test_function():
+    """This is a test function."""
+
+
+class TestClass:
+    """This is a test class."""
+
+    # should be ignored
+    an_attribute = None
+
+    def __init__(self):
+        """This is the init method."""
+
+    def a_method(self):
+        """This is a method."""
+
+    @staticmethod
+    def a_static_method():
+        """This is a static method."""
+
+    def _a_private_method(self):
+        """A private method."""
+
+    def _another_private_method(self):
+        """This method will be manually added."""
+
+
+class AutoAutoSummary(autosummary.Autosummary):
+    """
+    Automatically generates a summary for a class or module.
+
+    For classes this adds a summary for all methods.
+
+    For modules this adds a summary for all classes/functions.
+    """
+
+    option_spec = {
+        "nosignatures": directives.unchanged,
+        "exclude-members": directives.unchanged,
+    }
+
+    required_arguments = 1
+
+    def get_members(self, obj):
+        if inspect.isclass(obj):
+            module_name = obj.__module__
+
+            def filter(x):
+                return inspect.isroutine(x)
+
+        elif inspect.ismodule(obj):
+            module_name = obj.__name__
+
+            def filter(x):
+                return inspect.isclass(x) or inspect.isfunction(x)
+
+        else:
+            raise TypeError(
+                "AutoAutoSummary only works with classes or modules (got %s)"
+                % type(obj)
+            )
+
+        excluded = [
+            x.strip() for x in self.options.get("exclude-members", "").split(",")
+        ]
+
+        items = []
+        # note: we use __dict__ because it preserves the order of attribute definitions
+        # (in python >= 3.6)
+        for name in obj.__dict__:
+            if not (name.startswith("_") or name in excluded):
+                attr = getattr(obj, name)
+
+                if filter(attr) and attr.__module__ == module_name:
+                    items.append(name)
+
+        return items
+
+    def run(self):
+        clazz = str(self.arguments[0])
+        (module_name, obj_name) = clazz.rsplit(".", 1)
+        mod = __import__(module_name, globals(), locals(), [obj_name])
+        obj = getattr(mod, obj_name)
+
+        new_content = ["%s.%s" % (clazz, item) for item in self.get_members(obj)]
+
+        if inspect.isclass(obj):
+            # add the class itself
+            new_content = [clazz] + new_content
+
+        self.content = new_content + self.content.data
+
+        return super(AutoAutoSummary, self).run()
+
+
+def patch_autosummary_import_by_name():
+    """Monkeypatch a function in autosummary to disallow module cycles"""
+
+    orig_f = autosummary.import_by_name
+
+    def import_by_name(name, prefixes):
+        # Filter out problematic prefixes
+        prefixes = [p for p in prefixes if p is None or not name.startswith(p)]
+        return orig_f(name, prefixes)
+
+    autosummary.import_by_name = import_by_name
+
+
+def setup(app):
+    patch_autosummary_import_by_name()
+    app.add_directive("autoautosummary", AutoAutoSummary)

nengo_sphinx_theme/version.py

@@ -7,7 +7,7 @@
 """
 
 name = "nengo_sphinx_theme"
-version_info = (1, 0, 4)  # (major, minor, patch)
+version_info = (1, 1, 0)  # (major, minor, patch)
 dev = 0
 
 version = "{v}{dev}".format(

setup.py

@@ -31,8 +31,16 @@ def read(*filenames, **kwargs):
     "version"
 ]
 
-install_req = ["sphinx>=1.8"]
-docs_req = ["jupyter", "matplotlib", "nbsphinx", "nengo", "numpydoc"]
+install_req = [
+    "sphinx>=1.8",
+]
+docs_req = [
+    "jupyter",
+    "matplotlib",
+    "nbsphinx",
+    "nengo",
+    "numpydoc",
+]
 optional_req = []
 tests_req = []
 
@@ -56,7 +64,7 @@ def read(*filenames, **kwargs):
         "tests": tests_req,
     },
     python_requires=">=3.5",
-    entry_points={"sphinx.html_themes": ["nengo_sphinx_theme=nengo_sphinx_theme"]},
+    entry_points={"sphinx.html_themes": ["nengo_sphinx_theme=nengo_sphinx_theme",],},
     classifiers=[
         "Development Status :: 4 - Beta",
         "Framework :: Nengo",