From: Jason Ish <jason.ish@oisf.net>
Date: Thu, 1 May 2025 15:37:41 +0000 (-0600)
Subject: doc: add rst header order recommendation
X-Git-Tag: suricata-8.0.0-rc1~381
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=f968a7bfb0add319b5245ff755d9299e0de8e92f;p=thirdparty%2Fsuricata.git

doc: add rst header order recommendation

Ticket: #7396
---

diff --git a/doc/userguide/devguide/contributing/contribution-process.rst b/doc/userguide/devguide/contributing/contribution-process.rst
index 766122511b..006fecf035 100644
--- a/doc/userguide/devguide/contributing/contribution-process.rst
+++ b/doc/userguide/devguide/contributing/contribution-process.rst
@@ -224,8 +224,16 @@ We have a :ref:`Coding Style` that must be followed.
 Documentation Style
 ===================
 
-For documenting *code*, please follow Rust documentation and/or Doxygen
-guidelines, according to what your contribution is using (Rust or C).
+For documenting *code*, please follow Rust documentation and/or
+Doxygen guidelines, according to what your contribution is using (Rust
+or C). The rest of this section refers to the user and developer
+documentation.
+
+The user and developer guide documentation (what you are reading now)
+is written in *reStructuredText* and rendered with `Sphinx
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_. For
+a primer *reStucturedText* please see the `reStrucutredText Primer
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_.
 
 When writing or updating *documentation pages*, please:
 
@@ -236,6 +244,32 @@ When writing or updating *documentation pages*, please:
   /docs.suricata.io/en/latest/#suricata-user-guide>`_ and can also be
   built to pdf, so it is important that it looks good in such formats.
 
+Headings
+--------
+
+reStructuredText allows for flexible header order, for consistency
+please use the following order:
+
+* ``#``: for h1
+* ``*``: for h2
+* ``=``: for h3
+* ``-``: for h4
+* ``~``: for h5
+* ``^``: for h6
+
+For example, in a new documentation page:
+
+.. code-block:: rst
+
+  Page Title
+  ##########
+
+  Section
+  *******
+
+  Sub-Section
+  ===========
+
 Rule examples
 -------------