From abce7c2f8ea4e8e677573bec0628ecaa3031a3ef Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edouard=20Choini=C3=A8re?=
 <27212526+echoix@users.noreply.github.com>
Date: Sun, 15 Jun 2025 21:19:09 +0000
Subject: [PATCH 1/3] 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.
---
 doc/usage/extensions/apidoc.rst | 9 +++++++++
 sphinx/ext/apidoc/__init__.py   | 1 +
 sphinx/ext/apidoc/_extension.py | 2 ++
 sphinx/ext/apidoc/_shared.py    | 2 ++
 4 files changed, 14 insertions(+)

diff --git a/doc/usage/extensions/apidoc.rst b/doc/usage/extensions/apidoc.rst
index 4dc8ca941a2..8f62711af95 100644
--- a/doc/usage/extensions/apidoc.rst
+++ b/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`
diff --git a/sphinx/ext/apidoc/__init__.py b/sphinx/ext/apidoc/__init__.py
index be52485771c..61df922f184 100644
--- a/sphinx/ext/apidoc/__init__.py
+++ b/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})
     )
diff --git a/sphinx/ext/apidoc/_extension.py b/sphinx/ext/apidoc/_extension.py
index c5a67528ec0..fb9bfabfaed 100644
--- a/sphinx/ext/apidoc/_extension.py
+++ b/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'],
diff --git a/sphinx/ext/apidoc/_shared.py b/sphinx/ext/apidoc/_shared.py
index 527f240f9df..f79e0b95eac 100644
--- a/sphinx/ext/apidoc/_shared.py
+++ b/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,

From edfd3bc9f365d716b4d385ce2eba090035e10a47 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edouard=20Choini=C3=A8re?=
 <27212526+echoix@users.noreply.github.com>
Date: Sun, 15 Jun 2025 21:29:37 +0000
Subject: [PATCH 2/3] Add entry to AUTHORS.rst as requested in the PR template

---
 AUTHORS.rst | 1 +
 1 file changed, 1 insertion(+)

diff --git a/AUTHORS.rst b/AUTHORS.rst
index 43a8da3469d..ba123f1b882 100644
--- a/AUTHORS.rst
+++ b/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

From aac8a283a8500412f8abac42ea59d2b88235113e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Edouard=20Choini=C3=A8re?=
 <27212526+echoix@users.noreply.github.com>
Date: Sun, 15 Jun 2025 21:40:55 +0000
Subject: [PATCH 3/3] Add entry to CHANGES.rst as requested in the PR template

---
 CHANGES.rst | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/CHANGES.rst b/CHANGES.rst
index 4920b4c7736..3f64b91e92c 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -43,6 +43,10 @@ Features added
   Patch by Adam Turner.
 * #13647: LaTeX: allow more cases of table nesting.
   Patch by Jean-François B.
+* #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
 ----------