airship/deckhand
Code Issues Proposed changes

docs: Reorganize documentation structure

Browse Source 
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
This commit is contained in:
Felipe Monteiro 2018-09-21 22:15:38 -04:00
parent 243c2741bd
commit a8660a7e53
28 changed files with 301 additions and 239 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

55
README.rst
View File

@ -4,13 +4,18 @@ Deckhand
|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
.. |Doc Status| image:: https://readthedocs.io/projects/airship-deckhand/badge/?version=latest
:target: https://airship-deckhand.readthedocs.io/

5
doc/source/REVIEWING.rst
View File

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

2
doc/source/HACKING.rst → doc/source/developers/HACKING.rst
View File

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

20
doc/source/developers/REVIEWING.rst Normal file
View File

@ -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

6
doc/source/developer-overview.rst → doc/source/developers/developer-overview.rst
View File

@ -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
==========

34
doc/source/developers/index.rst Normal file
View File

@ -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`

2
doc/source/policy-enforcement.rst → doc/source/developers/policy-enforcement.rst
View File

@ -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

0
doc/source/testing.rst → doc/source/developers/testing.rst
View File

141
doc/source/exceptions.rst
View File

@ -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:

BIN
doc/source/images/architecture-pegleg.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 37 KiB

After

Width:  |  Height:  |  Size: 37 KiB

BIN
doc/source/images/architecture.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 23 KiB

After

Width:  |  Height:  |  Size: 23 KiB

41
doc/source/index.rst
View File

@ -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
========

0
doc/source/api_client.rst → doc/source/operators/api_client.rst
View File

0
doc/source/api_ref.rst → doc/source/operators/api_ref.rst
View File

111
doc/source/operators/exceptions.rst Normal file
View File

@ -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:

32
doc/source/operators/index.rst Normal file
View File

@ -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`

18
doc/source/overview.rst
View File

@ -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

0
doc/source/document-types.rst → doc/source/users/document-types.rst
View File

0
doc/source/documents.rst → doc/source/users/documents.rst
View File

0
doc/source/encryption.rst → doc/source/users/encryption.rst
View File

0
doc/source/getting-started.rst → doc/source/users/getting-started.rst
View File

39
doc/source/users/index.rst Normal file
View File

@ -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`

0
doc/source/layering.rst → doc/source/users/layering.rst
View File

0
doc/source/rendering.rst → doc/source/users/rendering.rst
View File

0
doc/source/replacement.rst → doc/source/users/replacement.rst
View File

0
doc/source/revision-history.rst → doc/source/users/revision-history.rst
View File

10
doc/source/substitution.rst → doc/source/users/substitution.rst
View File

@ -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::

24
doc/source/validation.rst → doc/source/users/validation.rst
View File

@ -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.