Restructuring guide

andistryz · Apr 30, 2015 · 4356aea · 4356aea
1 parent df5813f
commit 4356aea
Show file tree

Hide file tree

Showing 24 changed files with 256 additions and 648 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -31,6 +31,7 @@
 html_sidebars = {
     '**': ['sidebarlogo.html',
            'globaltoc.html',
+           'localtoc.html',
            'searchbox.html',
            'feedback.html']
 }

diff --git a/docs/faq.rst b/docs/faq.rst
@@ -1,6 +1,6 @@
-================================
-Frequently Asked Questions (FAQ)
-================================
+===
+FAQ
+===
 
 
 What methods are available on a client?
@@ -146,4 +146,4 @@ If you are seeing this error and you are **not** intending to use instance
 profile credentials, then you need to make sure that you are properly providing
 credentials to the SDK.
 
-For more information, see :doc:`credentials`.
+For more information, see :doc:`/guide/credentials`.
diff --git a/docs/basic-usage.rst → docs/getting-started/basic-usage.rst b/docs/basic-usage.rst → docs/getting-started/basic-usage.rst
@@ -68,9 +68,9 @@ directory, AWS Identity and Access Management (IAM)
 :ref:`credential providers <credential_provider>`.
 
 All of the general client configuration options are described in detail in
-the :doc:`configuration guide <configuration>`. The array of options provided
-to a client may vary based on which client you are creating. These custom
-client configuration options are described in the
+the :doc:`configuration guide </guide/configuration>`. The array of options
+provided to a client may vary based on which client you are creating. These
+custom client configuration options are described in the
 `API documentation <http://docs.aws.amazon.com/aws-sdk-php/latest/>`_ of each
 client.
 

diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst
@@ -0,0 +1,13 @@
+===============
+Getting Started
+===============
+
+This chapter is dedicated to getting you up and running with the AWS SDK for
+PHP.
+
+.. toctree::
+    :maxdepth: 2
+
+    requirements
+    installation
+    basic-usage
diff --git a/docs/installation.rst → docs/getting-started/installation.rst b/docs/installation.rst → docs/getting-started/installation.rst
diff --git a/docs/requirements.rst → docs/getting-started/requirements.rst b/docs/requirements.rst → docs/getting-started/requirements.rst
diff --git a/docs/glossary.rst b/docs/glossary.rst
@@ -8,7 +8,8 @@ SDK
     <http://docs.aws.amazon.com/aws-sdk-php/v3/api/Aws/Sdk.html>`_, which acts
     as a factory for the client objects for each **service**. The ``Sdk`` class
     also let's you provide a set of :doc:`global configuration values
