googleapis / googleapis/python-aiplatform
docs: enable warning as errors
- Lenguaje dominante
- Python
- Estrellas
- 905
- Forks
- 465
- Merge medio
- 1 d 13 h
- PR fusionados (30 d)
- 44
Descripción
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
```
Guía de contribución
Evaluación
Este issue todavía no se ha evaluado.