docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference by jacalata · Pull Request #1832 · tableau/server-client-python · GitHub

Motivation

api-ref.md on gh-pages is the canonical reference doc today. It's
hand-edited: when a new method or model field lands, someone has to
remember to update it. Coverage drifts and diverges from the code.

Sphinx generates the same content from docstrings, so the update path
becomes "write the docstring, docs regenerate." Concepts and tutorials
stay in Jekyll -- Sphinx just replaces the reference section.

Not merging this into the live Jekyll site yet: docstring coverage
across the models package is thin, and the auto-generated output today
would be a regression from the handwritten api-ref.md. Landing the
pipeline now unblocks incremental docstring work without a public-facing
rush. #1855 is the first tranche of docstring backfill.

Behavior change

None to the runtime library. Adds a docs build pipeline:

.readthedocs.yaml -- RTD build config, Python 3.13
docs/conf.py -- Sphinx config; reads project details from pyproject.toml; furo theme
docs/index.rst -- automodule with :members: :imported-members:
so re-exports from __init__.py render (without :imported-members:
the output was nearly empty)
.github/workflows/docs.yml -- triggers on push: branches: [master],
builds Sphinx, opens a PR into gh-pages at sphinx/. Uses
concurrency: docs-publish to serialize runs
pyproject.toml -- adds docs = ["sphinx>=7,<9", "furo>=2024,<2027", "tomli; python_version < '3.11'"] optional-deps group

Also incidentally: small docstring cleanups in connection_item.py and
site_item.py (side effect of the initial Sphinx pass).

Why both RTD and gh-pages/sphinx: the workflow-driven PR into gh-pages
puts the built HTML next to the existing Jekyll site so we can add nav
links whenever coverage is good enough. RTD is the fallback/canonical
hosting if we prefer to keep gh-pages Jekyll-only. Long-term one goes
away; keeping both live in the setup lets us pick without rebuilding.

Test plan

Sphinx builds cleanly locally
(sphinx-build -b html docs sphinx_build) -- 3000-line index with all
re-exports rendering. One benign warning about a duplicate
UserItem.idp_configuration_id object description (pre-existing
property+setter shape).
RTD build succeeds via .readthedocs.yaml -- not exercised until
the PR merges and RTD picks up the config
.github/workflows/docs.yml runtime not exercised until this is
on master

🤖 Generated with Claude Code

Add Read the Docs configuration file for documentation build

Added configuration settings for Sphinx documentation. Direct copy from example conf file.

Updated project information to load from pyproject.toml.

- Add docs optional-dependencies group (sphinx, tomli) to pyproject.toml - Wire up .readthedocs.yaml to install .[docs] extra - Fix conf.py: correct pyproject.toml path, use importlib.metadata for version, switch to alabaster theme, use tomllib/tomli compat import - Add minimal docs/index.rst - Fix RST docstring errors in connection_item, site_item, job_item, task_item that caused Sphinx build warnings/errors Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

On push to master, builds Sphinx HTML and opens a PR from docs-update into gh-pages so the generated API reference can be reviewed before going live. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Coverage Report

