Close sphinx-doc#7549: autosummary: Enable autosummary_generate by de…

…fault
tk0miya · Mar 9, 2021 · 09423ea · 09423ea
1 parent 3693ffe
commit 09423ea
Show file tree

Hide file tree

Showing 3 changed files with 14 additions and 7 deletions.
diff --git a/CHANGES b/CHANGES
@@ -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/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
@@ -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')