[autosummary] address code review

doc/usage/extensions/autosummary.rst

@@ -25,9 +25,9 @@ The :mod:`sphinx.ext.autosummary` extension does this in three parts:
    These files by default contain only the corresponding
    :mod:`sphinx.ext.autodoc` directive, but can be customized with templates.
 
-3. Optionally, the new :confval:`autosummary_recursion_limit` config value can be
+3. Optionally, :confval:`autosummary_depth_limit` config value can be
-   used to generate "stub" files recursively for packages. Warning: this will overwrite
+   used to generate "stub" files of modules and sub-packages for packages
-   existing files for packages.
+   under the :rst:dir:`autosummary` directive.
 
 .. rst:directive:: autosummary
 
@@ -59,27 +59,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in three parts:
 
        .. currentmodule:: sphinx.ext.autosummary
 
-   When :confval:`autosummary_recursion_limit != 0`, the :rst:dir:`autosummary`
-   directive recursively generates stub ``.rst`` files for packages.
-
-   For example, ::
-
-       .. currentmodule:: sphinx
-
-       .. autosummary::
-
-          autosummary
-
-   produces a table like this:
-
-       .. currentmodule:: sphinx.ext
-
-       .. autosummary::
-
-          autosummary
-
-       .. currentmodule:: sphinx.ext.autosummary
-
    Autosummary preprocesses the docstrings and signatures with the same
    :event:`autodoc-process-docstring` and :event:`autodoc-process-signature`
    hooks as :mod:`~sphinx.ext.autodoc`.
@@ -169,17 +148,16 @@ also use these config values:
    The new files will be placed in the directories specified in the
    ``:toctree:`` options of the directives.
 
-Packages can be explored recursively when generating stub pages.
+.. confval:: autosummary_depth_limit
 
-.. confval:: autosummary_recursion_limit
+   Integer that determines the maximal depth (starting from root) when adding
+   modules and sub-packages of packages.
    
-   Integer that determines the maximal recursion depth.
+    - ``autosummary_depth_limit = -1``: no limit
+    - ``autosummary_depth_limit = 0``: disable adding modules and sub-packages (default)
+    - ``autosummary_depth_limit > 0``: limited depth starting from root
 
-    - ``autosummary_recursion_limit = -1``: no recursion limit
+   .. versionadded:: 2.1
-    - ``autosummary_recursion_limit = 0``: disable recursion (default)
-    - ``autosummary_recursion_limit > 0``: limit recursion depth
-
-   .. versionadded:: 2.0
 
 .. confval:: autosummary_mock_imports
 
@@ -284,14 +262,14 @@ The following variables available in the templates:
    List containing names of "public" modules in the package.  Only available for
    modules that are packages.
 
-   .. versionadded:: 2.0
+   .. versionadded:: 2.1
 
 .. data:: packages
 
    List containing names of "public" sub-packages in the package.  Only available for
    modules that are packages.
 
-   .. versionadded:: 2.0
+   .. versionadded:: 2.1
 
 Additionally, the following filters are available
 

sphinx/__main__.py

@@ -12,5 +12,4 @@ import sys
 
 from sphinx.cmd.build import main
 
-if __name__ == "__main__":
 sys.exit(main(sys.argv[1:]))

sphinx/ext/autosummary/__init__.py

@@ -733,14 +733,13 @@ def process_generate_options(app):
                           'But your source_suffix does not contain .rst. Skipped.'))
         return
 
-    recursion_limit = app.config.autosummary_recursion_limit
+    depth_limit = app.config.autosummary_depth_limit
 
     with mock(app.config.autosummary_mock_imports):
         generate_autosummary_docs(genfiles, builder=app.builder,
                                   warn=logger.warning, info=logger.info,
                                   suffix=suffix, base_path=app.srcdir,
-                                  recursion_limit=recursion_limit,
+                                  app=app, depth_limit=depth_limit)
-                                  app=app)
 
 
 def setup(app):
@@ -764,7 +763,7 @@ def setup(app):
     app.connect('doctree-read', process_autosummary_toc)
     app.connect('builder-inited', process_generate_options)
     app.add_config_value('autosummary_generate', [], True, [bool])
-    app.add_config_value('autosummary_recursion_limit', 0, True, [int])
+    app.add_config_value('autosummary_depth_limit', 0, 'env', [int])
     app.add_config_value('autosummary_mock_imports',
                          lambda config: config.autodoc_mock_imports, 'env')
     return {'version': sphinx.__display_version__, 'parallel_read_safe': True}

sphinx/ext/autosummary/generate.py

