docs: Reorganize documentation structure

This patch set reorganizes Deckhand's documentation structure
for better organization into 3 distinct categories:

* developer's guide
* operator's guide
* user's guide

This means that the RTD navigation menu on the left-hand side
will have fewer links (see list above) making navigation much
easier. This is similar to how Armada organizes its documentation
too.

This patch set also updates README section with a better
overview and trims some fat from it (remove testing
documentation as it doesn't really belong there -- there
is a dedicated page for that already).

Finally, this patch set changes the exceptions page to
render as a basic list of autoexception classes because
the current tabularized view is not rendering correctly
on RTD [0].

[0] https://airship-deckhand.readthedocs.io/en/latest/exceptions.html
Change-Id: I162383bf8e3bbd5004603c979ac7b0d760a210c4

README.rst

@@ -4,13 +4,18 @@ Deckhand
 
 |Doc Status|
 
-Deckhand is a storage service for YAML-based configuration documents, which are
+Deckhand provides document revision management, storage and mutation
-managed through version control and automatically validated. Deckhand provides
+functionality upon which the rest of the `Airship`_ components rely for
-users with a variety of different document types that describe complex
+orchestration of infrastructure provisioning. Deckhand understands declarative
-configurations using the features listed below.
+YAML documents that define, end-to-end, the configuration of sites: from the
+hardware -- encompassing network topology and hardware and host profile
+information -- up to the software level that comprises the overcloud.
 
-Find more documentation for Deckhand on
+* Free software: Apache license
-`Read the Docs <https://airship-deckhand.readthedocs.io/>`_.
+* Documentation: https://airship-deckhand.readthedocs.io/en/latest/
+* Source: https://git.openstack.org/cgit/openstack/airship-deckhand
+* Bugs: https://storyboard.openstack.org/#!/project/1004
+* Release notes: https://airship-deckhand.readthedocs.io/en/latest/releasenotes/index.html
 
 Core Responsibilities
 =====================
@@ -37,40 +42,6 @@ For more detailed installation and setup information, please refer to the
 `Getting Started <https://airship-deckhand.readthedocs.io/en/latest/getting-started.html>`_
 guide.
 
-Testing
--------
-
-Automated Testing
-^^^^^^^^^^^^^^^^^
-
-To run unit tests using sqlite, execute:
-
-::
-
-    $ tox -epy27
-    $ tox -epy35
-
-against a py27- or py35-backed environment, respectively. To run individual
-unit tests, run:
-
-::
-
-    $ tox -e py27 -- deckhand.tests.unit.db.test_revisions
-
-for example.
-
-To run functional tests:
-
-::
-
-    $ tox -e functional
-
-You can also run a subset of tests via a regex:
-
-::
-
-    $ tox -e functional -- gabbi.suitemaker.test_gabbi_document-crud-success-multi-bucket
-
 Integration Points
 ==================
 
@@ -100,7 +71,9 @@ with it, including:
 Further Reading
 ===============
 
-`Airship <https://www.airshipit.org/>`_.
+`Airship`_.
+
+.. _Airship: https://www.airshipit.org
 
 .. |Doc Status| image:: https://readthedocs.io/projects/airship-deckhand/badge/?version=latest
    :target: https://airship-deckhand.readthedocs.io/

doc/source/REVIEWING.rst

@@ -1,5 +0,0 @@
-=======================
-Reviewing Deckhand Code
-=======================
-
-.. include:: ../../REVIEWING.rst

doc/source/developers/HACKING.rst

@@ -19,4 +19,4 @@
 Deckhand Coding Guide
 =====================
 
-.. include:: ../../HACKING.rst
+.. include:: ../../../HACKING.rst

doc/source/developers/REVIEWING.rst

@@ -0,0 +1,20 @@
+..
+    Copyright 2018 AT&T Intellectual Property.  All other rights reserved.
+
+    Licensed under the Apache License, Version 2.0 (the "License");
+    you may not use this file except in compliance with the License.
+    You may obtain a copy of the License at
+
+        http://www.apache.org/licenses/LICENSE-2.0
+
+    Unless required by applicable law or agreed to in writing, software
+    distributed under the License is 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.
+
+=======================
+Reviewing Deckhand Code
+=======================
+
+.. include:: ../../../REVIEWING.rst

doc/source/developers/developer-overview.rst

@@ -26,7 +26,7 @@ Airship components.
 Architecture
 ============
 
-.. image:: images/architecture.png
+.. image:: ../images/architecture.png
    :alt: High level architecture of Deckhand
 
 From a high-level perspective, Deckhand consists of a RESTful API, a document
