[docs] fixed building at Python 2.x (#997)

* fixed docs building at Python 2.x

* updated docs building guide

* get back Python 3 at Travis

* test commit for OSX

* be more precise with python version inpylint task

* turned warnings into errors

* removed linkchecker validation from osx

* removed warning about not included into any toctree

* docs config cleanup

* refined deprecation warnings mechanism

* refine docs mock mechanism

* be more precise with python version in check-docs task

* redused the number of code lines

* refined venv deployment

* rollback python version in check-docs task

* revert 'refine docs mock mechanism'. autodoc_mock_imports seems to be not working

* added targets for big images

* rollback to default python version in check-docs task

* break long lines for mobile view

* replaced pip with conda where it's possible

.travis/test.sh

@@ -14,20 +14,25 @@ if [[ ${TASK} == "gpu" ]]; then
     export CPLUS_INCLUDE_PATH="$HOME/miniconda/envs/test-env/include:$AMDAPPSDK/include/:$CPLUS_INCLUDE_PATH"
 fi
 
-case ${TRAVIS_OS_NAME} in
-    osx)
-        export CXX=g++-7
-        export CC=gcc-7
-        ;;
-    linux)
-        ;;
-esac
+if [[ $TRAVIS_OS_NAME == "osx" ]]; then
+    export CXX=g++-7
+    export CC=gcc-7
+fi
+
+conda create -q -n test-env python=$PYTHON_VERSION
+source activate test-env
 
 cd $TRAVIS_BUILD_DIR
 
 if [[ ${TASK} == "check-docs" ]]; then
-    sudo apt-get install linkchecker
-    pip install rstcheck sphinx sphinx_rtd_theme  # html5validator
+    if [[ $TRAVIS_OS_NAME != "osx" ]]; then
+        sudo apt-get install linkchecker
+    fi
+    if [[ ${PYTHON_VERSION} == "2.7" ]]; then
+        conda install mock
+    fi
+    conda install sphinx sphinx_rtd_theme  # html5validator
+    pip install rstcheck
     cd python-package
     rstcheck --report warning `find . -type f -name "*.rst"` || exit -1
     cd ../docs
@@ -36,19 +41,20 @@ if [[ ${TASK} == "check-docs" ]]; then
     find ./_build/html/ -type f -name '*.html' -exec \
     sed -i -e 's;\(\.\/[^.]*\.\)rst\([^[:space:]]*\);\1html\2;g' {} \;  # Emulate js function
 #    html5validator --root ./_build/html/ || exit -1
