kaxil opened a new pull request, #73548:
URL: https://github.com/apache/airflow/pull/73548
After #73523 and #73542 the `common.ai` sidebar lists about fifty pages flat
under nine captions, and most labels are class names (`LLMBranchOperator`,
`HookToolset`), so a reader has to know the API to pick a page. Every toctree
also carried `:maxdepth: 1`, which stopped the Airflow theme from rendering
nested pages at all: the sandbox configuration and backends pages, and the MCP
connection and hook pages, were reachable only from inside their parent page.
This PR turns the sidebar into the shape the Pydantic AI docs use. Basics
and Getting started (installation, quick start, core concepts) stay flat; below
them sit seven expandable guides: What you can build, Models and providers,
Operators, Toolsets, LLM and agent features, Document and RAG pipelines, and
Reliability and operations. Each guide is a page that lists its children, and
the theme expands the branch the reader is in, down to a third level for MCP
servers and sandboxed execution under Toolsets. Labels lead with the feature
("Branch on an answer", "Airflow hooks as tools") and page titles carry both
the feature and the class name, so search and the API reference still find the
class.
A new supported-providers page maps each vendor to its model prefix, extra,
connection type and credential location, including Snowflake Cortex, and links
each vendor to an anchored example on the connection reference. The classifier
models page now links TypeSafe's site and documentation.
## Design rationale
**The theme already supports the nested tree; the provider was suppressing
it.** `sphinx_airflow_theme` renders `toctree(collapse=True)` and expands the
current branch with CSS, exactly as the core Airflow docs use it. Our
`:maxdepth: 1` capped the global tree at one level, and without `:titlesonly:`
the sidebar would list each page's section headings as extra levels. Both are
set on every toctree now. What the theme does not support is click-to-expand of
inactive branches, which is why each parent page also lists its children in the
body.
**Core concepts is an overview under Getting started, not a container.**
Structured output, message history, guardrails, code mode and the two review
pages are feature guides, and a reader looking for human approval would not
look under "concepts". They live under "LLM and agent features", with the
review pages labelled "Approve outputs" and "Review agent sessions" so the
distinction is visible in the sidebar.
**Sandboxed execution moved under Toolsets.** It is `SandboxToolset`, and
the Pydantic AI docs place their sandbox under tools and capabilities rather
than at the top level.
**Provider fallback is listed under both Models and providers and
Reliability and operations.** It is configured on the connection, but a reader
handling a provider outage looks under operations. The page has one home in the
toctree and a cross-linking bullet in the other.
## Gotchas
- No page moves or renames, so no new redirects. The three URLs the Pydantic
AI durable-execution guide deep-links are unchanged.
- The System tests and Resources toctrees are left byte-for-byte as the
`check-system-tests-tocs` hook requires.
- The generated supported-services page from #72939 belongs under Models and
providers when it lands; the hand-written providers page here is the how-to and
can link to it.
<img width="307" height="859" alt="image"
src="https://github.com/user-attachments/assets/8e909390-6ff2-4dc0-b564-2be64e80482a";
/>
<img width="1014" height="840" alt="image"
src="https://github.com/user-attachments/assets/f8c0e3da-e31e-4976-830a-5ba7df004b38";
/>
---
* Read the **[Pull Request
Guidelines](https://github.com/apache/airflow/blob/main/contributing-docs/05_pull_requests.rst#pull-request-guidelines)**
for more information. Note: commit author/co-author name and email in commits
become permanently public when merged.
* For fundamental code changes, an Airflow Improvement Proposal
([AIP](https://cwiki.apache.org/confluence/display/AIRFLOW/Airflow+Improvement+Proposals))
is needed.
* When adding dependency, check compliance with the [ASF 3rd Party License
Policy](https://www.apache.org/legal/resolved.html#category-x).
* For significant user-facing changes create newsfragment:
`{pr_number}.significant.rst`, in
[airflow-core/newsfragments](https://github.com/apache/airflow/tree/main/airflow-core/newsfragments).
You can add this file in a follow-up commit after the PR is created so you
know the PR number.
--
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]
