[docs] Document schemas used for document validation

This PS adds documentation for all the document schemas that are
used for ``deckhand-schema-validation`` validations. This will
help users to know what their schemas need to look like for
Deckhand to accept them.

The documentation like most of it is generated automically via sphinx.
A docstring was provided under each module schema variable and
included inside __all__ because according to docs [0]:
"For modules, __all__ will be respected when looking for members;
the order of the members will also be the order in __all__."

[0] http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-automodule

Change-Id: I224f3980dcf877bab400aa505728a332e67709cc

AUTHORS

@@ -9,3 +9,4 @@ Mike Kochetov <mike.nycmoma@gmail.com>
 Pete Birley <pete@port.direct>
 Scott Hussey <sh8121@att.com>
 Tin Lam <tin@irrational.io>
+portdirect <pete@port.direct>

deckhand/engine/schema/base_schema.py

@@ -34,3 +34,14 @@ schema = {
     'additionalProperties': False,
     'required': ['schema', 'metadata']
 }
+"""Base JSON schema against which all Deckhand documents are validated.
+
+.. literalinclude:: ../../deckhand/engine/schema/base_schema.py
+   :language: python
+   :lines: 15-36
+
+This schema is used to sanity-check all documents that are passed to Deckhand.
+Failure to pass this schema results in a critical error.
+"""
+
+__all__ = ['schema']

deckhand/engine/schema/v1_0/certificate_key_schema.py

@@ -47,3 +47,18 @@ schema = {
     'additionalProperties': False,
     'required': ['schema', 'metadata', 'data']
 }
+"""JSON schema against which all documents with ``deckhand/CertificateKey/v1``
+``schema`` are validated.
+
+.. literalinclude:: ../../deckhand/engine/schema/v1_0/certificate_key_schema.py
+   :language: python
+   :lines: 15-49
+
+This schema is used to sanity-check all CertificateKey documents that are
+passed to Deckhand. This schema is only enforced after validation for
+:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass
+this schema will result in an error entry being created for the validation
+with name ``deckhand-schema-validation`` corresponding to the created revision.
+"""
+
+__all__ = ['schema']

deckhand/engine/schema/v1_0/certificate_schema.py

@@ -47,3 +47,18 @@ schema = {
     'additionalProperties': False,
     'required': ['schema', 'metadata', 'data']
 }
+"""JSON schema against which all documents with ``deckhand/Certificate/v1``
+``schema`` are validated.
+
+.. literalinclude:: ../../deckhand/engine/schema/v1_0/certificate_schema.py
+   :language: python
+   :lines: 15-49
+
+This schema is used to sanity-check all Certificate documents that are
+passed to Deckhand. This schema is only enforced after validation for
+:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass
+this schema will result in an error entry being created for the validation
+with name ``deckhand-schema-validation`` corresponding to the created revision.
+"""
+
+__all__ = ['schema']

deckhand/engine/schema/v1_0/data_schema_schema.py

@@ -60,3 +60,18 @@ schema = {
     'additionalProperties': False,
     'required': ['schema', 'metadata', 'data']
 }
+"""JSON schema against which all documents with ``deckhand/DataSchema/v1``
+``schema`` are validated.
+
+.. literalinclude:: ../../deckhand/engine/schema/v1_0/data_schema_schema.py
+   :language: python
+   :lines: 15-62
+
+This schema is used to sanity-check all DataSchema documents that are
+passed to Deckhand. This schema is only enforced after validation for
+:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass
+this schema will result in an error entry being created for the validation
+with name ``deckhand-schema-validation`` corresponding to the created revision.
+"""
+
+__all__ = ['schema']

deckhand/engine/schema/v1_0/document_schema.py

@@ -100,3 +100,21 @@ schema = {
     'additionalProperties': False,
     'required': ['schema', 'metadata', 'data']
 }
