diff options
| -rw-r--r-- | CHANGES | 1 | ||||
| -rw-r--r-- | doc/conf.py | 1 | ||||
| -rw-r--r-- | doc/usage/extensions/autosummary.rst | 18 | ||||
| -rw-r--r-- | sphinx/ext/autosummary/__init__.py | 2 |
4 files changed, 15 insertions, 7 deletions
@@ -62,6 +62,7 @@ Features added -------------- * #8924: autodoc: Support ``bound`` argument for TypeVar +* #7549: autosummary: Enable :confval:`autosummary_generate` by default * #4826: py domain: Add ``:canonical:`` option to python directives to describe the location where the object is defined * #7199: py domain: Add :confval:`python_use_unqualified_type_names` to suppress diff --git a/doc/conf.py b/doc/conf.py index 7cf74dc97..ddf68de05 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -79,6 +79,7 @@ latex_show_urls = 'footnote' latex_use_xindy = True autodoc_member_order = 'groupwise' +autosummary_generate = False todo_include_todos = True extlinks = {'duref': ('http://docutils.sourceforge.net/docs/ref/rst/' 'restructuredtext.html#%s', ''), diff --git a/doc/usage/extensions/autosummary.rst b/doc/usage/extensions/autosummary.rst index 03ea7548e..28f207de7 100644 --- a/doc/usage/extensions/autosummary.rst +++ b/doc/usage/extensions/autosummary.rst @@ -19,11 +19,13 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts: that contain links to the documented items, and short summary blurbs extracted from their docstrings. -2. Optionally, the convenience script :program:`sphinx-autogen` or the new - :confval:`autosummary_generate` config value can be used to generate short - "stub" files for the entries listed in the :rst:dir:`autosummary` directives. - These files by default contain only the corresponding - :mod:`sphinx.ext.autodoc` directive, but can be customized with templates. +2. A :rst:dir:`autosummary` directive also generates short "stub" files for the + entries listed in its content. These files by default contain only the + corresponding :mod:`sphinx.ext.autodoc` directive, but can be customized with + templates. + + The :program:`sphinx-autogen` script is also able to generate "stub" files + from command line. .. rst:directive:: autosummary @@ -161,7 +163,7 @@ also use these config values: .. confval:: autosummary_generate Boolean indicating whether to scan all found documents for autosummary - directives, and to generate stub pages for each. It is disabled by default. + directives, and to generate stub pages for each. It is enabled by default. Can also be a list of documents for which stub pages should be generated. @@ -173,6 +175,10 @@ also use these config values: Emits :event:`autodoc-skip-member` event as :mod:`~sphinx.ext.autodoc` does. + .. versionchanged:: 4.0 + + Enabled by default. + .. confval:: autosummary_generate_overwrite If true, autosummary overwrites existing files by generated stub pages. diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 7dbaaf686..1a0fd2409 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -772,7 +772,7 @@ def setup(app: Sphinx) -> Dict[str, Any]: app.connect('builder-inited', process_generate_options) app.add_config_value('autosummary_context', {}, True) app.add_config_value('autosummary_filename_map', {}, 'html') - app.add_config_value('autosummary_generate', [], True, [bool]) + app.add_config_value('autosummary_generate', True, True, [bool]) app.add_config_value('autosummary_generate_overwrite', True, False) app.add_config_value('autosummary_mock_imports', lambda config: config.autodoc_mock_imports, 'env') |