-    linkchecker --config=.linkcheckerrc ./_build/html/*.html || exit -1
+    if [[ $TRAVIS_OS_NAME != "osx" ]]; then
+        linkchecker --config=.linkcheckerrc ./_build/html/*.html || exit -1
+    fi
     exit 0
 fi
 
 if [[ ${TASK} == "pylint" ]]; then
-    pip install pep8
+    conda install pep8
     pep8 --ignore=E501 --exclude=./compute,./docs . || exit -1
     exit 0
 fi
 
 if [[ ${TASK} == "if-else" ]]; then
-    conda create -q -n test-env python=$PYTHON_VERSION numpy
-    source activate test-env
+    conda install numpy
     mkdir build && cd build && cmake .. && make lightgbm || exit -1
     cd $TRAVIS_BUILD_DIR/tests/cpp_test && ../../lightgbm config=train.conf convert_model_language=cpp convert_model=../../src/boosting/gbdt_prediction.cpp && ../../lightgbm config=predict.conf output_result=origin.pred || exit -1
     cd $TRAVIS_BUILD_DIR/build && make lightgbm || exit -1
@@ -57,7 +63,7 @@ if [[ ${TASK} == "if-else" ]]; then
 fi
 
 if [[ ${TASK} == "proto" ]]; then
-    conda create -q -n test-env python=$PYTHON_VERSION numpy
+    conda install numpy
     source activate test-env
     mkdir build && cd build && cmake .. && make lightgbm || exit -1
     cd $TRAVIS_BUILD_DIR/tests/cpp_test && ../../lightgbm config=train.conf && ../../lightgbm config=predict.conf output_result=origin.pred || exit -1
@@ -68,8 +74,7 @@ if [[ ${TASK} == "proto" ]]; then
     exit 0
 fi
 
-conda create -q -n test-env python=$PYTHON_VERSION numpy nose scipy scikit-learn pandas matplotlib pytest
-source activate test-env
+conda install numpy nose scipy scikit-learn pandas matplotlib pytest
 
 if [[ ${TASK} == "sdist" ]]; then
     LGB_VER=$(head -n 1 VERSION.txt)

docs/GPU-Performance.rst

@@ -163,6 +163,7 @@ We record the wall clock time after 500 iterations, as shown in the figure below
 
 .. image:: ./_static/images/gpu-performance-comparison.png
    :align: center
+   :target: ./_static/images/gpu-performance-comparison.png
 
 When using a GPU, it is advisable to use a bin size of 63 rather than 255, because it can speed up training significantly without noticeably affecting accuracy.
 On CPU, using a smaller bin size only marginally improves performance, sometimes even slows down training,

docs/GPU-Targets.rst

@@ -1,3 +1,6 @@
+GPU SDK Correspondence and Device Targeting Table
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 GPU Targets Table
 =================
 

docs/GPU-Windows.rst

@@ -45,16 +45,19 @@ To modify PATH, just follow the pictures after going to the ``Control Panel``:
 
 .. image:: ./_static/images/screenshot-system.png
    :align: center
+   :target: ./_static/images/screenshot-system.png
 
 Then, go to ``Advanced`` > ``Environment Variables...``:
 
 .. image:: ./_static/images/screenshot-advanced-system-settings.png
    :align: center
+   :target: ./_static/images/screenshot-advanced-system-settings.png
 
 Under ``System variables``, the variable ``Path``:
 
 .. image:: ./_static/images/screenshot-environment-variables.png
    :align: center
+   :target: ./_static/images/screenshot-environment-variables.png
 
 --------------
 
@@ -99,6 +102,7 @@ You may choose a version other than the most recent one if you need a previous M
 
 .. image:: ./_static/images/screenshot-mingw-installation.png
    :align: center
+   :target: ./_static/images/screenshot-mingw-installation.png
 
 Then, add to your PATH the following (to adjust to your MinGW version):
 
@@ -116,6 +120,7 @@ You can check which MinGW version you are using by running the following in a co
 
 .. image:: ./_static/images/screenshot-r-mingw-used.png
    :align: center
+   :target: ./_static/images/screenshot-r-mingw-used.png
 
 To check whether you need 32-bit or 64-bit MinGW for R, install LightGBM as usual and check for the following:
 
@@ -211,6 +216,7 @@ This is what you should (approximately) get at the end of Boost compilation:
 
 .. image:: ./_static/images/screenshot-boost-compiled.png
    :align: center
+   :target: ./_static/images/screenshot-boost-compiled.png
 
 If you are getting an error:
 
@@ -233,6 +239,7 @@ Installing Git for Windows is straightforward, use the following `link`_.
 
 .. image:: ./_static/images/screenshot-git-for-windows.png
    :align: center
+   :target: ./_static/images/screenshot-git-for-windows.png
 
 Then, click on the big Download button, you can't miss it.
 
@@ -261,6 +268,7 @@ Installing CMake requires one download first and then a lot of configuration for
 
 .. image:: ./_static/images/screenshot-downloading-cmake.png
    :align: center
+   :target: ./_static/images/screenshot-downloading-cmake.png
 
 -  Download `CMake`_ 3.8.0
 
@@ -278,21 +286,25 @@ Installing CMake requires one download first and then a lot of configuration for
 
    .. image:: ./_static/images/screenshot-create-directory.png
       :align: center
+      :target: ./_static/images/screenshot-create-directory.png
 
    .. image:: ./_static/images/screenshot-mingw-makefiles-to-use.png
       :align: center
+      :target: ./_static/images/screenshot-mingw-makefiles-to-use.png
 
 -  Lookup for ``USE_GPU`` and check the checkbox
 
    .. image:: ./_static/images/screenshot-use-gpu.png
       :align: center
+      :target: ./_static/images/screenshot-use-gpu.png
 
 -  Click ``Configure``
 
    You should get (approximately) the following after clicking Configure:
 
    .. image:: ./_static/images/screenshot-configured-lightgbm.png
       :align: center
+      :target: ./_static/images/screenshot-configured-lightgbm.png
 
    ::
 
@@ -352,6 +364,7 @@ You can do everything in the Git Bash console you left open:
 
 .. image:: ./_static/images/screenshot-lightgbm-with-gpu-support-compiled.png
    :align: center
+   :target: ./_static/images/screenshot-lightgbm-with-gpu-support-compiled.png
 
 If everything was done correctly, you now compiled CLI LightGBM with GPU support!
 
@@ -367,6 +380,7 @@ You can now test LightGBM directly in CLI in a **command prompt** (not Git Bash)
 
 .. image:: ./_static/images/screenshot-lightgbm-in-cli-with-gpu.png
    :align: center
+   :target: ./_static/images/screenshot-lightgbm-in-cli-with-gpu.png
 
 Congratulations for reaching this stage!
 
@@ -381,6 +395,7 @@ Now that you compiled LightGBM, you try it... and you always see a segmentation
 
 .. image:: ./_static/images/screenshot-segmentation-fault.png
    :align: center
+   :target: ./_static/images/screenshot-segmentation-fault.png
 
 Please check you are using the right device and whether it works with the default ``gpu_device_id = 0`` and ``gpu_platform_id = 0``.
 If it still does not work with the default values, then you should follow all the steps below.
@@ -393,17 +408,20 @@ You will have to redo the compilation steps for LightGBM to add debugging mode.
 
 .. image:: ./_static/images/screenshot-files-to-remove.png
    :align: center
+   :target: ./_static/images/screenshot-files-to-remove.png
 
 Once you removed the file, go into CMake, and follow the usual steps.
 Before clicking "Generate", click on "Add Entry":
 
 .. image:: ./_static/images/screenshot-added-manual-entry-in-cmake.png
    :align: center
+   :target: ./_static/images/screenshot-added-manual-entry-in-cmake.png
 
 In addition, click on Configure and Generate:
 
 .. image:: ./_static/images/screenshot-configured-and-generated-cmake.png
    :align: center
+   :target: ./_static/images/screenshot-configured-and-generated-cmake.png
 
 And then, follow the regular LightGBM CLI installation from there.
 
@@ -416,6 +434,7 @@ open a command prompt and run the following:
 
 .. image:: ./_static/images/screenshot-debug-run.png
    :align: center
+   :target: ./_static/images/screenshot-debug-run.png
 
 Type ``run`` and press the Enter key.
 

docs/Installation-Guide.rst

@@ -22,9 +22,9 @@ With GUI
 
 3. Go to ``LightGBM-master/windows`` folder.
 
-4. Open ``LightGBM.sln`` file with Visual Studio, choose ``Release`` configuration and click ``BUILD-> Build Solution (Ctrl+Shift+B)``.
+4. Open ``LightGBM.sln`` file with Visual Studio, choose ``Release`` configuration and click ``BUILD``->\ ``Build Solution (Ctrl+Shift+B)``.
 
-   If you have errors about **Platform Toolset**, go to ``PROJECT-> Properties-> Configuration Properties-> General`` and select the toolset installed on your machine.
+   If you have errors about **Platform Toolset**, go to ``PROJECT``->\ ``Properties``->\ ``Configuration Properties``->\ ``General`` and select the toolset installed on your machine.
 
 The exe file will be in ``LightGBM-master/windows/x64/Release`` folder.
 
@@ -135,9 +135,9 @@ With GUI
 
 4. Go to ``LightGBM-master/windows`` folder.
 
-5. Open ``LightGBM.sln`` file with Visual Studio, choose ``Release_mpi`` configuration and click ``BUILD-> Build Solution (Ctrl+Shift+B)``.
+5. Open ``LightGBM.sln`` file with Visual Studio, choose ``Release_mpi`` configuration and click ``BUILD``->\ ``Build Solution (Ctrl+Shift+B)``.
 
-   If you have errors about **Platform Toolset**, go to ``PROJECT-> Properties-> Configuration Properties-> General`` and select the toolset installed on your machine.
+   If you have errors about **Platform Toolset**, go to ``PROJECT``->\ ``Properties``->\ ``Configuration Properties``->\ ``General`` and select the toolset installed on your machine.
 
 The exe file will be in ``LightGBM-master/windows/x64/Release_mpi`` folder.
 

docs/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W
 SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = LightGBM
 SOURCEDIR     = .

docs/README.rst

@@ -8,9 +8,19 @@ After each commit on ``master``, documentation is updated and published to `Read
 Build
 -----
 
-You can build the documentation locally. Just run in ``docs`` folder:
+You can build the documentation locally. Just run in ``docs`` folder
+
+for Python 3.x:
 
 .. code:: sh
 
     pip install sphinx sphinx_rtd_theme
     make html
+
+ 
+for Python 2.x:
+
+.. code:: sh
+
+    pip install mock sphinx sphinx_rtd_theme
+    make html

docs/_static/js/rst_links_fix.js

@@ -1,4 +1,5 @@
 $(function() {
     $('a[href^="./"][href*=".rst"]').attr('href', (i, val) => { return val.replace('.rst', '.html'); });  /* Replace '.rst' with '.html' in all internal links like './[Something].rst[#anchor]' */
     $('.wy-nav-content').each(function () { this.style.setProperty('max-width', 'none', 'important'); });
