From 7671bcc23bbcacc0c2dd0e927477f6e6d11b93eb Mon Sep 17 00:00:00 2001 From: Takeshi KOMIYA Date: Tue, 21 Apr 2020 23:22:05 +0900 Subject: [PATCH] Remove autosummary_recursive configuration Now autosummary directive has :recursive: option to enable the recursive feature individually. So the configuration is no longer needed. --- doc/usage/extensions/autosummary.rst | 16 +--------------- sphinx/ext/autosummary/__init__.py | 4 +--- sphinx/ext/autosummary/generate.py | 12 +++--------- tests/test_ext_autosummary.py | 26 ++------------------------ 4 files changed, 7 insertions(+), 51 deletions(-) diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 1a1b945d3..a1fb9f405 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -13,7 +13,7 @@ those output e.g. by Epydoc and other API doc generation tools. This is especially useful when your docstrings are long and detailed, and putting each one of them on a separate page makes them easier to read. -The :mod:`sphinx.ext.autosummary` extension does this in three parts: +The :mod:`sphinx.ext.autosummary` extension does this in two parts: 1. There is an :rst:dir:`autosummary` directive for generating summary listings that contain links to the documented items, and short summary blurbs @@ -25,10 +25,6 @@ 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 :confval:`autosummary_recursive` config value can be - used to generate "stub" files of modules and sub-packages for packages - under the :rst:dir:`autosummary` directive. - .. rst:directive:: autosummary Insert a table that contains links to documented items, and a short summary @@ -119,9 +115,6 @@ The :mod:`sphinx.ext.autosummary` extension does this in three parts: sphinx.environment.BuildEnvironment - It is needed to enable :confval:`autosummary_recursive` also to - use this option. - .. versionadded:: 3.1 @@ -180,13 +173,6 @@ also use these config values: .. versionadded:: 3.0 -.. confval:: autosummary_recursive - - Boolean that determines whether to add modules and sub-packages - recursively. It is disabled by default. - - .. versionadded:: 3.0 - .. confval:: autosummary_mock_imports This value contains a list of modules to be mocked up. See diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index c9427d8ce..23527d5c8 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -755,8 +755,7 @@ def process_generate_options(app: Sphinx) -> None: generate_autosummary_docs(genfiles, builder=app.builder, suffix=suffix, base_path=app.srcdir, app=app, imported_members=imported_members, - overwrite=app.config.autosummary_generate_overwrite, - recursive=app.config.autosummary_recursive) + overwrite=app.config.autosummary_generate_overwrite) def setup(app: Sphinx) -> Dict[str, Any]: @@ -779,7 +778,6 @@ def setup(app: Sphinx) -> Dict[str, Any]: app.connect('builder-inited', process_generate_options) app.add_config_value('autosummary_generate', [], True, [bool]) app.add_config_value('autosummary_generate_overwrite', True, False) - app.add_config_value('autosummary_recursive', False, True) app.add_config_value('autosummary_mock_imports', lambda config: config.autodoc_mock_imports, 'env') app.add_config_value('autosummary_imported_members', [], False, [bool]) diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 6616cc0fe..f5e65eb44 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -252,7 +252,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, info: Callable = None, base_path: str = None, builder: Builder = None, template_dir: str = None, imported_members: bool = False, app: Any = None, - overwrite: bool = True, recursive: bool = True) -> None: + overwrite: bool = True) -> None: if info: warnings.warn('info argument for generate_autosummary_docs() is deprecated.', RemovedInSphinx40Warning) @@ -303,13 +303,8 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, _warn(__('[autosummary] failed to import %r: %s') % (entry.name, e)) continue - if entry.recursive and not recursive: - _warn('[autosummary] :resursive: option found. But ignored. ' - 'Please read document for autosummary_recursive option') - content = generate_autosummary_content(name, obj, parent, template, entry.template, - imported_members, app, - recursive and entry.recursive) + imported_members, app, entry.recursive) filename = os.path.join(path, name + suffix) if os.path.isfile(filename): @@ -334,7 +329,7 @@ def generate_autosummary_docs(sources: List[str], output_dir: str = None, base_path=base_path, builder=builder, template_dir=template_dir, imported_members=imported_members, app=app, - overwrite=overwrite, recursive=recursive) + overwrite=overwrite) # -- Finding documented entries in files --------------------------------------- @@ -525,7 +520,6 @@ def main(argv: List[str] = sys.argv[1:]) -> None: '.' + args.suffix, template_dir=args.templates, imported_members=args.imported_members, - recursive=args.recursive, app=app) diff --git a/tests/test_ext_autosummary.py b/tests/test_ext_autosummary.py index 41758003b..880fae078 100644 --- a/tests/test_ext_autosummary.py +++ b/tests/test_ext_autosummary.py @@ -262,10 +262,8 @@ def test_autosummary_generate_overwrite2(app_params, make_app): assert 'autosummary_dummy_module.rst' not in app._warning.getvalue() -@pytest.mark.sphinx('dummy', testroot='ext-autosummary-recursive', - srcdir='ext-autosummary-recursive-enabled', - confoverrides={'autosummary_recursive': True}) -def test_autosummary_recursive_enabled(app, status, warning): +@pytest.mark.sphinx('dummy', testroot='ext-autosummary-recursive') +def test_autosummary_recursive(app, status, warning): app.build() toctree = 'modules' # see module.rst template @@ -305,26 +303,6 @@ def test_autosummary_recursive_enabled(app, status, warning): assert not (generated / 'package2.module.rst').exists() -@pytest.mark.sphinx('dummy', testroot='ext-autosummary-recursive', - srcdir='ext-autosummary-recursive-disabled', - confoverrides={'autosummary_recursive': False}) -def test_autosummary_recursive_disabled(app, status, warning): - app.build() - toctree = 'modules' # see module.rst template - - # Modules should not be generated - generated = app.srcdir / 'generated' - assert (generated / 'package.rst').exists() - content = (generated / 'package.rst').text() - assert 'package.module' not in content - assert 'package.package' not in content - - # Recursively generate modules of top-level package (should be missing) - generated /= toctree - assert not (generated / 'package.module.rst').exists() - assert not (generated / 'package.package.rst').exists() - - @pytest.mark.sphinx('latex', **default_kw) def test_autosummary_latex_table_colspec(app, status, warning): app.builder.build_all()