docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference - #1832
Open
jacalata wants to merge 8 commits into
Open
docs: set up Sphinx + ReadTheDocs pipeline for auto-generated API reference#1832jacalata wants to merge 8 commits into
jacalata wants to merge 8 commits into
Conversation
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>
2 tasks
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>
There was a problem hiding this comment.
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.rstthat documents the top-leveltableauserverclientmodule. - Adds Read the Docs configuration and a GitHub Actions workflow that builds docs and opens an automated PR into
gh-pages/sphinx/. - Adds a
docsoptional-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.
Comment on lines
+13
to
+25
| # Build documentation in the "docs/" directory with Sphinx | ||
| sphinx: | ||
| configuration: docs/conf.py | ||
|
|
||
| # Optionally, but recommended, | ||
| # declare the Python requirements required to build your documentation | ||
| # See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html | ||
| python: | ||
| install: | ||
| - method: pip | ||
| path: . | ||
| extra_requirements: | ||
| - docs |
Comment on lines
+4
to
+7
| .. toctree:: | ||
| :maxdepth: 2 | ||
| :caption: Contents: | ||
|
|
Comment on lines
+27
to
+28
| - name: Install docs dependencies | ||
| run: pip install -e ".[docs]" |
2 tasks
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
api-ref.mdongh-pagesis the canonical reference doc today. It'shand-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 thepipeline 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.13docs/conf.py-- Sphinx config; reads project details frompyproject.toml; furo themedocs/index.rst--automodulewith:members: :imported-members:so re-exports from
__init__.pyrender (without:imported-members:the output was nearly empty)
.github/workflows/docs.yml-- triggers onpush: branches: [master],builds Sphinx, opens a PR into
gh-pagesatsphinx/. Usesconcurrency: docs-publishto serialize runspyproject.toml-- addsdocs = ["sphinx>=7,<9", "furo>=2024,<2027", "tomli; python_version < '3.11'"]optional-deps groupAlso incidentally: small docstring cleanups in
connection_item.pyandsite_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-build -b html docs sphinx_build) -- 3000-line index with allre-exports rendering. One benign warning about a duplicate
UserItem.idp_configuration_idobject description (pre-existingproperty+setter shape).
.readthedocs.yaml-- not exercised untilthe PR merges and RTD picks up the config
.github/workflows/docs.ymlruntime not exercised until this ison
master🤖 Generated with Claude Code