dev: tool to generate api endpoint documentation #3085
Draft
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
|
Jira: This PR is not related to a Jira item. (The PR title does not include a SC-#### reference) GitHub Issues: No GitHub issues are fixed by this PR. (No commits have Fixes: #### references) Launchpad Bugs: No Launchpad bugs are fixed by this PR. (No commits have LP: #### references) Documentation: The changes in this PR do not require documentation changes. 👍 this comment to confirm that this is correct. |
orndorffgrant
force-pushed
the
generate-api-docs
branch
from
5231ca8
to
ac082b1
Compare
tools/apidocgen.py
Outdated
| from uaclient import data_types | ||
|
|
||
| NO_ARGS = "- This endpoint takes no arguments." | ||
| NO_EXCEPTIONS = "- No exceptions raised by this endpoint." |
There was a problem hiding this comment.
now may be the time to fix this kinda incorrect information
this is more like "no PARTICULAR exception expected to be raised here"
because see - all endpoints may spit UbuntuProErrors if things go wrong?
There was a problem hiding this comment.
Yes good catch!
orndorffgrant
force-pushed
the
generate-api-docs
branch
2 times, most recently
from
21f9600
to
fcaa40f
Compare
orndorffgrant
force-pushed
the
generate-api-docs
branch
from
fcaa40f
to
1c6985b
Compare
lucasmoura
approved these changes
May 14, 2024
orndorffgrant
force-pushed
the
generate-api-docs
branch
from
1c6985b
to
5322989
Compare
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.
Why is this needed?
Our api docs are growing, and keeping them up-to-date and consistently styled is becoming tedious. This automates a lot of the work of creating the endpoint documentation by putting the docstrings as metadata with the code itself.
@lucasmoura @dheyay LMK what you think before I apply this strategy to the other existing endpoints.
Test Steps
Try out the new script (hopefully the docstring at the top of the file is sufficient to start playing with it)
Checklist
Does this PR require extra reviews?