rsyslog-doc

name: rsyslog_doc description: Guidelines for maintaining structured, RAG-optimized documentation and module metadata. triggers: - doc/source/**/*.rst

rsyslog_doc

This skill ensures that all documentation is consistent, discoverable, and optimized for both human readers and AI ingestion systems.

Quick Start

1. Metadata Block: Every .rst must have a .. meta:: block.
2. Summary Slices: Wrap intros in .. summary-start and .. summary-end.
3. Cross-Link: Update index.rst and doc/ai/module_map.yaml.

Detailed Instructions

1. Structured Requirements

Every documentation page must include:

• Meta Block:

  .. meta::
     :description: Brief description for SEO and RAG.
     :keywords: rsyslog, module, config, ...
  

• Summary Slices: Essential for RAG (Retrieval-Augmented Generation).

  .. summary-start
  Concise summary of what this module/feature does.
  .. summary-end
  

[!IMPORTANT] Trigger Side-Effect: If you add, move, or remove any .rst file, YOU MUST follow the rsyslog_doc_dist skill to update doc/Makefile.am and run the extended distribution check.

[!IMPORTANT] Sample Config Security Review: If you add or materially update a sample rsyslog configuration, you MUST review that specific configuration for security posture before finishing the documentation change. Check whether the example exposes listeners, weakens authentication or TLS, writes to sensitive paths, follows unsafe file/link behavior, uses overly broad permissions, enables compatibility fallbacks, or recommends defaults that are unsuitable for new deployments. Use doc/ai/security_triage_rubric.md to classify any concern as a confirmed issue, potential issue, hardening, or not actionable. If this review exposes vulnerable or unsafe code behavior, do not treat it as documentation-only work: either fix the code in the same change when the scope is clear and bounded, or record the implementation follow-up with enough evidence for maintainers to reproduce and prioritize it.

2. Module Documentation

• Parameters: Use the include directive to pull parameter details from doc/source/reference/parameters/.
• Anchors: Use explicit anchors (e.g., .. _parameter_name:) for consistent linking.
• Templates: Reference doc/ai/templates/template-module.rst.

3. Metadata Files

• Plugins/Contrib: Maintain MODULE_METADATA.yaml in the module directory.
• Built-in Tools: Update tools/MODULE_METADATA.json.
• Required Keys: support_status, maturity_level, primary_contact, last_reviewed.

4. Validation

• Build Docs: For rendered user-facing documentation changes under doc/source/**, or Sphinx support files that affect that tree, run a high-concurrency HTML build: ./doc/tools/build-doc-linux.sh --clean --format html --jobs "${RSYSLOG_LOCAL_DOC_JOBS:-$(nproc)}". Add --strict for larger, structural, navigation-heavy, or warning-sensitive documentation edits.
• Internal docs that are not rendered into the user manual, such as doc/ai/**, repository agent guides, and skill files, do not require a Sphinx docs build unless they also change rendered Sphinx inputs.
• json-formatter: Run make -j16 json-formatter to update the RAG knowledge base.
• Mermaid: Ensure Mermaid diagrams have a blank line after the directive and quoted labels.

5. Style & Tone

• Follow the Doc Assistant Prompt: ai/rsyslog_doc_assistant/base_prompt.txt.
• Use canonical terminology from doc/ai/terminology.md.

Related Skills

• rsyslog_module: For technical details to include in docs.
• rsyslog_commit: For doc-only commit message rules.