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

style guide update #940

Open
wants to merge 3 commits into
base: master
Choose a base branch
from

Conversation

daniel-demelo
Copy link

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
Copy link
Member

dbader commented Nov 26, 2018

screenshot 2018-11-26 13 10 35

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
Copy link
Author

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
Copy link
Contributor

mpoulin commented Nov 27, 2018

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
Copy link
Author

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
Copy link
Contributor

mpoulin commented Dec 5, 2018

@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.

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.

3 participants