Callback docs with autosummary (#3908)

* callback docs with autosummary

* do not show private methods

* callback base docstring

.gitignore

@@ -15,6 +15,7 @@ test_tube_exp/
 # Documentations
 docs/source/api
 docs/source/*.md
+docs/source/generated
 
 # Byte-compiled / optimized / DLL files
 __pycache__/

docs/.build_docs.sh

@@ -1 +1 @@
-make clean ; make html --debug --jobs 2 SPHINXOPTS="-W"
+rm -rf source/generated; make clean ; make html --debug --jobs 2 SPHINXOPTS="-W"

docs/source/_static/main.css

@@ -0,0 +1,3 @@
+col {
+    width: 50% !important;
+}

docs/source/_templates/classtemplate.rst

@@ -0,0 +1,14 @@
+.. role:: hidden
+    :class: hidden-section
+.. currentmodule:: {{ module }}
+
+
+{{ name | underline }}
+
+.. autoclass:: {{ name }}
+    :members:
+
+
+..
+  autogenerated from source/_templates/classtemplate.rst
+  note it does not have :inherited-members:

docs/source/callbacks.rst

@@ -68,19 +68,6 @@ You can do pretty much anything with callbacks.
 
 --------------
 
-Callback Hooks
---------------
-
-.. automodule:: pytorch_lightning.callbacks.base
-   :noindex:
-   :exclude-members:
-        _del_model,
-        _save_model,
-        _abc_impl,
-        check_monitor_top_k,
-
-----------------
-
 Built-in Callbacks
 ------------------
 Lightning has a few built-in callbacks.
@@ -89,58 +76,21 @@ Lightning has a few built-in callbacks.
     For a richer collection of callbacks, check out our
     `bolts library <https://pytorch-lightning-bolts.readthedocs.io/en/latest/callbacks.html>`_.
 
-----------------
+.. currentmodule:: pytorch_lightning.callbacks
 
-.. automodule:: pytorch_lightning.callbacks.early_stopping
-   :noindex:
-   :exclude-members:
-        _del_model,
-        _save_model,
-        _abc_impl,
-        check_monitor_top_k,
+.. autosummary::
+    :toctree: generated
+    :nosignatures:
+    :template: classtemplate.rst
 
-----------------
-
-.. automodule:: pytorch_lightning.callbacks.gpu_stats_monitor
-    :noindex:
-    :exclude-members:
-        _get_gpu_stats,
-        _get_gpu_stat_keys,
-        _get_gpu_device_stat_keys,
-
-----------------
-
-.. automodule:: pytorch_lightning.callbacks.gradient_accumulation_scheduler
-   :noindex:
-   :exclude-members:
-        _del_model,
-        _save_model,
-        _abc_impl,
-        check_monitor_top_k,
-
-----------------
-
-.. automodule:: pytorch_lightning.callbacks.lr_monitor
-    :noindex:
-    :exclude-members:
-        _extract_lr,
-        _find_names
-
-----------------
-
-.. automodule:: pytorch_lightning.callbacks.model_checkpoint
-   :noindex:
-   :exclude-members:
-        _del_model,
-        _save_model,
-        _abc_impl,
-        check_monitor_top_k,
-
-----------------
-
-.. automodule:: pytorch_lightning.callbacks.progress
-   :noindex:
-   :exclude-members:
+    Callback
+    EarlyStopping
+    GPUStatsMonitor
+    GradientAccumulationScheduler
+    LearningRateMonitor
+    ModelCheckpoint
+    ProgressBar
+    ProgressBarBase
 
 ----------
 

docs/source/conf.py

@@ -21,7 +21,6 @@ import inspect
 # import m2r
 import builtins
 import pt_lightning_sphinx_theme
-from sphinx.ext import apidoc
 
 PATH_HERE = os.path.abspath(os.path.dirname(__file__))
 PATH_ROOT = os.path.join(PATH_HERE, '..', '..')
@@ -138,10 +137,6 @@ language = None
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
-    'api/pytorch_lightning.rst',
-    'api/pl_examples.*',
-    'api/pytorch_lightning.accelerators.*',
-    'api/modules.rst',
     'PULL_REQUEST_TEMPLATE.md',
 ]
 
@@ -268,39 +263,11 @@ intersphinx_mapping = {
 todo_include_todos = True
 
 
-# packages for which sphinx-apidoc should generate the docs (.rst files)
-PACKAGES = [
-    pytorch_lightning.__name__,
-    'pl_examples',
-]
-
-apidoc_output_folder = os.path.join(PATH_HERE, 'api')
-
-
-def run_apidoc(_):
-    sys.path.insert(0, apidoc_output_folder)
-
-    # delete api-doc files before generating them
-    if os.path.exists(apidoc_output_folder):
-        shutil.rmtree(apidoc_output_folder)
-
-    for pkg in PACKAGES:
-        argv = ['-e',
-                '-o', apidoc_output_folder,
-                os.path.join(PATH_ROOT, pkg),
-                '**/test_*',
-                '--force',
-                '--private',
-                '--module-first']
-
-        apidoc.main(argv)
-
-
 def setup(app):
     # this is for hiding doctest decoration,
     # see: http://z4r.github.io/python/2011/12/02/hides-the-prompts-and-output/
     app.add_javascript('copybutton.js')
-    app.connect('builder-inited', run_apidoc)
+    app.add_css_file('main.css')
 
 
 # copy all notebooks to local folder
@@ -382,19 +349,17 @@ def linkcode_resolve(domain, info):
            % (github_user, github_repo, filename)
 
 
+autosummary_generate = True
 autodoc_member_order = 'groupwise'
 autoclass_content = 'both'
 # the options are fixed and will be soon in release,
 #  see https://github.com/sphinx-doc/sphinx/issues/5459
 autodoc_default_options = {
-    'members': None,
-    'methods': None,
-    # 'attributes': None,
+    'members': True,
+    'methods': True,
     'special-members': '__call__',
     'exclude-members': '_abc_impl',
     'show-inheritance': True,
-    'private-members': True,
-    'noindex': True,
 }
 
 # Sphinx will add “permalinks” for each heading and description environment as paragraph signs that

docs/source/index.rst

@@ -124,22 +124,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-
-
-
-.. This is here to make sphinx aware of the modules but not throw an error/warning
-.. toctree::
-   :hidden:
-
-   api/pytorch_lightning.core
-   api/pytorch_lightning.callbacks
-   api/pytorch_lightning.loggers
-   api/pytorch_lightning.metrics
-   api/pytorch_lightning.overrides
-   api/pytorch_lightning.profiler
-   api/pytorch_lightning.trainer
-   api/pytorch_lightning.utilities
-   api/pytorch_lightning.tuner
-   api/pytorch_lightning.plugins
-   api/pytorch_lightning.distributed
-   api/pytorch_lightning.cluster_environments

pytorch_lightning/callbacks/base.py

@@ -23,6 +23,8 @@ import abc
 class Callback(abc.ABC):
     r"""
     Abstract base class used to build new callbacks.
+
+    Subclass this class and override any of the relevant hooks
     """
 
     def setup(self, trainer, pl_module, stage: str):

pytorch_lightning/callbacks/early_stopping.py

@@ -39,6 +39,7 @@ torch_inf = torch.tensor(np.Inf)
 
 class EarlyStopping(Callback):
     r"""
+    Monitor a validation metric and stop training when it stops improving.
 
     Args:
         monitor: quantity to be monitored. Default: ``'early_stop_on'``.