Permit putting class members on 'stub' pages

.gitignore

@@ -33,6 +33,7 @@ develop-eggs
 distribute-*.tar.gz
 
 # Other
+.vimsession
 .cache
 .tox
 .*.swp

sphinx_automodapi/automodapi.py

@@ -434,7 +434,7 @@ def setup(app):
     from . import automodsumm
     app.setup_extension(automodsumm.__name__)
 
-    app.connect('source-read', process_automodapi)
+    app.connect('source-read', process_automodapi, priority=100)
 
     app.add_config_value('automodapi_inheritance_diagram', True, True)
     app.add_config_value('automodapi_toctreedirnm', 'api', True)

sphinx_automodapi/automodsumm.py

@@ -55,6 +55,12 @@
     actually used by sphinx, so this option is only for figuring out the
     cause of sphinx warnings or other debugging.  Defaults to ``False``.
 
+* ``automodsumm_stub_pages``
+    Should be a bool, and if ``True``, will cause `automodsumm`_ to
+    generate individual stub pages for class attributes and class methods
+    rather than documenting all class methods and attributes on the same
+    page. Defaults to ``False``.
+
 * ``automodsumm_inherited_members``
     Should be a bool and if ``True``, will cause `automodsumm`_ to document
     class members that are inherited from a base class. This value can be
@@ -266,10 +272,13 @@ def process_automodsumm_generation(app):
     for sfn, lines in zip(filestosearch, liness):
         suffix = os.path.splitext(sfn)[1]
         if len(lines) > 0:
-            generate_automodsumm_docs(
+            new_files = generate_automodsumm_docs(
                 lines, sfn, app=app, builder=app.builder,
                 suffix=suffix, base_path=app.srcdir,
+                stub_pages=app.config.automodsumm_stub_pages,
                 inherited_members=app.config.automodsumm_inherited_members)
+            for f in new_files:
+                env.found_docs.add(env.path2doc(f))
 
 
 # _automodsummrex = re.compile(r'^(\s*)\.\. automodsumm::\s*([A-Za-z0-9_.]+)\s*'
@@ -408,6 +417,7 @@ def automodsumm_to_autosummary_lines(fn, app):
 def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst',
                               base_path=None, builder=None,
                               template_dir=None,
+                              stub_pages=False,
                               inherited_members=False):
     """
     This function is adapted from
@@ -434,7 +444,13 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst',
     template_dirs = [os.path.join(os.path.dirname(__file__), 'templates'),
                      os.path.join(base_path, '_templates')]
     if builder is not None:
-        # allow the user to override the templates
+        # allow the user to override the templates and ensure class stub
+        # pages read the automodsumm base.rst
+        # TODO: Will this override user base.rst files?
+        local_dir_full = os.path.join(template_dirs[0], 'autosummary_core')
+        templates_path = builder.config.templates_path
+        if local_dir_full not in templates_path:
+            templates_path.append(local_dir_full)
         template_loader = BuiltinTemplateLoader()
         template_loader.init(builder, dirs=template_dirs)
     else:
@@ -487,11 +503,11 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst',
         fn = os.path.join(path, name + suffix)
 
         # skip it if it exists
+        # always add to new_files so we can add them to env.found_docs
+        new_files.append(fn)
         if os.path.isfile(fn):
             continue
 
-        new_files.append(fn)
-
         f = open(fn, 'w')
 
         try:
@@ -502,8 +518,11 @@ def generate_automodsumm_docs(lines, srcfn, app=None, suffix='.rst',
                 template = template_env.get_template(template_name)
             else:
                 tmplstr = 'autosummary_core/%s.rst'
+                tmplname = doc.objtype
+                if tmplname == 'class':
+                    tmplname = 'class-stubs' if stub_pages else 'class-flat'
                 try:
-                    template = template_env.get_template(tmplstr % doc.objtype)
+                    template = template_env.get_template(tmplstr % tmplname)
                 except TemplateNotFound:
                     template = template_env.get_template(tmplstr % 'base')
 
@@ -649,6 +668,7 @@ def get_members_class(obj, typ, include_public=[],
         finally:
             f.close()
 
+    return new_files
 
 def setup(app):
 
@@ -663,9 +683,10 @@ def setup(app):
 
     app.add_directive('automod-diagram', Automoddiagram)
     app.add_directive('automodsumm', Automodsumm)
-    app.connect('builder-inited', process_automodsumm_generation)
+    app.connect('builder-inited', process_automodsumm_generation, priority=100)
 
     app.add_config_value('automodsumm_writereprocessed', False, True)
+    app.add_config_value('automodsumm_stub_pages', False, 'env')
     app.add_config_value('automodsumm_inherited_members', False, 'env')
 
     return {'parallel_read_safe': True,

sphinx_automodapi/templates/autosummary_core/class-stubs.rst

@@ -0,0 +1,46 @@
+{% if referencefile %}
+.. include:: {{ referencefile }}
+{% endif %}
+
+{{ objname }}
+{{ underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :show-inheritance:
+
+   {% if '__init__' in methods %}
+     {% set caught_result = methods.remove('__init__') %}
+   {% endif %}
+
+   {% block attributes_summary %}
+   {% if attributes %}
+
+   .. rubric:: Attributes Summary
+
+   .. autosummary::
+      :toctree:
+      :template: base.rst
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+
+   {% block methods_summary %}
+   {% if methods %}
+
+   .. rubric:: Methods Summary
+
+   .. autosummary::
+      :toctree:
+      :template: base.rst
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+
+   {% endif %}
+   {% endblock %}
+