[Django] #26020: Standardize restructed text header convention in docs
Django
------------------------------------------------+------------------------
Reporter: timgraham | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Severity: Normal | Keywords:
Triage Stage: Accepted | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 1
UI/UX: 0 |
------------------------------------------------+------------------------
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 [http://documentation-style-guide-
sphinx.readthedocs.org/en/latest/style-guide.html#headings 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:`.
--
Ticket URL: <https://code.djangoproject.com/ticket/26020>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
Django
Reporter: timgraham | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by timgraham):
* Attachment "headers.diff" added.
Django
Reporter: timgraham | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: master
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by aaugustin):
Go ahead, no one's going to stop you :-)
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:1>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by elif):
* owner: nobody => elif
* status: new => assigned
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:2>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by elif):
@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`}}}"?
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:3>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by timgraham):
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:`.
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:4>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by elif):
I deleted the comment before seeing your answer :/.
Ok thank you.
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:5>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by elif):
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 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):
fag\*.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.
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:6>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by elif):
* has_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:7>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by elif):
* has_patch: 1 => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:8>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by elif):
* has_patch: 0 => 1
Comment:
Resubmitted the pull request: https://github.com/django/django/pull/5924
The above comments still hold.
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:9>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by timgraham):
Yes, please fix the other headings if you are able.
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:10>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Changes (by timgraham):
* needs_better_patch: 0 => 1
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:11>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by elif):
I'm working on the subheadings.
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:12>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 1 | UI/UX: 0
Comment (by elif):
Patch is updated.
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:13>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: assigned
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by elif):
* needs_better_patch: 1 => 0
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:14>
Django
Reporter: timgraham | Owner: elif
Component: Documentation | Version: master
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Changes (by Tim Graham <timograham@…>):
* status: assigned => closed
* resolution: => fixed
Comment:
In [changeset:"bca9faae95db2a92e540fbd08505c134639916fe" bca9faa]:
{{{
#!CommitTicketReference repository=""
revision="bca9faae95db2a92e540fbd08505c134639916fe"
Fixed #26020 -- Normalized header stylings in docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:15>
Django
Reporter: timgraham | Owner: elif
Type: Cleanup/optimization | Status: closed
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 1 | UI/UX: 0
Comment (by Tim Graham <timograham@…>):
In [changeset:"5dceb1f07807d76f163ce1929e9f1dc1b2da6289" 5dceb1f0]:
{{{
#!CommitTicketReference repository=""
revision="5dceb1f07807d76f163ce1929e9f1dc1b2da6289"
[1.9.x] Fixed #26020 -- Normalized header stylings in docs.
Backport of bca9faae95db2a92e540fbd08505c134639916fe from master
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/26020#comment:16>