docs: fix api-ref method-heading naming typos and duplicate section - #1857
Open
jacalata wants to merge 2 commits into
Open
docs: fix api-ref method-heading naming typos and duplicate section#1857jacalata wants to merge 2 commits into
jacalata wants to merge 2 commits into
Conversation
api-ref.md addressed several endpoint methods with the singular form of the endpoint attribute rather than the plural form actually bound on `Server`: - `datasource.*` -> `datasources.*` (2 headings) - `subscription.*` -> `subscriptions.*` (4 headings) - `webhook.*` -> `webhooks.*` (5 headings) - `groupsets.*` -> `group_sets.*` (9 headings) Discovered while auditing api-ref.md against source for the Sphinx migration in server-client-python#1832. Section content is unchanged; only heading + code-block invocation lines are renamed. No internal anchor links reference the old headings. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
api-ref.md had two adjacent sections describing webhooks.delete (h3 at line 9573 and h4 at line 9684 pre-rename). Both documented the same method with the same signature. Keeping the h4 entry: it lives with the other webhook methods at h4 level, matches the surrounding template (includes Version info, concise Example, standard REST API link), and is what search results consistently pointed at. Discovered while working on the singular/plural heading rename in the previous commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR updates the handwritten API reference (docs/api-ref.md) to align method headings (and the adjacent signature/code-sample invocation lines) with the actual pluralized endpoint names exposed on Server, and removes a duplicated webhooks.delete section discovered during the Sphinx migration audit.
Changes:
- Renames multiple method headings from singular to plural forms (and updates the nearby invocation line accordingly) to improve searchability (Ctrl-F) and correctness.
- Renames
groupsets.*headings togroup_sets.*to match the endpoint naming pattern used elsewhere. - Removes a duplicate
webhooks.deletesection to eliminate redundant documentation.
Suppressed comments (9)
docs/api-ref.md:4075
- The
group_sets.getsection example still callsserver.groupsets.get(), which contradicts the renamed endpoint (group_sets). Update the example to useserver.group_sets.get()so readers can copy/paste it successfully.
#### group_sets.get_by_id
```py
group_sets.get_by_id(groupset_id)
**docs/api-ref.md:4109**
* The `group_sets.get_by_id` example still calls `server.groupsets.get_by_id(...)` even though the endpoint has been renamed to `group_sets`. Update the example to `server.group_sets.get_by_id(...)` for consistency and correctness.
group_sets.create
group_sets.create(groupset_item)**docs/api-ref.md:4144**
* The `group_sets.create` example still calls `server.groupsets.create(...)`, which is inconsistent with the renamed endpoint (`group_sets`). Update the example to `server.group_sets.create(...)`.
group_sets.update
group_sets.update(groupset_item)**docs/api-ref.md:4178**
* The `group_sets.update` example still calls `server.groupsets.update(...)`. After renaming the endpoint to `group_sets`, update this example to `server.group_sets.update(...)` to avoid conflicting guidance in the same section.
group_sets.delete
group_sets.delete(groupset)**docs/api-ref.md:4211**
* The `group_sets.delete` example still uses `server.groupsets.delete(...)`. Update to `server.group_sets.delete(...)` to match the renamed endpoint.
group_sets.add_group
group_sets.add_group(groupset_item, group)**docs/api-ref.md:4248**
* The `group_sets.add_group` example still calls `server.groupsets.add_group(...)`. Update to `server.group_sets.add_group(...)` to match the renamed endpoint.
group_sets.remove_group
group_sets.remove_group(groupset_item, group)**docs/api-ref.md:4282**
* The `group_sets.remove_group` example still calls `server.groupsets.remove_group(...)`. Update it to `server.group_sets.remove_group(...)` to match the renamed endpoint.
group_sets.filter
group_sets.filter(**kwargs)**docs/api-ref.md:9613**
* Typo in the code sample: `get_by_ide` should be `get_by_id`. As written, readers copy/pasting this call will hit an AttributeError.
webhooks.get_by_id
webhooks.get_by_ide(webhook_id)**docs/api-ref.md:4282**
* The `group_sets.filter` example later in this section still uses `server.groupsets.filter(...)` (e.g., around line 4310). After renaming the endpoint to `group_sets`, that example should also be updated to `server.group_sets.filter(...)` to avoid conflicting copy/paste instructions.
group_sets.filter
group_sets.filter(**kwargs)</details>
---
💡 <a href="/tableau/server-client-python/new/gh-pages?filename=.github/skills/code-review/SKILL.md" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Add a `code-review` agent skill</a> or configure MCP servers for context-aware, tailored reviews. <a href="https://docs.github.com/en/copilot/how-tos/use-copilot-agents/request-a-code-review/use-code-review#mcp-servers-and-agent-skills" class="Link--inTextBlock" target="_blank" rel="noopener noreferrer">Learn more in the docs.</a>
Comment on lines
+4035
to
4039
| #### group_sets.get | ||
|
|
||
| ```py | ||
| groupsets.get(req_options=None, result_level=None) | ||
| group_sets.get(req_options=None, result_level=None) | ||
| ``` |
| <br> | ||
|
|
||
| #### webhook.get() | ||
| #### webhooks.get() |
Comment on lines
+7277
to
7281
| #### subscriptions.update | ||
|
|
||
| ```py | ||
| subscription.update(subscription_item) | ||
| subscriptions.update(subscription_item) | ||
| ``` |
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
Auditing api-ref.md against source for the Sphinx migration (#1832)
surfaced 20 headings that reference endpoint methods by the singular
form rather than the plural form actually bound on
Server. These havebeen drifting since well before Sphinx work started -- users Ctrl-F'ing
datasources.update_connectiondon't find the section today becausethe heading spells it
datasource.update_connection. The same auditturned up a duplicate
webhooks.deletesection (h3 and h4 bothdescribing the same method); folded here since it's discovered along
the way.
Behavior change
Docs only. Two commits:
Rename typo'd method headings. Only heading text and the code-sample
invocation line change; section prose is untouched.
datasource.*datasources.*subscription.*subscriptions.*webhook.*webhooks.*groupsets.*group_sets.*(snake_case, matchingcustom_views,flow_runs)Total: 20 headings renamed.
Remove duplicate
webhooks.deletesection. Two adjacent sectionsdescribed the same method (h3 at line 9573, h4 at line 9684). Kept the
h4 entry -- it lives with the other webhook methods at h4 level, matches
the surrounding template (includes Version info, standard REST API
link, concise Example).
Anchor slug impact. Kramdown regenerates anchor slugs from
headings, so the fragment URLs change (e.g.
#datasourceupdate_connection->#datasourcesupdate_connection).Searched across Salesforce-hosted repos for external references to the
old anchor slugs: none found. Existing external links to
tableau.github.io/server-client-python/docs/api-refall targetsection-level anchors (
#workbooks,#data-sources,#jobs,#server,#tableauauth-class) that this PR does not touch.Internal anchor links in api-ref.md itself: grepped for references to
the renamed method-heading slugs; none found.
Test plan
references_missingbucket went 20 -> 0; the 20 entries redistributedinto
reproducible(+9) andneeds_docstring(+11), matchingsource-side docstring coverage.
singular forms; none found.
renamed anchor slugs; none found.
api-ref.mdon the gh-pages Jekyll site;confirm the renamed sections render and their TOC entries regenerate.
🤖 Generated with Claude Code