Modernize XGBoost Python document. (#7468)

* Use sphinx gallery to integrate examples.
* Remove mock objects.
* Add dask doc inventory.

doc/conf.py

@@ -62,12 +62,6 @@ libpath = os.path.join(curr_path, '../python-package/')
 sys.path.insert(0, libpath)
 sys.path.insert(0, curr_path)
 
-# -- mock out modules
-import mock                     # NOQA
-MOCK_MODULES = ['scipy', 'scipy.sparse', 'sklearn', 'pandas']
-for mod_name in MOCK_MODULES:
-    sys.modules[mod_name] = mock.Mock()
-
 # -- General configuration ------------------------------------------------
 
 # General information about the project.
@@ -90,10 +84,17 @@ extensions = [
     'sphinx.ext.napoleon',
     'sphinx.ext.mathjax',
     'sphinx.ext.intersphinx',
+    "sphinx_gallery.gen_gallery",
     'breathe',
     'recommonmark'
 ]
 
+sphinx_gallery_conf = {
+    "examples_dirs": "../demo/guide-python",  # path to your example scripts
+    "gallery_dirs": "python/examples",  # path to where to save gallery generated output
+    "matplotlib_animations": True,
+}
+
 autodoc_typehints = "description"
 
 graphviz_output_format = 'png'
@@ -201,11 +202,13 @@ latex_documents = [
 ]
 
 intersphinx_mapping = {
-    'python': ('https://docs.python.org/3.6', None),
-    'numpy': ('http://docs.scipy.org/doc/numpy/', None),
-    'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None),
-    'pandas': ('http://pandas-docs.github.io/pandas-docs-travis/', None),
-    'sklearn': ('http://scikit-learn.org/stable', None)
+    "python": ("https://docs.python.org/3.6", None),
+    "numpy": ("http://docs.scipy.org/doc/numpy/", None),
+    "scipy": ("http://docs.scipy.org/doc/scipy/reference/", None),
+    "pandas": ("http://pandas-docs.github.io/pandas-docs-travis/", None),
+    "sklearn": ("http://scikit-learn.org/stable", None),
+    "dask": ("https://docs.dask.org/en/stable/", None),
+    "distributed": ("https://distributed.dask.org/en/stable/", None),
 }
 
 

doc/python/.gitignore

@@ -0,0 +1 @@
+examples

doc/python/index.rst

@@ -13,4 +13,4 @@ Contents
   python_api
   callbacks
   model
-  Python examples <https://github.com/dmlc/xgboost/tree/master/demo/guide-python>
+  examples/index

doc/python/python_intro.rst

@@ -5,7 +5,7 @@ This document gives a basic walkthrough of the xgboost package for Python.
 
 **List of other Helpful Links**
 
-* `Python walkthrough code collections <https://github.com/dmlc/xgboost/blob/master/demo/guide-python>`_
+* :doc:`/python/examples/index`
 * :doc:`Python API Reference <python_api>`
 
 Install XGBoost

doc/requirements.txt

@@ -8,3 +8,4 @@ graphviz
 numpy
 recommonmark
 xgboost_ray
+sphinx-gallery

doc/tutorials/categorical.rst

@@ -57,13 +57,10 @@ can plot the model and calculate the global feature importance:
 
 The ``scikit-learn`` interface from dask is similar to single node version.  The basic
 idea is create dataframe with category feature type, and tell XGBoost to use ``gpu_hist``
-with parameter ``enable_categorical``.  See `this demo
-<https://github.com/dmlc/xgboost/blob/master/demo/guide-python/categorical.py>`__ for a
-worked example of using categorical data with ``scikit-learn`` interface.  A comparison
-between using one-hot encoded data and XGBoost's categorical data support can be found
-`here
-<https://github.com/dmlc/xgboost/blob/master/demo/guide-python/cat_in_the_dat.py>`__.
-
+with parameter ``enable_categorical``.  See :ref:`sphx_glr_python_examples_categorical.py`
+for a worked example of using categorical data with ``scikit-learn`` interface.  A
+comparison between using one-hot encoded data and XGBoost's categorical data support can
+be found :ref:`sphx_glr_python_examples_cat_in_the_dat.py`.
 
 
 **********************