From a8660a7e5371293866a4ac622a93e932f527606c Mon Sep 17 00:00:00 2001 From: Felipe Monteiro Date: Fri, 21 Sep 2018 22:15:38 -0400 Subject: [PATCH] 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 | 55 ++----- doc/source/REVIEWING.rst | 5 - doc/source/{ => developers}/HACKING.rst | 2 +- doc/source/developers/REVIEWING.rst | 20 +++ .../{ => developers}/developer-overview.rst | 6 +- doc/source/developers/index.rst | 34 +++++ .../{ => developers}/policy-enforcement.rst | 2 +- doc/source/{ => developers}/testing.rst | 0 doc/source/exceptions.rst | 141 ------------------ doc/source/images/architecture-pegleg.png | Bin 37597 -> 37598 bytes doc/source/images/architecture.png | Bin 23226 -> 23227 bytes doc/source/index.rst | 41 +++-- doc/source/{ => operators}/api_client.rst | 0 doc/source/{ => operators}/api_ref.rst | 0 doc/source/operators/exceptions.rst | 111 ++++++++++++++ doc/source/operators/index.rst | 32 ++++ doc/source/overview.rst | 18 +-- doc/source/{ => users}/document-types.rst | 0 doc/source/{ => users}/documents.rst | 0 doc/source/{ => users}/encryption.rst | 0 doc/source/{ => users}/getting-started.rst | 0 doc/source/users/index.rst | 39 +++++ doc/source/{ => users}/layering.rst | 0 doc/source/{ => users}/rendering.rst | 0 doc/source/{ => users}/replacement.rst | 0 doc/source/{ => users}/revision-history.rst | 0 doc/source/{ => users}/substitution.rst | 10 +- doc/source/{ => users}/validation.rst | 24 +-- 28 files changed, 301 insertions(+), 239 deletions(-) delete mode 100644 doc/source/REVIEWING.rst rename doc/source/{ => developers}/HACKING.rst (95%) create mode 100644 doc/source/developers/REVIEWING.rst rename doc/source/{ => developers}/developer-overview.rst (97%) create mode 100644 doc/source/developers/index.rst rename doc/source/{ => developers}/policy-enforcement.rst (97%) rename doc/source/{ => developers}/testing.rst (100%) delete mode 100644 doc/source/exceptions.rst rename doc/source/{ => operators}/api_client.rst (100%) rename doc/source/{ => operators}/api_ref.rst (100%) create mode 100644 doc/source/operators/exceptions.rst create mode 100644 doc/source/operators/index.rst rename doc/source/{ => users}/document-types.rst (100%) rename doc/source/{ => users}/documents.rst (100%) rename doc/source/{ => users}/encryption.rst (100%) rename doc/source/{ => users}/getting-started.rst (100%) create mode 100644 doc/source/users/index.rst rename doc/source/{ => users}/layering.rst (100%) rename doc/source/{ => users}/rendering.rst (100%) rename doc/source/{ => users}/replacement.rst (100%) rename doc/source/{ => users}/revision-history.rst (100%) rename doc/source/{ => users}/substitution.rst (97%) rename doc/source/{ => users}/validation.rst (93%) diff --git a/README.rst b/README.rst index 4101559a..460121aa 100644 --- a/README.rst +++ b/README.rst @@ -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 `_. +* 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 `_ 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 `_. +`Airship`_. + +.. _Airship: https://www.airshipit.org .. |Doc Status| image:: https://readthedocs.io/projects/airship-deckhand/badge/?version=latest :target: https://airship-deckhand.readthedocs.io/ diff --git a/doc/source/REVIEWING.rst b/doc/source/REVIEWING.rst deleted file mode 100644 index 6d84d41e..00000000 --- a/doc/source/REVIEWING.rst +++ /dev/null @@ -1,5 +0,0 @@ -======================= -Reviewing Deckhand Code -======================= - -.. include:: ../../REVIEWING.rst diff --git a/doc/source/HACKING.rst b/doc/source/developers/HACKING.rst similarity index 95% rename from doc/source/HACKING.rst rename to doc/source/developers/HACKING.rst index 53d3411c..93a7710b 100644 --- a/doc/source/HACKING.rst +++ b/doc/source/developers/HACKING.rst @@ -19,4 +19,4 @@ Deckhand Coding Guide ===================== -.. include:: ../../HACKING.rst +.. include:: ../../../HACKING.rst diff --git a/doc/source/developers/REVIEWING.rst b/doc/source/developers/REVIEWING.rst new file mode 100644 index 00000000..4d1b00fc --- /dev/null +++ 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 diff --git a/doc/source/developer-overview.rst b/doc/source/developers/developer-overview.rst similarity index 97% rename from doc/source/developer-overview.rst rename to doc/source/developers/developer-overview.rst index 079d813c..718ec622 100644 --- a/doc/source/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 `_ 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 ========== diff --git a/doc/source/developers/index.rst b/doc/source/developers/index.rst new file mode 100644 index 00000000..37304de9 --- /dev/null +++ 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` diff --git a/doc/source/policy-enforcement.rst b/doc/source/developers/policy-enforcement.rst similarity index 97% rename from doc/source/policy-enforcement.rst rename to doc/source/developers/policy-enforcement.rst index 120854db..b9e21d9a 100644 --- a/doc/source/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 diff --git a/doc/source/testing.rst b/doc/source/developers/testing.rst similarity index 100% rename from doc/source/testing.rst rename to doc/source/developers/testing.rst diff --git a/doc/source/exceptions.rst b/doc/source/exceptions.rst deleted file mode 100644 index ce49eee5..00000000 --- a/doc/source/exceptions.rst +++ /dev/null @@ -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: diff --git a/doc/source/images/architecture-pegleg.png b/doc/source/images/architecture-pegleg.png index 173c7aef4cac90ce225f918cf1db61a4b57ab89a..f35812da5a7c19578fb37279499b61a643b9812c 100644 GIT binary patch delta 529 zcmV+s0`C3Yr2^ii0+3mM_IgxUbZ~58Zgh2RYybdwoNZEFYuhjseHZvYT>O+g*wkg& zN*+SV$NDjcWpk1}givJb))ld(Aj@gP*ni(uY^Ny{fzbUpN9P{twzAyVx-2~A7SF6U z;7@11$52^mkKo@gmy3%q`4wM8f0DZg-yxq3FOiU#?OwPNKK%867{F$tl{LE9LKu!< zGgG-#xb@h-3&;ZV0`m^gL@eX5skS?WyV!YlVE1h zLPGN)j0qB;65CVf4?I>@zmp4YdCDs%O;=>!36L_6h^NIQ^o$(3s72qoJC z1i|S22AE4B3Vh{%#$EPl`UG%LkGb7Zb{-O?@4O_h(x$S?kma;tn17!u+euR>0-^gjN9P{trn21Fx-2~A7SF6U z;7_K$$52^m58&S|7W1<(d5q7ZKgsRA?~pHsmqJea3u9gGv?5j2k!ZwCDl@J+nglb0 z7805dVMLGsmDn_$zwl65{Xs6c`LL2O=dWtX!U_Gl`p6@-J! zi|~37hACPe_Lgd^^qYc=UP~4TR+iXjz1w*Vm99;OAY^5KjZAAx=stVkdk#;va(xlF zsJEE)A(z+Y`FNo<-|1DXRM4J8MJ8 zp|WJ{e7rYr-rUu!9XC}ODE}d`;Uk2Pi^V*=gz5L`yXa^7@Fn!!FHTno;XUTNUz&;# z{sanOJ+{QomK%uUTUbwMYX~=i`uh&@ZI6_)&UY}j)!vd&*Jt=hyUgU8e@^%mbB7Em zTZb?bNQ6{u+Rm?dtl3`33(Y#yweZhv&0B|FcgHF(h+tiuq&^qf8RS>>rN*x%$KY0-Fl^s`oITLTwwDBNV1)XR?L`-d9ih zpy5YDzHbOV>Mdq{NGIncOz2>orAkhso>sH22_7w{d&_O}#}CoS$VJeJDp<`r(p9H$ zC=x%#SI^gjC`$%P4(&7>+CnOpVKs!Qq2{-`#~0m{EYosZNO=g$9>wSAMol$s8@&~6 bNNQ|FlRHW+RsR6LI@9FrVaBer76PPL$WYs* delta 432 zcmV;h0Z;zBwE?=d0gzb%w2@jOe`zBQQ3Rn$Q&4FP^ng&bwkLFjJ&V?3QdIT7ch-iG zLuAR?`FL;Myt%DeJ8r5nQ2s+=!v_c-=JQ#24%45LchRr({#)p~U!1NG!aK~jzcm#h z{0$VqYGjF>E!PmoH?SJh#t^Op_3s_z#||lFoo``etDPmGu21lxcA3dFe;x5D<_;NB zwhmz^kO-+*x1HbdP_sRg7n*gZYvG^Snl}!;?v7Pn5W%WAN_{S}6UeXXOO0PklE()` z(am`ROifXg_^O>B_F=jOcxa&f-&3B95X8}ij#b3?+?!8r@@?%v-O7gTNz|;=#EaXjRN-m-vm(#8Z9xSIj%Wd=LPtnlGLC}dPSWY|AWhZbT z3cth`&zDzGmRu>hv(s#71F1NM)c_`jnm_6eUvyKlOv`N{