Opened 9 years ago

Closed 9 years ago

Last modified 9 years ago

#26020 closed Cleanup/optimization (fixed)

Standardize restructed text header convention in docs

Reported by: Tim Graham Owned by: Elif T. Kuş
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

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

Attachments (1)

headers.diff (1.3 KB ) - added by Tim Graham 9 years ago.

Download all attachments as: .zip

Change History (17)

by Tim Graham, 9 years ago

Attachment: headers.diff added

comment:1 by Aymeric Augustin, 9 years ago

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

comment:2 by Elif T. Kuş, 9 years ago

Owner: changed from nobody to Elif T. Kuş
Status: newassigned

comment:3 by Elif T. Kuş, 9 years ago

@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`"?

Version 0, edited 9 years ago by Elif T. Kuş (next)

comment:4 by Tim Graham, 9 years ago

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

comment:5 by Elif T. Kuş, 9 years ago

I deleted the comment before seeing your answer :/.

Ok thank you.

comment:6 by Elif T. Kuş, 9 years ago

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.

Last edited 9 years ago by Elif T. Kuş (previous) (diff)

comment:7 by Elif T. Kuş, 9 years ago

Has patch: set

comment:8 by Elif T. Kuş, 9 years ago

Has patch: unset

comment:9 by Elif T. Kuş, 9 years ago

Has patch: set

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

The above comments still hold.

comment:10 by Tim Graham, 9 years ago

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

comment:11 by Tim Graham, 9 years ago

Patch needs improvement: set

comment:12 by Elif T. Kuş, 9 years ago

I'm working on the subheadings.

comment:13 by Elif T. Kuş, 9 years ago

Patch is updated.

comment:14 by Elif T. Kuş, 9 years ago

Patch needs improvement: unset

comment:15 by Tim Graham <timograham@…>, 9 years ago

Resolution: fixed
Status: assignedclosed

In bca9faa:

Fixed #26020 -- Normalized header stylings in docs.

comment:16 by Tim Graham <timograham@…>, 9 years ago

In 5dceb1f0:

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

Backport of bca9faae95db2a92e540fbd08505c134639916fe from master

Note: See TracTickets for help on using tickets.
Back to Top