1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
|
Documentation Reference Section Structure Guidelines
====================================================
This page describes the desired layout for reference documentation pages.
It reflects the new per-parameter reference model used in the rsyslog
documentation archive.
Overview
--------
Each module (for example ``omfwd``) keeps its master RST file under
``source/configuration/modules/``. Parameters are moved into individual
files under ``source/reference/parameters/``. The master page lists all
parameters in compact tables and links to the per-parameter files.
**Do not move or rename existing module files**. Parameter files may be
added and removed freely.
Directory Layout
----------------
Modules stay at the top level while parameter files live in the shared
``reference/parameters`` directory.
.. code-block:: text
source/
├── configuration/modules/
│ ├── omfwd.rst # master reference page (unchanged)
│ └── imfile.rst # other modules (unchanged)
└── reference/parameters/
├── omfwd-target.rst
├── omfwd-port.rst
└── imfile-seekable.rst
Module Page (``<module>.rst``)
------------------------------
Enhance the existing module page with:
#. Narrative content (purpose, examples, performance notes, etc.).
#. **Module Parameters** and **Input Parameters** tables. Use the Module table
for parameters configured through ``module()`` statements or global module
settings. Use the Input table for parameters set in per-instance
``input()`` or ``action()`` blocks.
#. A note about case-insensitive parameter names.
#. A hidden ``.. toctree::`` pulling in all parameter files for this module.
**Example parameters section**
.. code-block:: rst
.. note::
Parameter names are case-insensitive; camelCase is recommended
for readability.
**Module Parameters**
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Summary
* - :ref:`param-omfwd-target`
- .. include:: ../../reference/parameters/omfwd-target.rst
:start-after: .. summary-start
:end-before: .. summary-end
**Input Parameters**
.. list-table::
:widths: 30 70
:header-rows: 1
* - Parameter
- Summary
* - :ref:`param-omfwd-port`
- .. include:: ../../reference/parameters/omfwd-port.rst
:start-after: .. summary-start
:end-before: .. summary-end
.. toctree::
:hidden:
../../reference/parameters/omfwd-target
../../reference/parameters/omfwd-port
Parameter Files (``reference/parameters/<module>-<param>.rst``)
---------------------------------------------------------------
Create one file per parameter using the pattern
``<module>-<param-lower>.rst``. Use lowercase in filenames and anchor
leaf names; replace dots with hyphens.
Each file must contain:
* Canonical anchor: ``.. _param-<module>-<param-lower>:``
* Scoped anchor: ``.. _<module>.parameter.<scope>.<param-lower>:``
where ``<scope>`` is ``module`` or ``input``. Use ``module`` for parameters
set in ``module()`` statements or affecting the module globally. Use
``input`` for per-instance parameters inside ``input()`` or ``action()``
blocks.
* Section heading matching the parameter name
* ``.. summary-start`` and ``.. summary-end`` markers
* Description copied from the original module page
* A usage subsection titled ``Module usage`` or ``Input usage`` (matching the
scope) with a usage example and a matching ``-usage`` anchor
* Optional ``Legacy names`` subsection for deprecated directives
* ``See also`` section referencing the module page
Anchors & Cross-References
---------------------------
* Reference parameters from module pages with::
:ref:`param-<module>-<param-lower>`
* Usage anchors must end in ``-usage`` and appear next to the example
``code-block``.
* Do not duplicate anchors across files.
Rules for Examples
------------------
* Parameter names are case-insensitive. Examples should use
``camelCase`` unless a module specifically requires ``CamelCase``.
* Headings and canonical parameter names retain their original casing.
Validation
----------
* All parameter files referenced in a module must exist.
* Sphinx must build without duplicate label warnings or unresolved
references.
* Every parameter from the original module page appears in the new tables.
TOC Integration
---------------
**In the module index** (e.g., ``source/configuration/modules/index.rst``):
Ensure that all module pages are listed in the appropriate index file's toctree to make them discoverable.
.. code-block:: rst
.. toctree::
:maxdepth: 2
omfwd
omrelp
imfile
# ... and so on
Add the following to ``doc_style_guide.rst``::
.. toctree::
:maxdepth: 1
doc_style_guide
reference_section_guidelines
|
