Rename viewcode_import to viewcode_follow_imported_members (refs: #4035)

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
 ----------

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,
+   If :confval:`viewcode_follow_imported_members` is True, or if the
-   or if the :event:`viewcode-find-source` event does not find source code
+   :event:`viewcode-find-source` event does not find source code for the given
-   for the given module,
+   module, ``viewcode`` will import the modules being linked to.  If any modules
-   ``viewcode`` will import the modules being linked to.
+   have side effects on import, these will be executed by ``viewcode`` when
-   If any modules have side effects on import, these will be
+   ``sphinx-build`` is run.
-   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

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

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)

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