update documentation with better markup

Author: Shawn P. Duncan

Diff for: ae_processor.py

@@ -24,16 +24,17 @@ def main(args: Namespace) -> None:
 
     For the training loop:
 
-    - Instantiates a data object using `cp_tokenized_data.QuackTokenizedDataModule`.
-    - Instantiates a model using `autoencoder.QuackAutoEncoder`.
-    - Instantiates a strategy plugin using `ray_lightning.ray_ddp.RayPlugin`.
+    - Instantiates a data object using ``cp_tokenized_data.QuackTokenizedDataModule``.
+    - Instantiates a model using ``autoencoder.QuackAutoEncoder``.
+    - Instantiates a strategy plugin using ``ray_lightning.ray_ddp.RayPlugin``.
     - Instantiates callback objects:
-    -- A logger using `pytorch_lightning.loggers.comet.CometLogger`
-    -- A learning rate monitor using `pytorch_lightning.callbacks.lr_monitor.LearningRateMonitor`
-    -- A checkpoint creator using `pytorch_lightning.callbacks.model_checkpoint.ModelCheckpoint`
-    -- An early stopping monitor using `pytorch_lightning.callbacks.early_stopping.EarlyStopping`
 
-    Then using these objects, instantiates a training control object using `pytorch_lightning.trainer.trainer.Trainer`
+        - A logger using ``pytorch_lightning.loggers.comet.CometLogger``
+        - A learning rate monitor using ``pytorch_lightning.callbacks.lr_monitor.LearningRateMonitor``
+        - A checkpoint creator using ``pytorch_lightning.callbacks.model_checkpoint.ModelCheckpoint``
+        - An early stopping monitor using ``pytorch_lightning.callbacks.early_stopping.EarlyStopping``
+
+    Then using these objects, instantiates a training control object using ``pytorch_lightning.trainer.trainer.Trainer``
 
     For inference with a trained model, just the logger and the ray strategy are used along with an instance of
     autoencoder.AutoencoderWriter which when composed with Trainer prepares the prediction loop to output its results
@@ -44,49 +45,49 @@ def main(args: Namespace) -> None:
     args: Namespace
          Command line arguments.  Possible arguments are:
 
-         `--data_dir`
+         --data_dir
             *str* default='./data'  The top directory of the data storage tree.
 
-         `--batch_size`
+         --batch_size
             *int* default=4 The batch size used for processing data.
 
-         `--num_workers`
+         --num_workers
             *int* default=0 The number of worker processes used by the data loader.
 
-         `--embed_size`
+         --embed_size
             *int* default=128 Hyperparameter passed to QuackAutoEncoder.
 
-         `--hidden_size`
+         --hidden_size
             *int* default=512 Hyperparameter passed to QuackAutoEncoder.
 
-         `--encode`
+         --encode
             *bool* Flag to run the inference loop instead of train. True when present, otherwise False
 
-         `--filtered`
+         --filtered
             *bool* Flag to output labeled data from the inference loop. True when present, otherwise False
 
-         `--evaluate`
+         --evaluate
             *bool* Flag to output undetermined data from the inference loop. True when present, otherwise False
 
-         `--checkpoint_path`
+         --checkpoint_path
             *str* A checkpoint used for manual restart. Only the weights are used.
 
-         `--storage_path`
+         --storage_path
             *str* default='./data/encoded' A path for storing the outputs from inference.
 
-         `--l_rate`
+         --l_rate
             *float* default=1e-1 Hyperparameter passed to QuackAutoEncoder.
 
-         `--l_rate_min`
+         --l_rate_min
             *float* default=1e-3 Hyperparameter passed to QuackAutoEncoder.
 
-         `--l_rate_max_epoch`
+         --l_rate_max_epoch
             *int* default=-1 Hyperparameter passed to QuackAutoEncoder.
 
-         `--exp_label`
+         --exp_label
             *str* default='autoencoder-train' Label passed to the logger.
 
-         `--ray_nodes`
+         --ray_nodes
             *int* default=4 Number of parallel nodes passed to the Ray plugin.
 
     Returns

Diff for: autoencoder.py

