Repository navigation
Fix docs pages listing their sections as separate pages in the sidebar - #75478
Merged
Merged
Conversation
Eight pages underlined a later section like the page title, so Sphinx treated it as another top-level title and listed it in the sidebar as its own page. Demote each extra title and its subsections one level. metric_tables.rst is included under Metric Descriptions and shares its heading levels, so the generator now writes its headings one level deeper to stay nested.
shahar1
approved these changes
Oct 23, 2026
potiuk
approved these changes
Oct 23, 2026
Contributor
|
Hi maintainer, this PR was merged without a milestone set.
|
Contributor
Backport successfully created: v3-4-testNote: As of Merging PRs targeted for Airflow 3.X In matter of doubt please ask in #release-management Slack channel.
|
kaxil
added a commit
that referenced
this pull request
Oct 23, 2026
…n the sidebar (#75478) (#75481) Eight pages underlined a later section like the page title, so Sphinx treated it as another top-level title and listed it in the sidebar as its own page. Demote each extra title and its subsections one level. metric_tables.rst is included under Metric Descriptions and shares its heading levels, so the generator now writes its headings one level deeper to stay nested. (cherry picked from commit b7dfaf6) Co-authored-by: Kaxil Naik <kaxilnaik@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Eight docs pages had a second (or third) section underlined like the page title. RST reads those as extra top-level titles, and Sphinx lists each one in the sidebar as if it were its own page. In How-to Guides, for example, "Configuring local settings", "Using Notifiers", "Support for Airflow 2 plugins" and "Adding Dashboard Alert Messages" appear as separate pages. This is the same problem #75468 fixed for the upgrade guide, and sphinx-airflow-theme 0.3.15 (#75471) cannot hide it: its pages-only sidebar still shows every top-level title of a page.
Each extra title moves down one level, and every heading under it moves down one level too, so the structure inside each section is unchanged. Only underline characters change, so existing
:ref:labels and anchors keep working.howto/set-config.rsthowto/notifications.rsthowto/custom-view-plugin.rsthowto/customize-ui.rsthowto/create-custom-decorator.rstcore-concepts/debug.rstadministration-and-deployment/dagfile-processing.rstadministration-and-deployment/logging-monitoring/metrics.rstSidebar from local
breezedocs builds with sphinx-airflow-theme 0.3.15. The highlighted entries in "Before" are section titles shown as pages:Why
metrics_registry.pychanges.metrics.rstincludesmetric_tables.rst, which is generated at build time, and an included file shares the parent page's heading levels. Its "Counters", "Gauges" and "Timers" headings used-, the level "Metric Descriptions" now takes, so they would have become its siblings. The generator now writes them with^, which keeps them nested under "Metric Descriptions".I found the pages by parsing every
.rstunderairflow-core/docswith docutils and counting top-level sections.index.rststill has several, which is fine: it is the root page, so its sections never appear as sidebar entries.