@@ -98,8 +98,8 @@ def generate_autosummary_docs(sources,                 # type: List[str]
                               builder=None,            # type: Builder
                               template_dir=None,       # type: str
                               imported_members=False,  # type: bool
-                              recursion_limit=0,       # type: int
+                              app=None,                # type: Any
-                              app=None                 # type: Any
+                              depth_limit=0,           # type: int
                               ):
     # type: (...) -> None
     showed_sources = list(sorted(sources))
@@ -163,20 +163,20 @@ def generate_autosummary_docs(sources,                 # type: List[str]
         ispackage = hasattr(obj, '__path__')
         if ispackage:
             depth = len(name.split('.')) - 1
-            recurse_package = depth < recursion_limit or recursion_limit < 0
+            add_package_children = depth < depth_limit or depth_limit < 0
-            if recurse_package:
+            if add_package_children:
                 info(__('[autosummary] add modules/packages from %s') % repr(name))
         else:
-            recurse_package = False
+            add_package_children = False
 
         fn = os.path.join(path, name + suffix)
 
         # Skip it if it exists and not a package.
         if os.path.isfile(fn):
-            if ispackage and recursion_limit != 0:
+            if ispackage and depth_limit != 0:
                 # Overwrite the file because submodules/packages
                 # could have been added/removed from the package
-                # or the recursion limit might have changed.
+                # or the depth limit might have changed.
                 # Warning: this file could have been created by the user
                 # in which case it is lost.
                 warn('[autosummary] overwriting docs of package %s' % (repr(name)))
@@ -242,7 +242,7 @@ def generate_autosummary_docs(sources,                 # type: List[str]
                     get_members(obj, 'class', imported=imported_members)
                 ns['exceptions'], ns['all_exceptions'] = \
                     get_members(obj, 'exception', imported=imported_members)
-                if recurse_package:
+                if add_package_children:
                     ns['modules'], ns['all_modules'] = \
                         get_package_members(obj, 'module')
                     ns['packages'], ns['all_packages'] = \
@@ -283,7 +283,7 @@ def generate_autosummary_docs(sources,                 # type: List[str]
                                   base_path=base_path, builder=builder,
                                   template_dir=template_dir,
                                   imported_members=imported_members,
-                                  recursion_limit=recursion_limit,
+                                  depth_limit=depth_limit,
                                   app=app)
 
 
@@ -465,7 +465,7 @@ def main(argv=sys.argv[1:]):
                               '.' + args.suffix,
                               template_dir=args.templates,
                               imported_members=args.imported_members,
-                              recursion_limit=args.recursion_limit,
+                              depth_limit=args.depth_limit,
                               app=app)
 
 

tests/roots/test-ext-autosummary-package/conf.py

@@ -5,6 +5,3 @@ sys.path.insert(0, os.path.abspath('.'))
 
 extensions = ['sphinx.ext.autosummary']
 autosummary_generate = True
-
-# The suffix of source filenames.
-source_suffix = '.rst'

tests/test_ext_autosummary.py

@@ -202,12 +202,12 @@ def test_autosummary_generate(app, status, warning):
 def _assert_autosummary_generate_package(app):
     app.builder.build_all()
 
-    # Prepare recursion
+    # Prepare package exploration
     max_depth = 3
-    recursion_limit = app.config.autosummary_recursion_limit
+    depth_limit = app.config.autosummary_depth_limit
-    assert recursion_limit <= max_depth
+    assert depth_limit <= max_depth
     
-    unlimited = recursion_limit < 0
+    unlimited = depth_limit < 0
 
     # All packages, modules and classes have the same name
     package_name = 'package'
@@ -270,7 +270,7 @@ def _assert_autosummary_generate_package(app):
     modules = []
     directories = []
     while True:
-        limit_reached = (depth == recursion_limit) and not unlimited
+        limit_reached = (depth == depth_limit) and not unlimited
         last_package = depth == max_depth
         has_packages = not limit_reached and not last_package
         has_modules = not limit_reached
@@ -319,15 +319,15 @@ def test_autosummary_generate_package(make_app, app_params):
     import sphinx.ext.autosummary.generate
     logger = sphinx.ext.autosummary.logger
     args, kwargs = app_params
-    confoverrides = {'autosummary_recursion_limit': 0}
+    confoverrides = {'autosummary_depth_limit': 0}
     kwargs['confoverrides'] = confoverrides
-    # Try different recursion limits
+    # Try different depth limits
     # TODO: going from higher to lower limit
     # currently fails because generated files
     # are not deleted
     for limit in 0, 1, 2, 3, -1:
-        logger.info('autosummary_recursion_limit = {}'.format(limit))
+        logger.info('autosummary_depth_limit = {}'.format(limit))
-        confoverrides['autosummary_recursion_limit'] = limit
+        confoverrides['autosummary_depth_limit'] = limit
         app = make_app(*args, **kwargs)
         _assert_autosummary_generate_package(app)
         # Cleanup