From 618bbd21503fd0afd6a688fbc24abdace843aefd Mon Sep 17 00:00:00 2001 From: tetrapod00 <145553014+tetrapod00@users.noreply.github.com> Date: Sun, 29 Dec 2024 14:42:29 -0800 Subject: [PATCH] Document standards for RST section header syntaxx --- .../documentation/docs_writing_guidelines.rst | 45 ++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/contributing/documentation/docs_writing_guidelines.rst b/contributing/documentation/docs_writing_guidelines.rst index 9206c156e..88552f419 100644 --- a/contributing/documentation/docs_writing_guidelines.rst +++ b/contributing/documentation/docs_writing_guidelines.rst @@ -665,7 +665,50 @@ as long as the lines don't exceed 100 characters. .. code:: json - "editor.rulers": [80,100], + "editor.rulers": [80,100], + +Section header syntax +~~~~~~~~~~~~~~~~~~~~~ + +Use the following syntax for section headers: + +.. code-block:: + + Page title + ========== + + Renders as h1. + Every page has this. + + Section header + -------------- + + Renders as h2. + Usually appears in sidebar. Many pages only need one level of nested headers. + + Sub-section header + ~~~~~~~~~~~~~~~~~~ + + Renders as h3. + Appears in sidebar in some pages, depending on how deeply nested the page is. + + Sub-sub-section header + ^^^^^^^^^^^^^^^^^^^^^^ + + Renders as h4. + Usually won't appear in the sidebar. + +Currently, there are no cases of deeper header nesting than this. Avoid +introducing any deeper nesting. + +Note that headers have no inherent meaning. In reStructuredText, headers are +parsed based on the order that they initially appear within a page. Make sure +that if you use an ``h3`` section header (``~~~``), you include an ``h2`` +sub-section header (``---``) first. + +See the `Sphinx documentation `__ +and the `reStructuredText documentation `__ +for more information. When to refer to a specific Godot version -----------------------------------------