turn on Sphinx warnings as errors (#13544)

* turn on warnings as errors

* move warnings as error logic to build_all_version

* fix typo in comment

* add warning as error option for docs pipeline

* bump ci to test again; use this chance to add notes on this feature

* fix bugs in image.py docs

ci/docker/runtime_functions.sh

@@ -1188,7 +1188,7 @@ nightly_straight_dope_python3_multi_gpu_tests() {
 nightly_tutorial_test_ubuntu_python3_gpu() {
  set -ex
  cd /work/mxnet/docs
- export BUILD_VER=tutorial 
+ export BUILD_VER=tutorial
  export MXNET_DOCS_BUILD_MXNET=0
  make html
  export MXNET_STORAGE_FALLBACK_LOG_VERBOSE=0
@@ -1218,7 +1218,7 @@ deploy_docs() {
  set -ex
  pushd .
 
- make docs
+ make docs SPHINXOPTS=-W
 
  popd
 }
@@ -1274,5 +1274,3 @@ EOF
  declare -F | cut -d' ' -f3
  echo
 fi
-
-

docs/README.md

@@ -17,9 +17,13 @@ git clone --recursive https://github.com/apache/incubator-mxnet.git mxnet
 cd mxnet/docs/build_version_doc
 ./setup_docs_ubuntu.sh
 cd ../../
-make docs USE_OPENMP=1
+make docs USE_OPENMP=1 SPHINXOPTS=-W
 ```
 
+OpenMP speeds things up and will work on Ubuntu if you used the `setup_docs_ubuntu.sh` script.
+The `-W` Sphinx option enforces "warnings as errors". This will help you debug your builds and get them through CI.
+**CI will not let a PR through if it breaks the website.** Refer to the [MXNet Developer wiki's documentation guide](https://cwiki.apache.org/confluence/display/MXNET/Documentation+Guide) for troubleshooting tips.
+
 For more information on each API's documentation dependencies, how to serve the docs, or how to build the full website with each legacy MXNet version, refer to the following links:
 
 * [Dependencies](https://github.com/apache/incubator-mxnet/tree/master/docs/build_version_doc#dependencies) - required before you build the docs

docs/build_version_doc/build_all_version.sh

@@ -43,6 +43,9 @@
 set -e
 set -x
 
+# Set OPTS to any Sphinx build options, like -W for "warnings as errors"
+OPTS=
+
 # $1 is the list of branches/tags to build
 if [ -z "$1" ]
  then
@@ -117,6 +120,8 @@ function checkout () {
  git checkout "$repo_folder" || git branch $repo_folder "upstream/$repo_folder" && git checkout "$repo_folder" || exit 1
  if [ $tag == 'master' ]; then
  git pull
+ # master gets warnings as errors for Sphinx builds
+ OPTS="-W"
  fi
  git submodule update --init --recursive
  cd ..
@@ -160,7 +165,7 @@ for key in ${!build_arr[@]}; do
 
  echo "Building $tag..."
  cd $tag/docs
- make html USE_OPENMP=1 BUILD_VER=$tag || exit 1
+ make html USE_OPENMP=1 BUILD_VER=$tag SPHINXOPTS=$OPTS || exit 1
  # Navigate back to build_version_doc folder
  cd ../../../
  # Use the display tag name for the folder name

python/mxnet/image/image.py

@@ -46,7 +46,7 @@ def imread(filename, *args, **kwargs):
  """Read and decode an image to an NDArray.
 
  .. note:: `imread` uses OpenCV (not the CV2 Python library).
- MXNet must have been built with USE_OPENCV=1 for `imdecode` to work.
+  MXNet must have been built with USE_OPENCV=1 for `imdecode` to work.
 
  Parameters
  ----------
@@ -87,7 +87,7 @@ def imresize(src, w, h, *args, **kwargs):
  r"""Resize image with OpenCV.
 
  .. note:: `imresize` uses OpenCV (not the CV2 Python library). MXNet must have been built
- with USE_OPENCV=1 for `imresize` to work.
+  with USE_OPENCV=1 for `imresize` to work.
 
  Parameters
  ----------
@@ -144,7 +144,7 @@ def imdecode(buf, *args, **kwargs):
  """Decode an image to an NDArray.
 
  .. note:: `imdecode` uses OpenCV (not the CV2 Python library).
- MXNet must have been built with USE_OPENCV=1 for `imdecode` to work.
+  MXNet must have been built with USE_OPENCV=1 for `imdecode` to work.
 
  Parameters
  ----------
@@ -345,7 +345,7 @@ def resize_short(src, size, interp=2):
  """Resizes shorter edge to size.
 
  .. note:: `resize_short` uses OpenCV (not the CV2 Python library).
- MXNet must have been built with OpenCV for `resize_short` to work.
+  MXNet must have been built with OpenCV for `resize_short` to work.
 
  Resizes the original image by setting the shorter edge to size
  and setting the longer edge accordingly.