Documentation guidelines around indenting reference docs

[Sarah Boyce]

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.

[Natalia Bidart]

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/