From f968a7bfb0add319b5245ff755d9299e0de8e92f Mon Sep 17 00:00:00 2001 From: Jason Ish Date: Thu, 1 May 2025 09:37:41 -0600 Subject: [PATCH] doc: add rst header order recommendation Ticket: #7396 --- .../contributing/contribution-process.rst | 38 ++++++++++++++++++- 1 file changed, 36 insertions(+), 2 deletions(-) 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 +`_. For +a primer *reStucturedText* please see the `reStrucutredText Primer +`_. 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 ------------- -- 2.47.2