googleapis / googleapis/python-aiplatform

docs: enable warning as errors

未关闭
#2,395 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
api: vertex-ai
主要语言
Python
星标
905
派生
465
平均合并
1 天 13 小时
30 天内合并 PR
44

描述

I noticed in the docs build in noxfile.py, warnings are not treated as errors because the `-W` option is missing here:

https://github.com/googleapis/python-aiplatform/blob/cb904d772abd0836f67b1034074395ce7a032d66/noxfile.py#L279-L280

https://github.com/googleapis/python-aiplatform/blob/cb904d772abd0836f67b1034074395ce7a032d66/noxfile.py#L291-L301

```
-W
Turn warnings into errors. This means that the build stops at the first warning and sphinx-build exits with exit status 1.
```

https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-W

There is a workaround in owlbot.py to only fail the docs build if there are errors.

https://github.com/googleapis/python-aiplatform/blob/cb904d772abd0836f67b1034074395ce7a032d66/owlbot.py#L148-L149

The docs build is a form of static analysis and can catch docs issues which are not caught upstream. These issues may be reported via warnings. I checked the history and it looks like warnings as errors was disabled in https://github.com/googleapis/python-aiplatform/pull/22.

To enable warnings locally, make the following change
```
(py39) partheniou@partheniou-vm-3:~/git/python-aiplatform$ git diff
diff --git a/noxfile.py b/noxfile.py
index f90f5cad8..f134192e8 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -290,6 +290,7 @@ def docs(session):
shutil.rmtree(os.path.join("docs", "_build"), ignore_errors=True)
session.run(
"sphinx-build",
+ "-W",
"-T", # show full traceback on exception
"-N", # no colors
"-b",
```

The first warning which appeared is
```
Warning, treated as error:
/usr/local/google/home/partheniou/git/python-aiplatform/google/cloud/aiplatform/v1/schema/trainingjob/definition_v1/types/automl_image_classification.py:docstring of google.cloud.aiplatform.v1.schema.trainingjob.definition_v1.types.AutoMlImageClassification.inputs:1:duplicate object description of google.cloud.aiplatform.v1.schema.trainingjob.definition_v1.types.AutoMlImageClassification.inputs, other instance in aiplatform/definition_v1, use :noindex: for one of them
```

贡献指南

打开贡献指南

调研方向

从 noxfile.py 中的 docs 会话开始,比较链接行中的 sphinx-build 调用;issue 指出了缺少的 -W 选项。运行 docs nox 会话,并检查生成文档中报告的重复对象描述。完成的标准是 docs 构建将警告视为错误,并且报告的警告已得到处理。

由索引模型根据 Issue 内容生成。

评估

技术栈
python
领域
build-system, documentation
Issue 类型
文档
难度
2/5
预计耗时
1-3 小时
活跃度
停滞
描述清晰度
描述清楚
新手友好度
58/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。