Feature render mermaid diagrams in sphinx docs as GFM does

[reactive-firewall]

Patch Notes

• This patch focuses on project documentation and while it greatly enhances dark-mode viewing with diagrams, it may have little impact on light-mode viewing.
• includes a minor CI/CD hotfix for coverage testing to use bash shell

Impacted GHI

• Closes v2.1.x Chore - Setup sphinx to render mermaid code-blocks like GFM does #413

Included and Superseded PR/MRs

• None

---

Summary by CodeRabbit

• Documentation

  • Enhanced Mermaid diagram support and styling across multiple documentation files for a consistent dark theme.
  • Corrected typographical errors in documentation and README.
  • Added detailed docstring and embedded unit tests to an existing documentation function.
  • Updated documentation dependencies to include Mermaid diagram support.
  • Added new known typo pair for spell-checking regression tests.

• Chores

  • Updated test workflow configuration for improved shell specification and command formatting.

[coderabbitai]

Walkthrough

This change updates documentation and CI configuration to improve Mermaid diagram rendering in Sphinx-generated docs, corrects a typo in the README, and specifies the shell for a test coverage step in the GitHub Actions workflow. It also adds the sphinxcontrib-mermaid dependency and enhances Sphinx configuration for Mermaid support.

Changes

Files/Group	Change Summary
docs/conf.py, docs/requirements.txt	Added Mermaid plugin and configuration to Sphinx; updated requirements for sphinxcontrib-mermaid; added docstring tests to linkcode_resolve.
docs/CI.md, docs/Testing.md	Inserted Mermaid diagram initialization for dark theme and color consistency; fixed a typo in CI.md.
.github/workflows/Tests.yml	Specified shell: bash for test coverage step and adjusted the run command syntax.
README.md	Corrected a typographical error ("recieved" to "received").
tests/check_spelling	Added a new known typo pair "selectivly:selectively" for regression spell-checking.

Sequence Diagram(s)

sequenceDiagram
    participant User
    participant Sphinx
    participant MermaidPlugin

    User->>Sphinx: Build documentation
    Sphinx->>MermaidPlugin: Render mermaid code-blocks
    MermaidPlugin-->>Sphinx: Return diagrams with dark theme
    Sphinx-->>User: Serve rendered documentation

Loading

Assessment against linked issues

