Standardize restructed text header convention in docs

[Tim Graham]

It would be nice to fix some inconsistencies in our heading styles and document the convention in docs/internals/contributing/writing-documentation.txt. To avoid changing everything, I think we should deviate slightly from ​the sphinx style guide and use something like this (where "four" and below are subject to change depending on what documents already use):

===
One
===

Two
===

Three
-----

Four
~~~~

Five
^^^^

I attached a patch to get started. Note that any top level .. _ links can be removed. These are replaced with :doc:.

[Aymeric Augustin]

Go ahead, no one's going to stop you :-)

[Elif T. Kuş]

@timgraham

Note that any top level .. _ links can be removed. These are replaced with :doc:.

Does that mean that I should replace ".. _glossary:" with ":doc:`glossary`"?

[Tim Graham]

Not quite; you can remove .. _glossary: and if there are any links pointing to it, you'll update them to use :doc: instead of :ref:.

[Elif T. Kuş]

I deleted the comment before seeing your answer :/.

Ok thank you.

[Elif T. Kuş]

Here is my pull request ​https://github.com/django/django/pull/5923

It's my first pull request to the django repo.

I was not clear to me whether I should also change second level headings. Some files where I left the second level heading as it is (which was in the third level heading format):
faq\*.txt
howto\custom-template-tags.txt
howto\error-reporting.txt
howto\writing-migrations.txt
internals\mailing-lists.txt
internals\contributing\writing-code\working-with-git.txt
intro\install.txt

I can change them if you think they need to be changed.

[Elif T. Kuş]

Resubmitted the pull request: ​https://github.com/django/django/pull/5924

The above comments still hold.

[Tim Graham]

Yes, please fix the other headings if you are able.

[Elif T. Kuş]

I'm working on the subheadings.

[Elif T. Kuş]

Patch is updated.

[Tim Graham <timograham@…>]

In bca9faa:

Fixed #26020 -- Normalized header stylings in docs.

[Tim Graham <timograham@…>]

In 5dceb1f0:

[1.9.x] Fixed #26020 -- Normalized header stylings in docs.

Backport of bca9faae95db2a92e540fbd08505c134639916fe from master