Skip to content

Commit bddcefb

Browse files
Ankan0503jacobtylerwalls
authored andcommitted
Fixed #36305 -- Added documentation indentation guidelines to contributing docs.
1 parent cc8ee49 commit bddcefb

1 file changed

Lines changed: 37 additions & 0 deletions

File tree

docs/internals/contributing/writing-documentation.txt

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -420,6 +420,43 @@ documentation:
420420
* Use :rst:role:`:cve:<cve>` to reference a Common Vulnerabilities and
421421
Exposures (CVE) identifier. For example, use ``:cve:`2019-14232```.
422422

423+
* When documenting Python objects (classes, methods, attributes, etc.) using
424+
`Sphinx directives`__ such as ``.. class::``, ``.. method::``, and
425+
``.. attribute::``, all content must be properly indented to ensure correct
426+
rendering and to support features like automatic table of contents
427+
generation.
428+
429+
Follow these rules:
430+
431+
* The directive itself remains flush with the left margin (no indentation).
432+
* All descriptive text under the directive must be indented by 4 spaces.
433+
* Multi-line descriptions must keep the same indentation level.
434+
* Nested directives (for example, methods inside a class) require an
435+
additional 4 spaces of indentation to maintain hierarchy.
436+
* Field lists (such as ``:param:``, ``:returns:``, etc.) must align with the
437+
directive's content level.
438+
439+
Example:
440+
441+
.. code-block:: rst
442+
443+
.. class:: MyClass
444+
445+
A brief description of the class.
446+
447+
.. method:: my_method(arg1, arg2)
448+
449+
Method description.
450+
451+
:param arg1: Description of the first parameter
452+
:param arg2: Description of the second parameter
453+
454+
.. attribute:: my_attribute
455+
456+
Attribute description.
457+
458+
__ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
459+
423460
Django-specific markup
424461
======================
425462

0 commit comments

Comments
 (0)