polish documentation

doc/source/advanced.rst

@@ -8,7 +8,7 @@ experiments. Guidelines on implementation are also elaborated.
 Model
 -------------
 
-As a common practice with paddlepaddle, models are implemented as subclasse
+As a common practice with paddlepaddle, models are implemented as subclasses
 of ``paddle.nn.Layer``. More complicated models, it is recommended to split 
 the model into different components.
 
@@ -18,8 +18,66 @@ extract the sublayer as a seperate layer.
 
 There are two common ways to define a model which consists of several modules.
 
-#. 
+#. Define a module given the specifications.
 
+   .. code-block:: python
+
+      class MLP(nn.Layer):
+          def __init__(self, input_size, hidden_size, output_size):
+              self.linear1 = nn.Linear(input_size, hidden_size)
+              self.linear2 = nn.Linear(hidden_size, output_size)
+              
+          def forward(self, x):
+              return self.linear2(paddle.tanh(self.linear1(x))
+
+      module = MLP(16, 32, 4) # intialize a module
+
+   When the module is intended to be a generic reusable layer that can be 
+   integrated into a larger model, we prefer to define it in this way.
+
+   For considerations of readability and usability, we strongly recommend **NOT** to 
+   pack specifications into a single object. Here's an example below.
+
+   .. code-block:: python
+
+      class MLP(nn.Layer):
+          def __init__(self, hparams):
+              self.linear1 = nn.Linear(hparams.input_size, hparams.hidden_size)
+              self.linear2 = nn.Linear(hparams.hidden_size, hparams.output_size)
+              
+          def forward(self, x):
+              return self.linear2(paddle.tanh(self.linear1(x))
+
+   For a module defined in this way, it's harder for the user to initialize a 
+   instance. The user have to read the code to check what attributes are used.
+
+   Code in this style tend to pass a huge config object to initialize every 
+   module used in an experiment, thought each module may not need the whole 
+   configuration.
+   
+   We prefer to be explicit.
+
+#. Define a module as a combination given its components.
+
+   .. code-block:: python
+   
+      class Seq2Seq(nn.Layer):
+          def __init__(self, encoder, decoder):
+              self.encoder = encoder
+              self.decoder = decoder
+              
+          def forward(self, x):
+              encoder_output = self.encoder(x)
+              output = self.decoder(encoder_output)
+              return output
+      
+      encoder = Encoder(...)
+      decoder = Decoder(...)
+      model = Seq2Seq(encoder, decoder) # compose two components
+
+   When a model is a complicated one made up of several components, each of which 
+   has a separate functionality, and can be replaced by other components with the 
+   same functionality, we prefer to define it in this way.
 
 Data
 -------------

doc/source/demo.rst

@@ -0,0 +1,2 @@
+Audio Sample 
+==================

doc/source/index.rst

@@ -20,12 +20,18 @@ Parakeet
 
     install
     tutorials
+    advanced 
+
+.. toctree::
+    :caption: Demos
+    :maxdepth: 1
+    
+    demo
 
 .. toctree::
     :caption: Design of Parakeet
     :maxdepth: 1
     
-    advanced
     design
 
 .. toctree::

doc/source/tutorials.rst

@@ -61,5 +61,12 @@ Like the example above, after loading the pretrained ConditionalWaveFlow model,
 
 For more details on how to use the model, please refer the documentation.
 
+.. raw:: html
+
+   <audio controls="controls">
+         <source src="https://paddlespeech.bj.bcebos.com/Parakeet/transformer_tts_ljspeech_griffin-lim_samples_1.0/step_120000_sentence_0.wav" type="audio/wav">
+         Your browser does not support the <code>audio</code> element. 
+   </audio>
+
 
 

parakeet/data/__init__.py

@@ -14,5 +14,5 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from .dataset import *
-from .batch import *
+from parakeet.data.dataset import *
+from parakeet.data.batch import *