Shipping Better Docs with AI: Restructuring Module Parameters for Clarity and Consistency

Rsyslog docs: parameter split root prompt — v4 (no‑content‑loss, scope‑correct anchors)

SET MODULE FOR THIS RUN
-----------------------
Set <module-name> to the module you are converting. For this run:
    <module-name> = imfile
Change only this value for other modules in later runs.

Task
====
Restructure rsyslog docs for the given module (<module-name>) by splitting every logical parameter from
`doc/source/configuration/modules/<module-name>.rst` into **single canonical parameter pages** (one page per parameter name),
documenting all applicable scopes (module/action/input) on the same page. Apply strict labeling, H1 headings, include-slice summaries,
and `<module-name>-<param>` slug rules. Handle legacy names. Keep CI light (PoC).

Absolute no-content-loss policy
-------------------------------
- **Do NOT reduce information.** Carry over all cautions, platform caveats (e.g., `recvmmsg()` availability, kernel behavior), limits,
  ranges, examples, notes about privilege requirements, performance trade-offs, warnings about crashes, and recommendations.
- If the original page has examples, **preserve them**, placing them under *Description* or the relevant *Usage* section (add a short "**Examples:**" list or literal blocks).
- Preserve any `.. versionadded::`, `.. warning::`, `.. note::`, and similar admonitions.
- If the original text contains strong advice (e.g., “do not set above 128”), **keep it verbatim or paraphrase with equal specificity**.
- If a parameter is platform-gated (e.g., only active on Linux, or ignored if feature not present), explicitly state that.
- If the earlier docs described a legacy type like “binary”, map it to **boolean** but mention that mapping in **Notes**.

Scope & constraints
-------------------
- Touch only:
  - `doc/source/configuration/modules/<module-name>.rst`
  - new files under `doc/source/reference/parameters/`
- Do not invent parameters; enumerate **exactly** those present on the module page.
- Preserve semantics; normalize wording/formatting lightly.
- US-ASCII only. Config snippets use `.. code-block:: rsyslog`.
- rsyslog params are case-insensitive; **display** preserves historical CamelCase and dots; filenames/labels use lowercase slugs.
- Transitional split: future automation will rely on these paths & labels.

Location, filename & slug
-------------------------
- **One page per parameter** at: `doc/source/reference/parameters/<module-name>-<param-slug>.rst`
- **Slug rule** for `<param-slug>`: lowercase; replace `.` with `-`; remove other punctuation; trim spaces.
  Examples: `RateLimit.Interval` → `ratelimit-interval`; `compression.zstd.workers` → `compression-zstd-workers`.

Top-of-page order (labels → H1 → index → summary → backlink)
------------------------------------------------------------
```
.. _param-<module-name>-<param-slug>:
.. _<module-name>.parameter.<scope>.<param-slug>:
.. _<module-name>.parameter.<param-slug>:          # optional scope-free alias (keep at most one)

<ParamName>
==========

.. index::
   single: <module-name>; <ParamName>
   single: <ParamName>

.. summary-start

<one concise sentence; ≤160 chars; use backticks for tokens>

.. summary-end

This parameter applies to :doc:`../../configuration/modules/<module-name>`.
```
Rules:
- The **second label MUST use the actual primary scope** of the parameter: `<scope>` ∈ {`module`, `action`, `input`}.
  (Example: `.. _imudp.parameter.input.port:` for an input-scoped parameter.)
- The scope-free alias label is **optional**; include at most one: `..<module>.parameter.<param-slug>:`.
- The summary markers **must** be isolated as RST comments with a blank line before and after both `.. summary-start` and `.. summary-end`,
  and there must be a blank line **after** the one-line summary. This prevents marker text from leaking into HTML.

Compact header field list (omit empty fields entirely; keep order)
------------------------------------------------------------------
```
:Name: <ParamName as in config (keep CamelCase and dots)>
:Scope: module | action | input     # list all that apply
:Type: string (see :doc:`../../rainerscript/constant_strings`) | integer | boolean | size | word | uid | gid | array[string] | positive-integer
:Default: module=<val>; action=<val or "inherits module">; input=<val>   # include only scopes that apply
:Required?: yes | no
:Introduced: <version> | at least 8.x, possibly earlier
```

Introduced fallback policy
--------------------------
- Default: `at least 8.x, possibly earlier`
- If any **legacy equivalent** is listed on the page: `at least 5.x, possibly earlier`

Sections (exact order; omit a section if empty)
-----------------------------------------------
```
Description
-----------
<Shared semantics across scopes. If multiple scopes apply, state precedence: action > module > hardcoded default. Carry all warnings, caveats, ranges, platform notes, examples.>

Module usage
------------
<Only if :Scope: contains module>
.. _param-<module-name>-module-<param-slug>:
.. _<module-name>.parameter.module.<param-slug>-usage:
.. code-block:: rsyslog
   module(load="<module-name>" <ParamName>="...")

Action usage
------------
<Only if :Scope: contains action>
.. _param-<module-name>-action-<param-slug>:
.. _<module-name>.parameter.action.<param-slug>-usage:
.. code-block:: rsyslog
   action(type="<module-name>" <ParamName>="...")

Input usage
-----------
<Only if :Scope: contains input>
.. _param-<module-name>-input-<param-slug>:
.. _<module-name>.parameter.input.<param-slug>-usage:
.. code-block:: rsyslog
   input(type="<module-name>" <ParamName>="...")

Notes
-----
- Use backticks for API names/options (e.g., ``recvmmsg()``, ``List Containers``).
- Map legacy wording like “binary” to **boolean** here if applicable.
- Carry over any ``.. versionadded::`` info if present.
- If the OS may adjust a requested value (e.g., `SO_RCVBUF`), say so. Mention privilege needs if relevant.
- If the parameter is **experimental** or dangerous, say so explicitly (and keep any crash warnings).

Legacy names (for reference)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
<Include ONLY if legacy tokens exist>
Historic names/directives for compatibility. Do not use in new configs.

.. _<module-name>.parameter.legacy.<legacy-slug-1>:
- <LegacyToken1> — maps to <ParamName> (status: legacy)

.. index::
   single: <module-name>; <LegacyToken1>
   single: <LegacyToken1>

See also
--------
See also :doc:`../../configuration/modules/<module-name>`.
```