-    <configuration>` that are applied to all client objects that it creates.
+    </guide/configuration>` that are applied to all client objects that it
+    creates.
 
 Service
     A general way to refer to any of the AWS services (e.g., Amazon S3, Amazon
@@ -29,8 +30,8 @@ Client
     Client objects are used to execute operations for a service. Each service
     that is supported in the SDK has a corresponding client object. Client
     objects have methods that correspond one-to-one with the service operations.
-    See the :doc:`basic usage guide <basic-usage>` for details on how to create
-    and use client objects.
+    See the :doc:`basic usage guide </getting-started/basic-usage>` for details
+    on how to create and use client objects.
 
 API Version
     Services have one or more API versions, and which version you are using
@@ -53,8 +54,8 @@ Credentials
     <http://aws.amazon.com/developers/access-keys/>`_. Your access keys consist
     of two parts: your access key ID, which identifies your account, and your
     secret access, which is used to create **signatures** when executing
-    operations. You must :doc:`provide credentials <credentials>` when you
-    configure a client object.
+    operations. You must :doc:`provide credentials </guide/credentials>` when
+    you configure a client object.
 
 Signature
     When executing operations, the SDK uses your credentials to create a digital
@@ -64,11 +65,11 @@ Signature
 
 Command
     Command objects encapsulate the execution of an operation. When following
-    the :doc:`basic usage patterns <basic-usage>` of the SDK, you will not deal
-    directly with command objects. Command objects can be accessed using the
-    ``getCommand()`` method of a client, in order to use advanced features of
-    the SDK like concurrent requests and batching. See the :doc:`commands` guide
-    for more details.
+    the :doc:`basic usage patterns </getting-started/basic-usage>` of the SDK,
+    you will not deal directly with command objects. Command objects can be
+    accessed using the ``getCommand()`` method of a client, in order to use
+    advanced features of the SDK like concurrent requests and batching. See
+    the :doc:`/guide/commands` guide for more details.
 
 Paginator
     Some AWS service operations are paginated and respond with truncated
@@ -78,7 +79,7 @@ Paginator
     results. Paginators are a feature of the SDK that act as an abstraction over
     this process to make it easier for developers to use paginated APIs. They
     are accessed via the ``getPaginator()`` method of the client. See the
-    :doc:`paginators` guide for more details.
+    :doc:`/guide/paginators` guide for more details.
 
 Waiter
     Waiters are a feature of the SDK that make it easier to work with operations
@@ -88,4 +89,4 @@ Waiter
     to access for several seconds. Executing a waiter allows you to wait until a
     resource enters into a particular state by sleeping and polling the
     resource's status. Waiters are accessed using the ``waitUntil()`` method of
-    the client. See the :doc:`waiters` guide for more details.
+    the client. See the :doc:`/guide/waiters` guide for more details.
diff --git a/docs/commands.rst → docs/guide/commands.rst b/docs/commands.rst → docs/guide/commands.rst
@@ -10,8 +10,6 @@ sending asynchronous requests.
 Typical SDK usage
 -----------------
 
-.. include:: _snippets/performing-operations.txt
-
 
 A peek under the hood
 ---------------------

diff --git a/docs/configuration.rst → docs/guide/configuration.rst b/docs/configuration.rst → docs/guide/configuration.rst
@@ -3,8 +3,16 @@ Configuration
 =============
 
 This guide describes client constructor options. These options can be provided
-in a client constructor or to the ``Aws\Sdk`` class. The following example
-shows how to pass options into an Amazon S3 client constructor.
+in a client constructor or to the ``Aws\Sdk`` class.
+
+
+.. contents:: Configuration Options
+    :depth: 1
+    :local:
+
+
+The following example shows how to pass options into an Amazon S3 client
+constructor.
 
 .. code-block:: php
 
@@ -18,7 +26,7 @@ shows how to pass options into an Amazon S3 client constructor.
 
     $s3Client = new S3Client($options);
 
-Refer to the :doc:`basic usage guide <basic-usage>` for more
+Refer to the :doc:`basic usage guide </getting-started/basic-usage>` for more
 information on constructing clients.
 
 

diff --git a/docs/credentials.rst → docs/guide/credentials.rst b/docs/credentials.rst → docs/guide/credentials.rst
diff --git a/docs/guide/index.rst b/docs/guide/index.rst
@@ -0,0 +1,17 @@
+==========
+SDK Guides
+==========
+
+The AWS SDK for PHP consists of various components. Each of the following
+guides describe the components that are used in the SDK.
+
+.. toctree::
+    :maxdepth: 1
+
+    configuration
+    credentials
+    commands
+    paginators
+    waiters
+    jmespath
+    migration
diff --git a/docs/jmespath.rst → docs/guide/jmespath.rst b/docs/jmespath.rst → docs/guide/jmespath.rst
diff --git a/docs/migration-guide.rst → docs/guide/migration.rst b/docs/migration-guide.rst → docs/guide/migration.rst
diff --git a/docs/paginators.rst → docs/guide/paginators.rst b/docs/paginators.rst → docs/guide/paginators.rst
diff --git a/docs/waiters.rst → docs/guide/waiters.rst b/docs/waiters.rst → docs/guide/waiters.rst
@@ -5,8 +5,6 @@ Waiters
 Introduction
 ------------
 
-.. include:: _snippets/waiters-intro.txt
-
 If the waiter has to poll the bucket too many times, it will throw an ``Aws\Common\Exception\RuntimeException``
 exception.
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -5,25 +5,12 @@ AWS SDK for PHP
 .. toctree::
     :hidden:
 
-    requirements
-    installation
-    basic-usage
-
-    configuration
-    credentials
-    commands
-    waiters
-    paginators
+    getting-started/index
+    guide/index
+    service/index
     faq
     glossary
 
-    service-cloudfront
-    feature-dynamodb-session-handler
-    service-s3
-    feature-s3-stream-wrapper
-
-    migration-guide
-
 The **AWS SDK for PHP** enables PHP developers to use
 `Amazon Web Services <http://aws.amazon.com/>`_ from their PHP code, and build
 robust applications and software using services like Amazon S3, Amazon
@@ -44,39 +31,54 @@ External links: `API Docs <http://docs.aws.amazon.com/aws-sdk-php/v3/api/>`_
 Getting Started
 ---------------
 
-1. :doc:`requirements`
-2. :doc:`installation`
-3. :doc:`basic-usage`
+1. :doc:`getting-started/requirements`
+2. :doc:`getting-started/installation`
+3. :doc:`getting-started/basic-usage`
+
+
+SDK Guides
+----------
+
+* :doc:`guide/configuration`
+* :doc:`guide/credentials`
+* :doc:`guide/commands`
+* :doc:`guide/paginators`
+* :doc:`guide/waiters`
+* :doc:`guide/jmespath`
+* :doc:`guide/migration`
+
+
+Service Features
+----------------
 
-.. 4. `Sample Project <http://aws.amazon.com/developers/getting-started/php/>`_
+* :doc:`service/cloudfront`
+* :doc:`service/dynamodb-session-handler`
+* :doc:`guide/paginators`
+* :doc:`service/s3-presigned-url`
+* :doc:`service/s3-stream-wrapper`
+* :doc:`service/s3-transfer`
 
 
-SDK Details
------------
+Reference
+---------
 
-* :doc:`configuration`
-* :doc:`credentials`
-* :doc:`paginators`
-* :doc:`waiters`
-* :doc:`commands`
 * :doc:`faq`
-* :doc:`concepts`
+* :doc:`glossary`
 * `Contributing to the SDK <https://github.com/aws/aws-sdk-php/blob/master/CONTRIBUTING.md>`_
 * `Guzzle Documentation <http://guzzlephp.org>`_
 
 
 .. _supported-services:
 
-Supported Services
-------------------
+API Documentation
+-----------------
+
+API documentation for the SDK can be found at http://docs.aws.amazon.com/aws-sdk-php/v3/api/.
+Documentation for specific AWS services can found below.
 
 - :apiref:`Amazon CloudFront | CloudFront`
-  - :doc:`service-cloudfront`
 - :apiref:`Amazon CloudWatch | CloudWatch`
 - :apiref:`Amazon DynamoDB | DynamoDb`
-
-  - :doc:`DynamoDB Session Handler <feature-dynamodb-session-handler>`
-
 - :apiref:`Amazon Elastic Compute Cloud (Amazon EC2) | Ec2`
 - :apiref:`Amazon Elastic MapReduce (Amazon EMR) | Emr`
 - :apiref:`Amazon Elastic Transcoder | ElasticTranscoder`
@@ -85,16 +87,11 @@ Supported Services
 - :apiref:`Amazon Kinesis | Kinesis`
 - :apiref:`Amazon Redshift | Redshift`
 - :apiref:`Amazon Relational Database Service (Amazon RDS) | Rds`
-
 - :apiref:`Amazon Route 53 | Route53`
 - :apiref:`Amazon Simple Email Service (Amazon SES) | Ses`
 - :apiref:`Amazon Simple Notification Service (Amazon SNS) | Sns`
 - :apiref:`Amazon Simple Queue Service (Amazon SQS) | Sqs`
 - :apiref:`Amazon Simple Storage Service (Amazon S3) | S3`
-
-  - :doc:`service-s3`
-  - :doc:`Amazon S3 Stream Wrapper <feature-s3-stream-wrapper>`
-
 - :apiref:`Amazon Simple Workflow Service (Amazon SWF) | Swf`
 - :apiref:`Amazon SimpleDB | SimpleDb`
 - :apiref:`Auto Scaling | AutoScaling`