Revamp docs

.gitignore

@@ -8,6 +8,7 @@
 /.coverage*
 /build
 /doc/generated/*
+/doc/lib/generated/*
 /runpy
 __pycache__
 build

CHANGELOG.rst

@@ -0,0 +1,7 @@
+*********
+Changelog
+*********
+
+1.x.x -- 2018-xx-xx
+===================
+* Initial public release

README.rst

@@ -0,0 +1,3 @@
+#####################################
+DynamoDB Encryption Client for Python
+#####################################

doc/conf.py

@@ -38,7 +38,7 @@ def get_version():
 extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',
               'sphinx.ext.intersphinx', 'sphinx.ext.todo',
               'sphinx.ext.coverage', 'sphinx.ext.autosummary',
-              'sphinx.ext.napoleon']
+              'sphinx.ext.napoleon', 'sphinx.ext.viewcode']
 napoleon_include_special_with_doc = False
 
 # Add any paths that contain templates here, relative to this directory.

doc/index.rst

@@ -1,53 +1,41 @@
 .. include:: ../README.rst
 
-*******
-Modules
-*******
-
-.. autosummary::
-    :toctree: generated
-
-    .. Add/replace module names you want documented here
-    dynamodb_encryption_sdk
-    dynamodb_encryption_sdk.exceptions
-    dynamodb_encryption_sdk.identifiers
-    dynamodb_encryption_sdk.structures
-    dynamodb_encryption_sdk.transform
-    dynamodb_encryption_sdk.delegated_keys
-    dynamodb_encryption_sdk.delegated_keys.jce
-    dynamodb_encryption_sdk.encrypted
-    dynamodb_encryption_sdk.encrypted.client
-    dynamodb_encryption_sdk.encrypted.item
-    dynamodb_encryption_sdk.encrypted.resource
-    dynamodb_encryption_sdk.encrypted.table
-    dynamodb_encryption_sdk.material_providers
-    dynamodb_encryption_sdk.material_providers.aws_kms
-    dynamodb_encryption_sdk.material_providers.most_recent
-    dynamodb_encryption_sdk.material_providers.static
-    dynamodb_encryption_sdk.material_providers.wrapped
-    dynamodb_encryption_sdk.material_providers.store
-    dynamodb_encryption_sdk.material_providers.store.meta
-    dynamodb_encryption_sdk.materials
-    dynamodb_encryption_sdk.materials.raw
-    dynamodb_encryption_sdk.materials.wrapped
-    dynamodb_encryption_sdk.internal
-    dynamodb_encryption_sdk.internal.dynamodb_types
-    dynamodb_encryption_sdk.internal.identifiers
-    dynamodb_encryption_sdk.internal.str_ops
-    dynamodb_encryption_sdk.internal.utils
-    dynamodb_encryption_sdk.internal.validators
-    dynamodb_encryption_sdk.internal.crypto
-    dynamodb_encryption_sdk.internal.crypto.authentication
-    dynamodb_encryption_sdk.internal.crypto.encryption
-    dynamodb_encryption_sdk.internal.crypto.jce_bridge
-    dynamodb_encryption_sdk.internal.crypto.jce_bridge.authentication
-    dynamodb_encryption_sdk.internal.crypto.jce_bridge.encryption
-    dynamodb_encryption_sdk.internal.crypto.jce_bridge.primitives
-    dynamodb_encryption_sdk.internal.formatting
-    dynamodb_encryption_sdk.internal.formatting.material_description
-    dynamodb_encryption_sdk.internal.formatting.deserialize
-    dynamodb_encryption_sdk.internal.formatting.deserialize.attribute
-    dynamodb_encryption_sdk.internal.formatting.serialize
-    dynamodb_encryption_sdk.internal.formatting.serialize.attribute
+API
+***
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Encryption Helpers
+
+   lib/encrypted/config.rst
+   lib/encrypted/helpers
+   lib/encrypted/item
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Key Management
+
+   lib/materials_providers/providers
+   lib/materials_providers/provider_stores
+   lib/materials/index
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Cryptographic Operators
+
+   lib/delegated_keys/index
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Additional Resources
+
+   lib/tools/index
+   lib/tools/exceptions
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Informational Only
+
+   lib/internal
 
 .. include:: ../CHANGELOG.rst

doc/lib/delegated_keys/index.rst

@@ -0,0 +1,11 @@
+Delegated Keys
+==============
+
+.. toctree::
+
+   jce
+
+.. autosummary::
+
+    dynamodb_encryption_sdk.delegated_keys
+    dynamodb_encryption_sdk.delegated_keys.jce

doc/lib/delegated_keys/jce.rst

@@ -0,0 +1,4 @@
+JCE Standard Name Delegated Key
+-------------------------------
+
+.. automodule:: dynamodb_encryption_sdk.delegated_keys.jce

doc/lib/encrypted/client.rst

@@ -0,0 +1,4 @@
+Encrypted Client
+----------------
+
+.. automodule:: dynamodb_encryption_sdk.encrypted.client

doc/lib/encrypted/config.rst

@@ -0,0 +1,4 @@
+Cryptographic Configuration
+---------------------------
+
+.. automodule:: dynamodb_encryption_sdk.encrypted

doc/lib/encrypted/helpers.rst

@@ -0,0 +1,14 @@
+Helper Clients
+==============
+
+.. toctree::
+
+   table
+   resource
+   client
+
+.. autosummary::
+
+    dynamodb_encryption_sdk.encrypted.table
+    dynamodb_encryption_sdk.encrypted.resource
+    dynamodb_encryption_sdk.encrypted.client

doc/lib/encrypted/item.rst

@@ -0,0 +1,4 @@
+Item Encryptor
+--------------
+
+.. automodule:: dynamodb_encryption_sdk.encrypted.item

doc/lib/encrypted/resource.rst

@@ -0,0 +1,4 @@
+Encrypted Service Resource
+--------------------------
+
+.. automodule:: dynamodb_encryption_sdk.encrypted.resource

doc/lib/encrypted/table.rst

@@ -0,0 +1,4 @@
+Encrypted Table Resource
+------------------------
+
+.. automodule:: dynamodb_encryption_sdk.encrypted.table

doc/lib/internal.rst

@@ -0,0 +1,28 @@
+Internal Resources
+==================
+
+.. warning::
+
+   These are provided for informational purposes only. No guarantee is provided on the modules
+   and APIs described here remaining consistent. Directly reference at your own risk.
+
+.. autosummary::
+   :toctree: generated
+
+    dynamodb_encryption_sdk.internal.identifiers
+    dynamodb_encryption_sdk.internal.str_ops
+    dynamodb_encryption_sdk.internal.utils
+    dynamodb_encryption_sdk.internal.validators
+    dynamodb_encryption_sdk.internal.crypto
+    dynamodb_encryption_sdk.internal.crypto.authentication
+    dynamodb_encryption_sdk.internal.crypto.encryption
+    dynamodb_encryption_sdk.internal.crypto.jce_bridge
+    dynamodb_encryption_sdk.internal.crypto.jce_bridge.authentication
+    dynamodb_encryption_sdk.internal.crypto.jce_bridge.encryption
+    dynamodb_encryption_sdk.internal.crypto.jce_bridge.primitives
+    dynamodb_encryption_sdk.internal.formatting
+    dynamodb_encryption_sdk.internal.formatting.material_description
+    dynamodb_encryption_sdk.internal.formatting.deserialize
+    dynamodb_encryption_sdk.internal.formatting.deserialize.attribute
+    dynamodb_encryption_sdk.internal.formatting.serialize
+    dynamodb_encryption_sdk.internal.formatting.serialize.attribute

doc/lib/materials/index.rst

@@ -0,0 +1,13 @@
+Cryptographic Materials
+-----------------------
+
+.. toctree::
+
+   wrapped
+   raw
+
+.. autosummary::
+
+    dynamodb_encryption_sdk.materials
+    dynamodb_encryption_sdk.materials.raw
+    dynamodb_encryption_sdk.materials.wrapped

doc/lib/materials/raw.rst

@@ -0,0 +1,4 @@
+Raw Cryptographic Materials
+---------------------------
+
+.. automodule:: dynamodb_encryption_sdk.materials.raw

doc/lib/materials/wrapped.rst

@@ -0,0 +1,4 @@
+Wrapped Cryptographic Materials
+-------------------------------
+
+.. automodule:: dynamodb_encryption_sdk.materials.wrapped

doc/lib/materials_providers/aws_kms.rst

@@ -0,0 +1,4 @@
+AWS KMS Provider
+----------------
+
+.. automodule:: dynamodb_encryption_sdk.material_providers.aws_kms

doc/lib/materials_providers/metastore.rst

@@ -0,0 +1,4 @@
+MetaStore
+---------
+
+.. automodule:: dynamodb_encryption_sdk.material_providers.store.meta

doc/lib/materials_providers/most_recent.rst

@@ -0,0 +1,4 @@
+Most Recent Provider
+--------------------
+
+.. automodule:: dynamodb_encryption_sdk.material_providers.most_recent

doc/lib/materials_providers/provider_stores.rst

@@ -0,0 +1,11 @@
+Provider Stores
+===============
+
+.. toctree::
+
+   metastore
+
+.. autosummary::
+
+    dynamodb_encryption_sdk.material_providers.store
+    dynamodb_encryption_sdk.material_providers.store.meta

doc/lib/materials_providers/providers.rst

@@ -0,0 +1,16 @@
+Cryptographic Materials Providers
+=================================
+
+.. toctree::
+
+   aws_kms
+   wrapped
+   most_recent
+   static
+
+.. autosummary::
+
+    dynamodb_encryption_sdk.material_providers
+    dynamodb_encryption_sdk.material_providers.wrapped
+    dynamodb_encryption_sdk.material_providers.most_recent
+    dynamodb_encryption_sdk.material_providers.static

doc/lib/materials_providers/static.rst

@@ -0,0 +1,4 @@
+Static Provider
+---------------
+
+.. automodule:: dynamodb_encryption_sdk.material_providers.static

doc/lib/materials_providers/wrapped.rst

@@ -0,0 +1,4 @@
+Wrapped Provider
+----------------
+
+.. automodule:: dynamodb_encryption_sdk.material_providers.wrapped

doc/lib/tools/exceptions.rst

@@ -0,0 +1,4 @@
+Exceptions
+----------
+
+.. automodule:: dynamodb_encryption_sdk.exceptions

doc/lib/tools/identifiers.rst

@@ -0,0 +1,4 @@
+Identifiers
+-----------
+
+.. automodule:: dynamodb_encryption_sdk.identifiers

doc/lib/tools/index.rst

@@ -0,0 +1,14 @@
+Tools
+=====
+
+.. toctree::
+
+   identifiers
+   structures
+   transform
+
+.. autosummary::
+
+    dynamodb_encryption_sdk.identifiers
+    dynamodb_encryption_sdk.structures
+    dynamodb_encryption_sdk.transform

doc/lib/tools/structures.rst

@@ -0,0 +1,4 @@
+Structures
+----------
+
+.. automodule:: dynamodb_encryption_sdk.structures

doc/lib/tools/transform.rst

@@ -0,0 +1,4 @@
+Transformers
+------------
+
+.. automodule:: dynamodb_encryption_sdk.transform

setup.py

@@ -1,4 +1,4 @@
-"""DynamoDB Encryption SDK."""
+"""DynamoDB Encryption Client for Python."""
 import io
 import os
 import re
@@ -31,12 +31,13 @@ def get_requirements():
     version=get_version(),
     packages=find_packages('src'),
     package_dir={'': 'src'},
-    url='http://dynamodb-encryption-sdk.readthedocs.io/en/latest/',
+    url='https://github.com/awslabs/aws-dynamodb-encryption-python',
     author='Amazon Web Services',
     author_email='[email protected]',
     maintainer='Amazon Web Services',
+    description='DynamoDB Encryption Client for Python',
     long_description=read('README.rst'),
-    keywords='aws-encryption-sdk aws kms encryption dynamodb',
+    keywords='dynamodb-encryption-sdk aws kms encryption dynamodb',
     data_files=[
         'README.rst',
         'CHANGELOG.rst',

src/dynamodb_encryption_sdk/delegated_keys/jce.py

@@ -10,7 +10,7 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-"""Delegated key that JCE StandardName algorithm values to determine behavior."""
+"""Delegated key that uses JCE StandardName values to determine behavior."""
 from __future__ import division
 
 import logging
@@ -76,7 +76,7 @@ def _generate_rsa_key(key_length):
 @attr.s(init=False)
 class JceNameLocalDelegatedKey(DelegatedKey):
     # pylint: disable=too-many-instance-attributes
-    """Delegated key that uses JCE StandardName algorithm values to determine behavior.
+    """Delegated key that uses JCE StandardName values to determine behavior.
 
     Accepted algorithm names for this include:
 

src/dynamodb_encryption_sdk/encrypted/__init__.py

@@ -32,7 +32,8 @@
 
 @attr.s(init=False)
 class CryptoConfig(object):
-    """Container for all configuration needed to encrypt or decrypt an item.
+    """Container for all configuration needed to encrypt or decrypt an item using the item
+    encryptor functions in :py:mod:`dynamodb_encryption_sdk.encrypted.item`.
 
     :param CryptographicMaterialsProvider materials_provider: Cryptographic materials provider
         to use

src/dynamodb_encryption_sdk/internal/crypto/__init__.py

@@ -10,4 +10,9 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-"""Inner cryptographic components."""
+"""Inner cryptographic components.
+
+.. warning::
+    No guarantee is provided on the modules and APIs within this
+    namespace staying consistent. Directly reference at your own risk.
+"""

src/dynamodb_encryption_sdk/internal/crypto/authentication.py

@@ -10,7 +10,12 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-"""Functions to handle calculating and verifying signatures of encrypted items."""
+"""Functions to handle calculating and verifying signatures of encrypted items.
+
+.. warning::
+    No guarantee is provided on the modules and APIs within this
+    namespace staying consistent. Directly reference at your own risk.
+"""
 from cryptography.hazmat.backends import default_backend
 from cryptography.hazmat.primitives import hashes