kaxil opened a new pull request, #75483: URL: https://github.com/apache/airflow/pull/75483
The "On this page" contents on the CLI reference pages are hard to use. sphinx-argparse turns every sub-command and each of its argument groups into a section, so the right-hand contents for the `airflow` CLI listed 290 entries, 172 of them a repeated "Named Arguments" (97), "Positional Arguments" (59) or "Sub-commands" (16). You cannot tell which "Named Arguments" belongs to which command, and the list is about 10,000px tall. This adds `:tocdepth: 4` to the `airflow` and `airflowctl` CLI reference pages, so the contents stop at the top-level commands (`api-server`, `assets`, `backfill`, ...). The page itself is unchanged: every sub-command and argument group is still there, along with its anchor. The `airflow` contents drop from 290 entries to 32, and `airflowctl` from 291 to 21. sphinx-argparse 0.6.1 has no option to emit these groups as anything other than sections, so the page-level depth is the narrowest fix. **Why the field sits above the license header.** Sphinx reads file-wide metadata only from a field list that comes before any content. Airflow's license header starts with a space, so docutils parses it as a block quote, which counts as content. Below the license, the field rendered as a visible "tocdepth: 4" line on the page. Directly above it, the indented license was read as part of the field's value, so Sphinx's `int()` failed and silently fell back to no limit. The empty `..` comment ends the field and makes the license that comment's body, which is not rendered. The RST license hook still finds the header. -- 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]
