diff options
Diffstat (limited to 'docs/internals/contributing/writing-documentation.txt')
| -rw-r--r-- | docs/internals/contributing/writing-documentation.txt | 37 |
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 ====================== |