docs: enable warning as errors

[parthea]

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

python-aiplatform/noxfile.py

Lines 279 to 280 in cb904d7

	def docs(session):
	"""Build the docs for this library."""

python-aiplatform/noxfile.py

Lines 291 to 301 in cb904d7

	session.run(
	"sphinx-build",
	"-T", # show full traceback on exception
	"-N", # no colors
	"-b",
	"html",
	"-d",
	os.path.join("docs", "_build", "doctrees", ""),
	os.path.join("docs", ""),
	os.path.join("docs", "_build", "html", ""),
	)

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

python-aiplatform/owlbot.py

Lines 148 to 149 in cb904d7

	# Don't treat docs warnings as errors
	s.replace("noxfile.py", """ ["']-W["'], # warnings as errors\n""", "")

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