Normalize heading underlines in policy docs#2656
Merged
Merged
Conversation
Per the lightweight style guide proposed in #2460, RST heading underlines should follow the canonical hierarchy: - Page title: = - H1: ~ - H2: + - H3: ^ The pages under docs/policy/ used a mix of -/+/' for those levels. Remap them positionally per file (first level encountered becomes =, second becomes ~, etc.) so the rendered hierarchy matches the convention. Underline lengths and heading text are unchanged; only the underline character is swapped.
Contributor
Author
|
I have manually compared and confirmed the before-and-after and see no regression in the built docs. |
Contributor
There was a problem hiding this comment.
Pull request overview
Normalizes reStructuredText heading underline characters across the docs/policy/ documentation set to match the proposed documentation style hierarchy (title/H1/H2/H3), continuing prior normalization work in other doc areas.
Changes:
- Updated page titles to use
=underlines. - Remapped section/subsection underline characters to the canonical set (
~,+) across policy documents. - Kept heading text and underline lengths unchanged while swapping underline characters.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/policy/index.rst | Updates the policy index page title underline to =. |
| docs/policy/policies.rst | Normalizes underline characters for the page title and top-level sections. |
| docs/policy/security.rst | Normalizes underline characters for the page title and sections. |
| docs/policy/contributors.rst | Normalizes underline characters for the page title and sections. |
| docs/policy/contributors-roles.rst | Normalizes underline characters for the page title/sections and a subsection. |
| docs/policy/contributing.rst | Normalizes underline characters across multiple section levels within the contributing guide. |
| docs/policy/compatibility-policy.rst | Normalizes underline characters across the policy and its subsections. |
| docs/policy/airflow3-compatibility.rst | Normalizes underline characters for the page title and sections. |
Comments suppressed due to low confidence (1)
docs/policy/contributors-roles.rst:17
- Use the canonical "GitHub" capitalization in brand references (currently "Github").
Cosmos contributors can be found in the Astronomer Cosmos Github `insights page <https://github.com/astronomer/astronomer-cosmos/graphs/contributors>`_ and in the `#airflow-dbt <https://join.slack.com/t/apache-airflow/shared_invite/zt-1zy8e8h85-es~fn19iMzUmkhPwnyRT6Q>`_ Slack channel.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- contributing.rst: convert the four H3 subsections under "Working
with Hatch" from `.` underlines to `^` so they conform to the
canonical hierarchy declared in the PR.
- contributing.rst: GitHub brand fixes ("we use a Hatch" → "we use
Hatch", "GitHub actions" → "GitHub Actions").
- contributors.rst, contributors-roles.rst: spell GitHub the
canonical way (was "Github") and rephrase "project contributors
roles" to use the possessive "contributors'".
pankajastro
approved these changes
May 11, 2026
This was referenced May 12, 2026
tatiana
pushed a commit
that referenced
this pull request
May 12, 2026
Per the lightweight style guide proposed in #2460, RST heading underlines should follow the canonical hierarchy: - Page title: `=` - H1: `~` - H2: `+` - H3: `^` The pages under `docs/reference/` used a mix of `-`/`+` for those levels. Remap them positionally per file (first level encountered becomes `=`, second becomes `~`, etc.) so the rendered hierarchy matches the convention. Underline lengths and heading text are unchanged; only the underline character is swapped. Scope of this PR: - `docs/reference/configs/` — `cosmos-conf.rst`, `execution-config.rst`, `profile-config.rst`, `project-config.rst`. - `docs/reference/index.rst` — page title and the two H1 sections. - `docs/reference/templates/profile_mapping.rst.jinja2` — the "Default values" subheading, so the generated profile pages (Snowflake variants, etc.) emit the canonical H1 underline. `docs/reference/profiles/*.rst` is gitignored and regenerated from this template at docs build time. `docs/reference/glossary.rst` and the "Profile mapping reference" title in `templates/index.rst.jinja2` already use `=`, so they are unchanged. Continues the underline-normalization work from #2641 (`getting_started/`), #2655 (`optimize_performance/`), and #2656 (`policy/`). ## Related Issue(s) Refs #2460 --------- Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
tatiana
pushed a commit
that referenced
this pull request
May 12, 2026
Per the lightweight style guide proposed in #2460, RST heading underlines should follow the canonical hierarchy: - Page title: `=` - H1: `~` - H2: `+` - H3: `^` The pages under `docs/guides/` and the top-level `docs/index.rst` used a mix of `-`/`+`/`'`/`.` for those levels. Remap them positionally per file (first level encountered becomes `=`, second becomes `~`, third becomes `+`, fourth becomes `^`) so the rendered hierarchy matches the convention. Underline lengths and heading text are unchanged; only the underline character is swapped. Scope of this PR: - `docs/guides/connect_database/` (4 files) - `docs/guides/cosmos_devex/` (4 files) - `docs/guides/dbt_docs/` (2 files) - `docs/guides/dbt_setup/` (2 files) - `docs/guides/multi_project/` (1 file) - `docs/guides/run_dbt/airflow-worker/` (5 files) - `docs/guides/run_dbt/callbacks/` (1 file) - `docs/guides/run_dbt/container/` (8 files) - `docs/guides/run_dbt/customization/` (4 files) - `docs/guides/run_dbt/operators/` (4 files) - `docs/guides/run_dbt/execution-modes.rst`, `run_dbt/index.rst` (2 files) - `docs/guides/translate_dbt_to_airflow/` (6 files) - `docs/guides/index.rst` (1 file) - `docs/index.rst` (1 file) Wraps up the underline-character slice of the header commit in #2462 across the remaining `docs/` subtrees. Continues the work from #2641 (`getting_started/`), #2655 (`optimize_performance/`), #2656 (`policy/`), and #2663 (`reference/`). ## Related Issue(s) Refs #2460
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.
Description
Per the lightweight style guide proposed in #2460, RST heading underlines
should follow the canonical hierarchy:
=~+^The pages under
docs/policy/used a mix of-/+/'for those levels.Remap them positionally per file (first level encountered becomes
=, secondbecomes
~, etc.) so the rendered hierarchy matches the convention. Underlinelengths and heading text are unchanged; only the underline character is
swapped.
Continues the underline-normalization work from #2641 (
getting_started/)and #2655 (
optimize_performance/).Related Issue(s)
Refs #2460
Breaking Change?
No. Documentation only.
Checklist