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 diff --git a/CHANGES.rst b/CHANGES.rst index 2626062b18f..673ec5d02d0 100644 --- a/CHANGES.rst +++ b/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 ---------- 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,