Revise Plugins API, add plugins keyword arg for makedocs and doctest
#2249
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
This was referenced Sep 10, 2023
Instead of passing plugin objects to `makedocs` as positional arguments (which was undocumented), they are now passed as a a keyword argument `plugins`. The docstrings of the `Plugin` type and the `getplugin` function have been corrected. They were at best misleading, and at worst flat-out wrong.
Forward keyword arguments from `doctest` to `makedocs`. This includes the `plugins` keyword argument, but potentially other keyword arguments as well.
|
Ok, I made all the changes from @mortenpi's comments. Should be ready for merge, unless there's any more changes related to the revised more conservative approach of only passing |
mortenpi
approved these changes
Sep 11, 2023
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Plugin/getpluginAPI (testing all documented behavior)Plugin/getplugin. Specifically, the documentation claimed that it was possible to passPlugin-types instead of objects tomakedocs. This didn't match either the old or the new implementation, so the docstrings have been corrected to match what is actually implementedpluginskeyword argument tomakedocsthat replaces passing instances ofPluginas positional arguments (which was completely undocumented)pluginskeyword argument todoctestto address doctest and CitationBibliography DocumenterCitations.jl#34.This is implemented by forwarding all unknown keyword arguments fromdoctestto the internal call ofmaketest. The feature is documented as "use only as directed". Alternatively, I could implement this by fowarding onlyplugins, but generally forwardingkwargsseems more future-proof, avoid problems where in some specific contextmaketestrequires some argument thatdoctestisn't giving it.The introduction of the
pluginskeyword argument is (at least arguably) a breaking change, and thus should be included in the 1.0 release. The old behavior with regards to plugins wasn't documented, but anyone who might have been passingPluginobjects as positional arguments tomakedocshas to change that to apluginskeyword argument.Most notably, users of DocumenterCitations will be affected by this.
In any case, this PR makes the API for plugins significantly more explicit.
Closes #2245