From bddcefb00f555196d3c488fbad71d303e9f7ede1 Mon Sep 17 00:00:00 2001 From: ankan0503 Date: Wed, 19 Nov 2025 22:28:51 +0530 Subject: Fixed #36305 -- Added documentation indentation guidelines to contributing docs. --- .../contributing/writing-documentation.txt | 37 ++++++++++++++++++++++ 1 file changed, 37 insertions(+) (limited to 'docs') diff --git a/docs/internals/contributing/writing-documentation.txt b/docs/internals/contributing/writing-documentation.txt index 42e8aa7a89..b519fdbd86 100644 --- a/docs/internals/contributing/writing-documentation.txt +++ b/docs/internals/contributing/writing-documentation.txt @@ -420,6 +420,43 @@ documentation: * Use :rst:role:`:cve:` to reference a Common Vulnerabilities and Exposures (CVE) identifier. For example, use ``:cve:`2019-14232```. +* When documenting Python objects (classes, methods, attributes, etc.) using + `Sphinx directives`__ such as ``.. class::``, ``.. method::``, and + ``.. attribute::``, all content must be properly indented to ensure correct + rendering and to support features like automatic table of contents + generation. + + Follow these rules: + + * The directive itself remains flush with the left margin (no indentation). + * All descriptive text under the directive must be indented by 4 spaces. + * Multi-line descriptions must keep the same indentation level. + * Nested directives (for example, methods inside a class) require an + additional 4 spaces of indentation to maintain hierarchy. + * Field lists (such as ``:param:``, ``:returns:``, etc.) must align with the + directive's content level. + + Example: + + .. code-block:: rst + + .. class:: MyClass + + A brief description of the class. + + .. method:: my_method(arg1, arg2) + + Method description. + + :param arg1: Description of the first parameter + :param arg2: Description of the second parameter + + .. attribute:: my_attribute + + Attribute description. + +__ https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html + Django-specific markup ====================== -- cgit v1.3