Fix MkDocs example engine showing unrelated macro aliases - #649
Fix MkDocs example engine showing unrelated macro aliases#649luadebug wants to merge 37 commits into
Conversation
Summary of ChangesHello @luadebug, I'm Gemini Code Assist1! 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
Using Gemini Code AssistThe 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
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 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
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
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.
|
/gemini review |
There was a problem hiding this comment.
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.
|
/gemini review |
There was a problem hiding this comment.
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.
|
/gemini review |
There was a problem hiding this comment.
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.
|
/gemini review |
There was a problem hiding this comment.
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.
|
/gemini review |
There was a problem hiding this comment.
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.
|
/gemini review |
There was a problem hiding this comment.
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.
|
/gemini review |
There was a problem hiding this comment.
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.
|
Still provides 
|
Add _add_relevant_macro_aliases helper that only augments highlight tokens with relevant macro aliases when the alias actually appears in the snippet. Add _compute_hl_lines wrapper to centralize error handling. Remove repetitive try-except blocks throughout embed_doc and gen_pages.
- Fix C++ parser crashes on non-matching comment lines, enum forward declarations, and None returns from enum parsing - Escape C++ lambda introducer []() to prevent markdown link parsing - Add post-build hook to strip AUI_DECLARATIVE_FOR from search index on pages unrelated to AForEachUI fix: MkDocs example engine showing unrelated macro aliases - Add _add_relevant_macro_aliases helper for selective macro alias highlighting - Add _compute_hl_lines wrapper to centralize error handling - Remove repetitive try-except blocks throughout embed_doc and gen_pages - Remove hypertext links from example titles and note summaries - Wrap source paths in backticks to prevent auto-linking
- Centralize macro alias logic in _add_relevant_macro_aliases helper - Add _compute_hl_lines wrapper to remove repetitive try-except blocks - Strip leading blank lines in hl_lines computation - Extend hl_lines to cover full brace-delimited blocks - Prioritize documented name over strong patterns in snippet extraction - Remove URL-based index alias expansion - Convert example title links to plain text - Add parser cache for faster rebuilds - Fix C++ parser edge cases (None crashes, forward enum decls) - Escape C++ lambda []() from being parsed as markdown links - Add search index filtering hook for AUI_DECLARATIVE_FOR - Add port cleanup to pixi serve task
…versioning, consume_doc, CSS scope, gitignore
…rror and stale data leaks
…xample() function
…xi platforms, non-class guard, cache fingerprint, shared helpers
… and adjust CMake flags
…e cache fingerprint logic in Python generators
… 2019 Build Tools installation steps; refactor caching logic in cpp_parser.py and doxygen.py
… priority handling in documentation generation
…up MSVC for Windows
…mple snippet handling in documentation generation
…ation steps for Visual Studio 2019 Build Tools; refactor example printing logic in documentation generation
…ine handling in example snippets
…onymous enums in parser
|
Caution The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased. |
2 participants
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:
This ensures macro aliases are only highlighted in relevant examples, fixing the issue where unrelated macros were being highlighted.