@@ -41,8 +41,8 @@ Deckhand uses Barbican to securely storage sensitive document data.
 `Pegleg <https://airship-pegleg.readthedocs.io/>`_ in effect provides
 Deckhand with a CLI, which facilitates communication with Deckhand.
 
-.. image:: images/architecture-pegleg.png
+.. image:: ../images/architecture-pegleg.png
-   :alt: High level architecture of Deckhand
+   :alt: High level architecture of Deckhand + Pegleg
 
 Components
 ==========

doc/source/developers/index.rst

@@ -0,0 +1,34 @@
+..
+   Copyright 2018 AT&T Intellectual Property.
+   All Rights Reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License"); you may
+   not use this file except in compliance with the License. You may obtain
+   a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is 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.
+
+Developer's Guide
+=================
+
+.. toctree::
+   :maxdepth: 2
+
+   HACKING
+   REVIEWING
+   developer-overview
+   policy-enforcement
+   testing
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/developers/policy-enforcement.rst

@@ -51,4 +51,4 @@ Deckhand with the version of this documentation.
 
 The sample configuration can also be viewed in `file form <_static/deckhand.policy.yaml.sample>`_.
 
-.. literalinclude:: _static/deckhand.policy.yaml.sample
+.. literalinclude:: ../_static/deckhand.policy.yaml.sample

doc/source/exceptions.rst

@@ -1,141 +0,0 @@
-..
-  Copyright 2017 AT&T Intellectual Property.
-  All Rights Reserved.
-
-  Licensed under the Apache License, Version 2.0 (the "License"); you may
-  not use this file except in compliance with the License. You may obtain
-  a copy of the License at
-
-      http://www.apache.org/licenses/LICENSE-2.0
-
-  Unless required by applicable law or agreed to in writing, software
-  distributed under the License is 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.
-
-Deckhand Exceptions
-===================
-
-
-.. list-table::
-  :widths: 5 50
-  :header-rows: 1
-
-  * - Exception Name
-    - Description
-  * - BarbicanClientException
-    - .. autoexception:: deckhand.errors.BarbicanClientException
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - BarbicanServerException
-    - .. autoexception:: deckhand.errors.BarbicanServerException
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - DeepDiffException
-    - .. autoexception:: deckhand.errors.DeepDiffException
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - DocumentNotFound
-    - .. autoexception:: deckhand.errors.DocumentNotFound
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - DuplicateDocumentExists
-    - .. autoexception:: deckhand.errors.DuplicateDocumentExists
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - EncryptionSourceNotFound
-    - .. autoexception:: deckhand.errors.EncryptionSourceNotFound
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - InvalidDocumentFormat
-    - .. autoexception:: deckhand.errors.InvalidDocumentFormat
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - IndeterminateDocumentParent
-    - .. autoexception:: deckhand.errors.IndeterminateDocumentParent
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - InvalidInputException
-    - .. autoexception:: deckhand.errors.InvalidInputException
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - LayeringPolicyNotFound
-    - .. autoexception:: deckhand.errors.LayeringPolicyNotFound
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - MissingDocumentKey
-    - .. autoexception:: deckhand.errors.MissingDocumentKey
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - MissingDocumentPattern
-    - .. autoexception:: deckhand.errors.MissingDocumentPattern
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - PolicyNotAuthorized
-    - .. autoexception:: deckhand.errors.PolicyNotAuthorized
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - RevisionTagBadFormat
-    - .. autoexception:: deckhand.errors.RevisionTagBadFormat
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - RevisionTagNotFound
-    - .. autoexception:: deckhand.errors.RevisionTagNotFound
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - RevisionNotFound
-    - .. autoexception:: deckhand.errors.RevisionNotFound
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - SingletonDocumentConflict
-    - .. autoexception:: deckhand.errors.SingletonDocumentConflict
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - SubstitutionDependencyCycle
-    - .. autoexception:: deckhand.errors.SubstitutionDependencyCycle
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - SubstitutionSourceDataNotFound
-    - .. autoexception:: deckhand.errors.SubstitutionSourceDataNotFound
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - SubstitutionSourceNotFound
-    - .. autoexception:: deckhand.errors.SubstitutionSourceNotFound
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - UnknownSubstitutionError
-    - .. autoexception:: deckhand.errors.UnknownSubstitutionError
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - UnsupportedActionMethod
-    - .. autoexception:: deckhand.errors.UnsupportedActionMethod
-         :members:
-         :show-inheritance:
-         :undoc-members:
-  * - ValidationNotFound
-    - .. autoexception:: deckhand.errors.ValidationNotFound
-         :members:
-         :show-inheritance:
-         :undoc-members:

