From: Juliana Fajardini <jufajardini@oisf.net>
Date: Thu, 30 Nov 2023 15:16:27 +0000 (-0300)
Subject: devguide: explain example-rule container usage
X-Git-Tag: suricata-8.0.0-beta1~1887
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a37fa627100b2aa28e0cd351246083c726bcf984;p=thirdparty%2Fsuricata.git

devguide: explain example-rule container usage

Have these options documented, so that whoever writes rule-related
documentation can easily know what they could use to make the doc look
better.
---

diff --git a/doc/userguide/devguide/contributing/contribution-process.rst b/doc/userguide/devguide/contributing/contribution-process.rst
index eb8e53d820..e3058d7165 100644
--- a/doc/userguide/devguide/contributing/contribution-process.rst
+++ b/doc/userguide/devguide/contributing/contribution-process.rst
@@ -199,7 +199,7 @@ Documentation Style
 For documenting *code*, please follow Rust documentation and/or Doxygen
 guidelines, according to what your contribution is using (Rust or C).
 
-If you are writing or updating *documentation pages*, please:
+When writing or updating *documentation pages*, please:
 
 * wrap up lines at 79 (80 at most) characters;
 * when adding diagrams or images, we prefer alternatives that can be generated
@@ -208,6 +208,67 @@ If you are 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.
 
+Rule examples
+-------------
+
+.. role:: example-rule-action
+.. role:: example-rule-header
+.. role:: example-rule-options
+.. role:: example-rule-emphasis
+
+For rule documentation, we have a special container::
+
+    example-rule
+
+This will present the rule in a box with an easier to read font size, and also
+allows highlighting specific elements in the signature, as the names indicate
+- action, header, options, or emphasize custom portions:
+
+    - example-rule-action
+    - example-rule-header
+    - example-rule-options
+    - example-rule-emphasis
+
+When using these, indicate the portion to be highlighted by surrounding it with
+` . Before using them, one has to invoke the specific role, like so::
+
+    .. role:: example-rule-role
+
+It is only necessary to invoke the role once per document. One can see these
+being invoked in our introduction to the rule language (see `Rules intro
+<https://raw.githubusercontent.com/OISF/suricata/master/doc/userguide/rules/intro.rst>`_).
+
+A rule example like::
+
+    .. container:: example-rule
+
+    :example-rule-action:`alert` :example-rule-header:`http $HOME_NET any ->
+    $EXTERNAL_NET any` :example-rule-options:`(msg:"HTTP GET Request Containing
+    Rule in URI"; flow:established,to_server; http.method; content:"GET"; http.uri;
+    content:"rule"; fast_pattern; classtype:bad-unknown; sid:123; rev:1;)`
+
+Results in:
+
+.. container:: example-rule
+
+    :example-rule-action:`alert` :example-rule-header:`http $HOME_NET any ->
+    $EXTERNAL_NET any`  :example-rule-options:`(msg:"HTTP GET Request Containing
+    Rule in URI"; flow:established,to_server; http.method; content:"GET"; http.uri;
+    content:"rule"; fast_pattern; classtype:bad-unknown; sid:123; rev:1;)`
+
+Example - emphasis::
+
+    .. container:: example-rule
+
+    alert ssh any any -> any any (msg:"match SSH protocol version";
+    :example-rule-emphasis:`ssh.proto;` content:"2.0"; sid:1000010;)
+
+Renders as:
+
+.. container:: example-rule
+
+    alert ssh any any -> any any (msg:"match SSH protocol version";
+    :example-rule-emphasis:`ssh.proto;` content:"2.0"; sid:1000010;)
 
 Commit History matters
 ======================