doc: add faq for rsyslog as ETL tool
seems to be needed as people search and some vendors spread wrong info that rsyslog cannot do what it does well for over 15 years.
Include doc/tools and doc/source/_static/vendor in DOC_FILES so the
dist tarball ships required build scripts and vendored assets.
Make sitemap generation opt-in for local and CI preview builds. Add a
new `html-with-sitemap` Makefile target that enables the Sphinx tag
`with_sitemap`. Default `make html` no longer produces sitemap.xml.
Update doc/README.md and doc/BUILDS_README.md to prefer Makefile
targets, document SPHINXOPTS usage, and explain sitemap opt-in
workflows.
Why
- Keep local/manual builds clean (no sitemap by default)
- Ensure dist tarball contains all required documentation assets
- Address feedback from PR review
Impact
- Local `make html` builds: unchanged content, no sitemap.xml produced
- Opt-in sitemap via `make html-with-sitemap` (or `-t with_sitemap`)
Test plan
- make -C doc html
# verify no build/html/sitemap.xml
- make -C doc html-with-sitemap
# verify build/html/sitemap.xml exists
- make -C doc html SPHINXOPTS="-W -q --keep-going"
Refs: https://github.com/rsyslog/rsyslog/pull/6260
Add sphinx-sitemap extension to generate sitemap.xml for improved
SEO and discoverability of documentation pages.
- Add sphinx-sitemap to requirements.txt
- Configure sitemap extension in conf.py with clean URL scheme
- Verified sitemap.xml generation in build output
Co-authored-by: alorbach <alorbach@adiscon.com>
Add vendored copies of Mermaid, layout-elk, and D3 JavaScript assets
under doc/source/_static to make documentation builds self-contained
and compliant with packaging policies that forbid CDN dependencies.
Changes:
- Add vendored JavaScript files for Mermaid (11.2.0), layout-elk (0.1.4),
and D3 (7.9.0) under doc/source/_static/vendor
- Force sphinxcontrib-mermaid to use vendored assets via configuration
overrides and install_js monkey-patching
- Create tools/fix-mermaid-offline.py script to convert ES module syntax
to regular script tags for offline compatibility with file:// URLs
- Update doc/Makefile to automatically run the offline fix after builds
- Switch zoom helper bindings to const for modern JavaScript consistency
- Add .codespellignore to skip minified JavaScript files in vendor
directory and exclude common minified JS tokens from spell checking
The documentation now works seamlessly both offline (file:// URLs) and
online (http:// URLs). Basic Mermaid diagrams render correctly in both
cases. ELK layout functionality remains unavailable in offline mode due
to browser CORS restrictions on ES modules.
This resolves CORS errors that occurred when opening HTML files directly
in a browser, eliminating the need to serve files via a local HTTP server.
Fixes: https://github.com/rsyslog/rsyslog/issues/6255
Mark the custom edit_on_github extension as safe for parallel
reading/writing and forward GNU make's -j to sphinx-build. This removes
the Sphinx warning and allows true parallel docs builds.
Changes
- doc/source/_ext/edit_on_github.py: setup() now returns
parallel_read_safe=True and parallel_write_safe=True (plus version).
- doc/Makefile: if SPHINXOPTS lacks -j, propagate -jN from MAKEFLAGS to
sphinx-build. Bare "-j" maps to "-j auto". Respects explicit -j in
SPHINXOPTS.
Fixes: https://github.com/rsyslog/rsyslog/issues/6254
Co-authored-by: alorbach <alorbach@adiscon.com>
Building documentation from the dist tarball failed with a RuntimeError
("git executable not found") thrown during Sphinx startup. The helper
module hard-required git even when no .git repo is present.
This change replaces the hard requirement with a safe wrapper that
returns placeholders when git or a repository is unavailable. This lets
Sphinx complete when building from release/dist sources, while keeping
dev builds unchanged.
Details:
- conf_helpers.py: introduce _run_git(); return 'unknown'/'nogit' for
branch/commit and '0.0' for tag-derived versions when git is absent.
- Harden next-version parsing for non-git environments.
- conf.py already guards dev-only dynamic strings behind .git presence.
Fixes: https://github.com/rsyslog/rsyslog/issues/6253
Co-authored-by: alorbach <alorbach@adiscon.com>
* Updates for actions.rst, cryprov_gcry.rst, cryprov_ossl.rst, and dyn_stats.rst
Minor fix so that RainerScript has the same exact spelling in all documentation
Update cryprov_ossl.rst
Fixing spelling and typing mistakes
Update cryprov_gcry.rst
A minor fix for the case of the "algorithms" word and unnecessary an article has been removed.
Update actions.rst
A couple of typing mistakes are fixed in actions.rst.
* Update doc/source/configuration/cryprov_ossl.rst
* imklog: split parameter docs into reference pages
- moved module parameter descriptions into dedicated reference files with scope-correct anchors
- replaced inline parameter blocks with a summary list-table and added a hidden toctree
- preserved legacy directives and updated examples to camelCase per policy
With help of AI-Agent: ChatGPT
* imkafka: split parameter docs into reference pages
- create parameter reference pages for Broker, Topic, ConfParam, ConsumerGroup, Ruleset, and ParseHostname
- replace inline parameter tables with summary list-table and include the casing guidance note
- add a hidden toctree for the new parameter documentation files
With AI-Agent: ChatGPT
* imgssapi: split parameter docs into reference pages
* split legacy imgssapi input parameters into dedicated reference files with usage, metadata, and legacy directives
* replace inline parameter tables on the module page with a summary list-table, refreshed case-sensitivity note, and a hidden toctree linking the new parameter docs
AI-Agent: ChatGPT
Ensure osslChkPeerAuth starts with a null peer-certificate pointer and
frees any retrieved X509 certificate so OpenSSL allocations from
SSL_get_peer_certificate do not leak after TLS handshakes.
Add a new "Agent Chat Keywords" section documenting FINISH and
SUMMARIZE codewords to standardize agent end-of-session actions.
FINISH: review all changes.
SUMMARIZE: produce ready-to-copy PR and squashed commit summaries.
Doc-only change; no runtime or test impact.
Prevents potential crashes when logging connection failures where peer
name or IP information is unavailable.
The compiler detected a potential null pointer dereference in the
addSess() error cleanup path. When NULL_CHECK() macros fail and jump to
finalize_it, the peerName and peerIP parameters could be NULL but were
passed directly to propGetSzStr() in LogError().
Original error: ../../runtime/prop.h:66:18: error: potential null
pointer dereference [-Werror=null-dereference] 66 | return
(pThis->len < CONF_PROP_BUFSIZE) ? pThis->szVal.sz : pThis->szVal.psz; |
~~~~~^~~~~
