Merge "docs: Reorganize documentation structure"

2018-10-05 20:49:07 +00:00 · 2018-10-05 20:49:07 +00:00 · fd768bc163
parent ad376dd3b3 a8660a7e53
commit fd768bc163
28 changed files with 301 additions and 239 deletions
--- a/README.rst
+++ b/README.rst
@ -4,13 +4,18 @@ Deckhand

 |Docker Repository on Quay| |Doc Status|

-Deckhand is a storage service for YAML-based configuration documents, which are
-managed through version control and automatically validated. Deckhand provides
-users with a variety of different document types that describe complex
-configurations using the features listed below.
+Deckhand provides document revision management, storage and mutation
+functionality upon which the rest of the `Airship`_ components rely for
+orchestration of infrastructure provisioning. Deckhand understands declarative
+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
-`Read the Docs <https://airship-deckhand.readthedocs.io/>`_.
+* Free software: Apache license
+* 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

 .. |Docker Repository on Quay| image:: https://quay.io/repository/airshipit/deckhand/status
   :target: https://quay.io/repository/airshipit/deckhand
--- a/doc/source/REVIEWING.rst
+++ b/doc/source/REVIEWING.rst
@ -1,5 +0,0 @@
-=======================
-Reviewing Deckhand Code
-=======================
-
-.. include:: ../../REVIEWING.rst
--- a/doc/source/developers/HACKING.rst
+++ b/doc/source/developers/HACKING.rst
@ -19,4 +19,4 @@
 Deckhand Coding Guide
 =====================

-.. include:: ../../HACKING.rst
+.. include:: ../../../HACKING.rst
--- a/doc/source/developers/REVIEWING.rst
+++ b/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
--- a/doc/source/developers/developer-overview.rst
+++ b/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
-   :alt: High level architecture of Deckhand
+.. image:: ../images/architecture-pegleg.png
+   :alt: High level architecture of Deckhand + Pegleg

 Components
 ==========
--- a/doc/source/developers/index.rst
+++ b/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`
--- a/doc/source/developers/policy-enforcement.rst
+++ b/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
--- a/doc/source/developers/testing.rst
+++ b/doc/source/developers/testing.rst
--- a/doc/source/exceptions.rst
+++ b/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:
--- a/doc/source/images/architecture-pegleg.png
+++ b/doc/source/images/architecture-pegleg.png
--- a/doc/source/images/architecture.png
+++ b/doc/source/images/architecture.png
--- a/doc/source/index.rst
+++ b/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
-   overview
-   revision-history
-   documents
-   document-types
-   encryption
-   validation
-   rendering
-   substitution
-   layering
-   replacement
-   api_ref
-   api_client
-   exceptions
+   users/index

 Developer's Guide
 =================
@ -59,11 +54,15 @@ Developer's Guide
 .. toctree::
   :maxdepth: 2

-   HACKING
-   REVIEWING
-   developer-overview
-   policy-enforcement
-   testing
+   developers/index
+
+Operator's Guide
+================
+
+.. toctree::
+   :maxdepth: 2
+
+   operators/index

 Release Notes
 =============
@ -71,7 +70,7 @@ Release Notes
 .. toctree::
   :maxdepth: 1

-   releasenotes/index.rst
+   releasenotes/index

 Glossary
 ========
--- a/doc/source/operators/api_client.rst
+++ b/doc/source/operators/api_client.rst
--- a/doc/source/operators/api_ref.rst
+++ b/doc/source/operators/api_ref.rst
--- a/doc/source/operators/exceptions.rst
+++ b/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:
--- a/doc/source/operators/index.rst
+++ b/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`
--- a/doc/source/overview.rst
+++ b/doc/source/overview.rst
@ -17,17 +17,17 @@
 Overview
 ========

-Deckhand is a storage service for YAML-based configuration documents. Deckhand
-stores the documents using version control: Each time a collection of documents
-is passed to Deckhand, a new revision is created. Thus, documents have a
-revision history, allowing complex configurations to be incrementally modified
-and validated. For example, if the first revision of documents fail validation,
-deployers can make modifications to the documents and submit them to Deckhand
-again, until the documents pass validation and are ready to be rendered into
-their finalized state.
+Deckhand provides document revision management, storage and mutation
+functionality upon which the rest of the `Airship`_ components rely for
+orchestration of infrastructure provisioning. Deckhand understands declarative
+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.
+
+.. _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
--- a/doc/source/users/document-types.rst
+++ b/doc/source/users/document-types.rst
--- a/doc/source/users/documents.rst
+++ b/doc/source/users/documents.rst
--- a/doc/source/users/encryption.rst
+++ b/doc/source/users/encryption.rst
--- a/doc/source/users/getting-started.rst
+++ b/doc/source/users/getting-started.rst
--- a/doc/source/users/index.rst
+++ b/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`
--- a/doc/source/users/layering.rst
+++ b/doc/source/users/layering.rst
--- a/doc/source/users/rendering.rst
+++ b/doc/source/users/rendering.rst
--- a/doc/source/users/replacement.rst
+++ b/doc/source/users/replacement.rst
--- a/doc/source/users/revision-history.rst
+++ b/doc/source/users/revision-history.rst
--- a/doc/source/users/substitution.rst
+++ b/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
-specifying a ``pattern`` value and ``recurse`` as ``True`` (it otherwise
-defaults to ``False``). Best practice is to limit the scope of the recursion
-as much as possible: e.g. avoid passing in "$" as the ``jsonpath``, but rather
-a JSON path that lives closer to the nested strings in question.
+Patterns may also be replaced recursively. This can be achieved by specifying
+a ``pattern`` value and ``recurse`` as ``True`` (it otherwise defaults to
+``False``). Best practice is to limit the scope of the recursion as much as
+possible: e.g. avoid passing in "$" as the ``jsonpath``, but rather a JSON path
+that lives closer to the nested strings in question.

 .. note::

--- a/doc/source/users/validation.rst
+++ b/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.