Failed attempt at API doc

neulab · May 29, 2017 · 17ae692 · 17ae692
1 parent dc42983
commit 17ae692
Show file tree

Hide file tree

Showing 6 changed files with 122 additions and 66 deletions.
diff --git a/doc/source/api_doc.rst b/doc/source/api_doc.rst
@@ -2,3 +2,73 @@ API Doc
 =======
 
 TODO
+
+.. Embedder
+.. --------
+.. 
+.. .. autoclass:: embedder.Embedder
+..    :members:
+..    :show-inheritance:
+.. 
+.. .. autoclass:: embedder.SimpleWordEmbedder
+..    :members:
+..    :show-inheritance:
+.. 
+.. .. autoclass:: embedder.NoopEmbedder
+..    :members:
+..    :show-inheritance:
+.. 
+.. Encoder
+.. -------
+.. 
+.. .. autoclass:: encoder.Encoder
+..    :members:
+..    :show-inheritance:
+.. 
+.. .. autoclass:: encoder.BuilderEncoder
+..    :members:
+..    :show-inheritance:
+.. 
+.. .. autoclass:: encoder.ModularEncoder
+..    :members:
+..    :show-inheritance:
+.. 
+.. TODO: Pending refactoring to reduce the number of classes in Encoder, the doc should also be re-factored.
+.. 
+.. Attender
+.. --------
+.. 
+.. .. autoclass:: attender.Attender
+..    :members:
+..    :show-inheritance:
+.. 
+.. .. autoclass:: attender.StandardAttender
+..    :members:
+..    :show-inheritance:
+.. 
+.. Decoder
+.. -------
+.. 
+.. .. autoclass:: decoder.Decoder
+..    :members:
+..    :show-inheritance:
+.. 
+.. .. autoclass:: decoder.MlpSoftmaxDecoder
+..    :members:
+..    :show-inheritance:
+.. 
+.. SearchStrategy
+.. --------------
+.. 
+.. .. autoclass:: search_strategy.SearchStrategy 
+..    :members:
+..    :show-inheritance:
+.. 
+.. .. autoclass:: search_strategy.BeamSearch
+..    :members:
+..    :show-inheritance:
+.. 
+.. Other Classes
+.. -------------
+.. 
+.. TODO: Add documentation.
diff --git a/doc/source/conf.py b/doc/source/conf.py
@@ -19,7 +19,7 @@
 
 import os
 import sys
-sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('../../xnmt'))
 
 
 # -- General configuration ------------------------------------------------

diff --git a/doc/source/experiment_config_files.rst b/doc/source/experiment_config_files.rst
@@ -16,7 +16,8 @@ If any string option includes "<EXP>" this will be over-written by the name of t
 Option Tables
 =============
 
-**experiment**
+experiment
+~~~~~~~~~~
 
 +--------------------+-----------------------------------------------------------------+------+-----------+
 | Name               | Description                                                     | Type | Default   |
@@ -36,7 +37,8 @@ Option Tables
 | eval_every         | Evaluation period in iters, or 0 for never evaluating.          | int  | 0         |
 +--------------------+-----------------------------------------------------------------+------+-----------+
 
-**decode**
+decode
+~~~~~~
 
 +--------------------+-----------------------------------------------------------------+------+-----------+
 | Name               | Description                                                     | Type | Default   |
@@ -48,62 +50,43 @@ Option Tables
 | post_process       | post-processing of translation outputs: none/join-char/join-bpe | str  | none      |
 +--------------------+-----------------------------------------------------------------+------+-----------+
 
-**evaluate**
+evaluate
+~~~~~~~~
 
 +--------------------+-----------------------------------------------------------------+------+-----------+
 | Name               | Description                                                     | Type | Default   |
 +====================+=================================================================+======+===========+
-| **ref_file** | path of the reference file | str |  |
+| **ref_file**       | path of the reference file                                      | str  |           |
 +--------------------+-----------------------------------------------------------------+------+-----------+
 
