[docs] 🎨 Sphinx Autosummary for generating Python-API documentation (#2286)

* 🎨 `sphinx.ext.autosummary` for generating Python-API summaries

Add `docs/.gitignore` to not track autosummary stubs
Add `sphinx.ext.autosummary` in `docs/conf.py`
  Add 'members' and 'inherited-members' as default parameters
  Add 'autosummary = True' for setting output with `:toctree:`
Add `.. autosummary::` tags to replace `.. autoclass::`

Previously the `Python-API.rst` dumped all of the Python API onto
a single page.

This replaces the Python-API documentation with an index listing
all modules, and paginates all functions and classes onto
separate pages.

* ✏️ Corrections following feedback

Drop `docs/.gitignore` to use the general `.gitignore`
Add `show-inheritance` to `autodoc_default_flags` in `docs/conf.py`
Fix `both` to `class` in `autoclass_content` in `docs/conf.py`

* ✏️ Replacing deprecated Sphinx parameter

Fix deprecated `autodoc_default_flags` to `autodoc_default_options`

* ✏️ Adding `autodoc_default_flags` in to support early Sphinx versions

Add `autodoc_default_flags` with parameters from
  `autodoc_default_options`

.gitignore

@@ -339,6 +339,7 @@ instance/
 
 # Sphinx documentation
 docs/_build/
+docs/pythonapi/
 
 # Doxygen documentation
 docs/doxyoutput/

docs/Python-API.rst

 Python API
 ==========
 
+.. currentmodule:: lightgbm
+
 Data Structure API
 ------------------
 
-.. autoclass:: lightgbm.Dataset
-    :members:
-    :show-inheritance:
-
-.. autoclass:: lightgbm.Booster
-    :members:
-    :show-inheritance:
+.. autosummary::
+    :toctree: pythonapi/
 
+    Dataset
+    Booster
 
 Training API
 ------------
 
-.. autofunction:: lightgbm.train
-
-.. autofunction:: lightgbm.cv
+.. autosummary::
+    :toctree: pythonapi/
 
+    train
+    cv
 
 Scikit-learn API
 ----------------
 
-.. autoclass:: lightgbm.LGBMModel
-    :members:
-    :inherited-members:
-    :show-inheritance:
-
-.. autoclass:: lightgbm.LGBMClassifier
-    :members:
-    :inherited-members:
-    :show-inheritance:
-
-.. autoclass:: lightgbm.LGBMRegressor
-    :members:
-    :inherited-members:
-    :show-inheritance:
-
-.. autoclass:: lightgbm.LGBMRanker
-    :members:
-    :inherited-members:
-    :show-inheritance:
+.. autosummary::
+    :toctree: pythonapi/
 
+    LGBMModel
+    LGBMClassifier
+    LGBMRegressor
+    LGBMRanker
 
 Callbacks
 ---------
 
-.. autofunction:: lightgbm.early_stopping
-
-.. autofunction:: lightgbm.print_evaluation
-
-.. autofunction:: lightgbm.record_evaluation
-
-.. autofunction:: lightgbm.reset_parameter
+.. autosummary::
+    :toctree: pythonapi/
 
+    early_stopping
+    print_evaluation
+    record_evaluation
+    reset_parameter
 
 Plotting
 --------
 
-.. autofunction:: lightgbm.plot_importance
-
-.. autofunction:: lightgbm.plot_split_value_histogram
-
-.. autofunction:: lightgbm.plot_metric
-
-.. autofunction:: lightgbm.plot_tree
+.. autosummary::
+    :toctree: pythonapi/
 
-.. autofunction:: lightgbm.create_tree_digraph
+    plot_importance
+    plot_split_value_histogram
+    plot_metric
+    plot_tree
+    create_tree_digraph

docs/conf.py

@@ -68,14 +68,25 @@ if needs_sphinx > sphinx.__version__:
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'sphinx.ext.todo',
     'sphinx.ext.viewcode',
     'sphinx.ext.napoleon',
 ]
 
+autodoc_default_flags = ['members', 'inherited-members', 'show-inheritance']
+autodoc_default_options = {
+    "members": True,
+    "inherited-members": True,
+    "show-inheritance": True,
+}
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
+# Generate autosummary pages. Output should be set with: `:toctree: pythonapi/`
+autosummary_generate = True
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 # source_suffix = ['.rst', '.md']
@@ -117,7 +128,7 @@ pygments_style = 'default'
 todo_include_todos = False
 
 # Both the class' and the __init__ method's docstring are concatenated and inserted.
-autoclass_content = 'both'
+autoclass_content = 'class'
 
 # -- Configuration for C API docs generation ------------------------------