extend documentation (#569)

* extend documentation

* update index

* fix list

docs/source/conf.py

@@ -32,13 +32,13 @@ import pytorch_lightning  # noqa: E402
 
 # -- Project documents -------------------------------------------------------
 
-# export the documentation
+# # export the documentation
 # with open('intro.rst', 'w') as fp:
 #     intro = pytorch_lightning.__doc__.replace(os.linesep + ' ', '')
 #     fp.write(m2r.convert(intro))
 #     # fp.write(pytorch_lightning.__doc__)
 
-# export the READme
+# # export the READme
 # with open(os.path.join(PATH_ROOT, 'README.md'), 'r') as fp:
 #     readme = fp.read()
 # # replace all paths to relative
@@ -48,6 +48,9 @@ import pytorch_lightning  # noqa: E402
 # with open('readme.md', 'w') as fp:
 #     fp.write(readme)
 
+for md in glob.glob(os.path.join(PATH_ROOT, '.github', '*.md')):
+    shutil.copy(md, os.path.join(PATH_HERE, os.path.basename(md)))
+
 # -- Project information -----------------------------------------------------
 
 project = 'PyTorch-Lightning'

docs/source/documentation.rst

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

docs/source/examples.rst

@@ -0,0 +1,8 @@
+Examples & Tutorials
+====================
+
+
+.. toctree::
+   :maxdepth: 3
+
+   pl_examples

docs/source/index.rst

@@ -6,15 +6,29 @@
 Welcome to PyTorch-Lightning!
 =============================
 
-Table of content
-----------------
+.. toctree::
+   :maxdepth: 4
+   :name: start
+   :caption: Quick Start
+
+   new-project
+   examples
+
+.. toctree::
+   :maxdepth: 4
+   :name: docs
+   :caption: Docs
+
+   documentation
 
 .. toctree::
    :maxdepth: 1
+   :name: community
+   :caption: Community
 
-   intro
-   pytorch_lightning
-   pl_examples
+   CODE_OF_CONDUCT.md
+   CONTRIBUTING.md
+   BECOMING_A_CORE_CONTRIBUTOR.md
 
 
 Indices and tables

docs/source/intro.md

@@ -1,60 +0,0 @@
-## New project Quick Start    
-To start a new project define two files, a LightningModule and a Trainer file.    
-To illustrate Lightning power and simplicity, here's an example of a typical research flow.    
-
-### Case 1: BERT    
-Let's say you're working on something like BERT but want to try different ways of training or even different networks.  
-You would define a single LightningModule and use flags to switch between your different ideas.
-
-```python
-class BERT(pl.LightningModule):
-    def __init__(self, model_name, task):
-        self.task = task
-    
-        if model_name == 'transformer':
-            self.net = Transformer()
-        elif model_name == 'my_cool_version':
-            self.net = MyCoolVersion()
-            
-    def training_step(self, batch, batch_idx):
-        if self.task == 'standard_bert':
-            # do standard bert training with self.net...
-            # return loss
-            
-        if self.task == 'my_cool_task':
-            # do my own version with self.net
-            # return loss
-```   
-
-### Case 2: COOLER NOT BERT    
-But if you wanted to try something **completely** different, you'd define a new module for that.
-
-```python
-
-class CoolerNotBERT(pl.LightningModule):
-    def __init__(self):
-        self.net = ...
-        
-    def training_step(self, batch, batch_idx):
-        # do some other cool task
-        # return loss   
-```   
-
-### Rapid research flow    
-Then you could do rapid research by switching between these two and using the same trainer.
-
-```python
-
-if use_bert:
-    model = BERT()
-else:
-    model = CoolerNotBERT()
-    
-trainer = Trainer(gpus=4, use_amp=True)
-trainer.fit(model)
-```
-
-Notice a few things about this flow:   
-1. You're writing pure PyTorch... no unnecessary abstractions or new libraries to learn.   
-2. You get free GPU and 16-bit support without writing any of that code in your model.   
-3. You also get all of the capabilities below (without coding or testing yourself).     

docs/source/new-project.rst

@@ -0,0 +1,71 @@
+Quick Start
+===========
+To start a new project define two files, a LightningModule and a Trainer file.    
+To illustrate Lightning power and simplicity, here's an example of a typical research flow.    
+
+Case 1: BERT
+------------
+
+Let's say you're working on something like BERT but want to try different ways of training or even different networks.  
+You would define a single LightningModule and use flags to switch between your different ideas.
+
+.. code-block:: python
+
+    class BERT(pl.LightningModule):
+        def __init__(self, model_name, task):
+            self.task = task
+
+            if model_name == 'transformer':
+                self.net = Transformer()
+            elif model_name == 'my_cool_version':
+                self.net = MyCoolVersion()
+
+        def training_step(self, batch, batch_idx):
+            if self.task == 'standard_bert':
+                # do standard bert training with self.net...
+                # return loss
+
+            if self.task == 'my_cool_task':
+                # do my own version with self.net
+                # return loss
+
+
+Case 2: COOLER NOT BERT
+-----------------------
+
+But if you wanted to try something **completely** different, you'd define a new module for that.
+
+
+.. code-block:: python
+
+    class CoolerNotBERT(pl.LightningModule):
+        def __init__(self):
+            self.net = ...
+
+        def training_step(self, batch, batch_idx):
+            # do some other cool task
+            # return loss
+
+
+Rapid research flow
+-------------------
+
+Then you could do rapid research by switching between these two and using the same trainer.
+
+
+.. code-block:: python
+
+    if use_bert:
+        model = BERT()
+    else:
+        model = CoolerNotBERT()
+
+    trainer = Trainer(gpus=4, use_amp=True)
+    trainer.fit(model)
+
+
+**Notice a few things about this flow:**
+
+1. You're writing pure PyTorch... no unnecessary abstractions or new libraries to learn.   
+2. You get free GPU and 16-bit support without writing any of that code in your model.   
+3. You also get all of the capabilities below (without coding or testing yourself).