Add remove_old configuration to sphinx.ext.apidoc

AUTHORS.rst

@@ -50,6 +50,7 @@ Contributors
 * Dimitri Papadopoulos Orfanos -- linting and spelling
 * Dmitry Shachnev -- modernisation and reproducibility
 * Doug Hellmann -- graphviz improvements
+* Edouard Choinière -- ``sphinx.ext.apidoc`` extension improvement
 * Eric Larson -- better error messages
 * Eric N. Vander Weele -- autodoc improvements
 * Eric Wieser -- autodoc improvements

CHANGES.rst

@@ -58,6 +58,10 @@ Features added
   The location of the cache directory must not be relied upon externally,
   as it may change without notice or warning in future releases.
   Patch by Adam Turner.
+* #13668: :mod:`sphinx.ext.apidoc`: Support :confval:`apidoc_remove_old`
+  and :code:`'remove_old'` key of :confval:`apidoc_modules` when using apidoc as
+  an extension, like :option:`sphinx-apidoc --remove-old`.
+  Patch by Edouard Choinière.
 
 Bugs fixed
 ----------

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,