File	Stmts	Miss	Cover	Missing
tableauserverclient
__init__.py	5	0	100%
config.py	15	0	100%
datetime_helpers.py	25	1	1	96%
exponential_backoff.py	20	0	100%
filesys_helpers.py	31	0	100%
namespace.py	25	3	3	88%
tableauserverclient/bin
__init__.py	2	0	100%
_version.py	358	212	212	41%
tableauserverclient/helpers
__init__.py	1	0	100%
logging.py	2	0	100%
strings.py	31	1	1	97%
tableauserverclient/models
__init__.py	46	0	100%
collection_item.py	41	7	7	83%
column_item.py	55	32	32	42%
connection_credentials.py	35	11	11	69%
connection_item.py	94	14	14	85%
custom_view_item.py	144	21	21	85%
data_acceleration_report_item.py	54	1	1	98%
data_alert_item.py	158	4	4	97%
data_freshness_policy_item.py	155	15	15	90%
database_item.py	207	36	36	83%
datasource_item.py	300	12	12	96%
dqw_item.py	104	5	5	95%
exceptions.py	4	0	100%
extensions_item.py	132	4	4	97%
extract_item.py	44	4	4	91%
favorites_item.py	69	8	8	88%
fileupload_item.py	19	0	100%
flow_item.py	149	10	10	93%
flow_run_item.py	71	0	100%
group_item.py	89	6	6	93%
groupset_item.py	49	7	7	86%
interval_item.py	182	32	32	82%
job_item.py	192	10	10	95%
linked_tasks_item.py	79	1	1	99%
location_item.py	29	2	2	93%
metric_item.py	129	13	13	90%
oidc_item.py	63	3	3	95%
pagination_item.py	34	1	1	97%
permissions_item.py	111	12	12	89%
project_item.py	207	31	31	85%
property_decorators.py	100	18	18	82%
reference_item.py	26	2	2	92%
revision_item.py	59	1	1	98%
schedule_item.py	209	6	6	97%
server_info_item.py	37	7	7	81%
site_item.py	636	13	13	98%
subscription_item.py	101	2	2	98%
table_item.py	119	18	18	85%
tableau_auth.py	61	25	25	59%
tableau_types.py	27	1	1	96%
tag_item.py	15	0	100%
target.py	6	0	100%
task_item.py	56	2	2	96%
user_item.py	323	16	16	95%
view_item.py	220	16	16	93%
virtual_connection_item.py	64	8	8	88%
webhook_item.py	69	1	1	99%
workbook_item.py	362	16	16	96%
tableauserverclient/server
__init__.py	9	0	100%
exceptions.py	4	0	100%
filter.py	29	1	1	97%
pager.py	33	1	1	97%
query.py	143	15	15	90%
request_factory.py	1335	195	195	85%
request_options.py	386	5	5	99%
server.py	188	23	23	88%
sort.py	6	0	100%
tableauserverclient/server/endpoint
__init__.py	35	0	100%
auth_endpoint.py	73	10	10	86%
custom_views_endpoint.py	152	12	12	92%
data_acceleration_report_endpoint.py	21	0	100%
data_alert_endpoint.py	94	23	23	76%
databases_endpoint.py	111	30	30	73%
datasources_endpoint.py	323	33	33	90%
default_permissions_endpoint.py	44	3	3	93%
dqw_endpoint.py	45	16	16	64%
endpoint.py	259	24	24	91%
exceptions.py	79	6	6	92%
extensions_endpoint.py	31	0	100%
favorites_endpoint.py	94	22	22	77%
fileuploads_endpoint.py	51	0	100%
flow_runs_endpoint.py	62	9	9	85%
flow_task_endpoint.py	21	2	2	90%
flows_endpoint.py	198	53	53	73%
groups_endpoint.py	126	9	9	93%
groupsets_endpoint.py	72	7	7	90%
jobs_endpoint.py	67	9	9	87%
linked_tasks_endpoint.py	37	0	100%
metadata_endpoint.py	88	14	14	84%
metrics_endpoint.py	55	6	6	89%
oidc_endpoint.py	42	1	1	98%
permissions_endpoint.py	44	3	3	93%
projects_endpoint.py	178	24	24	87%
resource_tagger.py	127	35	35	72%
schedules_endpoint.py	119	11	11	91%
server_info_endpoint.py	36	10	10	72%
sites_endpoint.py	130	27	27	79%
subscriptions_endpoint.py	56	14	14	75%
tables_endpoint.py	110	36	36	67%
tasks_endpoint.py	63	6	6	90%
users_endpoint.py	183	8	8	96%
views_endpoint.py	150	9	9	94%
virtual_connections_endpoint.py	113	10	10	91%
webhooks_endpoint.py	54	9	9	83%
workbooks_endpoint.py	338	22	22	93%
TOTAL	12064	1424	88%

Four cleanups on the docs branch surfaced by an adversarial review: - Revert id_ -> id docstring renames in JobItem and TaskItem. The constructors take `id_` (trailing underscore because `id` shadows the builtin); the docstring should describe the actual parameter name. The original rename was cosmetic and made the docstring actively misleading — users copying the docstring's kwarg would get a TypeError. - Add :imported-members: to docs/index.rst. Without it, the top-level automodule directive only documents symbols defined in tableauserverclient/__init__.py itself (which is 99% re-exports), so the generated API reference was nearly empty. With this, all re-exported classes render. - Pin [docs] extras. Was `sphinx`, `tomli`, `furo` — unpinned. Now `sphinx>=7,<9`, `furo>=2024,<2027`, `tomli; python_version < '3.11'`. A future Sphinx major bump can silently break the RTD reproducible build otherwise. `tomli` narrowed to just the Python 3.10 build path; 3.11+ has stdlib tomllib. - Workflow changes: - Add `concurrency: docs-publish` so overlapping runs don't rewrite docs-update mid-flight. - Set `delete-branch: true` on peter-evans/create-pull-request so stale docs-update branches don't accumulate and force-updates don't strand review comments. - Set `fetch-depth: 0` on the gh-pages checkout so create-pull-request can detect no-op diffs correctly. - Remove the templates_path = ["_templates"] config in docs/conf.py. The referenced directory doesn't ship, so Sphinx emits a warning on every build. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Pull request overview

Adds a Sphinx/Read the Docs documentation pipeline to generate an API reference from docstrings, intended to live alongside (and eventually replace) the manually maintained api-ref.md on gh-pages.

Changes:

