Skip to content
This repository has been archived by the owner on Nov 17, 2023. It is now read-only.

turn on Sphinx warnings as errors #13544

Merged
merged 6 commits into from
Dec 18, 2018
Merged

turn on Sphinx warnings as errors #13544

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
02cb54e
turn on warnings as errors
aaronmarkham Dec 4, 2018
9061dee
move warnings as error logic to build_all_version
aaronmarkham Dec 5, 2018
e9b6fca
fix typo in comment
aaronmarkham Dec 5, 2018
8062d49
add warning as error option for docs pipeline
aaronmarkham Dec 6, 2018
2771065
bump ci to test again; use this chance to add notes on this feature
aaronmarkham Dec 6, 2018
985c837
fix bugs in image.py docs
aaronmarkham Dec 17, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions ci/docker/runtime_functions.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -1218,7 +1218,7 @@ deploy_docs() {
set -ex
pushd .

make docs
make docs SPHINXOPTS=-W

popd
}
Expand Down Expand Up @@ -1274,5 +1274,3 @@ EOF
declare -F | cut -d' ' -f3
echo
fi


6 changes: 5 additions & 1 deletion docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
7 changes: 6 additions & 1 deletion docs/build_version_doc/build_all_version.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't we enable this in general? Otherwise a release branch might run into problems.

Also, is this script executed as part of the pr pipeline? We want to fail PRs ideally

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I added the -W option to the new docs pipeline. This should force it to happen any time that runs. And the website build flow will still skip it for old versions. I'm not totally familiar with new pipelines, so please let me know if you think this is going to be an issue or not.

OPTS="-W"
fi
git submodule update --init --recursive
cd ..
Expand Down Expand Up @@ -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
Expand Down
8 changes: 4 additions & 4 deletions python/mxnet/image/image.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
----------
Expand Down Expand Up @@ -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
----------
Expand Down Expand Up @@ -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
----------
Expand Down Expand Up @@ -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.
Expand Down