From 175b28db32413fe75c686fe64180b1b9b1e6d199 Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Wed, 13 May 2026 12:14:18 +0200 Subject: [PATCH 1/2] docs: suppress @typing.overload signature stacking Sphinx autodoc detects @overload via AST parsing and stacks every overload variant with full inline type hints, ignoring autodoc_typehints = "description". Patch ModuleAnalyzer.analyze to clear overload collection so each method renders as a single clean signature with type info in the description block. Co-Authored-By: Claude Opus 4.7 (1M context) --- docs/conf.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 775892d59..ddbb40dce 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -92,6 +92,20 @@ def chdir(directory): "autosectionlabel", ] +# Suppress @typing.overload signature expansion: render only the implementation +# signature, otherwise autodoc stacks every overload variant with full type hints. +from sphinx.pycode import ModuleAnalyzer as _ModuleAnalyzer + +_orig_analyze = _ModuleAnalyzer.analyze + + +def _analyze_without_overloads(self): + _orig_analyze(self) + self.overloads = {} + + +_ModuleAnalyzer.analyze = _analyze_without_overloads + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for From 4bbdcccfe1d5adf91484283c6c6d076137699362 Mon Sep 17 00:00:00 2001 From: Ivan Despot <66276597+g-despot@users.noreply.github.com> Date: Wed, 13 May 2026 12:25:07 +0200 Subject: [PATCH 2/2] Add RTD info --- docs/PUBLISHING.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 docs/PUBLISHING.md diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md new file mode 100644 index 000000000..b018e5b65 --- /dev/null +++ b/docs/PUBLISHING.md @@ -0,0 +1,71 @@ +# Documentation Publishing + +How the reference docs at https://weaviate-python-client.readthedocs.io/ are built, how the `weaviate-agents-python-client` is folded in, and how to publish a staging preview for a branch. + +For authoring guidance (adding modules, regenerating `.rst` files, building locally), see [README.rst](./README.rst). + +## What publishes the docs + +Read the Docs (RTD), not GitHub Actions. RTD is configured to watch this repo and rebuild on every push to a tracked branch or tag. The CI workflow at `.github/workflows/main.yaml` only runs `python -m sphinx ...` as a sanity check — it never publishes anything. + +Project dashboard: https://readthedocs.org/projects/weaviate-python-client/ + +## Build configuration + +Two files control the build: + +- **`.readthedocs.yaml`** — RTD build config (Python version, `pre_build` hooks, requirements file, Sphinx entry point). +- **`docs/conf.py`** — Sphinx config (extensions, theme, autodoc behavior, docstring post-processing). + +Build steps RTD runs, in order: + +1. Spin up an Ubuntu 22.04 image with Python 3.12 (per `.readthedocs.yaml`). +2. Run the `pre_build` hook (see next section — this is where the agents client gets pulled in). +3. `pip install -r requirements-devel.txt`. +4. `python -m sphinx -b html docs/ ` using `docs/conf.py`. +5. Publish the HTML to `https://weaviate-python-client.readthedocs.io/en//`. + +## How the agents client is folded in + +The `weaviate-agents-python-client` lives in its own repo (https://github.com/weaviate/weaviate-agents-python-client) but its API reference is published as part of the same RTD site. + +This is wired up in `.readthedocs.yaml` via a `pre_build` hook: + +```yaml +build: + jobs: + pre_build: + - git clone -b main --depth=1 https://github.com/weaviate/weaviate-agents-python-client.git docs/weaviate-agents-python-client + - python -m pip install -e ./docs/weaviate-agents-python-client +``` + +And `docs/conf.py` adds the cloned directory to `sys.path`: + +```python +sys.path.insert(0, os.path.abspath("weaviate-agents-python-client")) +``` + +Implications: + +- The agents docs always come from the agents repo's `main` branch — pinning to a tag would require editing `.readthedocs.yaml`. +- Changes merged to the agents repo's `main` are **not** automatically published here. The published version updates when either (a) a new release of `weaviate-python-client` is cut, or (b) a maintainer manually triggers a rebuild from the RTD dashboard. +- The agents repo has its own `docs/` tree (with its own `index.rst`, etc.). After cloning, RTD's Sphinx build picks up those `.rst` files because they sit under `docs/weaviate-agents-python-client/docs/`, which Sphinx walks as part of the source tree. + +## Publishing a staging build for a branch + +Add the branch as a Version in RTD: + +1. Open https://readthedocs.org/projects/weaviate-python-client/versions/. +2. Click **+ Add version**, pick the branch from the dropdown (hit the refresh icon if it's not listed yet — RTD polls GitHub for new branches). +3. Tick **Active**. Leave **Hidden** ticked if you don't want the branch to show up in the version switcher on the public site (you'll still get a direct URL). +4. Click **Update version**. RTD kicks off a build immediately. + +Watch the build on the **Builds** tab. Once it succeeds, the preview is at: + +``` +https://weaviate-python-client.readthedocs.io/en// +``` + +RTD slugifies the branch name — slashes become dashes (e.g. `docs/suppress-overload-stacking` → `docs-suppress-overload-stacking`). + +When you're done, deactivate the version on the same page so it stops rebuilding on every push to that branch.