[Django] #36305: Documentation guidelines around indenting reference docs

[Django]

#36305: Documentation guidelines around indenting reference docs
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.2 | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
We have some inconsistency around indenting within the documentation.
For example:
-
https://docs.djangoproject.com/en/5.2/ref/checks/#django.core.checks.CheckMessage
the definition here is not indented
- https://docs.djangoproject.com/en/5.2/ref/contrib/sitemaps/#sitemap-
class-reference the definitions here are indented

Based off the Sphinx documentation, we should indent the content:
https://www.sphinx-
doc.org/en/master/usage/restructuredtext/basics.html#:~:text=Options%20must%20be%20indented%20to%20the%20same%20level%20as%20the%20directive%20content.

> Basically, a directive consists of a name, arguments, options and
content. (Keep this terminology in mind, it is used in the next chapter
describing custom directives.) Looking at this example,
>
> {{{
> .. function:: foo(x)
> foo(y, z)
> :module: some.module.name
>
> Return a line of text input from the user.
> }}}
>
> function is the directive name. It is given two arguments here, the
remainder of the first line and the second line, as well as one option
module (as you can > see, options are given in the lines immediately
following the arguments and indicated by the colons). Options must be
indented to the same level as the directive content.


Note that if we were to use the `toc_object_entries` Sphinx setting to
auto generate the table of contents, this would not generate correctly for
pages with the wrong indents.

I believe some guidelines around indenting should be documented within
https://docs.djangoproject.com/en/5.2/internals/contributing/writing-
documentation/#guidelines-for-restructuredtext-files would be useful.
--
Ticket URL: <https://code.djangoproject.com/ticket/36305>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36305: Documentation guidelines around indenting reference docs

--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 5.2

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Natalia Bidart):

* stage: Unreviewed => Accepted

Comment:

Thank you Sarah, I agree this is an issue that is worth fixing. Another
example of mixed indentations is, for example,
https://docs.djangoproject.com/en/5.2/ref/middleware/
--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:1>

[Django]

#36305: Documentation guidelines around indenting reference docs

-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Ahmed Nassar):

* owner: (none) => Ahmed Nassar
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:2>

[Django]

#36305: Documentation guidelines around indenting reference docs
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Ahmed Nassar):

* has_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:3>

[Django]

#36305: Documentation guidelines around indenting reference docs
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:4>

[Django]

#36305: Documentation guidelines around indenting reference docs
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Ahmed Nassar):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:5>

[Django]

#36305: Documentation guidelines around indenting reference docs
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ahmed
Type: | Nassar
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Bruno Alla):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:6>

[Django]

#36305: Documentation guidelines around indenting reference docs

--------------------------------------+------------------------------------
Reporter: Sarah Boyce | Owner: (none)
Type: Cleanup/optimization | Status: new

Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Jacob Walls):

* owner: Ahmed Nassar => (none)
* status: assigned => new

--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:7>

[Django]

#36305: Documentation guidelines around indenting reference docs

-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ankan
Type: | Giri
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Ankan Giri):

* owner: (none) => Ankan Giri

* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:8>

[Django]

#36305: Documentation guidelines around indenting reference docs
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ankan
Type: | Giri
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0

Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Jacob Walls):

* needs_better_patch: 1 => 0

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:9>

[Django]

#36305: Documentation guidelines around indenting reference docs
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ankan
Type: | Giri
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Jacob Walls <jacobtylerwalls@…>):

In [changeset:"cc8ee496a5293ecf7155d61c6052905c92db3ca0" cc8ee496]:
{{{#!CommitTicketReference repository=""
revision="cc8ee496a5293ecf7155d61c6052905c92db3ca0"
Refs #36305 -- Fixed indentation in checks and middleware documentation.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:10>

[Django]

#36305: Documentation guidelines around indenting reference docs
-------------------------------------+-------------------------------------
Reporter: Sarah Boyce | Owner: Ankan
Type: | Giri

Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.2
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Jacob Walls <jacobtylerwalls@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"bddcefb00f555196d3c488fbad71d303e9f7ede1" bddcefb]:
{{{#!CommitTicketReference repository=""
revision="bddcefb00f555196d3c488fbad71d303e9f7ede1"
Fixed #36305 -- Added documentation indentation guidelines to contributing
docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36305#comment:11>