Skip to content

Commit 1f06194

Browse files
chalmerlowechalmerlowe
authored
fix: filter sphinx warnings related to adding a new line after lists (#2533)
1 parent 35d1b0f commit 1f06194

File tree

11 files changed

+329
-24
lines changed

11 files changed

+329
-24
lines changed

‎packages/gapic-generator/gapic/ads-templates/docs/common_setup.py.j2‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{% macro sphinx_imports() -%}
2+
import logging
3+
from typing import Any
4+
{%- endmacro %}
5+
6+
{% macro sphinx_setup() -%}
7+
class UnexpectedUnindentFilter(logging.Filter):
8+
"""Filter out warnings about unexpected unindentation following bullet lists."""
9+
10+
def filter(self, record: logging.LogRecord) -> bool:
11+
"""Filter the log record.
12+
13+
Args:
14+
record (logging.LogRecord): The log record.
15+
16+
Returns:
17+
bool: False to suppress the warning, True to allow it.
18+
"""
19+
msg = record.getMessage()
20+
if "Bullet list ends without a blank line" in msg:
21+
return False
22+
return True
23+
24+
25+
def setup(app: Any) -> None:
26+
"""Setup the Sphinx application.
27+
28+
Args:
29+
app (Any): The Sphinx application.
30+
"""
31+
# Sphinx's logger is hierarchical. Adding a filter to the
32+
# root 'sphinx' logger will catch warnings from all sub-loggers.
33+
logger = logging.getLogger('sphinx')
34+
logger.addFilter(UnexpectedUnindentFilter())
35+
{%- endmacro %}

‎packages/gapic-generator/gapic/ads-templates/docs/conf.py.j2‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{% extends '_base.py.j2' %}
22

33
{% block content %}
4+
{% from "docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %}
45

56
#
67
# {{ api.naming.warehouse_package_name }} documentation build configuration file
@@ -14,9 +15,11 @@
1415
# All configuration values have a default; values that are commented out
1516
# serve to show the default.
1617

17-
import sys
18+
import logging
1819
import os
1920
import shlex
21+
import sys
22+
{{ sphinx_imports() }}
2023

2124
# If extensions (or modules to document with autodoc) are in another directory,
2225
# add these directories to sys.path here. If the directory is relative to the
@@ -361,4 +364,7 @@ napoleon_use_admonition_for_references = False
361364
napoleon_use_ivar = False
362365
napoleon_use_param = True
363366
napoleon_use_rtype = True
367+
368+
# Setup for sphinx behaviors such as warning filters.
369+
{{ sphinx_setup() }}
364370
{% endblock %}

‎packages/gapic-generator/gapic/templates/docs/common_setup.py.j2‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
{% macro sphinx_imports() -%}
2+
import logging
3+
from typing import Any
4+
{%- endmacro %}
5+
6+
{% macro sphinx_setup() -%}
7+
class UnexpectedUnindentFilter(logging.Filter):
8+
"""Filter out warnings about unexpected unindentation following bullet lists."""
9+
10+
def filter(self, record: logging.LogRecord) -> bool:
11+
"""Filter the log record.
12+
13+
Args:
14+
record (logging.LogRecord): The log record.
15+
16+
Returns:
17+
bool: False to suppress the warning, True to allow it.
18+
"""
19+
msg = record.getMessage()
20+
if "Bullet list ends without a blank line" in msg:
21+
return False
22+
return True
23+
24+
25+
def setup(app: Any) -> None:
26+
"""Setup the Sphinx application.
27+
28+
Args:
29+
app (Any): The Sphinx application.
30+
"""
31+
# Sphinx's logger is hierarchical. Adding a filter to the
32+
# root 'sphinx' logger will catch warnings from all sub-loggers.
33+
logger = logging.getLogger('sphinx')
34+
logger.addFilter(UnexpectedUnindentFilter())
35+
{%- endmacro %}

‎packages/gapic-generator/gapic/templates/docs/conf.py.j2‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
{% extends '_base.py.j2' %}
22

33
{% block content %}
4-
4+
{% from "docs/common_setup.py.j2" import sphinx_imports, sphinx_setup %}
55
#
66
# {{ api.naming.warehouse_package_name }} documentation build configuration file
77
#
@@ -14,9 +14,11 @@
1414
# All configuration values have a default; values that are commented out
1515
# serve to show the default.
1616

17-
import sys
17+
import logging
1818
import os
1919
import shlex
20+
import sys
21+
{{ sphinx_imports() }}
2022

2123
# If extensions (or modules to document with autodoc) are in another directory,
2224
# add these directories to sys.path here. If the directory is relative to the
@@ -372,4 +374,7 @@ napoleon_use_admonition_for_references = False
372374
napoleon_use_ivar = False
373375
napoleon_use_param = True
374376
napoleon_use_rtype = True
377+
378+
# Setup for sphinx behaviors such as warning filters.
379+
{{ sphinx_setup() }}
375380
{% endblock %}

‎packages/gapic-generator/tests/integration/goldens/asset/docs/conf.py‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,7 @@
1212
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1313
# See the License for the specific language governing permissions and
1414
# limitations under the License.
15-
#
16-
#
15+
##
1716
# google-cloud-asset documentation build configuration file
1817
#
1918
# This file is execfile()d with the current directory set to its
@@ -25,9 +24,12 @@
2524
# All configuration values have a default; values that are commented out
2625
# serve to show the default.
2726

28-
import sys
27+
import logging
2928
import os
3029
import shlex
30+
import sys
31+
import logging
32+
from typing import Any
3133

3234
# If extensions (or modules to document with autodoc) are in another directory,
3335
# add these directories to sys.path here. If the directory is relative to the
@@ -383,3 +385,33 @@
383385
napoleon_use_ivar = False
384386
napoleon_use_param = True
385387
napoleon_use_rtype = True
388+
389+
# Setup for sphinx behaviors such as warning filters.
390+
class UnexpectedUnindentFilter(logging.Filter):
391+
"""Filter out warnings about unexpected unindentation following bullet lists."""
392+
393+
def filter(self, record: logging.LogRecord) -> bool:
394+
"""Filter the log record.
395+
396+
Args:
397+
record (logging.LogRecord): The log record.
398+
399+
Returns:
400+
bool: False to suppress the warning, True to allow it.
401+
"""
402+
msg = record.getMessage()
403+
if "Bullet list ends without a blank line" in msg:
404+
return False
405+
return True
406+
407+
408+
def setup(app: Any) -> None:
409+
"""Setup the Sphinx application.
410+
411+
Args:
412+
app (Any): The Sphinx application.
413+
"""
414+
# Sphinx's logger is hierarchical. Adding a filter to the
415+
# root 'sphinx' logger will catch warnings from all sub-loggers.
416+
logger = logging.getLogger('sphinx')
417+
logger.addFilter(UnexpectedUnindentFilter())

‎packages/gapic-generator/tests/integration/goldens/credentials/docs/conf.py‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,7 @@
1212
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1313
# See the License for the specific language governing permissions and
1414
# limitations under the License.
15-
#
16-
#
15+
##
1716
# google-iam-credentials documentation build configuration file
1817
#
1918
# This file is execfile()d with the current directory set to its
@@ -25,9 +24,12 @@
2524
# All configuration values have a default; values that are commented out
2625
# serve to show the default.
2726

28-
import sys
27+
import logging
2928
import os
3029
import shlex
30+
import sys
31+
import logging
32+
from typing import Any
3133

3234
# If extensions (or modules to document with autodoc) are in another directory,
3335
# add these directories to sys.path here. If the directory is relative to the
@@ -383,3 +385,33 @@
383385
napoleon_use_ivar = False
384386
napoleon_use_param = True
385387
napoleon_use_rtype = True
388+
389+
# Setup for sphinx behaviors such as warning filters.
390+
class UnexpectedUnindentFilter(logging.Filter):
391+
"""Filter out warnings about unexpected unindentation following bullet lists."""
392+
393+
def filter(self, record: logging.LogRecord) -> bool:
394+
"""Filter the log record.
395+
396+
Args:
397+
record (logging.LogRecord): The log record.
398+
399+
Returns:
400+
bool: False to suppress the warning, True to allow it.
401+
"""
402+
msg = record.getMessage()
403+
if "Bullet list ends without a blank line" in msg:
404+
return False
405+
return True
406+
407+
408+
def setup(app: Any) -> None:
409+
"""Setup the Sphinx application.
410+
411+
Args:
412+
app (Any): The Sphinx application.
413+
"""
414+
# Sphinx's logger is hierarchical. Adding a filter to the
415+
# root 'sphinx' logger will catch warnings from all sub-loggers.
416+
logger = logging.getLogger('sphinx')
417+
logger.addFilter(UnexpectedUnindentFilter())

‎packages/gapic-generator/tests/integration/goldens/eventarc/docs/conf.py‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,7 @@
1212
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1313
# See the License for the specific language governing permissions and
1414
# limitations under the License.
15-
#
16-
#
15+
##
1716
# google-cloud-eventarc documentation build configuration file
1817
#
1918
# This file is execfile()d with the current directory set to its
@@ -25,9 +24,12 @@
2524
# All configuration values have a default; values that are commented out
2625
# serve to show the default.
2726

28-
import sys
27+
import logging
2928
import os
3029
import shlex
30+
import sys
31+
import logging
32+
from typing import Any
3133

3234
# If extensions (or modules to document with autodoc) are in another directory,
3335
# add these directories to sys.path here. If the directory is relative to the
@@ -383,3 +385,33 @@
383385
napoleon_use_ivar = False
384386
napoleon_use_param = True
385387
napoleon_use_rtype = True
388+
389+
# Setup for sphinx behaviors such as warning filters.
390+
class UnexpectedUnindentFilter(logging.Filter):
391+
"""Filter out warnings about unexpected unindentation following bullet lists."""
392+
393+
def filter(self, record: logging.LogRecord) -> bool:
394+
"""Filter the log record.
395+
396+
Args:
397+
record (logging.LogRecord): The log record.
398+
399+
Returns:
400+
bool: False to suppress the warning, True to allow it.
401+
"""
402+
msg = record.getMessage()
403+
if "Bullet list ends without a blank line" in msg:
404+
return False
405+
return True
406+
407+
408+
def setup(app: Any) -> None:
409+
"""Setup the Sphinx application.
410+
411+
Args:
412+
app (Any): The Sphinx application.
413+
"""
414+
# Sphinx's logger is hierarchical. Adding a filter to the
415+
# root 'sphinx' logger will catch warnings from all sub-loggers.
416+
logger = logging.getLogger('sphinx')
417+
logger.addFilter(UnexpectedUnindentFilter())

‎packages/gapic-generator/tests/integration/goldens/logging/docs/conf.py‎

Lines changed: 35 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,7 @@
1212
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
1313
# See the License for the specific language governing permissions and
1414
# limitations under the License.
15-
#
16-
#
15+
##
1716
# google-cloud-logging documentation build configuration file
1817
#
1918
# This file is execfile()d with the current directory set to its
@@ -25,9 +24,12 @@
2524
# All configuration values have a default; values that are commented out
2625
# serve to show the default.
2726

28-
import sys
27+
import logging
2928
import os
3029
import shlex
30+
import sys
31+
import logging
32+
from typing import Any
3133

3234
# If extensions (or modules to document with autodoc) are in another directory,
3335
# add these directories to sys.path here. If the directory is relative to the
@@ -383,3 +385,33 @@
383385
napoleon_use_ivar = False
384386
napoleon_use_param = True
385387
napoleon_use_rtype = True
388+
389+
# Setup for sphinx behaviors such as warning filters.
390+
class UnexpectedUnindentFilter(logging.Filter):
391+
"""Filter out warnings about unexpected unindentation following bullet lists."""
392+
393+
def filter(self, record: logging.LogRecord) -> bool:
394+
"""Filter the log record.
395+
396+
Args:
397+
record (logging.LogRecord): The log record.
398+
399+
Returns:
400+
bool: False to suppress the warning, True to allow it.
401+
"""
402+
msg = record.getMessage()
403+
if "Bullet list ends without a blank line" in msg:
404+
return False
405+
return True
406+
407+
408+
def setup(app: Any) -> None:
409+
"""Setup the Sphinx application.
410+
411+
Args:
412+
app (Any): The Sphinx application.
413+
"""
414+
# Sphinx's logger is hierarchical. Adding a filter to the
415+
# root 'sphinx' logger will catch warnings from all sub-loggers.
416+
logger = logging.getLogger('sphinx')
417+
logger.addFilter(UnexpectedUnindentFilter())

0 commit comments

Comments
 (0)