Fix MkDocs example engine showing unrelated macro aliases

[luadebug]

The Python parser was incorrectly adding AUI_DECLARATIVE_FOR to the highlight tokens for ALL examples, regardless of the symbol being documented. This caused examples with AUI_WITH_STYLE to show AUI_DECLARATIVE_FOR highlighting when documenting PropertyListRecursive.

Changes:

• Added _MACRO_ALIASES map to define macro-to-symbol relationships
• Created _add_relevant_macro_aliases() helper function
• Function only adds macro aliases when:
  1. The macro appears in the snippet AND
  2. The macro relates to the tokens being documented
• Replaced all 5 hardcoded AUI_DECLARATIVE_FOR checks with the new helper
• Added support for AUI_WITH_STYLE ↔ PropertyListRecursive mapping

This ensures macro aliases are only highlighted in relevant examples, fixing the issue where unrelated macros were being highlighted.

[gemini-code-assist]

Summary of Changes

Hello @luadebug, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request resolves an issue in the MkDocs example engine where macro aliases were being highlighted indiscriminately across all code examples, leading to inaccurate and confusing documentation. By introducing a structured mapping of macros to their canonical symbols and implementing a new function to conditionally add these aliases, the system now ensures that only macros relevant to the documented content are highlighted. This significantly improves the precision and clarity of code examples within the documentation.

Highlights

• Problem Addressed: The MkDocs example engine was incorrectly highlighting the AUI_DECLARATIVE_FOR macro in all examples, even when it was unrelated to the documented symbol. This was particularly noticeable in examples for PropertyListRecursive, which incorrectly showed AUI_DECLARATIVE_FOR highlighting instead of AUI_WITH_STYLE.
• New Macro Alias Mapping: Introduced a new _MACRO_ALIASES dictionary to explicitly define relationships between macro aliases (e.g., AUI_DECLARATIVE_FOR, AUI_WITH_STYLE) and their canonical symbol names (e.g., AForEachUI, PropertyListRecursive).
• Intelligent Macro Alias Addition: Implemented a helper function, _add_relevant_macro_aliases(), which intelligently adds macro aliases to the list of highlight tokens. This function ensures that a macro is only added if it appears within the code snippet AND is relevant to the symbols currently being documented.
• Refactoring Existing Logic: Replaced all five instances of hardcoded conditional logic for adding AUI_DECLARATIVE_FOR to highlight tokens with calls to the new _add_relevant_macro_aliases() helper function, centralizing the logic.
• Expanded Macro Support: Added specific mapping for AUI_WITH_STYLE to PropertyListRecursive and ass::PropertyListRecursive, ensuring correct highlighting for these related symbols.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request effectively resolves the issue of incorrect macro highlighting in MkDocs examples. The introduction of the _MACRO_ALIASES map and the _add_relevant_macro_aliases helper function provides a scalable and maintainable solution, replacing hardcoded logic with a more robust system. The changes are well-targeted and clearly explained. My review includes a couple of suggestions to improve code conciseness and error handling.

[luadebug]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively addresses the issue of unrelated macro alias highlighting in MkDocs examples. The introduction of the _MACRO_ALIASES map and the _add_relevant_macro_aliases helper function is a great way to centralize and manage the logic for macro highlighting. Replacing the hardcoded checks with calls to this new function significantly improves code clarity and maintainability. The improved exception handling is also a welcome change. I have one suggestion to make the symbol comparison logic in the new helper function more robust to prevent potential future issues.

[luadebug]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively addresses the issue of unrelated macro aliases being highlighted in MkDocs examples. The introduction of the _MACRO_ALIASES map and the _add_relevant_macro_aliases helper function provides a clean, centralized, and more robust solution compared to the previous hardcoded checks. Replacing the scattered logic with this new helper greatly improves code maintainability and readability. The improved exception handling is also a welcome change. I've suggested a small refactoring to the new helper function to further improve its performance and clarity.

[luadebug]

/gemini review

[gemini-code-assist]

Code Review

This pull request introduces a well-structured solution to fix incorrect macro highlighting in documentation examples. By creating a mapping between macros and their related symbols (_MACRO_ALIASES) and a helper function (_add_relevant_macro_aliases), the changes ensure that macros are only highlighted in relevant contexts. The refactoring correctly replaces multiple hardcoded checks with a single, more robust function call. Additionally, improving the exception handling from silently passing to logging a warning is a great enhancement for debuggability.

I have one suggestion to further improve the robustness and efficiency of the new helper function. Overall, this is a solid improvement to the documentation generation process.

[luadebug]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively resolves an issue where macro aliases were being incorrectly highlighted in unrelated documentation examples. The introduction of the _MACRO_ALIASES map and the _add_relevant_macro_aliases helper function provides a clean, data-driven solution that is a significant improvement over the previous hardcoded checks. By centralizing the logic for determining when to highlight a macro, the code is now more maintainable, extensible, and correct. The changes are well-implemented, and the improved error logging is a welcome addition. Overall, this is a solid enhancement to the documentation generator.

[luadebug]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively resolves the issue of unrelated macro aliases being highlighted by introducing a more robust and extensible system. The new _add_relevant_macro_aliases function and _MACRO_ALIASES map clarify the logic, and centralizing this functionality within the _compute_hl_lines wrapper is a significant improvement for code maintainability. I have one suggestion to further optimize the new logic.

[luadebug]

/gemini review

[gemini-code-assist]

Code Review

This pull request effectively refactors the logic for highlighting macro aliases in documentation examples. By introducing a centralized mapping and a helper function, you've eliminated hardcoded, repeated logic, making the system more maintainable and extensible. The new implementation correctly handles adding macro aliases only when they are relevant to the documented symbols, which fixes the bug described. My review includes a couple of minor suggestions to further refine the new code.

[luadebug]

/gemini review

[gemini-code-assist]

Code Review

This pull request provides an excellent fix for an issue where macro aliases were being highlighted incorrectly in documentation examples. The introduction of the _MACRO_ALIASES map and the _add_relevant_macro_aliases helper function is a great approach that centralizes the logic, making it more robust and easier to maintain. The removal of repetitive code blocks in favor of a new _compute_hl_lines wrapper with error handling is a significant improvement to the codebase. The changes are well-implemented and I have no further suggestions.

[Alex2772]

Still provides AUI_DECLARATIVE_FOR for unrelated pages. Use search bar