Skip to content

Lint: fixup subsubsection markups #1239

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

Merged
merged 2 commits into from
Dec 6, 2023

Conversation

erlend-aasland
Copy link
Contributor

@erlend-aasland erlend-aasland commented Dec 6, 2023

Consistently use ^ iso. ' markups for subsubsections


📚 Documentation preview 📚: https://cpython-devguide--1239.org.readthedocs.build/

Consistently use ^ iso. ' markups for subsubsections
@erlend-aasland
Copy link
Contributor Author

Discovered over at #1238.

@hugovk
Copy link
Member

hugovk commented Dec 6, 2023

For reference, the suggested convention is at https://devguide.python.org/documentation/markup/#sections

Normally, there are no heading levels assigned to certain characters as the structure is determined from the succession of headings. However, for the Python documentation, here is a suggested convention:

  • # with overline, for parts
  • * with overline, for chapters
  • =, for sections
  • -, for subsections
  • ^, for subsubsections
  • ", for paragraphs

For this file, are we starting at =, then - and ^?

@erlend-aasland
Copy link
Contributor Author

For this file, are we starting at =, then - and ^?

For which file?

@ezio-melotti
Copy link
Member

For which file?

This PR updates the headings of 8 files and, if the update follows the convention described above, then it can be approved and merged. If the other files already follow this convention, then there is nothing else to do.
If they don't, we might as well update all other files while we are at it, either in this PR or, if it turns out to be a major endeavor, we can also do it in batches.

@erlend-aasland
Copy link
Contributor Author

This PR updates all files in the devguide to follow the convention described in the style guide. Does that answer your question, @ezio-melotti?

Copy link
Member

@AlexWaygood AlexWaygood left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@hugovk
Copy link
Member

hugovk commented Dec 6, 2023

For this file, are we starting at =, then - and ^?

For which file?

I obviously didn't scroll very far down the diff! 😅

Let's try again:

For these files, are we starting at =, then - and ^?

When would we use the overlines?

  • # with overline, for parts
  • * with overline, for chapters

If a page wants more than four levels? In that case, it would be a bit of a tricky refactor, and it's probably a good idea to avoid such deep nesting.

@erlend-aasland
Copy link
Contributor Author

For these files, are we starting at =, then - and ^?

Starting at = it appears.

@erlend-aasland
Copy link
Contributor Author

Thanks for the reviews! I'll land this post house chores 🏠🗑️

@erlend-aasland erlend-aasland merged commit 477be7d into python:main Dec 6, 2023
@erlend-aasland erlend-aasland deleted the fixup-subsubsections branch December 6, 2023 19:34
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants