#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.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/010701961487ad18-ef10cae8-55ad-48fd-a5a0-57955341c3e1-000000%40eu-central-1.amazonses.com.
