Sphinx generated documentation (#521)

* upgrade req.

* move MkDocs

* create Sphinx

* init Sphinx

* move md from MkDocs to Sphinx

* CI: build docs

* build Sphinx

formatting

move docs from MD to docstring in particular package/modules

formatting

add Sphinx ext.

rename root_module to core

drop implicit name "_logger"

drop duplicate name "overwrite"

fix imports

use pytorch theme

add sample link mapping

try fix RTD build

use forked template

fix some docs warnings

fix paths

add deprecation warnings

fix flake8

fix paths

revert refactor

revert MLFlowLogger

* revert example import

* update link

* Update lightning_module_template.py

pytorch_lightning/core/__init__.py

@@ -0,0 +1,150 @@
+"""
+Lightning Module interface
+==========================
+
+A lightning module is a strict superclass of nn.Module, it provides a standard interface
+ for the trainer to interact with the model.
+
+The easiest thing to do is copy the minimal example below and modify accordingly.
+
+Otherwise, to Define a Lightning Module, implement the following methods:
+
+
+Minimal example
+---------------
+
+.. code-block:: python
+
+    import os
+    import torch
+    from torch.nn import functional as F
+    from torch.utils.data import DataLoader
+    from torchvision.datasets import MNIST
+    import torchvision.transforms as transforms
+
+    import pytorch_lightning as pl
+
+    class CoolModel(pl.LightningModule):
+
+        def __init__(self):
+            super(CoolModel, self).__init__()
+            # not the best model...
+            self.l1 = torch.nn.Linear(28 * 28, 10)
+
+        def forward(self, x):
+            return torch.relu(self.l1(x.view(x.size(0), -1)))
+
+        def training_step(self, batch, batch_nb):
+            # REQUIRED
+            x, y = batch
+            y_hat = self.forward(x)
+            return {'loss': F.cross_entropy(y_hat, y)}
+
+        def validation_step(self, batch, batch_nb):
+            # OPTIONAL
+            x, y = batch
+            y_hat = self.forward(x)
+            return {'val_loss': F.cross_entropy(y_hat, y)}
+
+        def validation_end(self, outputs):
+            # OPTIONAL
+            avg_loss = torch.stack([x['val_loss'] for x in outputs]).mean()
+            return {'avg_val_loss': avg_loss}
+
+        def test_step(self, batch, batch_nb):
+            # OPTIONAL
+            x, y = batch
+            y_hat = self.forward(x)
+            return {'test_loss': F.cross_entropy(y_hat, y)}
+
+        def test_end(self, outputs):
+            # OPTIONAL
+            avg_loss = torch.stack([x['test_loss'] for x in outputs]).mean()
+            return {'avg_test_loss': avg_loss}
+
+        def configure_optimizers(self):
+            # REQUIRED
+            return torch.optim.Adam(self.parameters(), lr=0.02)
+
+        @pl.data_loader
+        def train_dataloader(self):
+            return DataLoader(MNIST(os.getcwd(), train=True, download=True,
+                              transform=transforms.ToTensor()), batch_size=32)
+
+        @pl.data_loader
+        def val_dataloader(self):
+            # OPTIONAL
+            # can also return a list of val dataloaders
+            return DataLoader(MNIST(os.getcwd(), train=True, download=True,
+                              transform=transforms.ToTensor()), batch_size=32)
+
+        @pl.data_loader
+        def test_dataloader(self):
+            # OPTIONAL
+            # can also return a list of test dataloaders
+            return DataLoader(MNIST(os.getcwd(), train=False, download=True,
+                              transform=transforms.ToTensor()), batch_size=32)
+
+
+How do these methods fit into the broader training?
+---------------------------------------------------
+
+The LightningModule interface is on the right. Each method corresponds
+ to a part of a research project. Lightning automates everything not in blue.
+
+.. figure::  docs/source/_static/images/overview_flat.jpg
+   :align:   center
+
+   Overview.
+
+
+Optional Methods
+----------------
+
+**add_model_specific_args**
+
+.. code-block:: python
+
+    @staticmethod
+    def add_model_specific_args(parent_parser, root_dir)
+
+Lightning has a list of default argparse commands.
+ This method is your chance to add or modify commands specific to your model.
+ The `hyperparameter argument parser
+  <https://williamfalcon.github.io/test-tube/hyperparameter_optimization/HyperOptArgumentParser>`_
+ is available anywhere in your model by calling self.hparams.
+
+**Return**
+An argument parser
+
+**Example**
+
+.. code-block:: python
+
+    @staticmethod
+    def add_model_specific_args(parent_parser, root_dir):
+        parser = HyperOptArgumentParser(strategy=parent_parser.strategy, parents=[parent_parser])
+
+        # param overwrites
+        # parser.set_defaults(gradient_clip_val=5.0)
+
+        # network params
+        parser.opt_list('--drop_prob', default=0.2, options=[0.2, 0.5], type=float, tunable=False)
+        parser.add_argument('--in_features', default=28*28)
+        parser.add_argument('--out_features', default=10)
+        # use 500 for CPU, 50000 for GPU to see speed difference
+        parser.add_argument('--hidden_dim', default=50000)
+
+        # data
+        parser.add_argument('--data_root', default=os.path.join(root_dir, 'mnist'), type=str)
+
+        # training params (opt)
+        parser.opt_list('--learning_rate', default=0.001, type=float,
+                        options=[0.0001, 0.0005, 0.001, 0.005], tunable=False)
+        parser.opt_list('--batch_size', default=256, type=int,
+                        options=[32, 64, 128, 256], tunable=False)
+        parser.opt_list('--optimizer_name', default='adam', type=str,
+                        options=['adam'], tunable=False)
+        return parser
+
+"""

pytorch_lightning/core/hooks.py

@@ -1,3 +1,17 @@
+"""
+# Hooks
+
+There are cases when you might want to do something different at different parts of the training/validation loop.
+ To enable a hook, simply override the method in your LightningModule and the trainer will call it at the correct time.
+
+**Contributing** If there's a hook you'd like to add, simply:
+1. Fork PyTorchLightning.
+2. Add the hook :py:mod:`pytorch_lightning.base_module.hooks.py`.
+3. Add the correct place in the :py:mod:`pytorch_lightning.models.trainer` where it should be called.
+
+"""
+
+
 import torch
 
 
@@ -19,28 +33,47 @@ class ModelHooks(torch.nn.Module):
         pass
 
     def on_batch_start(self, batch):
+        """Called in the training loop before anything happens for that batch.
+
+        :param batch:
+        :return:
+        """
+        # do something when the batch starts
         pass
 
     def on_batch_end(self):
+        """Called in the training loop after the batch."""
+        # do something when the batch ends
         pass
 
     def on_epoch_start(self):
+        """Called in the training loop at the very beginning of the epoch."""
+        # do something when the epoch starts
         pass
 
     def on_epoch_end(self):
+        """Called in the training loop at the very end of the epoch."""
+        # do something when the epoch ends
         pass
 
     def on_pre_performance_check(self):
+        """Called at the very beginning of the validation loop."""
+        # do something before validation starts
         pass
 
     def on_post_performance_check(self):
+        """Called at the very end of the validation loop."""
+        # do something before validation end
         pass
 
     def on_before_zero_grad(self, optimizer):
-        """
-        Called after optimizer.step() and before optimizer.zero_grad()
+        """Called after optimizer.step() and before optimizer.zero_grad()
+
+        Called in the training loop after taking an optimizer step and before zeroing grads.
+        Good place to inspect weight information with weights updated.
+
+        for optimizer in optimizers::
 
-        for optimizer in optimizers:
             optimizer.step()
             model.on_before_zero_grad(optimizer) # < ---- called here
             optimizer.zero_grad
@@ -48,22 +81,54 @@ class ModelHooks(torch.nn.Module):
         :param optimizer:
         :return:
         """
+        # do something with the optimizer or inspect it.
         pass
 
     def on_after_backward(self):
-        """
-        Called after loss.backward() and before optimizers do anything
+        """Called after loss.backward() and before optimizers do anything.
+
         :return:
+
+        Called in the training loop after model.backward()
+        This is the ideal place to inspect or log gradient information
+
+        .. code-block:: python
+
+            def on_after_backward(self):
+                # example to inspect gradient information in tensorboard
+                if self.trainer.global_step % 25 == 0:  # don't make the tf file huge
+                    params = self.state_dict()
+                    for k, v in params.items():
+                        grads = v
+                        name = k
+                        self.logger.experiment.add_histogram(tag=name, values=grads,
+                                                             global_step=self.trainer.global_step)
+
         """
         pass
 
     def backward(self, use_amp, loss, optimizer):
-        """
-        Override backward with your own implementation if you need to
+        """Override backward with your own implementation if you need to
+
         :param use_amp: Whether amp was requested or not
         :param loss: Loss is already scaled by accumulated grads
         :param optimizer: Current optimizer being used
         :return:
+
+        Called to perform backward step.
+        Feel free to override as needed.
+
+        The loss passed in has already been scaled for accumulated gradients if requested.
+
+        .. code-block:: python
+
+            def backward(self, use_amp, loss, optimizer):
+                if use_amp:
+                    with amp.scale_loss(loss, optimizer) as scaled_loss:
+                        scaled_loss.backward()
+                else:
+                    loss.backward()
+
         """
         if use_amp:
             with amp.scale_loss(loss, optimizer) as scaled_loss: