potiuk opened a new pull request, #70957:
URL: https://github.com/apache/airflow/pull/70957
Publishing the provider docs has failed since 2026-07-28. The last green run
built with no `--python` flag; every run since passes `--python 3.12`. Nothing
in the repo changed — only four commits sit between the last green and first
red run (INTHEWILD.md, a secrets-backend change, a UI toggle, Helm docs). Two
independent problems surface only on 3.12.
### 1. Samba fails to import, so the provider cannot be documented at all
Python 3.12 added `__type_params__` to `functools.WRAPPER_ASSIGNMENTS`.
`smbclient` is in `autodoc_mock_imports`, and a Sphinx mock returns another
mock for that attribute rather than a tuple, so `functools` refuses the
assignment:
```
File ".../samba/hooks/samba.py", line 114, in SambaHook
@wraps(smbclient.link)
File "/usr/python/lib/python3.12/functools.py", line 56, in update_wrapper
setattr(wrapper, attr, value)
TypeError: __type_params__ must be set to a tuple
```
Every `SambaHook` method wraps an `smbclient` callable, so the module dies
at class-definition time. This is **not** a Sphinx regression — it reproduces
identically on Sphinx 8.2.3, 9.0.4 and 9.1.0.
All 24 wrapped methods now go through a helper that copies everything
`functools` normally copies **except** `__type_params__`. None of the wrapped
callables are PEP 695 generics, so nothing is lost — verified that `__doc__`,
`__name__` and `__wrapped__` are still inherited from `smbclient` when it is
not mocked.
### 2. Thirteen ambiguous cross-references
`amazon`, `google` and `openlineage` raise "more than one target found for
cross-reference" where two documented classes share a member name — `object` is
a documented parameter of both `GCSObjectExistenceSensor` and
`GCSObjectUpdateSensor`, `CommandType` exists in both the ECS and Lambda
executor utils, and so on.
These references live in autoapi-**generated** rst, so there is no place to
write a qualified name, and the duplication is legitimate.
`autodoc_typehints_format` does not help: most of these are `:param` names, not
type annotations. Sphinx exposes no subtype narrower than `ref.python` for this
message.
**Reviewers should weigh this trade-off:** suppressing `ref.python` also
means a genuinely unresolvable python reference will no longer fail the docs
build. If that is unacceptable, the alternative is leaving the docs build red
until each duplicate member name is renamed, which is a much larger change
across three providers.
---
##### Was generative AI tooling used to co-author this PR?
- [X] Yes — Claude Code (Opus 5)
Generated-by: Claude Code (Opus 5) following [the
guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
