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>
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
1 participant
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.
Summary
Introduces Sphinx + ReadTheDocs alongside the existing Jekyll site on gh-pages.
Long-term goal is to replace
api-ref.mdon gh-pages. Keepingapi-ref.mdin sync with the code is currently manual and dev-driven; Sphinx auto-generates the same content from docstrings, giving devs a smoother update path (write docstrings, docs regenerate). Concepts and tutorials stay in Jekyll.Not surfacing this in the Jekyll site yet -- docstring coverage across the models package is too thin for the generated reference to be an improvement over the current
api-ref.md. Merging the pipeline now unblocks incremental docstring work without a public-facing rush.What's included
.readthedocs.yaml-- RTD build config (Python 3.13)docs/conf.py-- Sphinx config; reads project details frompyproject.toml; usesfurothemedocs/index.rst--automodulewith:members: :imported-members:so re-exports fromtableauserverclient/__init__.pyrender (without:imported-members:the output was nearly empty).github/workflows/docs.yml-- triggers onpush: branches: [master], builds Sphinx, opens an automated PR intogh-pagesatsphinx/. Usesconcurrency: docs-publishto serialize runs,delete-branch: trueandfetch-depth: 0so unmerged prior PR review comments don't get strandedpyproject.toml-- addsdocs = ["sphinx>=7,<9", "furo>=2024,<2027", "tomli; python_version < '3.11'"]optional-deps group.tomliis only needed by Python 3.10 users building docs locally; the workflow and RTD both pin 3.13connection_item.py,job_item.py,site_item.py,task_item.py(side effect of the initial Sphinx pass;id_docstring parameters kept asid_to match the actual constructor signature)Notes for reviewers
master, notdevelopment. Docs regen only on the release-to-public branch; PRs and dev-branch churn don't rebuild.gh-pages/sphinx/, but the Jekyll site has no links to that path yet. Once docstring coverage is good enough to surface, we add nav links to the Jekyll templates.Test plan
sphinx-build -b html docs sphinx_build) -- 3000-line index with all re-exports rendering. One benign warning about a duplicateUserItem.idp_configuration_idobject description (pre-existing property+setter shape)..readthedocs.yaml.github/workflows/docs.ymlruntime not exercised until this is onmaster🤖 Generated with Claude Code