add appendix, fix links

Author: mchoi8739

doc/api/training/smd_data_parallel.rst

@@ -1,6 +1,6 @@
-##########################
-Distributed data parallel
-##########################
+###############################################
+The SageMaker Distributed Data Parallel Library
+###############################################
 
 SageMaker's distributed data parallel library extends SageMaker’s training
 capabilities on deep learning models with near-linear scaling efficiency,

doc/api/training/smd_model_parallel.rst

@@ -1,5 +1,5 @@
-Distributed model parallel
---------------------------
+The SageMaker Distributed Model Parallel Library
+------------------------------------------------
 
 The Amazon SageMaker distributed model parallel library is a model parallelism library for training
 large deep learning models that were previously difficult to train due to GPU memory limitations.
@@ -14,18 +14,19 @@ See the following sections to learn more about the SageMaker model parallel libr
 Use with the SageMaker Python SDK
 =================================
 
-Use the following page to learn how to configure and enable distributed model parallel
-when you construct an Amazon SageMaker Python SDK `Estimator`.
+Walk through the following pages to learn about the library's APIs
+to configure and enable distributed model parallelism
+through an Amazon SageMaker estimator.
 
 .. toctree::
    :maxdepth: 1
 
    smd_model_parallel_general
 
-The library's API to Adapt Training Scripts
-===========================================
+Use the Library's API to Adapt Training Scripts
+===============================================
 
-The library contains a Common API that is shared across frameworks,
+The library provides Common APIs that you can use across frameworks,
 as well as framework-specific APIs for TensorFlow and PyTorch.
 
 Select the latest or one of the previous versions of the API documentation

doc/api/training/smd_model_parallel_general.rst

@@ -1,12 +1,13 @@
 .. _sm-sdk-modelparallel-params:
 
-Required SageMaker Python SDK parameters
-========================================
+Configuration Parameters for Model Parallelism
+==============================================
 
-The TensorFlow and PyTorch ``Estimator`` objects contains a ``distribution`` parameter,
+Amazon SageMaker's TensorFlow and PyTorch estimator objects contain a ``distribution`` parameter,
 which is used to enable and specify parameters for the
-initialization of the SageMaker distributed model parallel library. The library internally uses MPI,
-so in order to use model parallelism, MPI must also be enabled using the ``distribution`` parameter.
+initialization of SageMaker distributed training. The library internally uses MPI.
+To use model parallelism, both ``smdistributed`` and MPI must be enabled
+through the ``distribution`` parameter.
 
 The following is an example of how you can launch a new PyTorch training job with the library.
 
@@ -50,12 +51,20 @@ The following is an example of how you can launch a new PyTorch training job wit
 
    smd_mp_estimator.fit('s3://my_bucket/my_training_data/')
 
-Parameters for ``modelparallel``
-================================
+For more conceptual guidance, see
+`Run a SageMaker Distributed Model Parallel Training Job <https://docs.aws.amazon.com/sagemaker/latest/dg/model-parallel-use-api.html>`_
+in the `SageMaker's Distributed Model Parallel developer guide <https://docs.aws.amazon.com/sagemaker/latest/dg/model-parallel.html>`_.
+
+.. contents:: Table of Contents
+  :depth: 3
+  :local:
+
+Parameters for ``"smdistributed"``
+----------------------------------
 
 You can use the following parameters to initialize the library
 configuring a dictionary for ``modelparallel``, which goes
-into the ``smdistributed`` of ``distribution``.
+into the ``smdistributed`` option for the ``distribution`` parameter.
 
 .. note::
 
@@ -224,8 +233,8 @@ PyTorch-specific Parameters
        loss and GPU bottlenecks during the CPU-to-GPU data transfer.
 
 
-``mpi`` Parameters
-==================
+Parameters for ``mpi``
+----------------------
 
 For the ``"mpi"`` key, a dict must be passed which contains:
 

doc/api/training/smp_versions/latest/smd_model_parallel_common_api.rst

@@ -1,14 +1,16 @@
-.. admonition:: Contents
-
-   - :ref:`communication_api`
-   - :ref:`mpi_basics`
-
 Common API
 ==========
 
 The following SageMaker distribute model parallel APIs are common across all frameworks.
 
-**Important**: This API document assumes you use the following import statement in your training scripts.
+.. contents:: Table of Contents
+  :depth: 3
+  :local:
+
+The Library's Core APIs
+-----------------------
+
+This API document assumes you use the following import statement in your training scripts.
 
 **TensorFlow**
 
@@ -254,7 +256,7 @@ The following SageMaker distribute model parallel APIs are common across all fra
 .. _mpi_basics:
 
 MPI Basics
-^^^^^^^^^^
+----------
 
 The library exposes the following basic MPI primitives to its Python API:
 
@@ -326,7 +328,7 @@ The library exposes the following basic MPI primitives to its Python API:
 .. _communication_api:
 
 Communication API
-^^^^^^^^^^^^^^^^^
+-----------------
 
 The library provides a few communication primitives which can be helpful while
 developing the training script. These primitives use the following