From c5b00ce59a25400dabe7cddb1f82471fa81ea62e Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 26 Jan 2026 15:45:10 +0000 Subject: [PATCH 1/4] Refactor Sphinx setup into a shared macro - Created gapic/templates/docs/common_setup.py.j2 - Updated gapic/templates/docs/conf.py.j2 - Updated gapic/ads-templates/docs/conf.py.j2 --- gapic/ads-templates/docs/conf.py.j2 | 3 +++ gapic/templates/docs/common_setup.py.j2 | 33 +++++++++++++++++++++++++ gapic/templates/docs/conf.py.j2 | 3 +++ 3 files changed, 39 insertions(+) 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 dcce591ca3..a2e2891557 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_setup %} # # {{ api.naming.warehouse_package_name }} documentation build configuration file @@ -361,4 +362,6 @@ napoleon_use_admonition_for_references = False napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +{{ 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..0af8ebe775 --- /dev/null +++ b/gapic/templates/docs/common_setup.py.j2 @@ -0,0 +1,33 @@ +{% macro sphinx_setup() -%} +import logging +from typing import Any + +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 %} diff --git a/gapic/templates/docs/conf.py.j2 b/gapic/templates/docs/conf.py.j2 index b509706ab6..7615ca09bc 100644 --- a/gapic/templates/docs/conf.py.j2 +++ b/gapic/templates/docs/conf.py.j2 @@ -1,6 +1,7 @@ {% extends '_base.py.j2' %} {% block content %} +{% from "docs/common_setup.py.j2" import sphinx_setup %} # # {{ api.naming.warehouse_package_name }} documentation build configuration file @@ -372,4 +373,6 @@ napoleon_use_admonition_for_references = False napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +{{ sphinx_setup() }} {% endblock %} From 0e58b5ac7a6410f8822da7a7f7d514053e49e37b Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 26 Jan 2026 15:59:24 +0000 Subject: [PATCH 2/4] Refactor Sphinx setup with separated imports and setup macros - Created gapic/templates/docs/common_setup.py.j2 with sphinx_imports and sphinx_setup macros - Updated gapic/templates/docs/conf.py.j2 to call imports at top and setup at bottom - Updated gapic/ads-templates/docs/conf.py.j2 similarly --- gapic/ads-templates/docs/conf.py.j2 | 3 ++- gapic/templates/docs/common_setup.py.j2 | 4 +++- gapic/templates/docs/conf.py.j2 | 3 ++- 3 files changed, 7 insertions(+), 3 deletions(-) diff --git a/gapic/ads-templates/docs/conf.py.j2 b/gapic/ads-templates/docs/conf.py.j2 index a2e2891557..13dd419581 100644 --- a/gapic/ads-templates/docs/conf.py.j2 +++ b/gapic/ads-templates/docs/conf.py.j2 @@ -1,7 +1,7 @@ {% extends '_base.py.j2' %} {% block content %} -{% from "docs/common_setup.py.j2" import sphinx_setup %} +{% 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 sys import os import shlex +{{ 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 diff --git a/gapic/templates/docs/common_setup.py.j2 b/gapic/templates/docs/common_setup.py.j2 index 0af8ebe775..aa88878dc7 100644 --- a/gapic/templates/docs/common_setup.py.j2 +++ b/gapic/templates/docs/common_setup.py.j2 @@ -1,7 +1,9 @@ -{% macro sphinx_setup() -%} +{% 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.""" diff --git a/gapic/templates/docs/conf.py.j2 b/gapic/templates/docs/conf.py.j2 index 7615ca09bc..4513ed3439 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_setup %} +{% 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 sys import os import shlex +{{ 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 From b554f1f8192cc3ad70aeee4cee49ccebd0402980 Mon Sep 17 00:00:00 2001 From: Chalmer Lowe Date: Mon, 26 Jan 2026 15:32:48 -0500 Subject: [PATCH 3/4] Apply suggestion from @chalmerlowe --- gapic/ads-templates/docs/conf.py.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gapic/ads-templates/docs/conf.py.j2 b/gapic/ads-templates/docs/conf.py.j2 index 13dd419581..7a40fbe67c 100644 --- a/gapic/ads-templates/docs/conf.py.j2 +++ b/gapic/ads-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 %} +{% from "‎gapic/templates/docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %} # # {{ api.naming.warehouse_package_name }} documentation build configuration file From 8ee15f6a3ba49c276d3e4db2417cb63a7cae30d4 Mon Sep 17 00:00:00 2001 From: "google-labs-jules[bot]" <161369871+google-labs-jules[bot]@users.noreply.github.com> Date: Mon, 26 Jan 2026 20:35:14 +0000 Subject: [PATCH 4/4] Refactor Sphinx setup - fix ads-templates import path - Updated gapic/ads-templates/docs/conf.py.j2 to use full path for common_setup import based on PR feedback. Co-authored-by: chalmerlowe <7291104+chalmerlowe@users.noreply.github.com> --- gapic/ads-templates/docs/conf.py.j2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/gapic/ads-templates/docs/conf.py.j2 b/gapic/ads-templates/docs/conf.py.j2 index 7a40fbe67c..082da22742 100644 --- a/gapic/ads-templates/docs/conf.py.j2 +++ b/gapic/ads-templates/docs/conf.py.j2 @@ -1,7 +1,7 @@ {% extends '_base.py.j2' %} {% block content %} -{% from "‎gapic/templates/docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %} +{% from "gapic/templates/docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %} # # {{ api.naming.warehouse_package_name }} documentation build configuration file