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 dcce591ca3..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 @@ -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 %} diff --git a/gapic/templates/docs/common_setup.py.j2 b/gapic/templates/docs/common_setup.py.j2 new file mode 100644 index 0000000000..42d2fef589 --- /dev/null +++ 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 b509706ab6..c468e5f018 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 # @@ -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 %} 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())