@@ -164,11 +164,7 @@ def __init__(self, dim: int) -> None:
 
     def forward(self, states: pt.Tensor, context: pt.Tensor) -> pt.Tensor:
         """
-        Computes the dot-product score:
-
-        :math`score(h_t, c) = \frac{h^T_t \cdot c}{\sqrt{H}}`
-        with values of h taken from the states parameter, c from the context paramter and H is the dim parameter
-        passed at construction.
+        Computes the dot-product score.
 
         Parameters
         ----------
@@ -382,6 +378,24 @@ def forward(self, x: pt.Tensor) -> Tuple[pt.Tensor, pt.Tensor]:
         return last_h, encoded_sequence
 
     def _common_step(self, x: pt.Tensor, batch_index: int, step_id: str) -> float:
+        """
+        The common step containds the decoder logic, and begins by calling self.forward() so that it executes the full
+        autoencder cycle.
+
+        Parameters
+        ----------
+        x: pt.Tensor
+            The input, which should be (B, T) shaped.
+       batch_index: int
+            The batch index
+        step_id: str
+            The step id.
+
+        Returns
+        -------
+        float
+            The total loss over the sequence.
+        """
         final_state, sequence = self.forward(x)
 
         # Now add the decoder part.
@@ -492,9 +506,9 @@ def predict_step(self, batch: Any, batch_idx: int, dataloader_idx: Optional[int]
 
         Parameters
         ----------
-       batch: pt. Tuple[dict, pt.Tensor]
+        batch: pt. Tuple[dict, pt.Tensor]
             An tuple of a metadata dictionary and the associated input data
-       batch_idx: int
+        batch_idx: int
             The index of the batch.  Required to match the parent signature.  Unused in our model.
         dataloader_idx: int
             Index of the current dataloader.   Required to match the parent signature.  Unused in our model.

Diff for: cp_flatten_processor.py

@@ -47,13 +47,13 @@ def main() -> None:
 
     **Required** arguments are:
 
-         `--source_path`
+         --source_path
             *str*   The path to the .tar file.  May be local or a url. Passed to `CensoredPlanetFlatten`.
-        ` --storage_path`
+         --storage_path
             *str* The top directory of the data storage tree.
-         `--log_path`
+         --log_path
             *str* default=0 The path to a log file.
-         `--vocab_path`
+         --vocab_path
             *str* default=0 The path to a .pyc file.  Passed to `CensoredPlanetFlatten`.
     """
     # Add args to make a more flexible cli tool.

Diff for: dn_processor.py

@@ -21,51 +21,53 @@ def main(args: Namespace) -> None:
     The executable logic for this controller.
 
     For the training loop:
-    - Instantiates a data object using `cp_image_data.QuackImageDataModule`.
-    - Instantiates a model using `densenet.QuackDenseNet`.
-    - Instantiates a strategy plugin using `ray_lightning.ray_ddp.RayPlugin`.
+    - Instantiates a data object using ``cp_image_data.QuackImageDataModule``.
+    - Instantiates a model using ``densenet.QuackDenseNet``.
+    - Instantiates a strategy plugin using ``ray_lightning.ray_ddp.RayPlugin``.
     - Instantiates callback objects:
-    -- A logger using `pytorch_lightning.loggers.comet.CometLogger`
-    -- A learning rate monitor using `pytorch_lightning.callbacks.lr_monitor.LearningRateMonitor`
-    -- A checkpoint creator using `pytorch_lightning.callbacks.model_checkpoint.ModelCheckpoint`
-    -- An early stopping monitor using `pytorch_lightning.callbacks.early_stopping.EarlyStopping`
-    Then using these objects, instantiates a training control object using `pytorch_lightning.trainer.trainer.Trainer`
+
+        - A logger using ``pytorch_lightning.loggers.comet.CometLogger``
+        - A learning rate monitor using ``pytorch_lightning.callbacks.lr_monitor.LearningRateMonitor``
+        - A checkpoint creator using ``pytorch_lightning.callbacks.model_checkpoint.ModelCheckpoint``
+        - An early stopping monitor using ``pytorch_lightning.callbacks.early_stopping.EarlyStopping``
+
+    Then using these objects, instantiates a training control object using ``pytorch_lightning.trainer.trainer.Trainer``
 
     For inference with a trained model, just the logger and the ray strategy are used along with an instance of
-    `densenet.CensoredDataWriter` which when composed with Trainer prepares the prediction loop to output its results
+    ``densenet.CensoredDataWriter`` which when composed with Trainer prepares the prediction loop to output its results
     to file on each iteration.
 
     Parameters
     ----------
     args: Namespace
          Command line arguments.  Possible arguments are:
 
-         `--data_dir`
+         --data_dir
             *str* default='./data'  The top directory of the data storage tree.
-         `--batch_size`
+         --batch_size
             *int* default=4 The batch size used for processing data.
-         `--num_workers`
+         --num_workers
             *int* default=0 The number of worker processes used by the data loader.
-         `--evaluate`
+         --evaluate
             *bool* Flag to output undetermined data from the inference loop. True when present, otherwise False
-         `--checkpoint_path`
+         --checkpoint_path
             *str* A checkpoint used for manual restart. Only the weights are used.
-         `--storage_path`
+         --storage_path
             *str* default='./data/encoded' A path for storing the outputs from inference.
