googleapis / googleapis/python-aiplatform

docs: enable warning as errors

Open
#2,395 0 comments 0 reactions 0 assignees View on GitHub
api: vertex-ai
Dominant language
Python
Stars
905
Forks
465
Avg merge
1d 13h
Merged PRs (30d)
44

Description

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
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.