[apidoc] Add --remove-old option
#12448
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
A common "gotcha" of re-running `sphinx-apidoc`, is that if the modules API changes it will not remove old files, leading to build errors. Here we introduce a `-r/----remove-old` option, to remove these files. Note, a key detail here is that we don't want to simply clear the directory, before running `sphinx-apidoc`, since this would lead to all files having a new `mtime`, and so `sphinx-build` would rebuild all of them, even if they have not changed.
picnixz
reviewed
Jun 20, 2024
picnixz
approved these changes
Jun 20, 2024
picnixz
approved these changes
Jun 20, 2024
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
A common "gotcha" of re-running
sphinx-apidoc, is that if the modules API changes it will not remove old files, leading to build errors for files not in atoctreeHere we introduce a
--remove-oldoption to remove these files.Note, a key detail here is that we don't want to simply clear the directory before running
sphinx-apidoc,since this would lead to all files having a new
mtime,and then
sphinx-buildwould rebuild all of them even if they have not changed.So we must first collect the list of all correct files, then remove any not in the list.
The PR also improves some typing of the code and replace
os.pathbypathlib.Pathin most instancesFYI, after this I intend to do the same for
sphinx-autogen