Disable SPHINXOPT=-W for local env (#2013)

Summary:
With the introduction of tutorials, the turn around time for doc build
has become longer. By default, the tutorial is not built but SPHINXOPT=-W
treats it as error.

This commit disable the option for the local build while keeping it
for the CI.

Pull Request resolved: https://github.com/pytorch/audio/pull/2013

Reviewed By: carolineechen

Differential Revision: D32538952

Pulled By: mthrok

fbshipit-source-id: eae4ffd87100dff466f91abfe26a82aa702d605a

.circleci/build_docs/build_docs.sh

@@ -11,5 +11,5 @@ pushd docs
 pip install -r requirements.txt
 yum install -y -q libsndfile-devel
 pip install -r requirements-tutorials.txt
-BUILD_GALLERY=1 make html
+BUILD_GALLERY=1 make 'SPHINXOPTS=-W' html
 popd

CONTRIBUTING.md

@@ -133,6 +133,13 @@ make html
 ```
 
 The built docs should now be available in `docs/build/html`.
+If docstrings are mal-formed, warnings will be shown.
+In CI doc build job, `SPHINXOPTS=-W` option is enabled and warnings are treated as error.
+Please fix all the warnings when submitting a PR.
+(You can use `SPHINXOPTS=-W` in local env, but by default,
+tutorials are not built and it will be treated as error.
+To use the option, please set  `BUILD_GALLERY` as well.
+e.g. `BUILD_GALLERY=1 make 'SPHINXOPTS=-W' html`.)
 
 By default, the documentation only builds API reference.
 If you are working to add a new example/tutorial with sphinx-gallery then

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    = -W  # converts warnings into error
+SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = torchaudio
 SOURCEDIR     = source