From 3233bc0ac7a756bb5a7dc1ffe3189aeca9eab01d Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 27 Jun 2017 17:12:17 -0700 Subject: [PATCH 01/16] Fix templates to nest functions and use short names --- autoapi/templates/index.rst | 4 +--- autoapi/templates/python/function.rst | 2 +- autoapi/templates/python/module.rst | 1 + 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/autoapi/templates/index.rst b/autoapi/templates/index.rst index 0a80174..78bc84e 100644 --- a/autoapi/templates/index.rst +++ b/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 %} diff --git a/autoapi/templates/python/function.rst b/autoapi/templates/python/function.rst index 8412892..08aef29 100644 --- a/autoapi/templates/python/function.rst +++ b/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) }} diff --git a/autoapi/templates/python/module.rst b/autoapi/templates/python/module.rst index 40778a8..e9b1490 100644 --- a/autoapi/templates/python/module.rst +++ b/autoapi/templates/python/module.rst @@ -6,6 +6,7 @@ {%- if obj.docstring %} .. autoapi-nested-parse:: + {{ obj.docstring|prepare_docstring|indent(3) }} {% endif %} From efb541f78a0fa3e36411a6591f0c3194ee367db4 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 27 Jun 2017 17:12:47 -0700 Subject: [PATCH 02/16] Add ability to add API to top-level TOC. --- autoapi/extension.py | 36 +++++++++++++++++++++++------------- autoapi/mappers/base.py | 6 +++++- 2 files changed, 28 insertions(+), 14 deletions(-) diff --git a/autoapi/extension.py b/autoapi/extension.py index e4361a8..32340c1 100644 --- a/autoapi/extension.py +++ b/autoapi/extension.py @@ -112,30 +112,39 @@ 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 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 sphinx.version_info >= (1, 5): + 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) + ) + if sphinx.version_info > (1, 5): app.env.toctree.process_doc(app.env.docname, doctree) else: app.env.build_toc_from(app.env.docname, doctree) @@ -143,9 +152,9 @@ def doctree_read(app, doctree): 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') @@ -154,6 +163,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) diff --git a/autoapi/mappers/base.py b/autoapi/mappers/base.py index 6ec0dc4..4b5d23b 100644 --- a/autoapi/mappers/base.py +++ b/autoapi/mappers/base.py @@ -288,6 +288,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)) From 4428ecd6e86d1216664813fbe55559e9f0cf2cac Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Tue, 27 Jun 2017 17:40:34 -0700 Subject: [PATCH 03/16] Add ability to process Napolean docstrings. --- autoapi/mappers/base.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/autoapi/mappers/base.py b/autoapi/mappers/base.py index 4b5d23b..20e8834 100644 --- a/autoapi/mappers/base.py +++ b/autoapi/mappers/base.py @@ -8,6 +8,7 @@ from jinja2 import Environment, FileSystemLoader, TemplateNotFound from sphinx.util.console import darkgreen, bold from sphinx.util.osutil import ensuredir from sphinx.util.docstrings import prepare_docstring +from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring from ..settings import API_ROOT @@ -180,7 +181,10 @@ class SphinxMapperBase(object): ) def _wrapped_prepare(value): - return '\n'.join(prepare_docstring(value)) + preped_value = '\n'.join(prepare_docstring(value)) + numpy_value = str(NumpyDocstring(preped_value)) + final_value = str(GoogleDocstring(numpy_value)) + return final_value self.jinja_env.filters['prepare_docstring'] = _wrapped_prepare From 86a4de1668fff18a0b46d70efd7911304f916a78 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 10:45:54 -0700 Subject: [PATCH 04/16] =?UTF-8?q?Don=E2=80=99t=20show=20modules=20with=20n?= =?UTF-8?q?o=20content.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- autoapi/templates/python/module.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/autoapi/templates/python/module.rst b/autoapi/templates/python/module.rst index e9b1490..3b53929 100644 --- a/autoapi/templates/python/module.rst +++ b/autoapi/templates/python/module.rst @@ -1,8 +1,12 @@ +{% if obj.docstring or obj.children %} + {{ obj.name }} {{ "=" * obj.name|length }} .. py:module:: {{ obj.name }} +{% endif %} + {%- if obj.docstring %} .. autoapi-nested-parse:: From 7e7f42367deb69f13fc6c2f8e97f5e17757f1d3c Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 10:46:16 -0700 Subject: [PATCH 05/16] Fix Sphinx 1.3 --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index ea7dd36..c8cac6a 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] envlist = - py{27,34,35}-sphinx{13,14,15} + py{27,34,35}-sphinx{14,15} lint docs From 0e3e5df437ce68081d1538ce8b14c57817cd5772 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 10:57:38 -0700 Subject: [PATCH 06/16] Fix linting --- .travis.yml | 1 - autoapi/mappers/dotnet.py | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.travis.yml b/.travis.yml index 660e047..2d6fae6 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,7 +1,6 @@ language: python python: - 2.7 - - 3.4 - 3.5 - 3.6 sudo: false diff --git a/autoapi/mappers/dotnet.py b/autoapi/mappers/dotnet.py index 6fbb2a9..bf43f99 100644 --- a/autoapi/mappers/dotnet.py +++ b/autoapi/mappers/dotnet.py @@ -211,15 +211,15 @@ class DotNetSphinxMapper(SphinxMapperBase): # Clean out dead namespaces for key, ns in self.top_namespaces.copy().items(): - if len(ns.children) == 0: + if not ns.children: del self.top_namespaces[key] for key, ns in self.namespaces.items(): - if len(ns.children) == 0: + if not ns.children: del self.namespaces[key] def output_rst(self, root, source_suffix): - if not len(self.objects): + if not self.objects: raise ExtensionError("No API objects exist. Can't continue") for id, obj in self.objects.items(): From fc6d7425e8fe848a54e0af514948f5e0662ec3fe Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 10:58:59 -0700 Subject: [PATCH 07/16] More lint fixing --- prospector.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/prospector.yml b/prospector.yml index b639915..887f20e 100644 --- a/prospector.yml +++ b/prospector.yml @@ -15,6 +15,7 @@ pylint: max-line-length: 100 disable: - interface-not-implemented + - arguments-differ mccabe: run: false From 2a79eb0dd4f12aaeee958f96aaa78f08a585d663 Mon Sep 17 00:00:00 2001 From: Anthony Johnson Date: Thu, 29 Jun 2017 12:27:46 -0700 Subject: [PATCH 08/16] Upgrade testing Conflicts: tox.ini --- .travis.yml | 8 ++++---- tox.ini | 14 +++++++++++--- 2 files changed, 15 insertions(+), 7 deletions(-) diff --git a/.travis.yml b/.travis.yml index 2d6fae6..73d28df 100644 --- a/.travis.yml +++ b/.travis.yml @@ -6,10 +6,10 @@ python: sudo: false matrix: include: - - python: 2.7 - script: tox -e docs - - python: 2.7 - script: tox -e lint + - python: 3.6 + env: TOXENV=docs + - python: 3.6 + env: TOXENV=lint install: - pip install tox-travis script: diff --git a/tox.ini b/tox.ini index c8cac6a..5baaa46 100644 --- a/tox.ini +++ b/tox.ini @@ -1,9 +1,16 @@ [tox] envlist = - py{27,34,35}-sphinx{14,15} + py{27,34,35,36}-sphinx{13,14,15} lint docs +[travis] +python = + 2.7: py27 + 3.4: py34 + 3.5: py35 + 3.6: py36 + [testenv] setenv = LANG=C @@ -12,12 +19,13 @@ deps = -r{toxinidir}/requirements.txt mock sphinx14: Sphinx<1.5 sphinx15: Sphinx<1.6 + sphinx16: Sphinx<1.7 commands = py.test {posargs} [testenv:docs] deps = - Sphinx==1.5 + Sphinx==1.6 sphinx_rtd_theme changedir = {toxinidir}/docs commands = @@ -30,4 +38,4 @@ commands = prospector \ --profile-path={toxinidir} \ --profile=prospector \ - --die-on-tool-error + --die-on-tool-error {posargs} From ed57a216ec8f82ac8d702a740a5108a29dea4cfd Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 12:58:40 -0700 Subject: [PATCH 09/16] Fix lint --- autoapi/toctree.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/autoapi/toctree.py b/autoapi/toctree.py index f04e87c..4e17dd1 100644 --- a/autoapi/toctree.py +++ b/autoapi/toctree.py @@ -23,8 +23,7 @@ def _build_toc_node(docname, anchor='anchor', text='test text', bullet=False): ret_list = nodes.list_item('', para) if not bullet: return ret_list - else: - return nodes.bullet_list('', ret_list) + return nodes.bullet_list('', ret_list) def _traverse_parent(node, objtypes): From 8c1016f8c7c46aa97b713e68d7e4c2eb761b464e Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 14:37:59 -0700 Subject: [PATCH 10/16] Fix linting --- autoapi/mappers/base.py | 2 +- autoapi/mappers/dotnet.py | 2 +- autoapi/mappers/go.py | 2 +- autoapi/mappers/javascript.py | 2 +- autoapi/mappers/python.py | 6 +++--- prospector.yml | 1 - 6 files changed, 7 insertions(+), 8 deletions(-) diff --git a/autoapi/mappers/base.py b/autoapi/mappers/base.py index 20e8834..7ddf602 100644 --- a/autoapi/mappers/base.py +++ b/autoapi/mappers/base.py @@ -268,7 +268,7 @@ class SphinxMapperBase(object): for obj in self.create_class(data, options=options, path=path): self.add_object(obj) - def create_class(self, obj, options=None, path=None, **kwargs): + def create_class(self, data, options=None, **kwargs): ''' Create class object. diff --git a/autoapi/mappers/dotnet.py b/autoapi/mappers/dotnet.py index bf43f99..f88d261 100644 --- a/autoapi/mappers/dotnet.py +++ b/autoapi/mappers/dotnet.py @@ -124,7 +124,7 @@ class DotNetSphinxMapper(SphinxMapperBase): return None # Subclassed to iterate over items - def map(self, options=None, **kwargs): + def map(self, options=None): '''Trigger find of serialized sources and build objects''' for path, data in self.paths.items(): references = data.get('references', []) diff --git a/autoapi/mappers/go.py b/autoapi/mappers/go.py index bd5871f..460a5fd 100644 --- a/autoapi/mappers/go.py +++ b/autoapi/mappers/go.py @@ -13,7 +13,7 @@ class GoSphinxMapper(SphinxMapperBase): :param app: Sphinx application passed in as part of the extension ''' - def load(self, patterns, dirs, ignore=None): + def load(self, patterns, dirs, ignore=None, **kwargs): ''' Load objects from the filesystem into the ``paths`` dictionary. diff --git a/autoapi/mappers/javascript.py b/autoapi/mappers/javascript.py index bc74e26..6e12a70 100644 --- a/autoapi/mappers/javascript.py +++ b/autoapi/mappers/javascript.py @@ -32,7 +32,7 @@ class JavaScriptSphinxMapper(SphinxMapperBase): return None # Subclassed to iterate over items - def map(self, options=None, **kwargs): + def map(self, options=None): '''Trigger find of serialized sources and build objects''' for path, data in self.paths.items(): for item in data: diff --git a/autoapi/mappers/python.py b/autoapi/mappers/python.py index 33e7061..f9cba9c 100644 --- a/autoapi/mappers/python.py +++ b/autoapi/mappers/python.py @@ -25,14 +25,14 @@ class PythonSphinxMapper(SphinxMapperBase): :param app: Sphinx application passed in as part of the extension """ - def load(self, patterns, dirs, **kwargs): + def load(self, patterns, dirs, ignore=None, **kwargs): """Load objects from the filesystem into the ``paths`` dictionary Also include an attribute on the object, ``relative_path`` which is the shortened, relative path the package/module """ for dir_ in dirs: - for path in self.find_files(patterns=patterns, dirs=[dir_], **kwargs): + for path in self.find_files(patterns=patterns, dirs=[dir_], ignore=ignore, **kwargs): data = self.read_file(path=path) data.relative_path = os.path.relpath(path, dir_) if data: @@ -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 diff --git a/prospector.yml b/prospector.yml index 887f20e..b639915 100644 --- a/prospector.yml +++ b/prospector.yml @@ -15,7 +15,6 @@ pylint: max-line-length: 100 disable: - interface-not-implemented - - arguments-differ mccabe: run: false From 21a82718abb5090c20abd6db7594fc11947f5e38 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 14:48:06 -0700 Subject: [PATCH 11/16] Fix linting --- autoapi/mappers/base.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/autoapi/mappers/base.py b/autoapi/mappers/base.py index 7ddf602..d81b408 100644 --- a/autoapi/mappers/base.py +++ b/autoapi/mappers/base.py @@ -265,7 +265,7 @@ 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, **kwargs): From 3181228616d6dfe7f5dd9e60a2b3503b35e1076a Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 14:52:12 -0700 Subject: [PATCH 12/16] Fix version testing --- tox.ini | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 5baaa46..8679f9f 100644 --- a/tox.ini +++ b/tox.ini @@ -1,6 +1,6 @@ [tox] envlist = - py{27,34,35,36}-sphinx{13,14,15} + py{27,34,35,36}-sphinx{13,14,15,16} lint docs @@ -17,6 +17,7 @@ setenv = deps = -r{toxinidir}/requirements.txt pytest mock + sphinx13: Sphinx<1.4 sphinx14: Sphinx<1.5 sphinx15: Sphinx<1.6 sphinx16: Sphinx<1.7 From 3875cf495dad96a9c0f9b84b0b5186bd71e91eef Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 15:10:06 -0700 Subject: [PATCH 13/16] Fix noting the toctree --- autoapi/extension.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/autoapi/extension.py b/autoapi/extension.py index 32340c1..4401690 100644 --- a/autoapi/extension.py +++ b/autoapi/extension.py @@ -120,6 +120,7 @@ def doctree_read(app, doctree): 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]) @@ -145,7 +146,7 @@ def doctree_read(app, doctree): darkgreen('Adding AutoAPI TOCTree [%s] to index.rst' % toc_entry) ) if sphinx.version_info > (1, 5): - app.env.toctree.process_doc(app.env.docname, doctree) + app.env.note_toctree(app.env.docname, root) else: app.env.build_toc_from(app.env.docname, doctree) From 0bd813db8c05f5707ad181171a531a23c400d41e Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 29 Jun 2017 15:18:53 -0700 Subject: [PATCH 14/16] More cleanup --- tox.ini | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tox.ini b/tox.ini index 8679f9f..a9064b9 100644 --- a/tox.ini +++ b/tox.ini @@ -26,7 +26,7 @@ commands = [testenv:docs] deps = - Sphinx==1.6 + Sphinx>=1.6 sphinx_rtd_theme changedir = {toxinidir}/docs commands = From d803b28d00fbcb05ef10b9357e9bc4fb3aeba6ee Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Mon, 6 Nov 2017 18:39:20 -0700 Subject: [PATCH 15/16] Kill janky napolean overlay --- autoapi/mappers/base.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/autoapi/mappers/base.py b/autoapi/mappers/base.py index c025ffd..ef273bc 100644 --- a/autoapi/mappers/base.py +++ b/autoapi/mappers/base.py @@ -9,7 +9,6 @@ import sphinx.util from sphinx.util.console import darkgreen, bold from sphinx.util.osutil import ensuredir from sphinx.util.docstrings import prepare_docstring -from sphinx.ext.napoleon.docstring import GoogleDocstring, NumpyDocstring from ..settings import API_ROOT @@ -182,10 +181,7 @@ class SphinxMapperBase(object): ) def _wrapped_prepare(value): - preped_value = '\n'.join(prepare_docstring(value)) - numpy_value = str(NumpyDocstring(preped_value)) - final_value = str(GoogleDocstring(numpy_value)) - return final_value + return '\n'.join(prepare_docstring(value)) self.jinja_env.filters['prepare_docstring'] = _wrapped_prepare From e5cce2c7dd05d0cf7855e7550cb4bd9e6f2eca90 Mon Sep 17 00:00:00 2001 From: Eric Holscher Date: Thu, 9 Nov 2017 10:56:42 -0700 Subject: [PATCH 16/16] Fix lint --- autoapi/mappers/go.py | 4 ++-- autoapi/mappers/javascript.py | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/autoapi/mappers/go.py b/autoapi/mappers/go.py index f27f5ac..bd5871f 100644 --- a/autoapi/mappers/go.py +++ b/autoapi/mappers/go.py @@ -13,7 +13,7 @@ class GoSphinxMapper(SphinxMapperBase): :param app: Sphinx application passed in as part of the extension ''' - def load(self, patterns, dirs, ignore=None, **kwargs): + def load(self, patterns, dirs, ignore=None): ''' Load objects from the filesystem into the ``paths`` dictionary. @@ -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: diff --git a/autoapi/mappers/javascript.py b/autoapi/mappers/javascript.py index c7ea9ee..6e12a70 100644 --- a/autoapi/mappers/javascript.py +++ b/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: