From 78e2bbb57a50508def8afe9fd548d9585be821ac Mon Sep 17 00:00:00 2001 From: chalmer lowe Date: Fri, 23 Jan 2026 09:16:36 -0500 Subject: [PATCH 1/3] updates conf.py.js templates to add sphinx warnings --- gapic/ads-templates/docs/conf.py.j2 | 20 +++++++++++++++++++- gapic/templates/docs/conf.py.j2 | 20 +++++++++++++++++++- 2 files changed, 38 insertions(+), 2 deletions(-) diff --git a/gapic/ads-templates/docs/conf.py.j2 b/gapic/ads-templates/docs/conf.py.j2 index dcce591ca3..82d5e34d02 100644 --- a/gapic/ads-templates/docs/conf.py.j2 +++ b/gapic/ads-templates/docs/conf.py.j2 @@ -14,9 +14,10 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys +import logging import os import shlex +import sys # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -361,4 +362,21 @@ napoleon_use_admonition_for_references = False napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# --- Specific warning filters not covered by suppress_warnings --- + +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 + +def setup(app): + # Sphinx's logger is hierarchical. Adding a filter to the + # root 'sphinx' logger will catch warnings from all sub-loggers. + logger = logging.getLogger('sphinx') + logger.addFilter(UnexpectedUnindentFilter()) {% endblock %} diff --git a/gapic/templates/docs/conf.py.j2 b/gapic/templates/docs/conf.py.j2 index b509706ab6..3beaf57450 100644 --- a/gapic/templates/docs/conf.py.j2 +++ b/gapic/templates/docs/conf.py.j2 @@ -14,9 +14,10 @@ # All configuration values have a default; values that are commented out # serve to show the default. -import sys +import logging import os import shlex +import sys # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -372,4 +373,21 @@ napoleon_use_admonition_for_references = False napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# --- Specific warning filters not covered by suppress_warnings --- + +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 + +def setup(app): + # Sphinx's logger is hierarchical. Adding a filter to the + # root 'sphinx' logger will catch warnings from all sub-loggers. + logger = logging.getLogger('sphinx') + logger.addFilter(UnexpectedUnindentFilter()) {% endblock %} From df9df95d2ebab19317b0271910e33d673c4f2524 Mon Sep 17 00:00:00 2001 From: chalmer lowe Date: Mon, 26 Jan 2026 11:42:08 -0500 Subject: [PATCH 2/3] updates the location of common macros for ads and non-ads templates --- gapic/ads-templates/docs/conf.py.j2 | 20 ++++---------------- gapic/templates/docs/common_setup.py.j2 | 0 gapic/templates/docs/conf.py.j2 | 20 +++----------------- 3 files changed, 7 insertions(+), 33 deletions(-) create mode 100644 gapic/templates/docs/common_setup.py.j2 diff --git a/gapic/ads-templates/docs/conf.py.j2 b/gapic/ads-templates/docs/conf.py.j2 index 82d5e34d02..820808566e 100644 --- a/gapic/ads-templates/docs/conf.py.j2 +++ b/gapic/ads-templates/docs/conf.py.j2 @@ -1,6 +1,7 @@ {% extends '_base.py.j2' %} {% block content %} +{% from "docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %} # # {{ api.naming.warehouse_package_name }} documentation build configuration file @@ -18,6 +19,7 @@ import logging import os import shlex import sys +{{ sphinx_imports() }} # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -363,20 +365,6 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True -# --- Specific warning filters not covered by suppress_warnings --- - -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 - -def setup(app): - # Sphinx's logger is hierarchical. Adding a filter to the - # root 'sphinx' logger will catch warnings from all sub-loggers. - logger = logging.getLogger('sphinx') - logger.addFilter(UnexpectedUnindentFilter()) +# Setup for sphinx behaviors such as warning filters. +{{ sphinx_setup() }} {% endblock %} diff --git a/gapic/templates/docs/common_setup.py.j2 b/gapic/templates/docs/common_setup.py.j2 new file mode 100644 index 0000000000..e69de29bb2 diff --git a/gapic/templates/docs/conf.py.j2 b/gapic/templates/docs/conf.py.j2 index 3beaf57450..75a2c67865 100644 --- a/gapic/templates/docs/conf.py.j2 +++ b/gapic/templates/docs/conf.py.j2 @@ -1,7 +1,7 @@ {% extends '_base.py.j2' %} {% block content %} - +{% from "docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %} # # {{ api.naming.warehouse_package_name }} documentation build configuration file # @@ -18,6 +18,7 @@ import logging import os import shlex import sys +{{ sphinx_imports() }} # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -374,20 +375,5 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True -# --- Specific warning filters not covered by suppress_warnings --- - -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 - -def setup(app): - # Sphinx's logger is hierarchical. Adding a filter to the - # root 'sphinx' logger will catch warnings from all sub-loggers. - logger = logging.getLogger('sphinx') - logger.addFilter(UnexpectedUnindentFilter()) +{{ sphinx_setup() }} {% endblock %} From 3146a6392872c155261bb9ac722afeaeafb562ce Mon Sep 17 00:00:00 2001 From: chalmer lowe Date: Mon, 26 Jan 2026 11:50:57 -0500 Subject: [PATCH 3/3] updates conf.py.j2 templates and adds content to common_setup.py.j2 --- gapic/templates/docs/common_setup.py.j2 | 35 +++++++++++++++++++++++++ gapic/templates/docs/conf.py.j2 | 1 + 2 files changed, 36 insertions(+) diff --git a/gapic/templates/docs/common_setup.py.j2 b/gapic/templates/docs/common_setup.py.j2 index e69de29bb2..42d2fef589 100644 --- a/gapic/templates/docs/common_setup.py.j2 +++ b/gapic/templates/docs/common_setup.py.j2 @@ -0,0 +1,35 @@ +{% macro sphinx_imports() -%} +import logging +from typing import Any +{%- endmacro %} + +{% macro sphinx_setup() -%} +class UnexpectedUnindentFilter(logging.Filter): + """Filter out warnings about unexpected unindentation following bullet lists.""" + + def filter(self, record: logging.LogRecord) -> bool: + """Filter the log record. + + Args: + record (logging.LogRecord): The log record. + + Returns: + bool: 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 + + +def setup(app: Any) -> None: + """Setup the Sphinx application. + + Args: + app (Any): The Sphinx application. + """ + # Sphinx's logger is hierarchical. Adding a filter to the + # root 'sphinx' logger will catch warnings from all sub-loggers. + logger = logging.getLogger('sphinx') + logger.addFilter(UnexpectedUnindentFilter()) +{%- endmacro %} \ No newline at end of file diff --git a/gapic/templates/docs/conf.py.j2 b/gapic/templates/docs/conf.py.j2 index 75a2c67865..c468e5f018 100644 --- a/gapic/templates/docs/conf.py.j2 +++ b/gapic/templates/docs/conf.py.j2 @@ -375,5 +375,6 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True +# Setup for sphinx behaviors such as warning filters. {{ sphinx_setup() }} {% endblock %}