Skip to content

docs: fix api-ref method-heading naming typos and duplicate section - #1857

Open
jacalata wants to merge 2 commits into
gh-pagesfrom
jac/api-ref-name-fixes
Open

docs: fix api-ref method-heading naming typos and duplicate section#1857
jacalata wants to merge 2 commits into
gh-pagesfrom
jac/api-ref-name-fixes

Conversation

@jacalata

@jacalata jacalata commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

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 have
been drifting since well before Sphinx work started -- users Ctrl-F'ing
datasources.update_connection don't find the section today because
the heading spells it datasource.update_connection. The same audit
turned up a duplicate webhooks.delete section (h3 and h4 both
describing 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.

Old heading Correct name Headings renamed
datasource.* datasources.* 2
subscription.* subscriptions.* 4
webhook.* webhooks.* 6 (delete had two headings)
groupsets.* group_sets.* (snake_case, matching custom_views, flow_runs) 8

Total: 20 headings renamed.

Remove duplicate webhooks.delete section. Two adjacent sections
described 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-ref all target
section-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

  • Re-ran the audit script against the patched file:
    references_missing bucket went 20 -> 0; the 20 entries redistributed
    into reproducible (+9) and needs_docstring (+11), matching
    source-side docstring coverage.
  • Grepped api-ref.md for internal anchor references to the affected
    singular forms; none found.
  • Grepped Salesforce-hosted repos for external references to the
    renamed anchor slugs; none found.
  • Preview the rendered api-ref.md on the gh-pages Jekyll site;
    confirm the renamed sections render and their TOC entries regenerate.

🤖 Generated with Claude Code

jacalata and others added 2 commits August 10, 2026 18:19
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>
@jacalata jacalata changed the title docs: fix singular/plural typos in api-ref method-reference headings docs: fix api-ref method-heading naming typos and duplicate section Aug 11, 2026
@jacalata
jacalata requested a lite review from Copilot August 17, 2026 20:03

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 to group_sets.* to match the endpoint naming pattern used elsewhere.
  • Removes a duplicate webhooks.delete section to eliminate redundant documentation.
Suppressed comments (9)

docs/api-ref.md:4075

  • The group_sets.get section example still calls server.groupsets.get(), which contradicts the renamed endpoint (group_sets). Update the example to use server.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 thread docs/api-ref.md
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)
```
Comment thread docs/api-ref.md
<br>

#### webhook.get()
#### webhooks.get()
Comment thread docs/api-ref.md
Comment on lines +7277 to 7281
#### subscriptions.update

```py
subscription.update(subscription_item)
subscriptions.update(subscription_item)
```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants