diff options
author | Georg Brandl <georg@python.org> | 2014-09-22 11:06:42 +0200 |
---|---|---|
committer | Georg Brandl <georg@python.org> | 2014-09-22 11:06:42 +0200 |
commit | 5507173002b83324bb818ecf85f94a3c1bb95382 (patch) | |
tree | 8cca6002fbe256402ef15c92b643715cef01954b | |
parent | ebdd9c20182aac70e050789670c15f8bb761758e (diff) | |
download | sphinx-5507173002b83324bb818ecf85f94a3c1bb95382.tar.gz |
Change extension setup() return value to a dictionary of metadata.
This makes it possible to introduce more metadata values later.
-rw-r--r-- | doc/extdev/index.rst | 20 | ||||
-rw-r--r-- | doc/extdev/tutorial.rst | 2 | ||||
-rw-r--r-- | sphinx/application.py | 18 | ||||
-rw-r--r-- | sphinx/ext/autodoc.py | 2 | ||||
-rw-r--r-- | sphinx/ext/autosummary/__init__.py | 2 | ||||
-rw-r--r-- | sphinx/ext/coverage.py | 2 | ||||
-rw-r--r-- | sphinx/ext/doctest.py | 2 | ||||
-rw-r--r-- | sphinx/ext/extlinks.py | 2 | ||||
-rw-r--r-- | sphinx/ext/graphviz.py | 2 | ||||
-rw-r--r-- | sphinx/ext/ifconfig.py | 2 | ||||
-rw-r--r-- | sphinx/ext/inheritance_diagram.py | 2 | ||||
-rw-r--r-- | sphinx/ext/intersphinx.py | 2 | ||||
-rw-r--r-- | sphinx/ext/jsmath.py | 2 | ||||
-rw-r--r-- | sphinx/ext/linkcode.py | 2 | ||||
-rw-r--r-- | sphinx/ext/mathjax.py | 2 | ||||
-rw-r--r-- | sphinx/ext/napoleon/__init__.py | 2 | ||||
-rw-r--r-- | sphinx/ext/pngmath.py | 2 | ||||
-rw-r--r-- | sphinx/ext/todo.py | 2 | ||||
-rw-r--r-- | sphinx/ext/viewcode.py | 2 | ||||
-rw-r--r-- | sphinx/util/__init__.py | 2 |
20 files changed, 43 insertions, 31 deletions
diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index a82f33a8..481688ac 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -18,15 +18,25 @@ imports this module and executes its ``setup()`` function, which in turn notifies Sphinx of everything the extension offers -- see the extension tutorial for examples. -.. versionadded:: 1.3 - The ``setup()`` function can return a string, this is treated by Sphinx as - the version of the extension and used for informational purposes such as the - traceback file when an exception occurs. - The configuration file itself can be treated as an extension if it contains a ``setup()`` function. All other extensions to load must be listed in the :confval:`extensions` configuration value. +Extension metadata +------------------ + +.. versionadded:: 1.3 + +The ``setup()`` function can return a dictionary. This is treated by Sphinx +as metadata of the extension. Metadata keys currently recognized are: + +* ``'version'``: a string that identifies the extension version. It is used for + extension version requirement checking (see :confval:`needs_extensions`) and + informational purposes. If not given, ``"unknown version"`` is substituted. + +APIs used for writing extensions +-------------------------------- + .. toctree:: tutorial diff --git a/doc/extdev/tutorial.rst b/doc/extdev/tutorial.rst index 8f1773cd..e7912406 100644 --- a/doc/extdev/tutorial.rst +++ b/doc/extdev/tutorial.rst @@ -162,7 +162,7 @@ new Python module called :file:`todo.py` and add the setup function:: app.connect('doctree-resolved', process_todo_nodes) app.connect('env-purge-doc', purge_todos) - return '0.1' # identifies the version of our extension + return {'version': '0.1'} # identifies the version of our extension The calls in this function refer to classes and functions not yet written. What the individual calls do is the following: diff --git a/sphinx/application.py b/sphinx/application.py index a1cc4c4f..b1af74bf 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -73,7 +73,7 @@ class Sphinx(object): self.verbosity = verbosity self.next_listener_id = 0 self._extensions = {} - self._extension_versions = {} + self._extension_metadata = {} self._listeners = {} self.domains = BUILTIN_DOMAINS.copy() self.builderclasses = BUILTIN_BUILDERS.copy() @@ -129,7 +129,7 @@ class Sphinx(object): self.setup_extension(extension) # the config file itself can be an extension if self.config.setup: - # py31 doesn't have 'callable' function for bellow check + # py31 doesn't have 'callable' function for below check if hasattr(self.config.setup, '__call__'): self.config.setup(self) else: @@ -157,7 +157,7 @@ class Sphinx(object): 'version requirement for extension %s, but it is ' 'not loaded' % extname) continue - has_ver = self._extension_versions[extname] + has_ver = self._extension_metadata[extname]['version'] if has_ver == 'unknown version' or needs_ver > has_ver: raise VersionRequirementError( 'This project needs the extension %s at least in ' @@ -367,20 +367,22 @@ class Sphinx(object): if not hasattr(mod, 'setup'): self.warn('extension %r has no setup() function; is it really ' 'a Sphinx extension module?' % extension) - version = None + ext_meta = None else: try: - version = mod.setup(self) + ext_meta = mod.setup(self) except VersionRequirementError as err: # add the extension name to the version required raise VersionRequirementError( 'The %s extension used by this project needs at least ' 'Sphinx v%s; it therefore cannot be built with this ' 'version.' % (extension, err)) - if version is None: - version = 'unknown version' + if ext_meta is None: + ext_meta = {} + if not ext_meta.get('version'): + ext_meta['version'] = 'unknown version' self._extensions[extension] = mod - self._extension_versions[extension] = version + self._extension_metadata[extension] = ext_meta def require_sphinx(self, version): # check the Sphinx version if requested diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 9b7834cb..113a36d5 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1515,7 +1515,7 @@ def setup(app): app.add_event('autodoc-process-signature') app.add_event('autodoc-skip-member') - return sphinx.__version__ + return {'version': sphinx.__version__} class testcls: diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index cbdc16e5..aff9e005 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -570,4 +570,4 @@ def setup(app): app.connect('doctree-read', process_autosummary_toc) app.connect('builder-inited', process_generate_options) app.add_config_value('autosummary_generate', [], True) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py index 49dc02f4..841815e7 100644 --- a/sphinx/ext/coverage.py +++ b/sphinx/ext/coverage.py @@ -265,4 +265,4 @@ def setup(app): app.add_config_value('coverage_ignore_c_items', {}, False) app.add_config_value('coverage_write_headline', True, False) app.add_config_value('coverage_skip_undoc_in_source', False, False) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index 2e2a98b1..7a90ee16 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -443,4 +443,4 @@ def setup(app): app.add_config_value('doctest_test_doctest_blocks', 'default', False) app.add_config_value('doctest_global_setup', '', False) app.add_config_value('doctest_global_cleanup', '', False) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/extlinks.py b/sphinx/ext/extlinks.py index c0cfbcd2..2549de90 100644 --- a/sphinx/ext/extlinks.py +++ b/sphinx/ext/extlinks.py @@ -59,4 +59,4 @@ def setup_link_roles(app): def setup(app): app.add_config_value('extlinks', {}, 'env') app.connect('builder-inited', setup_link_roles) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py index b4b8bc27..05550e2a 100644 --- a/sphinx/ext/graphviz.py +++ b/sphinx/ext/graphviz.py @@ -323,4 +323,4 @@ def setup(app): app.add_config_value('graphviz_dot', 'dot', 'html') app.add_config_value('graphviz_dot_args', [], 'html') app.add_config_value('graphviz_output_format', 'png', 'html') - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/ifconfig.py b/sphinx/ext/ifconfig.py index ab15e1e1..f5d729f2 100644 --- a/sphinx/ext/ifconfig.py +++ b/sphinx/ext/ifconfig.py @@ -73,4 +73,4 @@ def setup(app): app.add_node(ifconfig) app.add_directive('ifconfig', IfConfig) app.connect('doctree-resolved', process_ifconfig_nodes) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/inheritance_diagram.py b/sphinx/ext/inheritance_diagram.py index fabdd44b..a6537d1f 100644 --- a/sphinx/ext/inheritance_diagram.py +++ b/sphinx/ext/inheritance_diagram.py @@ -408,4 +408,4 @@ def setup(app): app.add_config_value('inheritance_graph_attrs', {}, False), app.add_config_value('inheritance_node_attrs', {}, False), app.add_config_value('inheritance_edge_attrs', {}, False), - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py index b429ab9d..67e8b860 100644 --- a/sphinx/ext/intersphinx.py +++ b/sphinx/ext/intersphinx.py @@ -282,4 +282,4 @@ def setup(app): app.add_config_value('intersphinx_cache_limit', 5, False) app.connect('missing-reference', missing_reference) app.connect('builder-inited', load_mappings) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/jsmath.py b/sphinx/ext/jsmath.py index 897d87ac..765dfb33 100644 --- a/sphinx/ext/jsmath.py +++ b/sphinx/ext/jsmath.py @@ -57,4 +57,4 @@ def setup(app): mathbase_setup(app, (html_visit_math, None), (html_visit_displaymath, None)) app.add_config_value('jsmath_path', '', False) app.connect('builder-inited', builder_inited) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/linkcode.py b/sphinx/ext/linkcode.py index bbb0698c..a0b4d0da 100644 --- a/sphinx/ext/linkcode.py +++ b/sphinx/ext/linkcode.py @@ -71,4 +71,4 @@ def doctree_read(app, doctree): def setup(app): app.connect('doctree-read', doctree_read) app.add_config_value('linkcode_resolve', None, '') - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/mathjax.py b/sphinx/ext/mathjax.py index fd5c5f1d..c86a982d 100644 --- a/sphinx/ext/mathjax.py +++ b/sphinx/ext/mathjax.py @@ -69,4 +69,4 @@ def setup(app): app.add_config_value('mathjax_inline', [r'\(', r'\)'], 'html') app.add_config_value('mathjax_display', [r'\[', r'\]'], 'html') app.connect('builder-inited', builder_inited) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/napoleon/__init__.py b/sphinx/ext/napoleon/__init__.py index 554162ed..13350249 100644 --- a/sphinx/ext/napoleon/__init__.py +++ b/sphinx/ext/napoleon/__init__.py @@ -256,7 +256,7 @@ def setup(app): for name, (default, rebuild) in iteritems(Config._config_values): app.add_config_value(name, default, rebuild) - return sphinx.__version__ + return {'version': sphinx.__version__} def _process_docstring(app, what, name, obj, options, lines): diff --git a/sphinx/ext/pngmath.py b/sphinx/ext/pngmath.py index ee108d16..342b1bd8 100644 --- a/sphinx/ext/pngmath.py +++ b/sphinx/ext/pngmath.py @@ -246,4 +246,4 @@ def setup(app): app.add_config_value('pngmath_latex_preamble', '', 'html') app.add_config_value('pngmath_add_tooltips', True, 'html') app.connect('build-finished', cleanup_tempdir) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index d70617b9..7a369911 100644 --- a/sphinx/ext/todo.py +++ b/sphinx/ext/todo.py @@ -172,4 +172,4 @@ def setup(app): app.connect('doctree-read', process_todos) app.connect('doctree-resolved', process_todo_nodes) app.connect('env-purge-doc', purge_todos) - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index 3653a2da..25243d3c 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -204,4 +204,4 @@ def setup(app): app.connect('missing-reference', missing_reference) #app.add_config_value('viewcode_include_modules', [], 'env') #app.add_config_value('viewcode_exclude_modules', [], 'env') - return sphinx.__version__ + return {'version': sphinx.__version__} diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 56cd3888..72485570 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -205,7 +205,7 @@ def save_traceback(app): if isinstance(modfile, bytes): modfile = modfile.decode(fs_encoding, 'replace') os.write(fd, ('# %s (%s) from %s\n' % ( - extname, app._extension_versions[extname], + extname, app._extension_metadata[extname]['version'], modfile)).encode('utf-8')) os.write(fd, exc.encode('utf-8')) os.close(fd) |