Merge pull request #113 from rtfd/cleanup-june

Basic cleanup tasks

.travis.yml

@@ -1,7 +1,6 @@
 language: python
 python:
   - 2.7
-  - 3.4
   - 3.5
   - 3.6
 sudo: false

autoapi/extension.py

@@ -112,36 +112,46 @@ def doctree_read(app, doctree):
     """
     Inject AutoAPI into the TOC Tree dynamically.
     """
-
-    all_docs = set()
-    insert = True
     if app.env.docname == 'index':
+        all_docs = set()
+        insert = True
         nodes = doctree.traverse(toctree)
         toc_entry = '%s/index' % app.config.autoapi_root
         if not nodes:
             return
+        # Capture all existing toctree entries
+        root = nodes[0]
         for node in nodes:
             for entry in node['entries']:
                 all_docs.add(entry[1])
-        # Don't insert if it's already present
+        # Don't insert autoapi it's already present
         for doc in all_docs:
             if doc.find(app.config.autoapi_root) != -1:
                 insert = False
         if insert and app.config.autoapi_add_toctree_entry:
-            nodes[-1]['entries'].append(
-                (None, u'%s/index' % app.config.autoapi_root)
-            )
-            nodes[-1]['includefiles'].append(u'%s/index' % app.config.autoapi_root)
-            app.info(bold('[AutoAPI] ') +
-                     darkgreen('Adding AutoAPI TOCTree [%s] to index.rst' % toc_entry)
-                     )
+            if app.config.autoapi_add_api_root_toctree:
+                # Insert full API TOC in root TOC
+                for path in app.env.autoapi_toc_entries:
+                    nodes[-1]['entries'].append(
+                        (None, path[1:])
+                    )
+                    nodes[-1]['includefiles'].append(path)
+            else:
+                # Insert AutoAPI index
+                nodes[-1]['entries'].append(
+                    (None, u'%s/index' % app.config.autoapi_root)
+                )
+                nodes[-1]['includefiles'].append(u'%s/index' % app.config.autoapi_root)
+                app.info(bold('[AutoAPI] ') +
+                         darkgreen('Adding AutoAPI TOCTree [%s] to index.rst' % toc_entry)
+                         )
 
 
 def setup(app):
     app.connect('builder-inited', run_autoapi)
-    app.connect('build-finished', build_finished)
     app.connect('doctree-read', doctree_read)
     app.connect('doctree-resolved', add_domain_to_toctree)
+    app.connect('build-finished', build_finished)
     app.add_config_value('autoapi_type', 'python', 'html')
     app.add_config_value('autoapi_root', API_ROOT, 'html')
     app.add_config_value('autoapi_ignore', [], 'html')
@@ -150,6 +160,7 @@ def setup(app):
     app.add_config_value('autoapi_dirs', [], 'html')
     app.add_config_value('autoapi_keep_files', False, 'html')
     app.add_config_value('autoapi_add_toctree_entry', True, 'html')
+    app.add_config_value('autoapi_add_api_root_toctree', False, 'html')
     app.add_config_value('autoapi_template_dir', [], 'html')
     app.add_stylesheet('autoapi.css')
     directives.register_directive('autoapi-nested-parse', NestedParse)

autoapi/mappers/base.py

@@ -267,10 +267,10 @@ class SphinxMapperBase(object):
     def map(self, options=None):
         '''Trigger find of serialized sources and build objects'''
         for path, data in self.paths.items():
-            for obj in self.create_class(data, options=options, path=path):
+            for obj in self.create_class(data, options=options):
                 self.add_object(obj)
 
-    def create_class(self, data, options=None, path=None, **kwargs):
+    def create_class(self, data, options=None, **kwargs):
         '''
         Create class object.
 
@@ -294,6 +294,10 @@ class SphinxMapperBase(object):
         # Render Top Index
         top_level_index = os.path.join(root, 'index.rst')
         pages = self.objects.values()
+        self.app.env.autoapi_toc_entries = []
+        for page in pages:
+            if page.top_level_object:
+                self.app.env.autoapi_toc_entries.append(page.include_path)
         with open(top_level_index, 'w+') as top_level_file:
             content = self.jinja_env.get_template('index.rst')
-            top_level_file.write(content.render(pages=pages))
+            top_level_file.write(content.render(pages=self.app.env.autoapi_toc_entries))

autoapi/mappers/go.py

@@ -40,7 +40,7 @@ class GoSphinxMapper(SphinxMapperBase):
             self.app.warn('Error reading file: {0}'.format(path))
         return None
 
-    def create_class(self, data, options=None, path=None, **kwargs):
+    def create_class(self, data, options=None, **kwargs):
         '''Return instance of class based on Go data
 
         Data keys handled here:

autoapi/mappers/javascript.py

@@ -40,7 +40,7 @@ class JavaScriptSphinxMapper(SphinxMapperBase):
                     obj.jinja_env = self.jinja_env
                     self.add_object(obj)
 
-    def create_class(self, data, options=None, path=None, **kwargs):
+    def create_class(self, data, options=None, **kwargs):
         '''Return instance of class based on Javascript data
 
         Data keys handled here:

autoapi/mappers/python.py

@@ -50,7 +50,7 @@ class PythonSphinxMapper(SphinxMapperBase):
             self.app.warn('Error reading file: {0}'.format(path))
         return None
 
-    def create_class(self, data, options=None, path=None, **kwargs):
+    def create_class(self, data, options=None, **kwargs):
         """Create a class from the passed in data
 
         :param data: dictionary data of pydocstyle output

autoapi/templates/index.rst

@@ -12,7 +12,5 @@ Below is a list of all items that are documented here.
    {# Force whitespace #}
 
    {%- for page in pages %}
-   {%- if page.top_level_object %}
-   {{ page.include_path }}
-   {%- endif %}
+   {{ page }}
    {%- endfor %}

autoapi/templates/python/function.rst

@@ -1,6 +1,6 @@
 {%- if obj.display %}
 
-.. function:: {{ obj.name }}({{ obj.args|join(',') }})
+.. function:: {{ obj.short_name }}({{ obj.args|join(',') }})
 
    {% if obj.docstring %}
    {{ obj.docstring|prepare_docstring|indent(3) }}

autoapi/templates/python/module.rst

@@ -1,11 +1,16 @@
+{% if obj.docstring or obj.children %}
+
 {{ obj.name }}
 {{ "=" * obj.name|length }}
 
 .. py:module:: {{ obj.name }}
 
+{% endif %}
+
 {%- if obj.docstring %}
 
 .. autoapi-nested-parse::
+
    {{ obj.docstring|prepare_docstring|indent(3) }}
 
 {% endif %}

autoapi/toctree.py

@@ -21,7 +21,6 @@ def _build_toc_node(docname, anchor='anchor', text='test text', bullet=False):
                                 anchorname='#' + anchor, *[nodes.Text(text, text)])
     para = addnodes.compact_paragraph('', '', reference)
     ret_list = nodes.list_item('', para)
-
     return nodes.bullet_list('', ret_list) if bullet else ret_list