From 02cb54e1e71ad90c9153205a6fa357b3d1ed4a83 Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Tue, 4 Dec 2018 11:45:00 -0800 Subject: [PATCH 1/6] turn on warnings as errors --- docs/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Makefile b/docs/Makefile index 90603b0875fc..23399b38f958 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -74,7 +74,7 @@ livehtml: html: export BUILD_VER=$(BUILD_VER) @echo "Env var set for BUILD_VER: $(BUILD_VER)" - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + $(SPHINXBUILD) -W -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." From 9061dee8f5ba62f4b08f2d0efcf6a1d38ff96631 Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Wed, 5 Dec 2018 10:53:29 -0800 Subject: [PATCH 2/6] move warnings as error logic to build_all_version --- docs/Makefile | 2 +- docs/build_version_doc/build_all_version.sh | 7 ++++++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/Makefile b/docs/Makefile index 23399b38f958..90603b0875fc 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -74,7 +74,7 @@ livehtml: html: export BUILD_VER=$(BUILD_VER) @echo "Env var set for BUILD_VER: $(BUILD_VER)" - $(SPHINXBUILD) -W -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." diff --git a/docs/build_version_doc/build_all_version.sh b/docs/build_version_doc/build_all_version.sh index 5f857996f19d..5fafe3b4b5fb 100755 --- a/docs/build_version_doc/build_all_version.sh +++ b/docs/build_version_doc/build_all_version.sh @@ -43,6 +43,9 @@ set -e set -x +# Set OPT 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 From e9b6fcaef267e2acc217f65eacf94f7e1a8e2969 Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Wed, 5 Dec 2018 13:48:54 -0800 Subject: [PATCH 3/6] fix typo in comment --- ci/docker/runtime_functions.sh | 6 ++---- docs/build_version_doc/build_all_version.sh | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/ci/docker/runtime_functions.sh b/ci/docker/runtime_functions.sh index d12958fa613e..cb8df1862680 100755 --- a/ci/docker/runtime_functions.sh +++ b/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 -W popd } @@ -1274,5 +1274,3 @@ EOF declare -F | cut -d' ' -f3 echo fi - - diff --git a/docs/build_version_doc/build_all_version.sh b/docs/build_version_doc/build_all_version.sh index 5fafe3b4b5fb..6b8c3cbd864e 100755 --- a/docs/build_version_doc/build_all_version.sh +++ b/docs/build_version_doc/build_all_version.sh @@ -43,7 +43,7 @@ set -e set -x -# Set OPT to any Sphinx build options, like -W for "warnings as errors" +# Set OPTS to any Sphinx build options, like -W for "warnings as errors" OPTS= # $1 is the list of branches/tags to build From 8062d49d046f397b2df9a599b0e823b010aa0fe9 Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Wed, 5 Dec 2018 21:38:14 -0800 Subject: [PATCH 4/6] add warning as error option for docs pipeline --- ci/docker/runtime_functions.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/docker/runtime_functions.sh b/ci/docker/runtime_functions.sh index cb8df1862680..2ee03f931035 100755 --- a/ci/docker/runtime_functions.sh +++ b/ci/docker/runtime_functions.sh @@ -1218,7 +1218,7 @@ deploy_docs() { set -ex pushd . - make docs -W + make docs SPHINXOPTS=-W popd } From 277106557ca066e1f333aae0de92e9d0e23e68e9 Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Thu, 6 Dec 2018 15:26:42 -0800 Subject: [PATCH 5/6] bump ci to test again; use this chance to add notes on this feature --- docs/README.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index c21836edd821..80463cc68d54 100644 --- a/docs/README.md +++ b/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 From 985c8371b3f38ebdc4263117eb8dced15a349603 Mon Sep 17 00:00:00 2001 From: Aaron Markham Date: Mon, 17 Dec 2018 12:14:33 -0800 Subject: [PATCH 6/6] fix bugs in image.py docs --- python/mxnet/image/image.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/python/mxnet/image/image.py b/python/mxnet/image/image.py index b452aecdb04b..1dd665607597 100644 --- a/python/mxnet/image/image.py +++ b/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.