+"""JSON schema against which all documents with ``metadata/Document/v1``
+``metadata.schema`` are validated.
+
+.. literalinclude:: ../../deckhand/engine/schema/v1_0/document_schema.py
+   :language: python
+   :lines: 15-102
+
+This schema is used to sanity-check all "metadata/Document" documents that are
+passed to Deckhand. This validation comes into play when a new schema is
+registered under the ``data`` section of a ``deckhand/DataSchema/v1`` document.
+
+This schema is only enforced after validation for
+:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass
+this schema will result in an error entry being created for the validation
+with name ``deckhand-schema-validation`` corresponding to the created revision.
+"""
+
+__all__ = ['schema']

deckhand/engine/schema/v1_0/layering_policy_schema.py

@@ -50,3 +50,18 @@ schema = {
     'additionalProperties': False,
     'required': ['schema', 'metadata', 'data']
 }
+"""JSON schema against which all documents with ``deckhand/LayeringPolicy/v1``
+``schema`` are validated.
+
+.. literalinclude:: ../../deckhand/engine/schema/v1_0/layering_policy_schema.py
+   :language: python
+   :lines: 15-52
+
+This schema is used to sanity-check all LayeringPolicy documents that are
+passed to Deckhand. This schema is only enforced after validation for
+:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass
+this schema will result in an error entry being created for the validation
+with name ``deckhand-schema-validation`` corresponding to the created revision.
+"""
+
+__all__ = ['schema']

deckhand/engine/schema/v1_0/passphrase_schema.py

@@ -47,3 +47,18 @@ schema = {
     'additionalProperties': False,
     'required': ['schema', 'metadata', 'data']
 }
+"""JSON schema against which all documents with ``deckhand/Passphrase/v1``
+``schema`` are validated.
+
+.. literalinclude:: ../../deckhand/engine/schema/v1_0/passphrase_schema.py
+   :language: python
+   :lines: 15-49
+
+This schema is used to sanity-check all Passphrase documents that are
+passed to Deckhand. This schema is only enforced after validation for
+:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass
+this schema will result in an error entry being created for the validation
+with name ``deckhand-schema-validation`` corresponding to the created revision.
+"""
+
+__all__ = ['schema']

deckhand/engine/schema/v1_0/validation_policy_schema.py

@@ -62,3 +62,19 @@ schema = {
     'additionalProperties': False,
     'required': ['schema', 'metadata', 'data']
 }
+"""JSON schema against which all documents with
+``deckhand/ValidationPolicy/v1`` ``schema`` are validated.
+
+.. literalinclude::
+   ../../deckhand/engine/schema/v1_0/validation_policy_schema.py
+   :language: python
+   :lines: 15-64
+
+This schema is used to sanity-check all ValidationPolicy documents that are
+passed to Deckhand. This schema is only enforced after validation for
+:py:data:`~deckhand.engine.schema.base_schema` has passed. Failure to pass
+this schema will result in an error entry being created for the validation
+with name ``deckhand-schema-validation`` corresponding to the created revision.
+"""
+
+__all__ = ['schema']

doc/source/validation.rst

@@ -112,3 +112,31 @@ Validation Module
 .. autoclass:: deckhand.engine.document_validation.DocumentValidation
    :members:
    :private-members:
+
+.. _schemas:
+
+Validation Schemas
+==================
+
+Below are the schemas deckhand uses to validate documents.
+
+.. automodule:: deckhand.engine.schema.base_schema
+  :members: schema
+
+.. automodule:: deckhand.engine.schema.v1_0.certificate_key_schema
+  :members: schema
+
+.. automodule:: deckhand.engine.schema.v1_0.certificate_schema
+  :members: schema
+
+.. automodule:: deckhand.engine.schema.v1_0.data_schema_schema
+  :members: schema
+
+.. automodule:: deckhand.engine.schema.v1_0.layering_policy_schema
+  :members: schema
+
+.. automodule:: deckhand.engine.schema.v1_0.passphrase_schema
+  :members: schema
+
+.. automodule:: deckhand.engine.schema.v1_0.validation_policy_schema
+  :members: schema