diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..d3132a5 --- /dev/null +++ b/README.rst @@ -0,0 +1,18 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +.. airship-specs-readme: + +==================================== +Building Airship Specs Documentation +==================================== + +Using the equivalent of `pip install sphinx`, install the sphinx-build command +if it is not already installed. + +From the root of this project, issue the command `make html`. +Sphinx will render the output into doc/build/html. Open +doc/build/html/index.html using your browser. diff --git a/doc/source/index.rst b/doc/source/index.rst index 213ab7c..618f93f 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,8 +6,10 @@ Airship Specs Documentation =========================== -Proposed Specs --------------- +:ref:`genindex` + +About Specs +----------- .. toctree:: :maxdepth: 1 @@ -32,4 +34,3 @@ Implemented Specs :glob: specs/implemented/* - diff --git a/specs/approved/_placeholder.rst b/specs/approved/_placeholder.rst new file mode 100644 index 0000000..0cd761b --- /dev/null +++ b/specs/approved/_placeholder.rst @@ -0,0 +1,8 @@ +.. placeholder: + +=========== +Placeholder +=========== + +This file is a placeholder and should be deleted when the first spec is moved +to this directory. diff --git a/specs/implemented/_placeholder.rst b/specs/implemented/_placeholder.rst new file mode 100644 index 0000000..0cd761b --- /dev/null +++ b/specs/implemented/_placeholder.rst @@ -0,0 +1,8 @@ +.. placeholder: + +=========== +Placeholder +=========== + +This file is a placeholder and should be deleted when the first spec is moved +to this directory. diff --git a/specs/instructions.rst b/specs/instructions.rst new file mode 100644 index 0000000..d86e9ef --- /dev/null +++ b/specs/instructions.rst @@ -0,0 +1,96 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +.. index:: + single: instructions + single: getting started + +.. _instructions: + +============ +Instructions +============ + +- Use the template.rst as the basis of your specification. +- Attempt to detail each applicable section. +- If a section does not apply, use N/A, and optionally provide + a short explanation. +- New specs for review should be placed in the ``approved`` subfolder, where + they will undergo review and approval in Gerrit_. +- Specs that have finished implementation should be moved to the + ``implemented`` subfolder + +Indexing and Categorization +--------------------------- + +Use of the `index`_ directive in reStructuredText for each document provides +the ability to generate indexes to more easily find items later. Authors are +encouraged to use index entries for their documents to help with discovery. + +Naming +------ + +Document naming standards help readers find specs. For the Airship repository, +the following document naming is recommended. The categories listed here are +likely incomplete, and may need expansion to cover new cases. It is preferrable +to deviate (and hopefully amend the list) than force document names into +nonsense categories. Prefer using categories that have previously been used or +that are listed here over new categories, but don't force the category into +something that doesn't make sense. + +Document names should follow a pattern as follows:: + + [category]_title.rst + +Use the following guidelines to determine the category to use for a document: + +1) For new functionality and features, the best choice for a category is to + match a functional duty of Airship. + +site-definition + Parts of the platform that support the definition of a site, including + management of the yaml definitions, document authoring and translation, and + the collation of source documents. + +genesis + Used for the steps related to preparation and deployment of the genesis node + of an Airship deployment. + +baremetal + Those changes to Airflow that provide for the lifecycle of bare metal + components of the system - provisioning, maintenance, and teardown. This + includes booting, hardware and network configuration, operating system, and + other host-level management + +k8s + For functionality that is about interfacing with Kubernetes directly, other + than the initial setup that is done during genesis. + +software + Functionality that is related to the deployment or redeployment of workload + onto the Kubernetes cluster. + +workflow + Changes to existing workflows to provide new functionality and creation of + new workflows that span multiple other areas (e.g. baremetal, k8s, software), + or those changes that are new arrangements of existing functionality in one + or more of those other areas. + +administration + Security, logging, auditing, monitoring, and those things related to site + administrative functions of the Airship platform. + +2) For specs that are not feature focused, the component of the system may + be the best choice for a category, e.g. ``shipyard``, ``armada`` etc... + When there are multiple components involved, or the concern is cross + cutting, use of ``airship`` is an acceptable category. + +3) If the spec is related to the ecosystem Airship is maintained within, an + appropriate category would be related to the aspect it is impacting, e.g.: + ``git``, ``docker``, ``zuul``, etc... + +.. _index: http://www.sphinx-doc.org/en/stable/markup/misc.html#directive-index +.. _Gerrit: https://review.openstack.org/#/q/project:openstack/airship-specs diff --git a/specs/template.rst b/specs/template.rst index 8b753f0..01577ee 100644 --- a/specs/template.rst +++ b/specs/template.rst @@ -4,10 +4,20 @@ http://creativecommons.org/licenses/by/3.0/legalcode +.. index:: + single: template + single: creating specs + .. note:: Blueprints are written using ReSTructured text. +Add index directives to help others find your spec. E.g.:: + + .. index:: + single: template + single: creating specs + ===================================== Template: The title of your blueprint =====================================