Introduces Sphinx configuration and a minimal index.rst that documents the top-level tableauserverclient module.
Adds Read the Docs configuration and a GitHub Actions workflow that builds docs and opens an automated PR into gh-pages/sphinx/.
Adds a docs optional-dependency group and includes minor docstring adjustments to improve generated output.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
.readthedocs.yaml	Adds RTD build/install configuration for Sphinx docs.
docs/conf.py	Adds Sphinx configuration (theme/extensions) and reads project metadata from pyproject.toml.
docs/index.rst	Adds Sphinx root page that auto-documents tableauserverclient (including re-exports).
.github/workflows/docs.yml	Adds CI job to build Sphinx HTML and open a PR to gh-pages with generated output.
pyproject.toml	Adds docs extras (Sphinx, furo, tomli fallback).
tableauserverclient/models/connection_item.py	Refines docstring for XML parsing helper.
tableauserverclient/models/site_item.py	Clarifies tier capacity docstrings for Creator/Explorer/Viewer.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

The previous conf.py used a single `.. automodule:: tableauserverclient` which only covers names re-exported from `tableauserverclient/__init__.py`. That silently drops every endpoint class and every root helper module -- Favorites, VirtualConnections, config, datetime_helpers, filesys_helpers, namespace, exponential_backoff -- and readers running into missing methods had no way to find the underlying signatures. Wire in sphinx-autoapi with autoapi_dirs pointing at the source tree. The generator walks every module (including private endpoints) and produces a reference page per module under docs/reference/. `autoapi_root` and the corresponding .gitignore entry are kept in sync. Other tweaks: - Replace the empty toctree in docs/index.rst with a hidden one so autoapi's `autoapi_add_toctree_entry` has a node to append to (without an existing toctree it is a no-op and Furo's sidebar comes out empty). - Add `python -m pip install --upgrade pip` to the docs workflow to avoid the resolver-warnings that older pips emit on modern extras. Docstring warnings surfaced by autoapi are not addressed here; a follow-up PR will fix the RST-vs-Google mismatches introduced by the recent Favorites, VirtualConnections, and root-helper docstring passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

jacalata and others added 6 commits July 27, 2026 18:00

Create .readthedocs.yaml for documentation setup

db6b9a4

Add Read the Docs configuration file for documentation build

Create Sphinx configuration file for documentation

b021986

Added configuration settings for Sphinx documentation. Direct copy from example conf file.

Load project details from pyproject.toml

a195f86

Updated project information to load from pyproject.toml.

change theme

8cebc5e

ci: add workflow to build Sphinx docs and PR to gh-pages

3cf02f6

On push to master, builds Sphinx HTML and opens a PR from docs-update into gh-pages so the generated API reference can be reviewed before going live. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

jacalata mentioned this pull request Jul 28, 2026

feat: consolidate and export public type aliases (HyperAction, FilePath, AddResponse, IDP types) #1825

Open

2 tasks

jacalata and others added 2 commits July 28, 2026 00:21

Merge origin/development into jac/docs-sphinx-readthedocs

f0f4f2f

This was referenced Jul 30, 2026

[Discussion] Docs rewrite #1451

Open

Update docs for users.populate_favorites #958

Closed

jacalata enabled auto-merge (squash) August 6, 2026 21:22

jacalata requested a lite review from Copilot August 6, 2026 21:22

Copilot started reviewing on behalf of jacalata August 6, 2026 21:23 View session

Copilot AI reviewed Aug 6, 2026

View reviewed changes

Comment thread .readthedocs.yaml

Comment thread docs/index.rst Outdated

Comment on lines +4 to +7

.. toctree::

:maxdepth: 2

:caption: Contents:

Comment thread .github/workflows/docs.yml Outdated

docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference by jacalata · Pull Request #1832 · tableau/server-client-python · GitHub

Uh oh!

docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference - #1832

docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference#1832
jacalata wants to merge 9 commits into
developmentfrom
jac/docs-sphinx-readthedocs

jacalata commented Jul 28, 2026 •
edited
Loading

Uh oh!

Uh oh!

github-actions Bot commented Jul 28, 2026 •
edited
Loading

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

+              .. toctree::
+                 :maxdepth: 2
+                 :caption: Contents:

docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference by jacalata · Pull Request #1832 · tableau/server-client-python · GitHub

Uh oh!

docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference - #1832

docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference#1832jacalata wants to merge 9 commits intodevelopmenttableau/server-client-python:developmentfrom jac/docs-sphinx-readthedocstableau/server-client-python:jac/docs-sphinx-readthedocsCopy head branch name to clipboard

Conversation

jacalata commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation

Behavior change

Test plan

Uh oh!

github-actions Bot commented Jul 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference#1832
jacalata wants to merge 9 commits into
developmentfrom
jac/docs-sphinx-readthedocs

jacalata commented Jul 28, 2026 •
edited
Loading

github-actions Bot commented Jul 28, 2026 •
edited
Loading