fix: filter sphinx warnings related to adding a new line after lists #2533
Conversation
Summary of ChangesHello @chalmerlowe, 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 aims to streamline the Sphinx documentation build process by eliminating a common, often non-critical, warning related to bullet list formatting. By integrating a custom logging filter directly into the 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 updates the conf.py.j2 templates for Sphinx to suppress the 'Bullet list ends without a blank line' warning. This is achieved by adding a custom logging.Filter. The implementation is correct and follows standard Sphinx practices. I've provided a suggestion to make the filter logic more concise in both updated files.
| msg = record.getMessage() | ||
| if "Bullet list ends without a blank line" in msg: | ||
| return False | ||
| return True |
There was a problem hiding this comment.
For conciseness, the logic in the filter method can be simplified to a single return statement.
return "Bullet list ends without a blank line" not in record.getMessage()
| msg = record.getMessage() | ||
| if "Bullet list ends without a blank line" in msg: | ||
| return False | ||
| return True |
There was a problem hiding this comment.
For conciseness, the logic in the filter method can be simplified to a single return statement.
return "Bullet list ends without a blank line" not in record.getMessage()
|
To whomever reviews this. I am curious about your feelings on the Gemini suggestions. I worry that the concise version suggested decreases readability by forcing some mental gymnastics over |
parthea
changed the title
| class UnexpectedUnindentFilter(logging.Filter): | ||
| """Filter out warnings about unexpected unindentation following bullet lists.""" | ||
| def filter(self, record): | ||
| # Return False to suppress the warning, True to allow it | ||
| msg = record.getMessage() | ||
| if "Bullet list ends without a blank line" in msg: | ||
| return False | ||
| return True |
There was a problem hiding this comment.
Can we include this (and the setup function below) in a separate file as a macro and use it in both templates and ad-templates? I'm guessing we'll keep introducing new code for each warning as per this pattern and it'll be easier to maintain code if it's one place.
3 participants
This PR updates the
conf.pytemplates to suppress the "Bullet list ends without a blank line" warning from Sphinx.This warning often appears in generated documentation where strict adherence to blank lines after bullet lists is not always feasible or necessary. To reduce noise in the build logs, a custom logging filter is added to the Sphinx configuration.
Changes:
gapic/templates/docs/conf.py.j2andgapic/ads-templates/docs/conf.py.j2UnexpectedUnindentFilter, a customlogging.Filterclass, to catch warnings containing the message "Bullet list ends without a blank line".sphinxlogger in thesetup()function.