Felipe Monteiro a8660a7e53 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

2018-09-26 20:29:02 -04:00

2.7 KiB

Raw Blame History

Revision History

Documents will be ingested in batches which will be given a revision index. This provides a common language for describing complex validations on sets of documents.

Revisions can be thought of as commits in a linear git history, thus looking at a revision includes all content from previous revisions.

Revision Diffing

By maintaining a linear history of all the documents in each revision, Deckhand is able to diff different revisions together to report what has changed across revisions, allowing external services to determine whether the Deckhand configuration undergone any changes since the service last queried the Deckhand API.

The revision difference is calculated by comparing the overall difference across all the documents in the buckets associated with the two revisions that are diffed. For example, if a bucket shared between two revisions contains two documents, and between the first revision and the second revision, if only one of those two documents has been modified, the bucket itself is tagged as modified. For more information about revision diffing, please reference the api-ref.

Revision DeepDiffing

Revision DeepDiffing is an extended version of existing revision diff api. When any bucket state gets changed to modified, It shows deep difference between revisions. DeepDiffing resultset will consist of document_added, document_deleted and document_changed count and details. For more information about revision deepdiffing, please reference the api-ref.

Revision Rollback

As all the changes to documents are maintained via revisions, it is possible to rollback the latest revision in Deckhand to a prior revision. This behavior can be loosely compared to a git rebase in which it is possible to squash the latest revision in order to go back to the previous revision. This behavior is useful for undoing accidental changes and returning to a stable internal configuration.

2.7 KiB Raw Blame History

Revision History