Objective	Addressed	Explanation
Use mermaid plugin for sphinx, configuration for mermaid, configure myst to recognize mermaid codeblocks (#413)	✅
Credit plugin's authors and mention to users its license (#413)	✅

Assessment against linked issues: Out-of-scope changes

No out-of-scope changes found.

Suggested labels

Documentation, Bash Lang

Poem

In docs and code, a rabbit hops,
Adding Mermaid magic in Sphinxy stops.
Typos fixed, the README’s neat,
Workflows now with bash complete.
With diagrams bright and docs refined,
This bunny leaves no task behind!
🐇✨

---

📜 Recent review details

Configuration used: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between e377c70 and 7b63697.

📒 Files selected for processing (3)

• README.md (1 hunks)
• docs/conf.py (5 hunks)
• tests/check_spelling (1 hunks)

🧰 Additional context used

📓 Path-based instructions (4)

`README.md`: 1. Consider the file 'README.md' the overview/introduction of the project. Also consider the 'README.md' file the first place to look for project documentation. 2. ...

README.md: 1. Consider the file 'README.md' the overview/introduction of the project.
Also consider the 'README.md' file the first place to look for project documentation.
2. When reviewing the file 'README.md' it should be linted with help
from the tools markdownlint and languagetool, pointing out any issues.
3. You may assume the file 'README.md' will contain GitHub flavor Markdown. 4. The file README.md contains many links to additional valuable project documentation. 5. Ensure the README is kept current.

• README.md

`tests/*`: When reviewing **test** code: 1. Prioritize portability over clarity, especially when dealing with cross-Python compatibility. However, with the priority in mind, do ...

tests/*: When reviewing test code: 1. Prioritize portability over clarity, especially when dealing with cross-Python
compatibility. However, with the priority in mind, do still consider improvements
to clarity when relevant.
2. As a general guideline, consider the code style advocated in the PEP 8 standard
(excluding the use of spaces for indentation) and evaluate suggested changes
for code style compliance.
3. As a style convention, consider the code style advocated in
CEP-8
and evaluate suggested changes for code style compliance, pointing out any
violations discovered.
4. As a style convention, consider the code style advocated in
CEP-9
and evaluate suggested changes for nomenclature compliance, pointing out any
violations discovered, along with suggestions generated to correct the nomenclature.
5. As a general guideline, try to provide any relevant, official, and supporting
documentation links to any tool's suggestions in review comments. This guideline is
important for posterity.
6. As a project rule, Python source files with names prefixed by the string
"test_" and located in the project's "tests" directory are the project's unit-testing
code. It is safe, albeit a heuristic, to assume these are considered part of the
project's minimal acceptance testing unless a justifying exception to this assumption
is documented.
7. As a project rule, any files without extensions and with names prefixed by either the
string "check_" or the string "test_", and located in the project's "tests" directory,
are the project's non-unit test code. "Non-unit test" in this context refers to any
type of testing other than unit testing, such as (but not limited to)
functional testing, style linting, regression testing, etc. It can also be assumed
that non-unit testing code is usually (but not always) written as Bash shell scripts.

• tests/check_spelling

`**/*.py`: When reviewing **Python** code for this project: 1. Prioritize portability over clarity, especially when dealing with cross-Python compatibility. However, with the pr...

**/*.py: When reviewing Python code for this project: 1. Prioritize portability over clarity, especially when dealing with cross-Python
compatibility. However, with the priority in mind, do still consider improvements to
clarity when relevant.
2. As a general guideline, consider the code style advocated in the PEP 8 standard
(excluding the use of spaces for indentation) and evaluate suggested changes for code
style compliance.
3. As a style convention, consider the code style advocated in
CEP-8
and evaluate suggested changes for code style compliance.
4. As a general guideline, try to provide any relevant, official, and supporting
documentation links to any tool's suggestions in review comments. This guideline is
important for posterity.
5. As a general rule, undocumented function definitions and class definitions in the
project's Python code are assumed incomplete. Please consider suggesting a short
summary of the code for any of these incomplete definitions as docstrings when
reviewing. All documentation including docstrings in the project are to align with
the guidelines set by
CEP-7.
6. Verify Flake8's configuration file is located at ".flake8.ini". Flake8 is run
automaticly by the flake8-cq GHA used by the .github/workflows/flake8.yml workflow.
7. Verify alignment of any new changes, with the code style advocated in
CEP-8,
pointing out any introduced deviations.

• docs/conf.py

`docs/*`: When a project contains a `docs/` directory: 1. Consider the files in the `docs/` directory tree the core/main/in-depth documentation of the project. Also consider the...

docs/*: When a project contains a docs/ directory: 1. Consider the files in the docs/ directory tree the core/main/in-depth documentation
of the project. Also consider the 'docs/**.md' files the second place to look for
project documentation after the 'README.md' file.
2. When reviewing the documentation files (e.g., docs/**.md), they should additionally
be linted with help from the tool markdownlint, pointing out any issues.
3. When reviewing the documentation files in docs/ directory, they should additionally
be linted with help from the tool languagetool, pointing out any issues.

• docs/conf.py

🧠 Learnings (2)

📓 Common learnings

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#424
File: docs/Testing.md:308-312
Timestamp: 2025-05-27T22:39:32.660Z
Learning: Reactive-firewall prefers to maintain documentation formatting that preserves paragraph structure and readability over strict style rules, particularly when line length constraints and the intent of content organization (like maintaining single paragraph flow) are factors, indicating a preference for practical readability over cosmetic formatting adjustments.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#115
File: multicast/hear.py:180-180
Timestamp: 2024-09-19T03:43:24.037Z
Learning: Reactive-firewall prefers to re-use already loaded modules to keep memory overhead low when possible.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#115
File: multicast/hear.py:180-180
Timestamp: 2024-10-08T21:59:30.537Z
Learning: Reactive-firewall prefers to re-use already loaded modules to keep memory overhead low when possible.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#415
File: .github/AI_USAGE_POLICY.md:32-34
Timestamp: 2025-05-25T21:33:32.345Z
Learning: Reactive-firewall prefers to maintain existing documentation style and wording in policy documents, declining stylistic refinements when the current text is functional, indicating a preference for stability over cosmetic improvements in documentation.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#379
File: .ast-grep/utils/python/structure/multicast-mtool-subclass-definitions/undecorated_function_definition.yml:8-12
Timestamp: 2025-04-23T04:07:24.393Z
Learning: Reactive-firewall follows the "Avoid Hasty Abstraction" principle, being cautious about changes that might introduce unnecessary abstractions or alter existing behavior, particularly in configuration files like ast-grep rule definitions.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#139
File: tests/test_fuzz.py:73-73
Timestamp: 2024-10-08T21:59:27.171Z
Learning: Reactive-firewall prefers not to introduce new dependencies into the codebase when writing test functions.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#402
File: .github/actions/setup-py-reqs/action.yml:79-85
Timestamp: 2025-05-17T02:33:33.421Z
Learning: Reactive-firewall prefers to maintain the original structure of conditional statements when fixing logic errors in GitHub Action YAML files, and relies on environment variables with proper defaults rather than dynamic fallbacks when handling input parameters.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#420
File: docs/CI.md:445-447
Timestamp: 2025-05-27T04:12:39.228Z
Learning: Reactive-firewall prefers to maintain intentional wording choices in documentation even when automated grammar tools suggest changes, indicating a preference for preserving deliberate stylistic decisions over automated corrections.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#235
File: .github/workflows/makefile-lint.yml:41-52
Timestamp: 2024-12-06T08:21:21.876Z
Learning: Reactive-firewall prefers to suppress errors in `apt-get install` commands when individual checks of the installed packages are performed afterwards, to allow for more granular error handling.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#118
File: tests/check_pip:92-197
Timestamp: 2024-10-08T21:59:30.537Z
Learning: Reactive-firewall prefers defining functions before they are called in Bash scripts to avoid errors due to Bash's sequential interpretation.

docs/conf.py (14)

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#426
File: docs/conf.py:297-304
Timestamp: 2025-06-04T23:35:18.664Z
Learning: In Sphinx configuration files, extension configuration variables like mermaid_d3_zoom and mermaid_params must maintain their exact names as expected by the respective plugins (sphinxcontrib-mermaid in this case), and cannot be renamed to follow Python constant naming conventions without breaking functionality.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#148
File: tests/context.py:839-862
Timestamp: 2024-10-09T06:14:46.547Z
Learning: For future reviews, remember to consult [CEP-9](https://gist.github.com/reactive-firewall/d840ee9990e65f302ce2a8d78ebe73f6) for the project's naming conventions in testing.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#379
File: .ast-grep/utils/python/structure/multicast-mtool-subclass-definitions/undecorated_function_definition.yml:8-12
Timestamp: 2025-04-23T04:07:24.393Z
Learning: Reactive-firewall follows the "Avoid Hasty Abstraction" principle, being cautious about changes that might introduce unnecessary abstractions or alter existing behavior, particularly in configuration files like ast-grep rule definitions.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#402
File: .github/actions/setup-py-reqs/action.yml:90-97
Timestamp: 2025-05-17T05:02:42.856Z
Learning: Reactive-firewall prefers to maintain the original structure and approach in GitHub Action YAML files even when presented with alternative implementations that might improve readability, indicating a preference for consistency over refactoring.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#415
File: .github/AI_USAGE_POLICY.md:32-34
Timestamp: 2025-05-25T21:33:32.345Z
Learning: Reactive-firewall prefers to maintain existing documentation style and wording in policy documents, declining stylistic refinements when the current text is functional, indicating a preference for stability over cosmetic improvements in documentation.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#424
File: docs/Testing.md:396-396
Timestamp: 2025-05-27T20:36:21.684Z
Learning: Reactive-firewall prefers to maintain existing documentation heading structure and wording even when stylistic improvements are suggested, indicating a preference for stability over cosmetic changes in documentation headings.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#427
File: docs/utils.py:289-291
Timestamp: 2025-06-03T03:35:10.259Z
Learning: The reactive-firewall/multicast project uses tabs for indentation instead of spaces, explicitly deviating from PEP 8's space indentation recommendation as stated in their coding guidelines: "consider the code style advocated in the PEP 8 standard (excluding the use of spaces for indentation)". Pylint warnings about spaces vs tabs should be ignored as false positives in this project.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#427
File: docs/utils.py:289-291
Timestamp: 2025-06-03T03:35:10.259Z
Learning: The reactive-firewall/multicast project uses tabs for indentation instead of spaces, explicitly deviating from PEP 8's space indentation recommendation as stated in their coding guidelines: "consider the code style advocated in the PEP 8 standard (excluding the use of spaces for indentation)". Their .flake8.ini file explicitly ignores W191 (Indentation contains tabs) and pyproject.toml also ignores W191. Pylint warnings about spaces vs tabs should be ignored as false positives in this project.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#427
File: docs/utils.py:283-287
Timestamp: 2025-06-03T03:33:31.402Z
Learning: The multicast project uses tabs for indentation per CEP-8 standards, not spaces. When reviewing Python code in this project, tab indentation is correct and should not be changed to spaces.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#110
File: docs/FAQ.md:81-83
Timestamp: 2024-09-17T05:51:07.824Z
Learning: In the 'multicast' project, code should be indented using Tabs instead of spaces. This is detailed as a convention by [CEP-8](https://gist.github.com/reactive-firewall/b7ee98df9e636a51806e62ef9c4ab161)

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#426
File: docs/conf.py:458-497
Timestamp: 2025-06-05T00:26:31.207Z
Learning: PEP-8's tabs vs spaces guidance allows tabs "solely to remain consistent with code that is already indented with tabs." Projects that consistently use tabs throughout their codebase are compliant with PEP-8 via the consistency provision, not deviating from it. Converting tabs to spaces in such projects would actually violate PEP-8's consistency requirement.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#426
File: docs/conf.py:458-497
Timestamp: 2025-06-04T23:46:04.912Z
Learning: The multicast project follows CEP-8 coding conventions which use tabs for indentation instead of spaces, contrary to standard PEP-8. The coding guidelines explicitly state "excluding the use of spaces for indentation" when following PEP 8, and mandate following CEP-8 style conventions.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#426
File: docs/conf.py:458-497
Timestamp: 2025-06-04T23:46:04.912Z
Learning: CEP-8 explicitly requires using tabs instead of spaces for indentation in the multicast project. The document states "Use **tabs** instead of spaces for indentation" and "One tab equals one level of indentation (equivalent to 4 spaces)". This is a deliberate deviation from PEP-8's space-based indentation recommendation.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#427
File: docs/utils.py:276-276
Timestamp: 2025-06-03T03:18:38.024Z
Learning: The multicast project follows CEP-8 guidelines which explicitly specify using tabs instead of spaces for indentation (one tab equals one level of indentation, equivalent to 4 spaces). This is a deliberate deviation from standard PEP-8 and all indentation suggestions should be evaluated against CEP-8 standards rather than standard Python formatting conventions.

🪛 Pylint (3.3.7)

docs/conf.py

[convention] 301-301: Constant name "mermaid_d3_zoom" doesn't conform to UPPER_CASE naming style

(C0103)

---

[warning] 458-458: Bad indentation. Found 1 spaces, expected 4

(W0311)

🪛 ast-grep (0.38.1)

docs/conf.py

[hint] 497-497: Consider adding a trailing comma.
Context: str
Suggested replacement: str,

(python-rule-add-trailing-comma)

⏰ Context from checks skipped due to timeout of 90000ms (1)

• GitHub Check: CI-MATs

🔇 Additional comments (7)

tests/check_spelling (1)

161-161: LGTM! Proper regression test addition.

The new typo pair follows the established format and pattern for regression testing. This ensures the "selectivly:selectively" typo won't reappear in future commits.

README.md (1)

151-151: Good spelling correction!

The typo "recieved" has been correctly fixed to "received". This aligns with the broader documentation quality improvements in this PR.

docs/conf.py (5)

80-80: LGTM - Mermaid extension properly added.

The addition of sphinxcontrib.mermaid extension correctly enables Mermaid diagram support in Sphinx documentation.

---

106-106: LGTM - TOML file support added.

The addition of TOML file recognition to source_suffix appropriately extends Sphinx's source file processing capabilities.

---

201-201: LGTM - INI syntax highlighting configuration updated.

The change to use pygments_yaml_options for INI files provides more appropriate syntax highlighting with smaller tab size and stricter whitespace handling for configuration files.

---

297-304: LGTM - Mermaid configuration properly implemented.

The Mermaid configuration correctly enables GFM-style diagram rendering with appropriate dark theme settings. The variable names mermaid_d3_zoom and mermaid_params must maintain their exact form as expected by the sphinxcontrib-mermaid plugin.

Note: The Pylint warning about constant naming conventions should be ignored as these are plugin configuration variables that cannot be renamed.

🧰 Tools

🪛 Pylint (3.3.7)

[convention] 301-301: Constant name "mermaid_d3_zoom" doesn't conform to UPPER_CASE naming style

(C0103)

---

458-497: LGTM - Excellent comprehensive docstring with embedded tests.

The docstring significantly improves the function's documentation with:

• Clear description of the selective GitHub linking functionality
• Proper reference to official Sphinx documentation
• Comprehensive unit tests covering valid and invalid inputs
• Consistent CEP-8 tab indentation throughout

The embedded doctests provide valuable validation of the function's behavior and enhance maintainability.

Note: The Pylint W0311 indentation warning should be ignored as the project correctly follows CEP-8 standards which require tabs for indentation.

🧰 Tools

🪛 ast-grep (0.38.1)

[hint] 497-497: Consider adding a trailing comma.
Context: str
Suggested replacement: str,

(python-rule-add-trailing-comma)

🪛 Pylint (3.3.7)

[warning] 458-458: Bad indentation. Found 1 spaces, expected 4

(W0311)

✨ Finishing Touches

• 📝 Generate Docstrings

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

• Review comments: Directly reply to a review comment made by CodeRabbit. Example:
  • I pushed a fix in commit <commit_id>, please review it.
  • Explain this complex logic.
  • Open a follow-up GitHub issue for this discussion.
• Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
  • @coderabbitai explain this code block.
  • @coderabbitai modularize this function.
• PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
  • @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
  • @coderabbitai read src/utils.ts and explain its main purpose.
  • @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
  • @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

• @coderabbitai pause to pause the reviews on a PR.
• @coderabbitai resume to resume the paused reviews.
• @coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
• @coderabbitai full review to do a full review from scratch and review all the files again.
• @coderabbitai summary to regenerate the summary of the PR.
• @coderabbitai generate docstrings to generate docstrings for this PR.
• @coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
• @coderabbitai resolve resolve all the CodeRabbit review comments.
• @coderabbitai configuration to show the current CodeRabbit configuration for the repository.
• @coderabbitai help to get help.

Other keywords and placeholders

• Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
• Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
• Add @coderabbitai anywhere in the PR title to generate the title automatically.

Documentation and Community

• Visit our Documentation for detailed information on how to use CodeRabbit.
• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[deepsource-io]

Here's the code health analysis summary for commits 1e90003..7b63697. View details on DeepSource ↗.

Analysis Summary

Analyzer	Status	Summary	Link
Python	✅ Success		View Check ↗
Test coverage	✅ Success		View Check ↗

Code Coverage Report

Metric	Aggregate	Python
Branch Coverage	92.4%	92.4%
Composite Coverage	96.5%	96.5%
Line Coverage	96.8%, ✅ Above Threshold	96.8%, ✅ Above Threshold

---

💡 If you’re a repository administrator, you can configure the quality gates from the settings.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 95.056%. Comparing base (1e90003) to head (7b63697).

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #426   +/-   ##
=========================================
  Coverage   95.056%   95.056%           
=========================================
  Files           26        26           
  Lines         2144      2144           
  Branches       131       131           
=========================================
  Hits          2038      2038           
  Misses          66        66           
  Partials        40        40           

Flag	Coverage Δ
doctests	29.011% <ø> (ø)
multicast	99.259% <ø> (ø)
unittests	95.056% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

---

Continue to review full report in Codecov by Sentry.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 1e90003...7b63697. Read the comment docs.

[coderabbitai]

Actionable comments posted: 3

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 1e90003 and e377c70.

📒 Files selected for processing (6)

• .github/workflows/Tests.yml (1 hunks)
• README.md (1 hunks)
• docs/CI.md (6 hunks)
• docs/Testing.md (3 hunks)
• docs/conf.py (5 hunks)
• docs/requirements.txt (1 hunks)

🧰 Additional context used

📓 Path-based instructions (4)

`docs/*`: When a project contains a `docs/` directory: 1. Consider the files in the `docs/` directory tree the core/main/in-depth documentation of the project. Also consider the...

docs/*: When a project contains a docs/ directory: 1. Consider the files in the docs/ directory tree the core/main/in-depth documentation
of the project. Also consider the 'docs/**.md' files the second place to look for
project documentation after the 'README.md' file.
2. When reviewing the documentation files (e.g., docs/**.md), they should additionally
be linted with help from the tool markdownlint, pointing out any issues.
3. When reviewing the documentation files in docs/ directory, they should additionally
be linted with help from the tool languagetool, pointing out any issues.

• docs/requirements.txt
• docs/Testing.md
• docs/CI.md
• docs/conf.py

`README.md`: 1. Consider the file 'README.md' the overview/introduction of the project. Also consider the 'README.md' file the first place to look for project documentation. 2. ...

README.md: 1. Consider the file 'README.md' the overview/introduction of the project.
Also consider the 'README.md' file the first place to look for project documentation.
2. When reviewing the file 'README.md' it should be linted with help
from the tools markdownlint and languagetool, pointing out any issues.
3. You may assume the file 'README.md' will contain GitHub flavor Markdown. 4. The file README.md contains many links to additional valuable project documentation. 5. Ensure the README is kept current.

• README.md

`**/*.py`: When reviewing **Python** code for this project: 1. Prioritize portability over clarity, especially when dealing with cross-Python compatibility. However, with the pr...

**/*.py: When reviewing Python code for this project: 1. Prioritize portability over clarity, especially when dealing with cross-Python
compatibility. However, with the priority in mind, do still consider improvements to
clarity when relevant.
2. As a general guideline, consider the code style advocated in the PEP 8 standard
(excluding the use of spaces for indentation) and evaluate suggested changes for code
style compliance.
3. As a style convention, consider the code style advocated in
CEP-8
and evaluate suggested changes for code style compliance.
4. As a general guideline, try to provide any relevant, official, and supporting
documentation links to any tool's suggestions in review comments. This guideline is
important for posterity.
5. As a general rule, undocumented function definitions and class definitions in the
project's Python code are assumed incomplete. Please consider suggesting a short
summary of the code for any of these incomplete definitions as docstrings when
reviewing. All documentation including docstrings in the project are to align with
the guidelines set by
CEP-7.
6. Verify Flake8's configuration file is located at ".flake8.ini". Flake8 is run
automaticly by the flake8-cq GHA used by the .github/workflows/flake8.yml workflow.
7. Verify alignment of any new changes, with the code style advocated in
CEP-8,
pointing out any introduced deviations.

• docs/conf.py

`.github/**`: * When the project is hosted on GitHub: All GitHub-specific configurations, templates, and tools should be found in the '.github' directory tree. * 'actionlint' err...

.github/**: * When the project is hosted on GitHub: All GitHub-specific configurations, templates,
and tools should be found in the '.github' directory tree.

• 'actionlint' erroneously generates false positives when dealing with
  GitHub's ${{ ... }} syntax in conditionals.
• 'actionlint' erroneously generates incorrect solutions when suggesting the removal of
  valid ${{ ... }} syntax.

• .github/workflows/Tests.yml

🧠 Learnings (1)

📓 Common learnings

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#424
File: docs/Testing.md:308-312
Timestamp: 2025-05-27T22:39:32.660Z
Learning: Reactive-firewall prefers to maintain documentation formatting that preserves paragraph structure and readability over strict style rules, particularly when line length constraints and the intent of content organization (like maintaining single paragraph flow) are factors, indicating a preference for practical readability over cosmetic formatting adjustments.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#115
File: multicast/hear.py:180-180
Timestamp: 2024-09-19T03:43:24.037Z
Learning: Reactive-firewall prefers to re-use already loaded modules to keep memory overhead low when possible.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#115
File: multicast/hear.py:180-180
Timestamp: 2024-10-08T21:59:30.537Z
Learning: Reactive-firewall prefers to re-use already loaded modules to keep memory overhead low when possible.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#415
File: .github/AI_USAGE_POLICY.md:32-34
Timestamp: 2025-05-25T21:33:32.345Z
Learning: Reactive-firewall prefers to maintain existing documentation style and wording in policy documents, declining stylistic refinements when the current text is functional, indicating a preference for stability over cosmetic improvements in documentation.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#379
File: .ast-grep/utils/python/structure/multicast-mtool-subclass-definitions/undecorated_function_definition.yml:8-12
Timestamp: 2025-04-23T04:07:24.393Z
Learning: Reactive-firewall follows the "Avoid Hasty Abstraction" principle, being cautious about changes that might introduce unnecessary abstractions or alter existing behavior, particularly in configuration files like ast-grep rule definitions.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#139
File: tests/test_fuzz.py:73-73
Timestamp: 2024-10-08T21:59:27.171Z
Learning: Reactive-firewall prefers not to introduce new dependencies into the codebase when writing test functions.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#402
File: .github/actions/setup-py-reqs/action.yml:79-85
Timestamp: 2025-05-17T02:33:33.421Z
Learning: Reactive-firewall prefers to maintain the original structure of conditional statements when fixing logic errors in GitHub Action YAML files, and relies on environment variables with proper defaults rather than dynamic fallbacks when handling input parameters.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#420
File: docs/CI.md:445-447
Timestamp: 2025-05-27T04:12:39.228Z
Learning: Reactive-firewall prefers to maintain intentional wording choices in documentation even when automated grammar tools suggest changes, indicating a preference for preserving deliberate stylistic decisions over automated corrections.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#235
File: .github/workflows/makefile-lint.yml:41-52
Timestamp: 2024-12-06T08:21:21.876Z
Learning: Reactive-firewall prefers to suppress errors in `apt-get install` commands when individual checks of the installed packages are performed afterwards, to allow for more granular error handling.

Learnt from: reactive-firewall
PR: reactive-firewall/multicast#118
File: tests/check_pip:92-197
Timestamp: 2024-10-08T21:59:30.537Z
Learning: Reactive-firewall prefers defining functions before they are called in Bash scripts to avoid errors due to Bash's sequential interpretation.

🪛 LanguageTool

README.md

[uncategorized] ~151-~151: A comma might be missing here.
Context: ... on what needs to be done with received data each case will be a bit different. ```...

(AI_EN_LECTOR_MISSING_PUNCTUATION_COMMA)

🪛 Pylint (3.3.7)

docs/conf.py

[convention] 301-301: Constant name "mermaid_d3_zoom" doesn't conform to UPPER_CASE naming style

(C0103)

---

[warning] 458-458: Bad indentation. Found 1 spaces, expected 4

(W0311)

🪛 ast-grep (0.38.1)

docs/conf.py

[hint] 497-497: Consider adding a trailing comma.
Context: str
Suggested replacement: str,

(python-rule-add-trailing-comma)

🔇 Additional comments (10)

docs/requirements.txt (1)

53-54: Added sphinxcontrib-mermaid for Mermaid support
The new dependency aligns with the updated Sphinx configuration in docs/conf.py and enables Mermaid diagram rendering in the documentation.

docs/Testing.md (3)

201-201: Verify Mermaid init block consistency
Confirm that the %%{ init: { … } }%% directive before the sequenceDiagram is identical to the other Mermaid init blocks to avoid styling drift.

---

325-325: Verify Mermaid init block consistency
Double-check that the init directive preceding the coverage sequence diagram is the same as in other sections so all diagrams share the same dark-theme settings.

---

107-107:

✅ Verification successful

Verify Mermaid init block consistency
Ensure the initialization directive (%%{ init: { … } }%%) for the dark-themed graph matches the one in docs/CI.md (braces, spacing, themeVariables) to maintain uniform styling across all Mermaid diagrams.

Run this to diff the init blocks:

---

🏁 Script executed:

#!/bin/bash
rg "%%\{[[:space:]]*init:" -n docs/CI.md docs/Testing.md

Length of output: 2261

---

No inconsistencies found in Mermaid init blocks
The dark-theme %%{ init: … }%% directives in docs/Testing.md (line 107) and docs/CI.md (line 75) are identical. No changes needed.

.github/workflows/Tests.yml (1)

216-221: Explicitly set shell to bash for coverage step
Specifying shell: bash and switching to a multi-line run block improves readability and ensures consistent execution across different runner environments.

docs/CI.md (2)

75-75: Excellent consistency in Mermaid theme configuration.

The dark theme initialization directives are consistently applied across all Mermaid diagrams, ensuring uniform visual styling that aligns with the project's documentation theme. The configuration properly sets up dark mode with transparent background and orange accent colors.

Also applies to: 152-152, 198-198, 375-375, 477-477

---

350-350: Good catch on the typo fix.

Correcting "GitHub Anotated Messages" to "GitHub Annotated Messages" improves the documentation accuracy.

docs/conf.py (3)

80-80: Good addition of Mermaid extension support.

Adding sphinxcontrib.mermaid extension properly enables Mermaid diagram rendering in Sphinx documentation, aligning with the PR objectives.

---

106-106: Appropriate file format extension.

Adding TOML file support enhances the documentation's ability to include configuration files.

---

201-201: Sensible syntax highlighting configuration.

Applying YAML-style highlighting to INI files provides consistent formatting for configuration file types.

[reactive-firewall]

👍 LGTM!