+    $('.wy-menu.wy-menu-vertical > ul:nth-of-type(2)').hide();  /* Fix theme navbar shows hidden toctree */
 });

docs/conf.py

@@ -27,15 +27,18 @@
 sys.path.insert(0, libpath)
 
 # -- mock out modules
-from unittest.mock import Mock
-MOCK_MODULES = [
-    'numpy', 'scipy', 'scipy.sparse',
-    'sklearn', 'matplotlib', 'pandas', 'graphviz',
-    'lightgbm.compat.LGBMDeprecated'
+try:
+    from unittest.mock import Mock  # Python 3.x
+except ImportError:
+    from mock import Mock  # Python 2.x
+
+MOCK_MODULES = ['numpy', 'scipy', 'scipy.sparse',
+                'sklearn', 'matplotlib', 'pandas', 'graphviz',
 ]
 for mod_name in MOCK_MODULES:
     sys.modules[mod_name] = Mock()
 
+
 # -- General configuration ------------------------------------------------
 
 os.environ['LIGHTGBM_BUILD_DOC'] = '1'
@@ -126,56 +129,5 @@
 htmlhelp_basename = 'LightGBMdoc'
 
 
-# -- Options for LaTeX output ---------------------------------------------
-
-latex_elements = {
-    # The paper size ('letterpaper' or 'a4paper').
-    #
-    # 'papersize': 'letterpaper',
-
-    # The font size ('10pt', '11pt' or '12pt').
-    #
-    # 'pointsize': '10pt',
-
-    # Additional stuff for the LaTeX preamble.
-    #
-    # 'preamble': '',
-
-    # Latex figure (float) alignment
-    #
-    # 'figure_align': 'htbp',
-}
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title,
-#  author, documentclass [howto, manual, or own class]).
-# latex_documents = [
-#    (master_doc, 'LightGBM.tex', 'LightGBM Documentation',
-#     'Microsoft Corporation', 'manual'),
-# ]
-
-
-# -- Options for manual page output ---------------------------------------
-
-# One entry per manual page. List of tuples
-# (source start file, name, description, authors, manual section).
-# man_pages = [
-#     (master_doc, 'lightgbm', 'LightGBM Documentation',
-#      [author], 1)
-# ]
-
-
-# -- Options for Texinfo output -------------------------------------------
-
-# Grouping the document tree into Texinfo files. List of tuples
-# (source start file, target name, title, author,
-#  dir menu entry, description, category)
-# texinfo_documents = [
-#     (master_doc, 'LightGBM', 'LightGBM Documentation',
-#      author, 'LightGBM', 'One line description of project.',
-#      'Miscellaneous'),
-# ]
-
-
 def setup(app):
     app.add_javascript("js/rst_links_fix.js")