diff --git a/CHANGES b/CHANGES index 60a0c6f4f..d2d36dd23 100644 --- a/CHANGES +++ b/CHANGES @@ -29,6 +29,8 @@ Incompatible changes * #4811: The files under :confval:`html_static_path` are excluded from source files. * latex: Use ``\sphinxcite`` for citation references instead ``\hyperref`` +* The config value ``viewcode_import`` is renamed to + :confval:`viewcode_follow_imported_members` (refs: #4035) Deprecated ---------- diff --git a/doc/ext/viewcode.rst b/doc/ext/viewcode.rst index 9ea1262fa..7571c985d 100644 --- a/doc/ext/viewcode.rst +++ b/doc/ext/viewcode.rst @@ -17,12 +17,11 @@ from the source to the description will also be inserted. .. warning:: - If :confval:`viewcode_import` is True, - or if the :event:`viewcode-find-source` event does not find source code - for the given module, - ``viewcode`` will import the modules being linked to. - If any modules have side effects on import, these will be - executed by ``viewcode`` when ``sphinx-build`` is run. + If :confval:`viewcode_follow_imported_members` is True, or if the + :event:`viewcode-find-source` event does not find source code for the given + module, ``viewcode`` will import the modules being linked to. If any modules + have side effects on import, these will be executed by ``viewcode`` when + ``sphinx-build`` is run. If you document scripts (as opposed to library modules), make sure their main routine is protected by a ``if __name__ == '__main__'`` condition. @@ -34,7 +33,7 @@ support this extension (see :confval:`viewcode_enable_epub`). There is an additional config value: -.. confval:: viewcode_import +.. confval:: viewcode_follow_imported_members If this is ``True``, viewcode extension will follow alias objects that imported from another module such as functions, classes and attributes. @@ -43,6 +42,9 @@ There is an additional config value: .. versionadded:: 1.3 + .. versionchanged:: 1.8 + Renamed from ``viewcode_import`` to ``viewcode_follow_imported_members``. + .. confval:: viewcode_enable_epub If this is ``True``, viewcode extension is also enabled even if you use diff --git a/doc/extdev/index.rst b/doc/extdev/index.rst index dfe8dbaf0..6178b106c 100644 --- a/doc/extdev/index.rst +++ b/doc/extdev/index.rst @@ -126,6 +126,11 @@ The following is a list of deprecated interface. - 4.0 - :meth:`~sphinx.application.Sphinx.add_css_file()` + * - ``viewcode_import`` (config value) + - 1.8 + - 3.0 + - :confval:`viewcode_follow_imported_members` + * - ``sphinx.writers.latex.Table.caption_footnotetexts`` - 1.8 - 3.0 diff --git a/sphinx/ext/viewcode.py b/sphinx/ext/viewcode.py index f1ae4bf57..6d3c3c1c0 100644 --- a/sphinx/ext/viewcode.py +++ b/sphinx/ext/viewcode.py @@ -10,12 +10,14 @@ """ import traceback +import warnings from docutils import nodes from six import iteritems, text_type import sphinx from sphinx import addnodes +from sphinx.deprecation import RemovedInSphinx30Warning from sphinx.locale import _ from sphinx.pycode import ModuleAnalyzer from sphinx.util import get_full_modname, logging, status_iterator @@ -25,6 +27,7 @@ if False: # For type annotation from typing import Any, Dict, Iterable, Iterator, Set, Tuple # NOQA from sphinx.application import Sphinx # NOQA + from sphinx.config import Config # NOQA from sphinx.environment import BuildEnvironment # NOQA logger = logging.getLogger(__name__) @@ -100,7 +103,7 @@ def doctree_read(app, doctree): modname = signode.get('module') fullname = signode.get('fullname') refname = modname - if env.config.viewcode_import: + if env.config.viewcode_follow_imported_members: modname = _get_full_modname(app, modname, fullname) if not modname: continue @@ -239,10 +242,19 @@ def collect_pages(app): yield ('_modules/index', context, 'page.html') +def migrate_viewcode_import(app, config): + # type: (Sphinx, Config) -> None + if config.viewcode_import is not None: + warnings.warn('viewcode_import was renamed to viewcode_follow_imported_members. ' + 'Please update your configuration.', + RemovedInSphinx30Warning) + + def setup(app): # type: (Sphinx) -> Dict[unicode, Any] - app.add_config_value('viewcode_import', True, False) + app.add_config_value('viewcode_import', None, False) app.add_config_value('viewcode_enable_epub', False, False) + app.add_config_value('viewcode_follow_imported_members', True, False) app.connect('doctree-read', doctree_read) app.connect('env-merge-info', env_merge_info) app.connect('html-collect-pages', collect_pages) diff --git a/tests/roots/test-ext-viewcode-find/conf.py b/tests/roots/test-ext-viewcode-find/conf.py index c23c0762c..3f5ddc175 100644 --- a/tests/roots/test-ext-viewcode-find/conf.py +++ b/tests/roots/test-ext-viewcode-find/conf.py @@ -6,4 +6,4 @@ import sys extensions = ['sphinx.ext.viewcode'] master_doc = 'index' exclude_patterns = ['_build'] -viewcode_import = False +viewcode_follow_imported_members = False