Documentation Reference Section Structure Guidelines¶

This page describes the ultimate desired layout for all _reference_ pages (e.g. modules under Configuration → Output Modules), balancing both:

Human UX under the Furo theme
AI/RAG ingestion needs for fine-grained, semantically focused chunks

Overview¶

Each reference module (e.g., omfwd) is defined by its master RST file and an optional set of category pages for related parameters. Do not move or rename existing module files (e.g., source/configuration/modules/omfwd.rst) to preserve SEO, bookmarks, and inter-document links.

Directory Layout¶

Modules remain at top level; parameter group pages live in a new sub-folder.

source/configuration/modules/
├── omfwd.rst                    # master reference page (unchanged)
├── imfile.rst                   # other modules (unchanged)
└── omfwd/                       # new subdirectory for parameter categories
    └── parameters/
        ├── basic.rst            # core parameters (target, port, protocol)
        ├── transport.rst        # networking params (Address, NetworkNamespace)
        ├── security.rst         # TLS/auth params (StreamDriver, AuthMode)
        └── advanced.rst         # compression, framing, keep-alive, etc.

Master Page (“<module>.rst”)¶

Enhance the existing master file (e.g., omfwd.rst) with these sections:

Introduction and Best Practices (concise overview).
Common Pitfalls of legacy syntax with minimal before/after snippets.
Parameters at a Glance — two tables: - Module-Load Parameters (e.g., iobuffer.maxSize) - Action-Instance Parameters (e.g., target, queue.type)

A hidden .. toctree:: pulling in the category pages:

.. toctree::
   :hidden:
   :maxdepth: 1

   omfwd/parameters/basic
   omfwd/parameters/transport
   omfwd/parameters/security
   omfwd/parameters/advanced

Example Parameters at a Glance:

**Module-Load Parameters**

.. csv-table::
   :header: "Parameter", "Default", "Description", "Page"
   :widths: 20 15 50 25

   "iobuffer.maxSize", "full size", "Max TCP API buffer.", :doc:`module <omfwd/parameters/module>`

**Action-Instance Parameters**

.. csv-table::
   :header: "Parameter", "Default", "Description", "Page"
   :widths: 20 15 50 25

   "target", "none", "Remote host(s).", :doc:`action <omfwd/parameters/action>`
   "port", "514", "Destination port.", :doc:`action <omfwd/parameters/action>`
   "protocol", "udp", "Transport protocol (udp/tcp/TLS).", :doc:`action <omfwd/parameters/action>`
   "queue.type", "linkedList", "Per-action queue type.", :doc:`action <omfwd/parameters/action>`

Category Pages (“parameters/*.rst”)¶

Group related parameters into 3–8 per category. Example structure for “basic.rst”:

Basic Parameters
================

.. meta::
   :tag: module:omfwd
   :tag: category:basic

Core settings for forwarding.

---

target
~~~~~~

**Summary:** Name or IP of the remote syslog server.

:type: array/word
:default: none
:mandatory: no

.. code-block:: rsyslog

   action(
     type="omfwd"
     target="logs.example.com"
     port="514"
     protocol="tcp"
     queue.type="linkedList"
   )

.. toggle::
   :caption: Deep dive: How target pools work

   .. include:: ../../../concepts/queues.inc

Repeat for transport, security, and advanced categories.

Concept Snippets¶

Centralize deep theory under source/concepts/:

<topic>.inc — conceptual snippet content
<topic>.rst — standalone concept page including the snippet

Include snippets in parameter pages via:

.. toggle::
   :caption: Deep dive: How target pools work

   .. include:: ../../../concepts/queues.inc

Metadata & Tags¶

At the top of every page (master, category, concept), include:

.. meta::
   :tag: module:<module-name>
   :tag: category:<category-name>    # category pages only
   :tag: parameter:<parameter-name>  # if desired on parameter sections
   :tag: concept:<topic-name>        # on concept pages

These tags drive precise AI/RAG filtering.

TOC Integration¶

In Doc Writing → Development (source/development/doc_style_guide.rst):

.. toctree::
   :maxdepth: 1

   doc_style_guide
   reference_section_guidelines

In Configuration → Output Modules (source/configuration/modules/index.rst):

.. toctree::
   :maxdepth: 2

   omfwd
   omrelp
   omfile
   …

Support: rsyslog Assistant | GitHub Discussions | GitHub Issues: rsyslog source project

Contributing: Source & docs: rsyslog source project