doc/source/index.rst

@@ -28,30 +28,25 @@ site configuration data, including sensitive data. Secrets can be stored using
 specialized secret storage management services like Barbican and later
 substituted into finalized or "rendered" documents.
 
-The service understands a variety of document formats, the combination of which
+The service understands a variety of document types, the combination of which
 describe the manner in which Deckhand renders finalized documents for
 consumption by other Airship services.
 
+Overview
+========
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+
 User's Guide
 ============
 
 .. toctree::
    :maxdepth: 2
 
-   getting-started
+   users/index
-   overview
-   revision-history
-   documents
-   document-types
-   encryption
-   validation
-   rendering
-   substitution
-   layering
-   replacement
-   api_ref
-   api_client
-   exceptions
 
 Developer's Guide
 =================
@@ -59,11 +54,15 @@ Developer's Guide
 .. toctree::
    :maxdepth: 2
 
-   HACKING
+   developers/index
-   REVIEWING
+
-   developer-overview
+Operator's Guide
-   policy-enforcement
+================
-   testing
+
+.. toctree::
+   :maxdepth: 2
+
+   operators/index
 
 Release Notes
 =============
@@ -71,7 +70,7 @@ Release Notes
 .. toctree::
    :maxdepth: 1
 
-   releasenotes/index.rst
+   releasenotes/index
 
 Glossary
 ========

doc/source/operators/exceptions.rst

@@ -0,0 +1,111 @@
+..
+  Copyright 2017 AT&T Intellectual Property.
+  All Rights Reserved.
+
+  Licensed under the Apache License, Version 2.0 (the "License"); you may
+  not use this file except in compliance with the License. You may obtain
+  a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is 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.
+
+Deckhand Exceptions
+===================
+
+.. autoexception:: deckhand.errors.BarbicanClientException
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.BarbicanServerException
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.DeepDiffException
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.DocumentNotFound
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.DuplicateDocumentExists
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.EncryptionSourceNotFound
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.InvalidDocumentFormat
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.IndeterminateDocumentParent
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.InvalidInputException
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.LayeringPolicyNotFound
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.MissingDocumentKey
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.MissingDocumentPattern
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.PolicyNotAuthorized
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.RevisionTagBadFormat
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.RevisionTagNotFound
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.RevisionNotFound
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.SingletonDocumentConflict
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.SubstitutionDependencyCycle
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.SubstitutionSourceDataNotFound
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.SubstitutionSourceNotFound
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.UnknownSubstitutionError
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.UnsupportedActionMethod
+   :members:
+   :show-inheritance:
+   :undoc-members:
+.. autoexception:: deckhand.errors.ValidationNotFound
+   :members:
+   :show-inheritance:
+   :undoc-members:

doc/source/operators/index.rst

@@ -0,0 +1,32 @@
+..
+   Copyright 2018 AT&T Intellectual Property.
+   All Rights Reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License"); you may
+   not use this file except in compliance with the License. You may obtain
+   a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is 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.
+
+Operator's Guide
+================
+
+.. toctree::
+   :maxdepth: 2
+
+   api_ref
+   api_client
+   exceptions
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/overview.rst

@@ -17,17 +17,17 @@
 Overview
 ========
 
-Deckhand is a storage service for YAML-based configuration documents. Deckhand
+Deckhand provides document revision management, storage and mutation
-stores the documents using version control: Each time a collection of documents
+functionality upon which the rest of the `Airship`_ components rely for
-is passed to Deckhand, a new revision is created. Thus, documents have a
+orchestration of infrastructure provisioning. Deckhand understands declarative
-revision history, allowing complex configurations to be incrementally modified
+YAML documents that define, end-to-end, the configuration of sites: from the
-and validated. For example, if the first revision of documents fail validation,
+hardware -- encompassing network topology and hardware and host profile
-deployers can make modifications to the documents and submit them to Deckhand
+information -- up to the software level that comprises the overcloud.
-again, until the documents pass validation and are ready to be rendered into
+
-their finalized state.
+.. _Airship: https://www.airshipit.org
 
 Core Responsibilities
-=====================
+---------------------
 
 * *revision history* - improves auditability and enables services to provide
   functional validation of a well-defined collection of documents that are

doc/source/users/index.rst