-         `--l_rate`
+         --l_rate
             *float* default=1e-1 Hyperparameter passed to QuackAutoEncoder.
-         `--l_rate_min`
+         --l_rate_min
             *float* default=1e-3 Hyperparameter passed to QuackAutoEncoder.
-         `--l_rate_max_epoch`
+         --l_rate_max_epoch
             *int* default=-1 Hyperparameter passed to QuackAutoEncoder.
-         `--exp_label`
+         --exp_label
             *str* default='autoencoder-train' Label passed to the logger.
-         `--ray_nodes`
+         --ray_nodes
             *int* default=4 Number of parallel nodes passed to the Ray plugin.
-         `--freeze`
+         --freeze
             *bool* Flag to construct so that the image analyzing layers of the pre-trained Densenet are frozen for
             training.
-         `--simple_transforms`
+         --simple_transforms
             *bool* Flag passed to the data module to simplify image transforms.
 
     Returns

Diff for: latent_processor.py

@@ -22,48 +22,50 @@ def main(args: Namespace) -> None:
     The executable logic for this controller.
 
     For the training loop:
-    - Instantiates a data object using `cp_latent_data.QuackLatentDataModule`.
-    - Instantiates a model using `cp_latent_classifier.QuackLatentClassifier`.
-    - Instantiates a strategy plugin using `ray_lightning.ray_ddp.RayPlugin`.
+    - Instantiates a data object using ``cp_latent_data.QuackLatentDataModule``.
+    - Instantiates a model using ``cp_latent_classifier.QuackLatentClassifier``.
+    - Instantiates a strategy plugin using ``ray_lightning.ray_ddp.RayPlugin``.
     - Instantiates callback objects:
-    -- A logger using `pytorch_lightning.loggers.comet.CometLogger`
-    -- A learning rate monitor using `pytorch_lightning.callbacks.lr_monitor.LearningRateMonitor`
-    -- A checkpoint creator using `pytorch_lightning.callbacks.model_checkpoint.ModelCheckpoint`
-    -- An early stopping monitor using `pytorch_lightning.callbacks.early_stopping.EarlyStopping`
-    Then using these objects, instantiates a training control object using `pytorch_lightning.trainer.trainer.Trainer`
+
+        - A logger using ``pytorch_lightning.loggers.comet.CometLogger``
+        - A learning rate monitor using ``pytorch_lightning.callbacks.lr_monitor.LearningRateMonitor``
+        - A checkpoint creator using ``pytorch_lightning.callbacks.model_checkpoint.ModelCheckpoint``
+        - An early stopping monitor using ``pytorch_lightning.callbacks.early_stopping.EarlyStopping``
+
+    Then using these objects, instantiates a training control object using ``pytorch_lightning.trainer.trainer.Trainer``
 
     For inference with a trained model, just the logger and the ray strategy are used along with an instance of
-    `densenet.CensoredDataWriter` which when composed with Trainer prepares the prediction loop to output its results
+    ``densenet.CensoredDataWriter`` which when composed with Trainer prepares the prediction loop to output its results
     to file on each iteration.
 
     Parameters
     ----------
     args: Namespace
          Command line arguments.  Possible arguments are:
 
-         `--data_dir`
+         --data_dir
             *str* default='./data'  The top directory of the data storage tree.
-         `--batch_size`
+         --batch_size
             *int* default=4 The batch size used for processing data.
-         `--num_workers`
+         --num_workers
             *int* default=0 The number of worker processes used by the data loader.
-         `--evaluate`
+         --evaluate
             *bool* Flag to output undetermined data from the inference loop. True when present, otherwise False
-         `--checkpoint_path`
+         --checkpoint_path
             *str* A checkpoint used for manual restart. Only the weights are used.
-         `--storage_path`
+         --storage_path
             *str* default='./data/encoded' A path for storing the outputs from inference.
-         `--l_rate`
+         --l_rate
             *float* default=1e-1 Hyperparameter passed to QuackAutoEncoder.
-         `--l_rate_min`
+         --l_rate_min
             *float* default=1e-3 Hyperparameter passed to QuackAutoEncoder.
-         `--l_rate_max_epoch`
+         --l_rate_max_epoch
             *int* default=-1 Hyperparameter passed to QuackAutoEncoder.
-         `--exp_label`
+         --exp_label
             *str* default='autoencoder-train' Label passed to the logger.
-         `--ray_nodes`
+         --ray_nodes
             *int* default=4 Number of parallel nodes passed to the Ray plugin.
-         `--freeze`
+         --freeze
             *bool* Flag to construct so that the image analyzing layers of the pre-trained Densenet are frozen for
             training.