-**train**
+train
+~~~~~
 
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| Name               | Description                                                     | Type | Default   |
-+====================+=================================================================+======+===========+
-| eval_every |  | int | 1000 |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| batch_size |  | int | 32 |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| batch_strategy |  | str | src |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| **train_source** |  | str |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| **train_target** |  | str |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| **dev_source** |  | str |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| **dev_target** |  | str |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| pretrained_model_file | Path of pre-trained model file | str |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| input_format | Format of input data: text/contvec | str | text |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| default_layer_dim | Default size to use for layers if not otherwise overridden | int | 512 |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| input_word_embed_dim |  | int |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| output_word_embed_dim |  | int |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| output_state_dim |  | int |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| output_mlp_hidden_dim |  | int |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| attender_hidden_dim |  | int |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| encoder_hidden_dim |  | int |  |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| trainer |  | str | sgd |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| eval_metrics |  | str | bleu |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| encoder_layers |  | int | 2 |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| decoder_layers |  | int | 2 |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| encoder_type |  | str | BiLSTM |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| decoder_type |  | str | LSTM |
-+--------------------+-----------------------------------------------------------------+------+-----------+
-| residual_to_output | If using residual networks, whether to add a residual connection to the output layer | bool | True |
-+--------------------+-----------------------------------------------------------------+------+-----------+
++-----------------------+-----------------------------------------------------------------+------+-----------+
+| Name                  | Description                                                     | Type | Default   |
++=======================+=================================================================+======+===========+
+| eval_every            |                                                                 | int  | 1000      |
++-----------------------+-----------------------------------------------------------------+------+-----------+
+| batch_size            |                                                                 | int  | 32        |
+| batch_strategy        |                                                                 | str  | src       |
+| **train_source**      |                                                                 | str  |           |
+| **train_target**      |                                                                 | str  |           |
+| **dev_source**        |                                                                 | str  |           |
+| **dev_target**        |                                                                 | str  |           |
+| pretrained_model_file | Path of pre-trained model file                                  | str  |           |
+| input_format          | Format of input data: text/contvec                              | str  | text      |
+| default_layer_dim     | Default size to use for layers if not otherwise overridden      | int  | 512       |
+| input_word_embed_dim  |                                                                 | int  |           |
+| output_word_embed_dim |                                                                 | int  |           |
+| output_state_dim      |                                                                 | int  |           |
+| output_mlp_hidden_dim |                                                                 | int  |           |
+| attender_hidden_dim   |                                                                 | int  |           |
+| encoder_hidden_dim    |                                                                 | int  |           |
+| trainer               |                                                                 | str  | sgd       |
+| eval_metrics          |                                                                 | str  | bleu      |
+| encoder_layers        |                                                                 | int  | 2         |
+| decoder_layers        |                                                                 | int  | 2         |
+| encoder_type          |                                                                 | str  | BiLSTM    |
+| decoder_type          |                                                                 | str  | LSTM      |
+| residual_to_output    | Whether to add a residual connection to the output layer        | bool | True      |
++-----------------------+-----------------------------------------------------------------+------+-----------+
diff --git a/doc/source/index.rst b/doc/source/index.rst
@@ -18,9 +18,3 @@ It is coded in Python based on `DyNet <http://github.com/clab/dynet>`_.
    api_doc
    programming_style
 
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/doc/source/translator_structure.rst b/doc/source/translator_structure.rst
@@ -4,17 +4,17 @@ Translator Structure
 If you want to dig in to using ``xnmt`` for your research it is necessary to understand
 the overall structure. Basically it consists of 5 major components:
 
-1. **Embedder:** This converts input symbols into continuous-space vectors. Usually this
+1. **Embedder**: This converts input symbols into continuous-space vectors. Usually this
                  is done by looking up the word in a lookup table, but it could be done
                  any other way.
-2. **Encoder:**  Takes the embedded input and encodes it, for example using a bi-directional
+2. **Encoder**:  Takes the embedded input and encodes it, for example using a bi-directional
                  LSTM to calculate context-sensitive embeddings.
-3. **Attender:** This is the "attention" module, which takes the encoded input and decoder
+3. **Attender**: This is the "attention" module, which takes the encoded input and decoder
                  state, then calculates attention.
-4. **Decoder:**  This calculates a probability distribution over the words in the output,
+4. **Decoder**:  This calculates a probability distribution over the words in the output,
                  either to calculate a loss function during training, or to generate outputs
                  at test time.
-5. **SearchStrategy:** This takes the probabilities calculated by the decoder and actually
+5. **SearchStrategy**: This takes the probabilities calculated by the decoder and actually
                  generates outputs at test time.
 
 There are a bunch of auxiliary classes as well to handle saving/loading of the inputs,

diff --git a/xnmt/encoder.py b/xnmt/encoder.py
@@ -23,6 +23,15 @@ def transduce(self, sent):
 
   @staticmethod
   def from_spec(spec, layers, input_dim, output_dim, model, residual_to_output):
+    """
+    Create an encoder from a specification.
+    :param spec: Options include bilstm, residuallstm, residualbylstm, pyramidalbilstm, convbilstm, modular.
+    :param layers: Number of layers
+    :param input_dim: Input dimension
+    :param output_dim: Output dimension
+    :param model: The model that we should add the parameters to
+    :param residual_to_output: For residual encoders, whether to add a residual to the output layer.
+    """
     spec_lower = spec.lower()
     if spec_lower == "bilstm":
       return BiLSTMEncoder(layers, input_dim, output_dim, model)