From c374c4fb80a4c041e910e4c6e49c6a5aa6692662 Mon Sep 17 00:00:00 2001 From: Jirka Borovec Date: Sat, 7 Dec 2019 06:23:48 +0100 Subject: [PATCH] extend documentation (#569) * extend documentation * update index * fix list --- docs/source/conf.py | 7 +++- docs/source/documentation.rst | 8 ++++ docs/source/examples.rst | 8 ++++ docs/source/index.rst | 24 +++++++++--- docs/source/intro.md | 60 ----------------------------- docs/source/new-project.rst | 71 +++++++++++++++++++++++++++++++++++ 6 files changed, 111 insertions(+), 67 deletions(-) create mode 100644 docs/source/documentation.rst create mode 100644 docs/source/examples.rst delete mode 100644 docs/source/intro.md create mode 100644 docs/source/new-project.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index 3f822edf..5f6df644 100644 --- a/docs/source/conf.py +++ b/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' diff --git a/docs/source/documentation.rst b/docs/source/documentation.rst new file mode 100644 index 00000000..6b22dfc1 --- /dev/null +++ b/docs/source/documentation.rst @@ -0,0 +1,8 @@ +Documentation +============= + + +.. toctree:: + :maxdepth: 4 + + pytorch_lightning \ No newline at end of file diff --git a/docs/source/examples.rst b/docs/source/examples.rst new file mode 100644 index 00000000..3f15f06e --- /dev/null +++ b/docs/source/examples.rst @@ -0,0 +1,8 @@ +Examples & Tutorials +==================== + + +.. toctree:: + :maxdepth: 3 + + pl_examples \ No newline at end of file diff --git a/docs/source/index.rst b/docs/source/index.rst index 8a8e8c00..0dd7a6af 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/intro.md b/docs/source/intro.md deleted file mode 100644 index 4155f660..00000000 --- a/docs/source/intro.md +++ /dev/null @@ -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). diff --git a/docs/source/new-project.rst b/docs/source/new-project.rst new file mode 100644 index 00000000..448e7e38 --- /dev/null +++ b/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).