Finish doc refactor to use extdoclink and tabs instead of doc_api_method and to put example usages in tabs #714
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
All remaining methods of the SearchClient which were not already converted to this method now use the tab-set and tab-item ReST blocks to document any examples and the API reference info.
API Info doc tabs are now in place for all methods. Where there was existing tab structure, these are added as the last tab. Where there were no tabs, tabs have been introduced for this purpose. This replaces the `_flowdoc` decorator, so that has been removed.
Wherever `doc_api_method` was used within the AuthClient, the tab-set documentation is now used, and external links are referenced using extdoclink, just like other services. In the particular case of get_identities, blacken docs and manual reformatting were slightly more extensive than in some other examples being converted to this style, but extraneous changes were avoided.
doc_api_method was only used for oauth2_start_flow, but in this place we now use the tabs for documentation and the API Info section is populated with specific and appropriate content. doc_api_method supported passing in a format string, a behavior which does not seem fully necessary and is intentionally omitted from extdoclink.
Where doc_api_method was used, introduce an API Info tab instead. As with NativeAppAuthClient, the oauth2_start_flow method is a special case which does not use extdoclink.
For all GCSClient methods, replace the custom decorator (_gcsdoc) with use of the tabbed doc layout and an API Info tab. The content therein is populated by the appropriate extdoclink usage.
Links ending with `_` are made into reference targets, whereas those ending with `__` are not. This "anonymous reference" behavior is part of the RST specification, not only a sphinx behavior. When sphinx sees multiple targets with the same name in a document, it emits a warning, which we turn into an error with `-W`. The duplicates easily occur with these links, which often match method names. Using the `__` behavior dodges the problem.
code-block directives with no language specified are not targetted by blacken-docs automatically. For this reason, we are removing them from various other clients where they appear. Remove them from GroupsClient as well, even though blacken-docs makes no changes.
This script converts examples from the bold header style to the tabbed documentation style. It makes some simple assumptions.
All examples using the bolded header style are converted to use the tab-set, tab-item style, and to put any pycon blocks into python code blocks as appropriate. This was done by first running the example conversion script, and then a few editor macros. In addition to these changes, blacken-docs was run and `format()` calls were converted to f-strings in the changed blocks. A few formatted blocks exceed the line length limit and therefore have their docstrings marked with `noqa: E501`.
Add a script which converts the standard API route reference strings to 'API Info' tabs in the method documentation tab-sets for each TransferClient method, and run this script. Additionally, tab-set declarations need to be added where they were missing.
Write a script to replace uses of doc_api_method decorator with the extdoclink, prepare the transfer client file by making all of the doc_api_method calls one line (using editor macros), then apply the script.
- Remove utils.doc_api_method as it is no longer used anywhere - Remove each of the client code transformation scripts
Using pre-commit pygrep, enforce that any code-block directive must take an argument (the language) so that code-blocks always set python explicitly. As a result, blacken-docs should always detect them correctly. Applying the changes as required by the hook allows blacken-docs to modify one of the relevant blocks.
sirosen
requested review from
ada-globus,
derek-globus,
kurtmckee and
aaschaer
as code owners
kurtmckee
requested changes
Apr 12, 2023
Co-authored-by: Kurt McKee <contactme@kurtmckee.org>
kurtmckee
approved these changes
Apr 12, 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.
Overall, I'm aiming to push us into "the next phase" regarding docstring formatting.
Example Usages
Older method examples are written with a boldface pseudo-header,
**Examples**. In all cases, this is converted to a tab containing the examples, as part of the per-method tab-set.External Links
Prior to this work, we had two ways to produce commonly structured external doc links.
Old: the
doc_api_methoddecorator.New: the
extdoclinkdirective.At the end of this series of changes, only the new way survives, and is always used inside of an
API Infotab.Review considerations & other changes
Each commit here is a separately reviewable step in the journey towards this state.
I worked one module at a time, intentionally leaving Transfer for last.
Along the way, the following notable related pieces accrued, in order of appearance:
.. code-block::cannot appear at the end of a line (without a following language). This guarantees that blacken-docs can correctly identify these blocksChangelog
format and display examples and other information