fix: filter sphinx warnings related to adding a new line after lists

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 %}

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
@@ -14,9 +15,11 @@
 # 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
+{{ 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
@@ -361,4 +364,7 @@ napoleon_use_admonition_for_references = False
 napoleon_use_ivar = False
 napoleon_use_param = True
 napoleon_use_rtype = True
+
+# Setup for sphinx behaviors such as warning filters.
+{{ sphinx_setup() }}
 {% endblock %}

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 %}

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
 #
@@ -14,9 +14,11 @@
 # 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
+{{ 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
@@ -372,4 +374,7 @@ napoleon_use_admonition_for_references = False
 napoleon_use_ivar = False
 napoleon_use_param = True
 napoleon_use_rtype = True
+
+# Setup for sphinx behaviors such as warning filters.
+{{ sphinx_setup() }}
 {% endblock %}

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())

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())

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())

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())