Add remove_old configuration to sphinx.ext.apidoc

Makes the option available to be configured when using apidoc as an extension instead of as a command-line tool.

Author: echoix

doc/usage/extensions/apidoc.rst

@@ -92,6 +92,9 @@ The apidoc extension uses the following configuration values:
    :code-py:`'follow_links'`
      See :confval:`apidoc_follow_links`.
 
+   :code-py:`'remove_old'`
+     See :confval:`apidoc_remove_old`.
+
    :code-py:`'separate_modules'`
      See :confval:`apidoc_separate_modules`.
 
@@ -129,6 +132,12 @@ The apidoc extension uses the following configuration values:
 
    Follow symbolic links.
 
+.. confval:: apidoc_remove_old
+   :type: :code-py:`bool`
+   :default: :code-py:`True`
+
+   Remove existing files in the output directory that are not created anymore.
+
 .. confval:: apidoc_separate_modules
    :type: :code-py:`bool`
    :default: :code-py:`False`

sphinx/ext/apidoc/__init__.py

@@ -37,6 +37,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     )
     app.add_config_value('apidoc_max_depth', 4, 'env', types=frozenset({int}))
     app.add_config_value('apidoc_follow_links', False, 'env', types=frozenset({bool}))
+    app.add_config_value('apidoc_remove_old', True, 'env', types=frozenset({bool}))
     app.add_config_value(
         'apidoc_separate_modules', False, 'env', types=frozenset({bool})
     )

sphinx/ext/apidoc/_extension.py

@@ -25,6 +25,7 @@
 
 _BOOL_KEYS = frozenset({
     'follow_links',
+    'remove_old',
     'separate_modules',
     'include_private',
     'no_headings',
@@ -220,6 +221,7 @@ def _parse_module_options(
         max_depth=max_depth,
         quiet=True,
         follow_links=bool_options['follow_links'],
+        remove_old=bool_options['remove_old'],
         separate_modules=bool_options['separate_modules'],
         include_private=bool_options['include_private'],
         no_headings=bool_options['no_headings'],

sphinx/ext/apidoc/_shared.py

@@ -77,6 +77,7 @@ class ApidocDefaults:
     automodule_options: frozenset[str]
     max_depth: int
     follow_links: bool
+    remove_old: bool
     separate_modules: bool
     include_private: bool
     no_headings: bool
@@ -91,6 +92,7 @@ def from_config(cls, config: Config, /) -> Self:
             automodule_options=frozenset(config.apidoc_automodule_options),
             max_depth=config.apidoc_max_depth,
             follow_links=config.apidoc_follow_links,
+            remove_old=config.apidoc_remove_old,
             separate_modules=config.apidoc_separate_modules,
             include_private=config.apidoc_include_private,
             no_headings=config.apidoc_no_headings,