Fixed #36305 -- Added documentation indentation guidelines to contributing docs.

1 files changed, 37 insertions, 0 deletions

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:<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
 ======================