docs: numpy-style docstrings on Favorites endpoint (15 methods) - #1855
Open
jacalata wants to merge 1 commit into
Open
docs: numpy-style docstrings on Favorites endpoint (15 methods)#1855jacalata wants to merge 1 commit into
jacalata wants to merge 1 commit into
Conversation
Adds a class-level docstring plus 15 method docstrings on Favorites (get, add_favorite, 6x add_favorite_<type>, delete_favorite, 6x delete_favorite_<type>). Content ported from docs/api-ref.md's Favorites section on gh-pages so that the Sphinx pipeline in #1832 will produce equivalent output once wired up. Part of the api-ref -> Sphinx migration; see the migration audit report for the full list of methods still needing docstrings. Favorites was the largest single chunk in the "needs_docstring" bucket (15/41 methods). No behavior change. Docs only.
This was referenced Aug 8, 2026
There was a problem hiding this comment.
Pull request overview
This PR backfills NumPy-style docstrings for the Favorites endpoint to support upcoming Sphinx-generated API reference output, with the intent of matching the existing handwritten api-ref.md content.
Changes:
- Added a class-level docstring to
Favoritesdescribing behavior and storage of retrieved favorites. - Added NumPy-style docstrings for 15 public endpoint methods covering get/add/delete favorites across supported types.
Suppressed comments (2)
tableauserverclient/server/endpoint/favorites_endpoint.py:260
delete_favoriteis the polymorphic entry point but its docstring is missing the REST API reference link that the type-specific delete helpers include. Adding a link keeps the generated docs consistent.
type; this method is the polymorphic entry point.
Parameters
tableauserverclient/server/endpoint/favorites_endpoint.py:400
- This docstring is missing a REST API reference link, unlike the other
delete_favorite_*helpers. Adding it improves consistency in the generated API reference.
"""Remove a metric from the user's favorites.
Parameters
----------
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+22
to
+26
| Favorites can be workbooks, views, datasources, flows, projects, or metrics. | ||
| Retrieved favorites are stored on the target ``UserItem`` object as a | ||
| dictionary keyed by content type (e.g. ``"workbooks"``, ``"views"``, | ||
| ``"datasources"``, ``"flows"``, ``"projects"``, ``"metrics"``), where | ||
| each value is a list of the corresponding item objects. |
Comment on lines
+223
to
+226
| """Add a metric to the user's favorites. | ||
|
|
||
| Parameters | ||
| ---------- |
This file contains hidden or 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
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.
Motivation
Favorites was the largest single chunk in the needs-docstring bucket per
the api-ref migration audit (15 of 41 remaining public endpoint methods
without docstrings). Once #1832 wires up Sphinx, the generated output
will cover what the handwritten
api-ref.mdpage does today.Behavior change
Docs only. No behavior change.
Adds a class-level docstring on
Favoritesplus 15 method docstrings:get,add_favorite, 6xadd_favorite_<type>,delete_favorite,6x
delete_favorite_<type>. Content ported from the Favorites section ofapi-ref.mdon gh-pages.Known asymmetry in the API surface (documented in the docstrings, not
resolved here):
add_favoritetakescontent_typeas a plainstrwithexample values like
"workbook";delete_favoritetakes it as aResourceenum. Callers reading the two side-by-side will notice theinconsistency.
Test plan
test/test_favorites.py: 9 passed🤖 Generated with Claude Code