Normalize heading underlines in docs/reference/#2663
Merged
Conversation
pankajkoti
changed the title
Contributor
There was a problem hiding this comment.
Pull request overview
Normalizes reStructuredText heading underline characters across docs/reference/ to match the style-guide hierarchy (= title, ~ H1, + H2, ^ H3), keeping heading text and underline lengths unchanged.
Changes:
- Updated page titles and section headings in
docs/reference/index.rstanddocs/reference/configs/*.rstto use the canonical underline characters. - Updated the
profile_mapping.rst.jinja2template so generated profile pages emit the canonical H1 underline for the “Default values” section.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| docs/reference/templates/profile_mapping.rst.jinja2 | Switches the “Default values” heading underline to the canonical H1 character. |
| docs/reference/index.rst | Updates the page title and the “Configurations” / “Profiles” H1 underline characters. |
| docs/reference/configs/project-config.rst | Updates the page title and the “Project config example” heading underline characters. |
| docs/reference/configs/profile-config.rst | Updates the page title underline character. |
| docs/reference/configs/execution-config.rst | Updates the page title underline character. |
| docs/reference/configs/cosmos-conf.rst | Updates the page title and section heading underline characters. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
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/configs/ used a mix of - and + 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.
Extend the underline-character remap from the prior commit to the rest of docs/reference/: - docs/reference/index.rst: remap the "Reference" page title from - to = and the "Configurations"/"Profiles" H1s from + to ~. - docs/reference/templates/profile_mapping.rst.jinja2: remap the "Default values" subheading from - to ~, so the generated profile pages (Snowflake variants, etc.) use the canonical H1 underline. docs/reference/glossary.rst and the "Profile mapping reference" title in templates/index.rst.jinja2 already use =, so no changes there. Underline lengths and heading text are unchanged; only the underline character is swapped.
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
pankajkoti
force-pushed
the
style-guide-underlines-reference-configs
branch
from
d387409 to
8901ecb
Compare
tatiana
approved these changes
May 12, 2026
Collaborator
tatiana
left a comment
tatiana
left a comment
There was a problem hiding this comment.
Thanks for making our docs adherent to the style guide, @pankajkoti !
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/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 "Defaultvalues" subheading, so the generated profile pages (Snowflake variants,
etc.) emit the canonical H1 underline.
docs/reference/profiles/*.rstis gitignored and regenerated from this template at docs build time.
docs/reference/glossary.rstand the "Profile mapping reference" titlein
templates/index.rst.jinja2already 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
Breaking Change?
No. Documentation only.