Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Standardize header syntax within About section #10369

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

tetrapod00
Copy link
Contributor

@tetrapod00 tetrapod00 commented Dec 4, 2024

This is a proof of concept, before making changes to the whole online documentation.

This standardizes our RST header syntax as follows:

Page title
==========
Renders as h1. Every page has this.

Header
------
Renders as h2. Usually appears in sidebar. Many pages only need one level of nested headers.

Sub-header
~~~~~~~~~~
Renders as h3. Appears in sidebar in some pages, depending on how deeply nested the *page* is.

Sub-sub-header
^^^^^^^^^^^^^^
Renders as h4. Usually won't appear in the sidebar.

Sub-sub-sub-header
""""""""""""""""""
Renders as h5. If you got this far something went wrong. I'm not actually sure if we have any 5-layer header nesting in the docs.

Feel free to bikeshed the syntax order here, if you care. =, -, ~ is fairly common, but so is =, -, ^. """ is rarely used, but it does follow ^^^ when it is used. +++ is occasionally used.

Edit: after going through a lot more pages, =, -, ^ is common on pages with only 3 heading levels, but on pages with four heading levels, =, -, ~, ^ is standard, and =, -, ^, ~ or any variant is almost never used. So I think my original guideline is still correct.

Note that RST assigns headers based on the order they appear, within a particular page. So this PR will not change the header level of any existing pages. It only standardizes our syntax. This also means that this PR is not a one-to-one replacement of particular characters with other particular characters. It depends on the existing page!

Approval of this PR indicates the header syntax that I will standardize the rest of the docs with, in #10370.

@tetrapod00 tetrapod00 added area:about Issues and PRs related to the About section of the documentation and other general articles content:proofreading Issues and PRs related to proofreading the documentation labels Dec 4, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
area:about Issues and PRs related to the About section of the documentation and other general articles content:proofreading Issues and PRs related to proofreading the documentation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant