From 78e2bbb57a50508def8afe9fd548d9585be821ac Mon Sep 17 00:00:00 2001 From: chalmer lowe Date: Fri, 23 Jan 2026 09:16:36 -0500 Subject: [PATCH 1/6] 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/6] 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/6] 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 %} From 4fa2a45b46bb16a0cfdfc1ae15e372571697f46c Mon Sep 17 00:00:00 2001 From: chalmer lowe Date: Wed, 28 Jan 2026 14:02:18 -0500 Subject: [PATCH 4/6] updates path to common macros in ads-template --- 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 820808566e..09b78e5dc2 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 f4afdea5adbbb972d7ab32479fea615f5cc61535 Mon Sep 17 00:00:00 2001 From: chalmer lowe Date: Thu, 29 Jan 2026 10:31:02 -0500 Subject: [PATCH 5/6] updates imports and duplicates content to ads-template --- gapic/ads-templates/docs/common_setup.py.j2 | 35 +++++++++++++++++++++ gapic/ads-templates/docs/conf.py.j2 | 2 +- 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 gapic/ads-templates/docs/common_setup.py.j2 diff --git a/gapic/ads-templates/docs/common_setup.py.j2 b/gapic/ads-templates/docs/common_setup.py.j2 new file mode 100644 index 0000000000..aa88878dc7 --- /dev/null +++ b/gapic/ads-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 %} diff --git a/gapic/ads-templates/docs/conf.py.j2 b/gapic/ads-templates/docs/conf.py.j2 index 09b78e5dc2..820808566e 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 "docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %} # # {{ api.naming.warehouse_package_name }} documentation build configuration file From c9f29cd93b6d40c287861a556d44178307d8274d Mon Sep 17 00:00:00 2001 From: chalmer lowe Date: Thu, 29 Jan 2026 13:14:21 -0500 Subject: [PATCH 6/6] update golden conf.py files --- tests/integration/goldens/asset/docs/conf.py | 38 +++++++++++++++++-- .../goldens/credentials/docs/conf.py | 38 +++++++++++++++++-- .../integration/goldens/eventarc/docs/conf.py | 38 +++++++++++++++++-- .../integration/goldens/logging/docs/conf.py | 38 +++++++++++++++++-- .../goldens/logging_internal/docs/conf.py | 38 +++++++++++++++++-- tests/integration/goldens/redis/docs/conf.py | 38 +++++++++++++++++-- .../goldens/redis_selective/docs/conf.py | 38 +++++++++++++++++-- 7 files changed, 245 insertions(+), 21 deletions(-) diff --git a/tests/integration/goldens/asset/docs/conf.py b/tests/integration/goldens/asset/docs/conf.py index 6c82dd6667..0c9f32e33e 100755 --- a/tests/integration/goldens/asset/docs/conf.py +++ b/tests/integration/goldens/asset/docs/conf.py @@ -12,8 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# -# +## # google-cloud-asset documentation build configuration file # # This file is execfile()d with the current directory set to its @@ -25,9 +24,12 @@ # 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 +import logging +from typing import Any # 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 @@ -383,3 +385,33 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# Setup for sphinx behaviors such as warning filters. +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()) diff --git a/tests/integration/goldens/credentials/docs/conf.py b/tests/integration/goldens/credentials/docs/conf.py index 0d3872aa87..b931406b01 100755 --- a/tests/integration/goldens/credentials/docs/conf.py +++ b/tests/integration/goldens/credentials/docs/conf.py @@ -12,8 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# -# +## # google-iam-credentials documentation build configuration file # # This file is execfile()d with the current directory set to its @@ -25,9 +24,12 @@ # 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 +import logging +from typing import Any # 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 @@ -383,3 +385,33 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# Setup for sphinx behaviors such as warning filters. +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()) diff --git a/tests/integration/goldens/eventarc/docs/conf.py b/tests/integration/goldens/eventarc/docs/conf.py index 33c2c7b641..7960c88ae9 100755 --- a/tests/integration/goldens/eventarc/docs/conf.py +++ b/tests/integration/goldens/eventarc/docs/conf.py @@ -12,8 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# -# +## # google-cloud-eventarc documentation build configuration file # # This file is execfile()d with the current directory set to its @@ -25,9 +24,12 @@ # 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 +import logging +from typing import Any # 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 @@ -383,3 +385,33 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# Setup for sphinx behaviors such as warning filters. +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()) diff --git a/tests/integration/goldens/logging/docs/conf.py b/tests/integration/goldens/logging/docs/conf.py index 0fe50dca96..182a272e31 100755 --- a/tests/integration/goldens/logging/docs/conf.py +++ b/tests/integration/goldens/logging/docs/conf.py @@ -12,8 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# -# +## # google-cloud-logging documentation build configuration file # # This file is execfile()d with the current directory set to its @@ -25,9 +24,12 @@ # 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 +import logging +from typing import Any # 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 @@ -383,3 +385,33 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# Setup for sphinx behaviors such as warning filters. +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()) diff --git a/tests/integration/goldens/logging_internal/docs/conf.py b/tests/integration/goldens/logging_internal/docs/conf.py index 0fe50dca96..182a272e31 100755 --- a/tests/integration/goldens/logging_internal/docs/conf.py +++ b/tests/integration/goldens/logging_internal/docs/conf.py @@ -12,8 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# -# +## # google-cloud-logging documentation build configuration file # # This file is execfile()d with the current directory set to its @@ -25,9 +24,12 @@ # 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 +import logging +from typing import Any # 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 @@ -383,3 +385,33 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# Setup for sphinx behaviors such as warning filters. +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()) diff --git a/tests/integration/goldens/redis/docs/conf.py b/tests/integration/goldens/redis/docs/conf.py index ee9513cfe0..b7a27a9b49 100755 --- a/tests/integration/goldens/redis/docs/conf.py +++ b/tests/integration/goldens/redis/docs/conf.py @@ -12,8 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# -# +## # google-cloud-redis documentation build configuration file # # This file is execfile()d with the current directory set to its @@ -25,9 +24,12 @@ # 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 +import logging +from typing import Any # 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 @@ -383,3 +385,33 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# Setup for sphinx behaviors such as warning filters. +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()) diff --git a/tests/integration/goldens/redis_selective/docs/conf.py b/tests/integration/goldens/redis_selective/docs/conf.py index ee9513cfe0..b7a27a9b49 100755 --- a/tests/integration/goldens/redis_selective/docs/conf.py +++ b/tests/integration/goldens/redis_selective/docs/conf.py @@ -12,8 +12,7 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions and # limitations under the License. -# -# +## # google-cloud-redis documentation build configuration file # # This file is execfile()d with the current directory set to its @@ -25,9 +24,12 @@ # 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 +import logging +from typing import Any # 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 @@ -383,3 +385,33 @@ napoleon_use_ivar = False napoleon_use_param = True napoleon_use_rtype = True + +# Setup for sphinx behaviors such as warning filters. +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())