style guide update

[daniel-demelo]

So, I update the style guide a little bit.
The headings section more specifically.
No more tilde headings, since it was breaking the rendering.
Sphinx reStructuredText Primer is used as baseline for the headings formats.
I also added a Blank lines section
Hopefully no one will be offended by the changes :)
Otherwise let me know and we can work on it

[dbader]

Hey thanks for opening this PR. The headline hierarchy still looks broken to me:

• h1 for the chapter title is correct, so that's great ✅
• h2 for "Relevancy" makes sense too ✅
• h3 for the other stuff until "TODOs" seems odd. We'd want all of those to be h2s as well I think
• Remaining h3s from the navbar on the side are not ideal but this is something that I need to fix in the template.

Apologies for sending you on a wild goose chase here—I'll buy you a thank coffee if you make it to PyCon next year ;-) It's going to be great to get this sorted out because I suspect this sort inconsistency also makes it harder on readers using accessibility tools like screen readers. So your help is very much appreciated.

[daniel-demelo]

No problem, all good.
Alles muss ordentlich sein ;)
I do should go to the PyCon at some point, I haven't been yet.
I added another change and applied the style to the document.
I'll apply the style to my other PR and start thinking about applying it to the rest of the python-guide.

[mpoulin]

I think the terminology here is confusing (chapters, pages, sections). What's the difference between a chapter and a page?

Headings
Use the following styles for headings.

Chapter title:

#############
H1: Chapter 1
#############
Page title:

***********************
H2: Time is an Illusion
***********************
Section headings:

H3: Lunchtime Doubly So
=======================
Sub section headings:

H4: Very Deep
-------------

I would prefer something like this

###############
Level 1 heading
###############


***************
Level 2 heading
***************


Level 3 heading
===============


Level 4 heading
---------------

Also, maybe add a note like "Note: Each .rst file should start with a Level 1 heading."

[daniel-demelo]

You make some valid points, when I first looked at it, I wasn't just sure if the chapter would encompass more pages, that later would be assembled into the chapter, like parts of a page.
That's the only logic I could come up with, no idea if there's any truth to it.
But if you consider, it's all a hierarchy in the end.
A chapter has pages, which have sections and so forth.
So as long as people use the right format/tags ...
Names don't appear when the formatting is done.
Also I just checked the commit history, this format has been there since Dec 30th, 2011. When the document was first created, if this gives any perspective.

About the examples, could be anything also, I guess the author was just trying to be funny when he wrote those.
But regardless of what is chosen to be in the future, I believe the H: tags should be kept, because they translate to the HTML tags that are created when Sphinx compiles the document to HMTL.

Your note suggestion is right on point, I mean, you would think that it is obvious that people should use from top down, and never starting anywhere in the middle.
I'm sure those individuals are out there somewhere just waiting for the opportunity.

From your note precaution, I think we should also have a similar one for mergers, to check the commit against the style guide before merging. Like a fail safe.

I guess we could hear some more thoughts before we do any more changes.

[mpoulin]

@daniel-demelo @dbader
I found this style guide for Sphinx
https://documentation-style-guide-sphinx.readthedocs.io/en/latest/style-guide.html

I like his examples the best

##################
H1: document title
##################

Introduction text.


*********
Sample H2
*********

Sample content.


**********
Another H2
**********

Sample H3
=========

Sample H4
---------

Sample H5
^^^^^^^^^

Sample H6
"""""""""

And some text.