You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@airflow.apache.org by "shahar1 (via GitHub)" <gi...@apache.org> on 2026/10/03 15:30:49 UTC
[PR] Fix docstring cross-references that Sphinx 9 cannot resolve [airflow]
shahar1 opened a new pull request, #74169:
URL: https://github.com/apache/airflow/pull/74169
related: #74151
related: #74168
<details><summary>AI Summary</summary>
Moving the docs build to Python 3.11 (#74151) moves it from Sphinx 8.1.3 to Sphinx 9.0.4, which resolves annotation and field types project-wide. That turns a few long-standing docstring mistakes into ambiguous or broken references that fail the docs and spellcheck jobs:
- **google `vertex_ai/auto_ml.py`**: `:param budget_milli_node_hours (int):` is not a valid field; Sphinx read `budget_milli_node_hours` as a type name and matched the operators' attributes of that name.
- **google `compute.py`**: three methods documented `:rtype: object` although their signatures already return `InstanceTemplate`, `Instance` and `InstanceGroupManager`; the field is removed so the real annotation is rendered. The two class names are added to the spelling wordlist next to the other Compute class names.
- **amazon `executors/batch/utils.py`**: `CommandType` and the alias target `WorkloadKey` matched the same-named aliases in the ECS and Lambda executors. `CommandType` is now annotated as a `TypeAlias` like theirs (so it resolves in its own module), and the core `WorkloadKey` is imported as `_WorkloadKey`, the pattern the Lambda executor already uses.
- **task-sdk `deferred-vs-async-operators.rst`**: `:doc:` used an `airflow:` inventory prefix that does not exist; every other cross-package link uses `apache-airflow:`.
The builtin `type`/`object` warnings are an upstream Sphinx regression and are handled in #74168.
Checks run: with both PRs applied, `--docs-only` for amazon, google, openlineage and task-sdk passes on Python 3.11 / Sphinx 9.0.4, and google spellcheck passes; Breeze mypy on the changed amazon and google modules passes on Python 3.11.
</details>
---
##### Was generative AI tooling used to co-author this PR?
- [X] Yes — Claude Code (Opus 5.5)
Generated-by: Claude Code (Opus 5.5) following [the guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#gen-ai-assisted-contributions)
🤖 Generated with [Claude Code](https://claude.com/claude-code)
https://claude.ai/code/session_01SkLWWaTT1cnFqTT1jhFGxe
--
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: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix docstring cross-references that Sphinx 9 cannot resolve [airflow]
Posted by "potiuk (via GitHub)" <gi...@apache.org>.
potiuk commented on code in PR #74169:
URL: https://github.com/apache/airflow/pull/74169#discussion_r4177982954
##########
providers/amazon/src/airflow/providers/amazon/aws/executors/batch/utils.py:
##########
@@ -29,14 +29,14 @@
from airflow.providers.amazon.version_compat import AIRFLOW_V_3_3_PLUS
if AIRFLOW_V_3_3_PLUS:
- from airflow.executors.workloads.types import WorkloadKey
+ from airflow.executors.workloads.types import WorkloadKey as _BatchWorkloadKey
- BatchJobWorkloadKey: TypeAlias = WorkloadKey
+ BatchJobWorkloadKey: TypeAlias = _BatchWorkloadKey
Review Comment:
It's a bitch catch 22. We could do it at once when migrating to 3.11 and new sphinx, but that would make the 3.11 migration bigger and spanning more stuff. This one is needed to support both 3.10 j+ sphinx 8 as well as 3.11 + Sphinx 9
> It's purely a Sphinx workaround; at runtime nothing changes. The rename has to satisfy both docs builds at once (Python 3.10 / Sphinx 8.1.3 and Python 3.11 / Sphinx 9.0.4):
Sphinx 9 (why it can't stay WorkloadKey). Sphinx 9 resolves annotation types project-wide. When autodoc renders BatchJobWorkloadKey: TypeAlias = WorkloadKey, the bare name WorkloadKey matches the same-named aliases documented in the ECS and Lambda executor modules. That gives an ambiguous cross-reference, which fails the docs job. CommandType had the same problem, which is why it also became an explicit TypeAlias.
Sphinx 8 (why it can't be _WorkloadKey). Sphinx 8 registers the canonical target of a documented type alias as an object of its own. The Lambda executor already imports the core type as _WorkloadKey, so reusing that name in batch would produce the same canonical name twice. That causes a "duplicate object description" failure, which only shows up on 3.10. This is what the second commit fixed.
So the import needs a name that is unique per module. _BatchWorkloadKey follows the pattern the ECS executor already uses with _EcsWorkloadKey.
I guess we can remove it after we migrate to 3.11.
--
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: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix docstring cross-references that Sphinx 9 cannot resolve [airflow]
Posted by "ashb (via GitHub)" <gi...@apache.org>.
ashb commented on code in PR #74169:
URL: https://github.com/apache/airflow/pull/74169#discussion_r4177840516
##########
providers/amazon/src/airflow/providers/amazon/aws/executors/batch/utils.py:
##########
@@ -29,14 +29,14 @@
from airflow.providers.amazon.version_compat import AIRFLOW_V_3_3_PLUS
if AIRFLOW_V_3_3_PLUS:
- from airflow.executors.workloads.types import WorkloadKey
+ from airflow.executors.workloads.types import WorkloadKey as _BatchWorkloadKey
- BatchJobWorkloadKey: TypeAlias = WorkloadKey
+ BatchJobWorkloadKey: TypeAlias = _BatchWorkloadKey
Review Comment:
Why's this needed?
--
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: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] Fix docstring cross-references that Sphinx 9 cannot resolve [airflow]
Posted by "shahar1 (via GitHub)" <gi...@apache.org>.
shahar1 merged PR #74169:
URL: https://github.com/apache/airflow/pull/74169
--
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: commits-unsubscribe@airflow.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org