Create initial docs (#4)

* init docs by sphinx.

* Update documentation theme to blue

* add doc to README

README.rst

@@ -17,7 +17,7 @@ Yews | Your Earthquake Waveform Solution
 .. image:: https://codecov.io/gh/lijunzh/yews/branch/master/graph/badge.svg
     :target: https://codecov.io/gh/lijunzh/yews
 
-.. image:: https://anaconda.org/lijunzhu/yews/badges/version.svg   
+.. image:: https://anaconda.org/lijunzhu/yews/badges/version.svg
     :target: https://anaconda.org/lijunzhu/yews
 
 .. image:: https://badge.fury.io/py/yews.svg
@@ -72,7 +72,7 @@ Note:
 Documentation
 =============
 
-Under construction.
+You can find the API documentation on the yews website: https://yews.info
 
 Contributing
 ============

docs/requirements.txt

@@ -0,0 +1,2 @@
+sphinx
+-e git://github.com/snide/sphinx_rtd_theme.git#egg=sphinx_rtd_theme

docs/source/_static/css/yews_theme.css

@@ -1,12 +1,19 @@
 body {
     font-family: "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
+		font-size: 1.2em;
+		line-height: 2.0;
 }
 
 /* Default header fonts are ugly */
 h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend, p.caption {
     font-family: "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
 }
 
+/* Transform the title to uppercase */
+h1 {
+	text-transform: uppercase;
+}
+
 /* Use white for docs background */
 .wy-side-nav-search {
     background-color: #fff;
@@ -59,8 +66,7 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend, p.capti
 
 /* Use our red for literals (it's very similar to the original color) */
 .rst-content tt.literal, .rst-content tt.literal, .rst-content code.literal {
-    /*color: #F05732;*/
-    color: #2D572C;
+    color: #2980b9;
 }
 
 .rst-content tt.xref, a .rst-content tt, .rst-content tt.xref,
@@ -69,21 +75,17 @@ h1, h2, .rst-content .toctree-wrapper p.caption, h3, h4, h5, h6, legend, p.capti
 }
 
 /* Change link colors (except for the menu) */
-
 a {
-    /*color: #F05732;*/
-    color: #386D37;
+    color: #2980b9;
 }
 
 a:hover {
-    /*color: #F05732;*/
-    color: #386D37;
+    color: #2980b9;
 }
 
 
 a:visited {
-    /*color: #D44D2C;*/
-    color: #244623
+    color: #2980b9;
 }
 
 .wy-menu a {

docs/source/conf.py

@@ -11,11 +11,12 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#
+
 # import os
 # import sys
-# sys.path.insert(0, os.path.abspath('.'))
+# sys.path.insert(0, os.path.abspath('..'))
 import sphinx_rtd_theme
+import yews
 
 
 # -- Project information -----------------------------------------------------
@@ -25,7 +26,7 @@
 author = 'Lijun Zhu'
 
 # The short X.Y version
-version = 'master (' + '0.0.1' + ')'
+version = 'master (' + yews.__version__ + ')'
 # The full version, including alpha/beta/rc tags
 release = 'master'
 

docs/source/dataset.rst

@@ -0,0 +1,41 @@
+yews.datasets
+====================
+
+All datasets are subclasses of :class:`torch.utils.data.Dataset`
+i.e, they have ``__getitem__`` and ``__len__`` methods implemented.
+Hence, they can all be passed to a :class:`torch.utils.data.DataLoader`
+which can load multiple samples parallelly using ``torch.multiprocessing`` workers.
+For example: ::
+
+    waveform_data = yews.datasets.Folder('path/to/waveform_folder_root/')
+    data_loader = torch.utils.data.DataLoader(waveform_data,
+                                              batch_size=4,
+                                              shuffle=True,
+                                              num_workers=args.nThreads)
+
+The following datasets are available:
+
+.. contents:: Datasets
+    :local:
+
+All the datasets have almost similar API. They all have two common arguments:
+``transform`` and  ``target_transform`` to transform the input and target
+respectively.
+
+
+.. currentmodule:: yews.datasets
+
+
+DatasetArray
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: DatasetArray
+   :members: __getitem__
+   :special-members:
+
+DatasetFolder
+~~~~~~~~~~~~~~~~~~~~~
+
+.. autoclass:: DatasetFolder
+   :members: __getitem__
+   :special-members:

docs/source/index.rst

@@ -10,8 +10,8 @@ seismic transformation for processing seismic waveforms using deep learning.
 
    dataset
    models
-   transform
+   transforms
    train
 
 .. automodule:: yews
-
+   :members:

docs/source/models.rst

@@ -0,0 +1,15 @@
+yews.models
+===========
+
+The models subpackage contains definitions for the following model
+architectures:
+
+.. contents:: Models
+   :local:
+
+.. currentmodule:: yews.models
+
+CPIC
+----
+
+.. autofunction:: cpic64

docs/source/train.rst

@@ -0,0 +1,8 @@
+yews.train
+----------
+
+.. currentmodule:: yews.train
+
+.. autoclass:: Trainer
+   :members: train, validate
+   :special-members:

docs/source/transforms.rst

@@ -0,0 +1,55 @@
+yews.transforms
+======================
+
+.. currentmodule:: yews.transforms
+
+Transforms are common waveform transformations. They can be chained together using :class:`Compose`.
+Additionally, there is the :mod:`yews.transforms.functional` module.
+Functional transforms give fine-grained control over the transformations.
+This is useful if you have to build a more complex transformation pipeline.
+
+.. autoclass:: Compose
+
+Transforms on Numpy Array
+-------------------------
+
+.. autoclass:: ZeroMean
+
+.. autoclass:: SoftClip
+
+.. autoclass:: CutWaveform
+
+Conversion Transforms
+---------------------
+
+.. autoclass:: ToTensor
+	:members: __call__
+	:special-members:
+
+Functional Transforms
+---------------------
+
+Functional transforms give you fine-grained control of the transformation pipeline.
+As opposed to the transformations above, functional transforms don't contain a random number
+generator for their parameters.
+That means you have to specify/generate all parameters, but you can reuse the functional transform.
+For example, you can apply a functional transform to multiple images like this:
+
+TODO: need to replace the image example by a seismic waveform example below:
+
+.. code:: python
+
+    import yews.transforms.functional as TF
+    import random
+
+    def my_segmentation_transforms(image, segmentation):
+        if random.random() > 5:
+            angle = random.randint(-30, 30)
+            image = TF.rotate(image, angle)
+            segmentation = TF.rotate(segmentation, angle)
+        # more transforms ...
+        return image, segmentation
+
+.. automodule:: yews.transforms.functional
+   :members:
+

yews/__init__.py

@@ -4,7 +4,7 @@
     __summary__,
 )
 
-from yews import dataset
+from yews import datasets
 from yews import transforms
 from yews import train
 from yews import models