update Docs [links & formatting] (#769)

* wip

* wip

* debug imports
docs formatting

* WIP

* formatting

* fix setup

.run_local_tests.sh

@@ -2,11 +2,11 @@
 
 # use this to run tests
 rm -rf _ckpt_*
-rm -rf tests/save_dir*
-rm -rf tests/mlruns_*
-rm -rf tests/cometruns*
-rm -rf tests/wandb*
-rm -rf tests/tests/*
-rm -rf lightning_logs
+rm -rf ./tests/save_dir*
+rm -rf ./tests/mlruns_*
+rm -rf ./tests/cometruns*
+rm -rf ./tests/wandb*
+rm -rf ./tests/tests/*
+rm -rf ./lightning_logs
 coverage run --source pytorch_lightning -m py.test pytorch_lightning tests pl_examples -v --doctest-modules
 coverage report -m

docs/requirements.txt

@@ -4,7 +4,7 @@ m2r  # fails with multi-line text
 nbsphinx
 pandoc
 docutils
-git+https://github.com/PytorchLightning/lightning_sphinx_theme.git
 sphinxcontrib-fulltoc
 sphinxcontrib-mockautodoc
-pip_shims
+git+https://github.com/PytorchLightning/lightning_sphinx_theme.git
+# pip_shims

docs/source/conf.py

@@ -348,7 +348,11 @@ def linkcode_resolve(domain, info):
 
 autodoc_member_order = 'groupwise'
 autoclass_content = 'both'
-autodoc_default_flags = [
-    'members', 'undoc-members', 'show-inheritance', 'private-members',
-    # 'special-members', 'inherited-members'
-]
+autodoc_default_options = {
+    'members': True,
+    'special-members': '__call__',
+    'undoc-members': True,
+    # 'exclude-members': '__weakref__',
+    'show-inheritance': True,
+    'private-members': True,
+}

docs/source/documentation.rst

@@ -1,8 +0,0 @@
-Documentation
-=============
-
-
-.. toctree::
-   :maxdepth: 4
-
-   pytorch_lightning

docs/source/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 PyTorch-Lightning Documentation
-=============================
+===============================
 
 .. toctree::
    :maxdepth: 1

docs/source/lightning-module.rst

@@ -2,7 +2,8 @@
     :class: hidden-section
 
 LightningModule
-===========
+===============
+
 .. automodule:: pytorch_lightning.core
    :exclude-members:
         _abc_impl,

docs/source/modules.rst

@@ -1,7 +0,0 @@
-pl_examples
-===========
-
-.. toctree::
-   :maxdepth: 4
-
-   pl_examples

docs/source/tutorials.rst

@@ -1,20 +1,20 @@
 Refactoring PyTorch into Lightning
-==================================
-`Tutorial <https://towardsdatascience.com/how-to-refactor-your-pytorch-code-to-get-these-42-benefits-of-pytorch-lighting-6fdd0dc97538>`_
+----------------------------------
+`How to refactor your PyTorch code to get these 42 benefits of PyTorch-Lighting <https://towardsdatascience.com/how-to-refactor-your-pytorch-code-to-get-these-42-benefits-of-pytorch-lighting-6fdd0dc97538>`_
 
 Start a research project
-=========================
+------------------------
 `Research seed <https://github.com/PytorchLightning/pytorch-lightning-conference-seed>`_
 
 Basic Lightning use
-====================
-`Tutorial <https://towardsdatascience.com/supercharge-your-ai-research-with-pytorch-lightning-337948a99eec>`_
+-------------------
+`Supercharge your AI research with PyTorch-Lightning <https://towardsdatascience.com/supercharge-your-ai-research-with-pytorch-lightning-337948a99eec>`_
 
 9 key Lightning  tricks
-========================
-`Tutorial <https://towardsdatascience.com/9-tips-for-training-lightning-fast-neural-networks-in-pytorch-8e63a502f565>`_
+-----------------------
+`Tutorial on 9 key speed features in PyTorch-Lightning <9 key speed features in Pytorch-Lightning>`_
 
 Multi-node training on SLURM
-=============================
-`Tutorial <https://towardsdatascience.com/trivial-multi-node-training-with-pytorch-lightning-ff75dfb809bd>`_
+----------------------------
+`Trivial multi node training with PyTorch-Lightning <https://towardsdatascience.com/trivial-multi-node-training-with-pytorch-lightning-ff75dfb809bd>`_
 

pl_examples/__init__.py

@@ -43,6 +43,7 @@ Normally, we want to let the `__main__` function start the training.
 
 The main function is your entry into the program. This is where you init your model, checkpoint directory,
  and launch the training. The main function should have 3 arguments:
+
 - hparams: a configuration of hyperparameters.
 - slurm_manager: Slurm cluster manager object (can be None)
 - dict: for you to return any values you want (useful in meta-learning, otherwise set to)

pl_examples/basic_examples/cpu_template.py

@@ -7,8 +7,8 @@ from argparse import ArgumentParser
 import numpy as np
 import torch
 
+import pytorch_lightning as pl
 from pl_examples.basic_examples.lightning_module_template import LightningTemplateModel
-from pytorch_lightning import Trainer
 
 SEED = 2334
 torch.manual_seed(SEED)
@@ -28,7 +28,7 @@ def main(hparams):
     # ------------------------
     # 2 INIT TRAINER
     # ------------------------
-    trainer = Trainer()
+    trainer = pl.Trainer()
 
     # ------------------------
     # 3 START TRAINING

pl_examples/basic_examples/gpu_template.py

@@ -7,8 +7,8 @@ from argparse import ArgumentParser
 import numpy as np
 import torch
 
+import pytorch_lightning as pl
 from pl_examples.basic_examples.lightning_module_template import LightningTemplateModel
-from pytorch_lightning import Trainer
 
 SEED = 2334
 torch.manual_seed(SEED)
@@ -28,7 +28,7 @@ def main(hparams):
     # ------------------------
     # 2 INIT TRAINER
     # ------------------------
-    trainer = Trainer(
+    trainer = pl.Trainer(
         gpus=hparams.gpus,
         distributed_backend=hparams.distributed_backend,
         use_amp=hparams.use_16bit

pl_examples/basic_examples/lightning_module_template.py

@@ -16,10 +16,9 @@ from torch.utils.data.distributed import DistributedSampler
 from torchvision.datasets import MNIST
 
 import pytorch_lightning as pl
-from pytorch_lightning.core.lightning import LightningModule
 
 
-class LightningTemplateModel(LightningModule):
+class LightningTemplateModel(pl.LightningModule):
     """
     Sample model to show how to define a template
     """

pl_examples/multi_node_examples/multi_node_ddp2_demo.py

@@ -7,8 +7,8 @@ from argparse import ArgumentParser
 import numpy as np
 import torch
 
+import pytorch_lightning as pl
 from pl_examples.basic_examples.lightning_module_template import LightningTemplateModel
-from pytorch_lightning import Trainer
 
 SEED = 2334
 torch.manual_seed(SEED)
@@ -29,7 +29,7 @@ def main(hparams):
     # ------------------------
     # 2 INIT TRAINER
     # ------------------------
-    trainer = Trainer(
+    trainer = pl.Trainer(
         gpus=2,
         num_nodes=2,
         distributed_backend='ddp2'

pl_examples/multi_node_examples/multi_node_ddp_demo.py

@@ -7,8 +7,8 @@ from argparse import ArgumentParser
 import numpy as np
 import torch
 
+import pytorch_lightning as pl
 from pl_examples.basic_examples.lightning_module_template import LightningTemplateModel
-from pytorch_lightning import Trainer
 
 SEED = 2334
 torch.manual_seed(SEED)
@@ -29,7 +29,7 @@ def main(hparams):
     # ------------------------
     # 2 INIT TRAINER
     # ------------------------
-    trainer = Trainer(
+    trainer = pl.Trainer(
         gpus=2,
         num_nodes=2,
         distributed_backend='ddp'

pytorch_lightning/__init__.py

@@ -1,6 +1,6 @@
 """Root package info."""
 
-__version__ = '0.6.0.dev'
+__version__ = '0.6.1.dev'
 __author__ = 'William Falcon et al.'
 __author_email__ = 'waf2107@columbia.edu'
 __license__ = 'Apache-2.0'
@@ -10,7 +10,6 @@ __homepage__ = 'https://github.com/PyTorchLightning/pytorch-lightning'
 __docs__ = "PyTorch Lightning is the lightweight PyTorch wrapper for ML researchers." \
            " Scale your models. Write less boilerplate."
 
-
 try:
     # This variable is injected in the __builtins__ by the build
     # process. It used to enable importing subpackages of skimage when
@@ -28,12 +27,12 @@ else:
     import logging as log
     log.basicConfig(level=log.INFO)
 
-    from .trainer.trainer import Trainer
-    from .core.lightning import LightningModule
-    from .core.decorators import data_loader
+    from .core import data_loader, LightningModule
+    from .trainer import Trainer
 
     __all__ = [
         'Trainer',
         'LightningModule',
         'data_loader',
     ]
+    # __call__ = __all__

pytorch_lightning/core/__init__.py

@@ -96,6 +96,9 @@ Check out this
 for a live demo.
 
 """
+
+from .decorators import data_loader
 from .lightning import LightningModule
 
-__all__ = ['LightningModule']
+__all__ = ['LightningModule', 'data_loader']
+# __call__ = __all__

pytorch_lightning/core/decorators.py

@@ -3,12 +3,11 @@ from functools import wraps
 
 
 def data_loader(fn):
-    """
-    Decorator to make any fx with this use the lazy property
+    """Decorator to make any fx with this use the lazy property.
+
     :param fn:
     :return:
     """
-
     wraps(fn)
     attr_name = '_lazy_' + fn.__name__
 

pytorch_lightning/core/lightning.py

@@ -18,6 +18,7 @@ from pytorch_lightning.overrides.data_parallel import LightningDistributedDataPa
 
 
 class LightningModule(ABC, GradInformation, ModelIO, ModelHooks):
+
     def __init__(self, *args, **kwargs):
         super(LightningModule, self).__init__(*args, **kwargs)
 
@@ -115,6 +116,7 @@ class LightningModule(ABC, GradInformation, ModelIO, ModelHooks):
         :param int batch_idx: Integer displaying which batch this is
         :return: dict with loss key and optional log, progress keys
          if implementing training_step, return whatever you need in that step:
+
             - loss -> tensor scalar [REQUIRED]
             - progress_bar -> Dict for progress bar display. Must have only tensors
             - log -> Dict of metrics to add to logger. Must have only tensors (no images, etc)
@@ -1061,30 +1063,30 @@ class LightningModule(ABC, GradInformation, ModelIO, ModelHooks):
         it  stores  the hyperparameters in the checkpoint if you initialized your  LightningModule
         with an argument  called `hparams` which is a Namespace or dictionary of hyperparameters
 
-            Example
-            -------
-            .. code-block:: python
+        Example
+        -------
+        .. code-block:: python
 
-                # --------------
-                # Case 1
-                # when using Namespace (output of using Argparse to parse command line arguments)
-                from argparse import Namespace
-                hparams = Namespace(**{'learning_rate': 0.1})
+            # --------------
+            # Case 1
+            # when using Namespace (output of using Argparse to parse command line arguments)
+            from argparse import Namespace
+            hparams = Namespace(**{'learning_rate': 0.1})
 
-                model = MyModel(hparams)
+            model = MyModel(hparams)
 
-                class MyModel(pl.LightningModule):
-                    def __init__(self, hparams):
-                        self.learning_rate = hparams.learning_rate
+            class MyModel(pl.LightningModule):
+                def __init__(self, hparams):
+                    self.learning_rate = hparams.learning_rate
 
-                # --------------
-                # Case 2
-                # when using a dict
-                model = MyModel({'learning_rate': 0.1})
+            # --------------
+            # Case 2
+            # when using a dict
+            model = MyModel({'learning_rate': 0.1})
 
-                class MyModel(pl.LightningModule):
-                    def __init__(self, hparams):
-                        self.learning_rate = hparams['learning_rate']
+            class MyModel(pl.LightningModule):
+                def __init__(self, hparams):
+                    self.learning_rate = hparams['learning_rate']
 
         Args:
             checkpoint_path (str): Path to checkpoint.

pytorch_lightning/testing/model_base.py

@@ -16,7 +16,7 @@ except ImportError:
     # TODO: this should be discussed and moved out of this package
     raise ImportError('Missing test-tube package.')
 
-from pytorch_lightning import data_loader
+from pytorch_lightning.core.decorators import data_loader
 from pytorch_lightning.core.lightning import LightningModule
 
 

pytorch_lightning/testing/model_mixins.py

@@ -2,7 +2,7 @@ from collections import OrderedDict
 
 import torch
 
-from pytorch_lightning import data_loader
+from pytorch_lightning.core.decorators import data_loader
 
 
 class LightningValidationStepMixin:

pytorch_lightning/trainer/__init__.py

@@ -26,4 +26,5 @@ This is the basic use of the trainer:
 """
 
 from .trainer import Trainer
+
 __all__ = ['Trainer']

pytorch_lightning/trainer/trainer.py

@@ -49,6 +49,7 @@ class Trainer(TrainerIOMixin,
               TrainerTrainLoopMixin,
               TrainerCallbackConfigMixin,
               ):
+
     def __init__(
             self,
             logger=True,

setup.py

@@ -58,6 +58,12 @@ setup(
     setup_requires=[],
     install_requires=load_requirements(PATH_ROOT),
 
+    project_urls={
+        "Bug Tracker": "https://github.com/PyTorchLightning/pytorch-lightning/issues",
+        "Documentation": "https://pytorch-lightning.rtfd.io/en/latest/",
+        "Source Code": "https://github.com/PyTorchLightning/pytorch-lightning",
+    },
+
     classifiers=[
         'Environment :: Console',
         'Natural Language :: English',