Type normalization
------------------
- Allowed set: `string | integer | boolean | size | word | uid | gid | array[string] | positive-integer`.
- Treat legacy “binary” as **boolean**; note this in **Notes** when applicable.
- For `string`, always link semantics to `:doc:`../../rainerscript/constant_strings``.
- If a specialized token appears (e.g., `FileCreateMode`, `UID`, `GID`, `size`), keep it in `:Type:` and optionally clarify in **Notes**.
- Keep examples from original docs (e.g., single vs. array forms).

Module page updates in `doc/source/configuration/modules/<module-name>.rst`
---------------------------------------------------------------------------
- Keep original group sections (**Module Parameters**, **Action Parameters**, **Input Parameters**).
- Replace inline parameter docs with a **two-column list-table** (Parameter | Summary). The Parameter column must link to the **page-level** anchor (top of page), not a scope anchor.
```
.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Parameter
     - Summary
   * - :ref:`param-<module-name>-<param-slug>`
     - .. include:: ../../reference/parameters/<module-name>-<param-slug>.rst
        :start-after: .. summary-start
        :end-before: .. summary-end
# repeat per parameter in this group
```
- Add once per module page (replacing any older variant):
```
.. note::
   Parameter names are case-insensitive; CamelCase is recommended for readability.
```
- Add a hidden toctree listing all parameter pages (prevents orphaned pages and aids navigation):
```
.. toctree::
   :hidden:

   ../../reference/parameters/<module-name>-<param-slug-1>
   ../../reference/parameters/<module-name>-<param-slug-2>
   # (all generated parameter pages)
```

Normalization & wording rules
-----------------------------
- Preserve CamelCase/dots in headings and examples; slugs/labels are lowercase with dots→hyphens.
- Backticks for function names, API endpoints, and option keys.
- Fix only **clear typos**. If you fix one, you may add a hidden alias label (rare; high confidence only).
- Omit **Legacy names** section if no legacy tokens.
- Elide other empty fields.
- When the original page includes concrete limits/recommendations (e.g., “do not set above 128”), **keep them**.

Light CI (PoC)
--------------
- Run (non-blocking):
  - `sphinx-build -b html doc/source doc/_build/html`
  - (Optional) `sphinx-build -b linkcheck doc/source doc/_build/linkcheck`
- Provide a brief summary of warnings/broken links if you run linkcheck; **do not** fail the task on warnings.

Deliverables
------------
1) Unified diffs for all created/modified files.
2) Mapping: original parameter names → `<param-slug>`, plus detected **Scope**(s).
3) Updated list-table block(s) for each group in `<module-name>.rst` and the hidden toctree block (paste-ready).
4) (Optional) Build summary if Sphinx was executed.

Execution notes
---------------
- Parse `<module-name>.rst` to enumerate parameters across all groups (module/action/input).
- Create **one canonical page per parameter** with multi-scope sections as applicable.
- Ensure module overview tables pull their Summary via the include slice to avoid divergence.
- Set `:Introduced:` using explicit version data if found; otherwise apply the fallback policy above.
- Preserve all details and warnings; do not shorten content.
- Begin now and return the diffs plus the mapping table.

Self-check before returning
---------------------------
- [ ] All page-level labels present and correct:
      `param-<module>-<slug>` and `<module>.parameter.<scope>.<slug>` (scope matches parameter’s primary scope).
- [ ] All usage-section labels present and end with `-usage` for their scope:
      `<module>.parameter.module.<slug>-usage`, `<module>.parameter.action.<slug>-usage`, `<module>.parameter.input.<slug>-usage`.
- [ ] Optional alias `<module>.parameter.<slug>` present at most once.
- [ ] Summary markers are isolated with required blank lines; one-line summary ≤160 chars, no trailing markers in HTML.
- [ ] US-ASCII only; backticks used for tokens, APIs, and function names.
- [ ] `:Type:` values are from the allowed set; `string` links to `constant_strings`; legacy “binary” mapped to boolean with note.
- [ ] All platform gating (e.g., `recvmmsg()`), privilege notes, ranges, caveats, and crash warnings are preserved.
- [ ] Examples from original docs are included where they existed.
- [ ] Module page shows list-table with include slices and a hidden toctree containing all generated parameter pages.
- [ ] No parameters invented, none omitted.
- [ ] Anchors are unique; no collisions across pages.

Shipping Better Docs with AI: Restructuring Module Parameters for Clarity and Consistency

The Challenge: Making Documentation More Accessible

The Workflow: Three AIs, One Human-in-the-Loop Process

Responsible AI in Open Source

How You Can Help

Appendix: Current Root Prompt (excerpt we run for each module)