[docs] documentation build test (#958)

* added doc test

* fixed 404

* prevented maito: ref creation

* added rst structure test

* fixed unknown directives

* added code for the future check for html syntax

* replaced problem link

.travis.yml

@@ -19,6 +19,7 @@ env:
     - TASK=regular
     - TASK=mpi PYTHON_VERSION=2.7
     - TASK=pylint
+    - TASK=check-docs
     - TASK=if-else
     - TASK=sdist PYTHON_VERSION=3.4
     - TASK=bdist PYTHON_VERSION=3.5
@@ -35,6 +36,8 @@ matrix:
       env: TASK=if-else
     - os: osx
       env: TASK=pylint
+    - os: osx
+      env: TASK=check-docs
 
 before_install:
   - test -n $CC  && unset CC

.travis/setup.sh

@@ -4,7 +4,7 @@ if [[ $TRAVIS_OS_NAME == "osx" ]]; then
     brew install openmpi  # use openmpi to install gcc
     wget -O conda.sh https://repo.continuum.io/miniconda/Miniconda${PYTHON_VERSION:0:1}-latest-MacOSX-x86_64.sh
 else
-    if [[ ${TASK} != "pylint" ]]; then
+    if [[ ${TASK} != "pylint" ]] && [[ ${TASK} != "check-docs" ]]; then
         sudo add-apt-repository ppa:george-edison55/cmake-3.x -y
         sudo apt-get update -q
         sudo apt-get install -y cmake

.travis/test.sh

@@ -25,6 +25,18 @@ esac
 
 cd $TRAVIS_BUILD_DIR
 
+if [[ ${TASK} == "check-docs" ]]; then
+    cd docs
+    sudo apt-get install linkchecker
+    pip install rstcheck  # html5validator
+    pip install -r requirements.txt
+    rstcheck --ignore-directives=autoclass,autofunction `find . -type f -name "*.rst"` || exit -1
+    make html || exit -1
+#    html5validator --root ./_build/html/ || exit -1  For future (Sphinx 1.6) usage
+    linkchecker --config=.linkcheckerrc ./_build/html/*.html || exit -1
+    exit 0
+fi
+
 if [[ ${TASK} == "pylint" ]]; then
     pip install pep8
     pep8 --ignore=E501 --exclude=./compute,./docs . || exit -1

docs/.linkcheckerrc

+[checking]
+recursionlevel=1
+anchors=1
+sslverify=0
+
+[filtering]
+ignorewarnings=http-robots-denied,https-certificate-error
+
+[output]
+# Set to 0 if you want see only warnings and errors
+verbose=1
+
+[AnchorCheck]

docs/GPU-Performance.rst

@@ -131,33 +131,33 @@ The following table lists the accuracy on test set that CPU and GPU learner can
 GPU with the same number of bins can achieve a similar level of accuracy as on the CPU, despite using single precision arithmetic.
 For most datasets, using 63 bins is sufficient.
 
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
 |                           | CPU 255 bins   | CPU 63 bins   | CPU 15 bins   | GPU 255 bins   | GPU 63 bins   | GPU 15 bins   |
-+=====================+================+===============+===============+================+===============+===============+
++===========================+================+===============+===============+================+===============+===============+
 | Higgs AUC                 | 0.845612       | 0.845239      | 0.841066      | 0.845612       | 0.845209      | 0.840748      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
 | Epsilon AUC               | 0.950243       | 0.949952      | 0.948365      | 0.950057       | 0.949876      | 0.948365      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
-| Yahoo-LTR NDCG@1    | 0.730824       | 0.730165      | 0.729647      | 0.730936       | 0.732257      | 0.73114       |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
-| Yahoo-LTR NDCG@3    | 0.738687       | 0.737243      | 0.736445      | 0.73698        | 0.739474      | 0.735868      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
-| Yahoo-LTR NDCG@5    | 0.756609       | 0.755729      | 0.754607      | 0.756206       | 0.757007      | 0.754203      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
-| Yahoo-LTR NDCG@10   | 0.79655        | 0.795827      | 0.795273      | 0.795894       | 0.797302      | 0.795584      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
+| Yahoo-LTR NDCG\ :sub:`1`  | 0.730824       | 0.730165      | 0.729647      | 0.730936       | 0.732257      | 0.73114       |
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
+| Yahoo-LTR NDCG\ :sub:`3`  | 0.738687       | 0.737243      | 0.736445      | 0.73698        | 0.739474      | 0.735868      |
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
+| Yahoo-LTR NDCG\ :sub:`5`  | 0.756609       | 0.755729      | 0.754607      | 0.756206       | 0.757007      | 0.754203      |
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
+| Yahoo-LTR NDCG\ :sub:`10` | 0.79655        | 0.795827      | 0.795273      | 0.795894       | 0.797302      | 0.795584      |
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
 | Expo AUC                  | 0.776217       | 0.771566      | 0.743329      | 0.776285       | 0.77098       | 0.744078      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
-| MS-LTR NDCG@1       | 0.521265       | 0.521392      | 0.518653      | 0.521789       | 0.522163      | 0.516388      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
-| MS-LTR NDCG@3       | 0.503153       | 0.505753      | 0.501697      | 0.503886       | 0.504089      | 0.501691      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
-| MS-LTR NDCG@5       | 0.509236       | 0.510391      | 0.507193      | 0.509861       | 0.510095      | 0.50663       |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
-| MS-LTR NDCG@10      | 0.527835       | 0.527304      | 0.524603      | 0.528009       | 0.527059      | 0.524722      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
+| MS-LTR NDCG\ :sub:`1`     | 0.521265       | 0.521392      | 0.518653      | 0.521789       | 0.522163      | 0.516388      |
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
+| MS-LTR NDCG\ :sub:`3`     | 0.503153       | 0.505753      | 0.501697      | 0.503886       | 0.504089      | 0.501691      |
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
+| MS-LTR NDCG\ :sub:`5`     | 0.509236       | 0.510391      | 0.507193      | 0.509861       | 0.510095      | 0.50663       |
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
+| MS-LTR NDCG\ :sub:`10`    | 0.527835       | 0.527304      | 0.524603      | 0.528009       | 0.527059      | 0.524722      |
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
 | Bosch AUC                 | 0.718115       | 0.721791      | 0.716677      | 0.717184       | 0.724761      | 0.717005      |
-+---------------------+----------------+---------------+---------------+----------------+---------------+---------------+
++---------------------------+----------------+---------------+---------------+----------------+---------------+---------------+
 
 We record the wall clock time after 500 iterations, as shown in the figure below:
 

docs/Parameters.md

@@ -38,7 +38,7 @@ The parameter format is `key1=value1 key2=value2 ... ` . And parameters can be s
     * `fair`, [Fair loss](https://www.kaggle.com/c/allstate-claims-severity/discussion/24520)
     * `poisson`, [Poisson regression](https://en.wikipedia.org/wiki/Poisson_regression "Poisson regression")
   * `binary`, binary classification application
-  * `lambdarank`, [lambdarank](https://pdfs.semanticscholar.org/fc9a/e09f9ced555558fdf1e997c0a5411fb51f15.pdf) application
+  * `lambdarank`, [lambdarank](https://papers.nips.cc/paper/2971-learning-to-rank-with-nonsmooth-cost-functions.pdf) application
     * The label should be `int` type in lambdarank tasks, and larger number represent the higher relevance (e.g. 0:bad, 1:fair, 2:good, 3:perfect).
     * `label_gain` can be used to set the gain(weight) of `int` label.
   * `multiclass`, multi-class classification application, should set `num_class` as well
@@ -267,7 +267,7 @@ The parameter format is `key1=value1 key2=value2 ... ` . And parameters can be s
   * `fair`, [Fair loss](https://www.kaggle.com/c/allstate-claims-severity/discussion/24520)
   * `poisson`, [Poisson regression](https://en.wikipedia.org/wiki/Poisson_regression "Poisson regression")
   * `ndcg`, [NDCG](https://en.wikipedia.org/wiki/Discounted_cumulative_gain#Normalized_DCG)
-  * `map`, [MAP](https://www.kaggle.com/wiki/MeanAveragePrecision)
+  * `map`, [MAP](https://en.wikipedia.org/wiki/Information_retrieval#Mean_average_precision)
   * `auc`, [AUC](https://en.wikipedia.org/wiki/Receiver_operating_characteristic#Area_under_the_curve)
   * `binary_logloss`, [log loss](https://www.kaggle.com/wiki/LogLoss)
   * `binary_error`. For one sample `0` for correct classification, `1` for error classification.

docs/Quick-Start.md

@@ -54,7 +54,7 @@ Some important parameters:
     * `fair`, [Fair loss](https://www.kaggle.com/c/allstate-claims-severity/discussion/24520)
     * `poisson`, [Poisson regression](https://en.wikipedia.org/wiki/Poisson_regression "Poisson regression")
   * `binary`, binary classification application 
-  * `lambdarank`, [lambdarank](https://pdfs.semanticscholar.org/fc9a/e09f9ced555558fdf1e997c0a5411fb51f15.pdf) application
+  * `lambdarank`, [lambdarank](https://papers.nips.cc/paper/2971-learning-to-rank-with-nonsmooth-cost-functions.pdf) application
     * The label should be `int` type in lambdarank tasks, and larger number represent the higher relevance (e.g. 0:bad, 1:fair, 2:good, 3:perfect).
     * `label_gain` can be used to set the gain(weight) of `int` label.
   * `multiclass`, multi-class classification application, should set `num_class` as well

docs/index.rst

@@ -28,5 +28,4 @@ Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`

docs/requirements.txt

-sphinx
+sphinx<=1.5.6
 sphinxcontrib-napoleon
 sphinx_rtd_theme
 recommonmark