rst format fix, ~~~ was being used instead of --- under subsections c…

[daniel-demelo]

…ausing the document not to render properly

[dbader]

Thanks for the PR @daniel-demelo. The headline hierarchy seems incorrect:

The goal is to have a h1 section title and then have the other sub-headings nested correctly underneath that, 1-2 levels deep.

[daniel-demelo]

Ok, I guess I can also fix the headline hierarchy. I'll add another commit to this PR to fix that.

I just took a look at The Guide Style Guide and it says that for "sub section headings" you should use a tilde line as below:

Very Deep
~~~~~~~~~

Now, the very reason that the page rendering was not working, was exactly because the tilde line was breaking the document, so either I am very wrong here, or this should be reviewed. Here's the link for a Style guide for Sphinx-based documentations. Take a look at the headings section, there are no tilde lines for headers formatting.

The Guide Style Guide might need to be updated

[dbader]

Now, the very reason that the page rendering was not working, was exactly because the tilde line was breaking the document, so either I am very wrong here, or this should be reviewed. Here's the link for a Style guide for Sphinx-based documentations. Take a look at the headings section, there are no tilde lines for headers formatting.

The Guide Style Guide might need to be updated

Thanks for bringing it up, looks like we should revisit that too :-)

Basically the goal here is to have a nice and SEO-friendly header structure where each page has a single h1 and then everything else in that chapter nested underneath it.

If you're interested in giving it a shot and putting together a PR to refresh the style guide, that would make my day! /cc @mpoulin

[daniel-demelo]

I'll do PR for the style guide later. I noticed that in the style guide there's no mention about indentation (how many spaces it should be, if tabs are allowed, ..) There was differing indentation sizes on virtualenvs.rst, most of the document seemed to use 4 spaces tabs, so I went along with it. If you want spaces only let me know.

[dbader]

Thanks, this is starting to look good—let's go with 4 spaces for consistency.

^ Does it make sense to have autoenv nested under virtualenv-burrito? To me they seem like two separate things

[daniel-demelo]

Done :)

[mpoulin]

@daniel-demelo @dbader

I have a pull request #945 that fixes this ~~~~~~ problem. Sphinx started throwing warnings when I fixed the H1/H2 headers.

I'll wait for you to merge first before I do my merge.

[mpoulin]

Hi @daniel-demelo , @dbader

I'd like to bring @apjanke into this discussion because he is running into this same problem.

[apjanke]

I agree with @daniel-demelo’s analysis here: those ‘~~~~~’-underlined headings, while valid RST, are not one of the levels that Sphinx recognizes for its structural headings. So the Guide Style Guide is mistaken in recommending their use, and should be updated to recommend (I think) ‘——-‘ and ‘^^^^^^’ for its deeply-nested headings.

(That would explain the issue I got: it looks like because ‘~~~~~~’ is not a special Sphinx structural level, it gets interpreted as an h1; thus the “Inconsistent heading levels” warning I saw when it was used in the place of a lower level heading.)

The changes in this PR look good to me.

[kennethreitz]

maybe we should fix sphinx?