@@ -0,0 +1,39 @@
+..
+   Copyright 2018 AT&T Intellectual Property.
+   All Rights Reserved.
+
+   Licensed under the Apache License, Version 2.0 (the "License"); you may
+   not use this file except in compliance with the License. You may obtain
+   a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is 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.
+
+User's Guide
+============
+
+.. toctree::
+   :maxdepth: 2
+
+   getting-started
+   revision-history
+   documents
+   document-types
+   encryption
+   validation
+   rendering
+   substitution
+   layering
+   replacement
+
+Indices and tables
+------------------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

doc/source/users/substitution.rst

@@ -271,11 +271,11 @@ document) will be:
 Recursive Replacement of Patterns
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Patterns may also be replaced recursively. This can be achieved by using
+Patterns may also be replaced recursively. This can be achieved by specifying
-specifying a ``pattern`` value and ``recurse`` as ``True`` (it otherwise
+a ``pattern`` value and ``recurse`` as ``True`` (it otherwise defaults to
-defaults to ``False``). Best practice is to limit the scope of the recursion
+``False``). Best practice is to limit the scope of the recursion as much as
-as much as possible: e.g. avoid passing in "$" as the ``jsonpath``, but rather
+possible: e.g. avoid passing in "$" as the ``jsonpath``, but rather a JSON path
-a JSON path that lives closer to the nested strings in question.
+that lives closer to the nested strings in question.
 
 .. note::
 

doc/source/users/validation.rst

@@ -210,7 +210,7 @@ Base Schema
 
   Base JSON schema against which all Deckhand documents are validated.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/base_schema.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/base_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Base schema that applies to all documents.
@@ -231,7 +231,7 @@ ingested by Deckhand.
   configure Deckhand behavior, like LayeringPolicy, ValidationPolicy,
   and DataSchema documents.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/metadata_control.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/metadata_control.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``metadata/Control`` metadata document sections.
@@ -242,7 +242,7 @@ ingested by Deckhand.
   document type is validated. Applies to all site definition documents or
   "regular" documents that require rendering.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/metadata_document.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/metadata_document.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``metadata/Document`` metadata document sections.
@@ -270,7 +270,7 @@ corresponding to the created revision.
   ``deckhand/CertificateAuthorityKey/v1`` schema are validated.
 
   .. literalinclude::
-    ../../deckhand/engine/schemas/certificate_authority_key_schema.yaml
+    ../../../deckhand/engine/schemas/certificate_authority_key_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``CertificateAuthorityKey`` documents.
@@ -284,7 +284,7 @@ corresponding to the created revision.
   ``deckhand/CertificateAuthority/v1`` schema are validated.
 
   .. literalinclude::
-    ../../deckhand/engine/schemas/certificate_authority_schema.yaml
+    ../../../deckhand/engine/schemas/certificate_authority_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``CertificateAuthority`` documents.
@@ -297,7 +297,7 @@ corresponding to the created revision.
   JSON schema against which all documents with ``deckhand/CertificateKey/v1``
   schema are validated.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/certificate_key_schema.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/certificate_key_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``CertificateKey`` documents.
@@ -310,7 +310,7 @@ corresponding to the created revision.
   JSON schema against which all documents with ``deckhand/Certificate/v1``
   schema are validated.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/certificate_schema.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/certificate_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``Certificate`` documents.
@@ -323,7 +323,7 @@ corresponding to the created revision.
   JSON schema against which all documents with ``deckhand/LayeringPolicy/v1``
   schema are validated.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/layering_policy_schema.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/layering_policy_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``LayeringPolicy`` documents.
@@ -336,7 +336,7 @@ corresponding to the created revision.
   JSON schema against which all documents with ``deckhand/PrivateKey/v1``
   schema are validated.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/passphrase_schema.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/passphrase_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``PrivateKey`` documents.
@@ -349,7 +349,7 @@ corresponding to the created revision.
   JSON schema against which all documents with ``deckhand/PublicKey/v1``
   schema are validated.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/public_key_schema.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/public_key_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``PublicKey`` documents.
@@ -362,7 +362,7 @@ corresponding to the created revision.
   JSON schema against which all documents with ``deckhand/Passphrase/v1``
   schema are validated.
 
-  .. literalinclude:: ../../deckhand/engine/schemas/private_key_schema.yaml
+  .. literalinclude:: ../../../deckhand/engine/schemas/private_key_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``Passphrase`` documents.
@@ -376,7 +376,7 @@ corresponding to the created revision.
   schema are validated.
 
   .. literalinclude::
-    ../../deckhand/engine/schemas/validation_policy_schema.yaml
+    ../../../deckhand/engine/schemas/validation_policy_schema.yaml
     :language: yaml
     :lines: 15-
     :caption: Schema for ``ValidationPolicy`` documents.