bootstrap repository structure

Set up an initial structure for the repository which provides sections
for both specs and use cases, plus a guide on how to contribute.

Story: 2001628
Task: 6614
Task: 6615
Change-Id: If117f8b4d634707a9375a78292f916f47a4f8b0c

CONTRIBUTING.rst

@@ -1,9 +1,18 @@
+:orphan:
+
 =============================================
 Contributing to OpenStack's self-healing SIG
 =============================================
 
-If you would like to contribute to the development of OpenStack, you must
-follow the steps in this page:
+If you would like to participate in discussions or contribute in any
+way to the design and development of self-healing in OpenStack, please
+first see:
+
+  https://wiki.openstack.org/wiki/Self_healing_SIG
+
+Contributions to the use-cases and specifications in this repository
+are very welcome.  To contribute to this repository, you must follow
+the steps in this page:
 
    http://docs.openstack.org/infra/manual/developers.html
 

doc/source/conf.py

@@ -24,16 +24,24 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
-    'oslosphinx',
+    'openstackdocstheme',
     'yasfb',
 ]
 
+html_theme = 'openstackdocs'
+
+# openstackdocstheme options
+repository_name = 'openstack/self-healing-sig'
+bug_project = '917'
+bug_tag = ''
+
 # Feed configuration for yasfb
 feed_base_url = 'http://specs.openstack.org/openstack/self-healing-sig'
-feed_author = 'OpenStack Development Team'
+feed_author = 'OpenStack Self-healing SIG'
 
 exclude_patterns = [
-    'template.rst',
+    'specs/template.rst',
+    'use-cases/template.rst',
 ]
 
 # Optionally allow the use of sphinxcontrib.spelling to verify the
@@ -55,7 +63,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = u'self-healing-sig'
+project = u'Self-healing SIG'
 copyright = u'%s, OpenStack Foundation' % datetime.date.today().year
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
@@ -70,24 +78,5 @@ pygments_style = 'sphinx'
 
 # -- Options for HTML output --------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  Major themes that come with
-# Sphinx are currently 'default' and 'sphinxdoc'.
-# html_theme_path = ["."]
-# html_theme = '_theme'
-# html_static_path = ['static']
-
-# Output file base name for HTML help builder.
-htmlhelp_basename = '%sdoc' % project
-
-# Grouping the document tree into LaTeX files. List of tuples
-# (source start file, target name, title, author, documentclass
-# [howto/manual]).
-latex_documents = [
-    ('index',
-     '%s.tex' % project,
-     u'%s Documentation' % project,
-     u'OpenStack Foundation', 'manual'),
-]
-
 # Example configuration for intersphinx: refer to the Python standard library.
 #intersphinx_mapping = {'http://docs.python.org/': None}

doc/source/contributing.rst

@@ -1,22 +0,0 @@
-=============================================
-Contributing to: self-healing-sig
-=============================================
-
-If you would like to contribute to the development of self-healing in
-OpenStack, please first see:
-
-  https://wiki.openstack.org/wiki/Self_healing_SIG
-
-To contribute to this repository, you must follow the steps in this
-page:
-
-   http://docs.openstack.org/infra/manual/developers.html
-
-If you already have a good understanding of how the system works and your
-OpenStack accounts are set up, you can skip to the development workflow
-section of this documentation to learn how changes to OpenStack should be
-submitted for review via the Gerrit tool:
-
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
-
-Pull requests submitted through GitHub will be ignored.

doc/source/index.rst

@@ -1,32 +1,25 @@
-.. self-healing-sig documentation master file, created by
-   sphinx-quickstart on Tue Jul  9 22:26:36 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
+==========================
+OpenStack Self-healing SIG
+==========================
 
-self-healing-sig Design Specifications
-======================================
+This documentation relates to some of the initiatives of OpenStack's
+Self-healing SIG (Special Interest Group).  For more information on
+the SIG itself, see `the SIG's home page on the wiki
+<https://wiki.openstack.org/wiki/Self-healing_SIG>`_.
 
-.. toctree::
-   :glob:
-   :maxdepth: 2
+Contributions to this documentation are warmly encouraged; please see
+:doc:`the guide to contributing <meta/CONTRIBUTING>`.
 
-   specs/*
-
-
-self-healing-sig Repository Information
-=======================================
 
 .. toctree::
    :maxdepth: 2
 
-   README <readme>
-   contributing
+   use-cases
+   specs
 
 
 Indices and tables
 ==================
 
-* :ref:`genindex`
-* :ref:`modindex`
 * :ref:`search`
 

doc/source/meta/CONTRIBUTING.rst

@@ -0,0 +1 @@
+../../../CONTRIBUTING.rst

doc/source/readme.rst

@@ -1,14 +0,0 @@
-===============================
-self-healing-sig
-===============================
-
-This documentation relates to the initiatives of OpenStack's
-Self-healing SIG.
-
-* Free software: Apache license
-* Documentation: http://docs.openstack.org/developer/self-healing-sig
-
-Features
---------
-
-* TODO

doc/source/specs

@@ -0,0 +1 @@
+../../specs

doc/source/specs.rst

@@ -0,0 +1,9 @@
+Design specifications
+=====================
+
+When adding a new spec, please use ``specs/template.rst`` as a
+starting point.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1

doc/source/use-cases

@@ -0,0 +1 @@
+../../use-cases

doc/source/use-cases.rst

@@ -0,0 +1,11 @@
+Use cases
+=========
+
+When adding a new use case, please use ``use-cases/template.rst`` as
+a starting point.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   use-cases/vitrage-mistral-integration.rst

requirements.txt

@@ -1,4 +1,3 @@
-pbr>=0.11,<2.0
-oslosphinx
-sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
+pbr>=2.0.0
+openstackdocstheme
 yasfb>=0.5.1

specs/template.rst

@@ -4,6 +4,10 @@ This work is licensed under a Creative Commons Attribution 3.0 Unported License.
 http://creativecommons.org/licenses/by/3.0/legalcode
 
 ..
+  This template is intended to encourage a certain level of consistency
+  between different use cases.  However strict adherence to the structure
+  of this template is not required.
+
   This template should be in ReSTructured text. The filename in the git
   repository should match the launchpad URL, for example a URL of
   https://blueprints.launchpad.net/self-healing-sig/+spec/awesome-thing should be named
@@ -12,21 +16,19 @@ http://creativecommons.org/licenses/by/3.0/legalcode
   For help with syntax, see http://sphinx-doc.org/rest.html
   To test out your formatting, see http://www.tele3.cz/jbar/rest/rest.html
 
-=============================
- The title of your blueprint
-=============================
-
-Include the URL of your launchpad blueprint:
-
-https://blueprints.launchpad.net/self-healing-sig/+spec/example
+===================================
+The title of your self-healing spec
+===================================
 
 Introduction paragraph -- why are we doing anything?
 
+
 Problem description
 ===================
 
 A detailed description of the problem.
 
+
 Proposed change
 ===============
 
@@ -36,14 +38,15 @@ propose to solve this problem?
 If this is one part of a larger effort make it clear where this piece ends. In
 other words, what's the scope of this effort?
 
-Include where in the self-healing-sig tree hierarchy this will reside.
+Include in which tree hierarchies of which projects this will reside.
 
 Alternatives
 ------------
 
-This is an optional section, where it does apply we'd just like a demonstration
+This is an optional section; where it does apply we'd just like a demonstration
 that some thought has been put into why the proposed approach is the best one.
 
+
 Implementation
 ==============
 
@@ -66,7 +69,7 @@ Milestones
 ----------
 
 Target Milestone for completion:
-  Juno-1
+  Stein-1
 
 Work Items
 ----------
@@ -79,7 +82,7 @@ but we're mostly trying to understand the timeline for implementation.
 Dependencies
 ============
 
-- Include specific references to specs and/or blueprints in self-healing-sig, or in other
+- Include specific references to specs and/or blueprints in this or other
   projects, that this one either depends on or is related to.
 
 - Does this feature require any new library dependencies or code otherwise not

tox.ini

@@ -15,7 +15,7 @@ deps = -r{toxinidir}/requirements.txt
 commands = {posargs}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = sphinx-build -W -b html doc/source doc/build/html
 
 [testenv:spelling]
 deps =

use-cases/template.rst

@@ -0,0 +1,145 @@
+..
+
+This work is licensed under a Creative Commons Attribution 3.0 Unported License.
+http://creativecommons.org/licenses/by/3.0/legalcode
+
+..
+  This template is intended to encourage a certain level of consistency
+  between different use cases.  However strict adherence to the structure
+  of this template is not required.
+
+  This template should be in ReSTructured text. The filename in the git
+  repository should match the launchpad URL, for example a URL of
+  https://blueprints.launchpad.net/self-healing-sig/+spec/awesome-thing should be named
+  awesome-thing.rst .  Please do not delete any of the sections in this
+  template.  If you have nothing to say for a whole section, just write: None
+  For help with syntax, see http://sphinx-doc.org/rest.html
+  To test out your formatting, see http://www.tele3.cz/jbar/rest/rest.html
+
+=======================================
+The title of your self-healing use case
+=======================================
+
+..
+  Please fill in the blanks in this use case statement, or rephrase
+  as appropriate.
+
+As a cloud operator, whenever one of my cloud's ________ has a _______
+failure, I want to be notified of all affected _______.  Moreover, I
+want _______ in order that ________ will continue to function.
+
+
+Problem description
+===================
+
+..
+  A more detailed description of the fault management scenario;
+  however it is not advised to duplicate details covered in the
+  sections below.  If the problem is not too complex, it may be more
+  appropriate to simply delete this section and provide the details in
+  the sections below.
+
+
+Fault class
+===========
+
+..
+  Please choose which of these classes are relevant and delete the
+  others.  If you can think of a new class which should be listed
+  here, please update the template.
+
+  Hardware failure
+  Software error
+  Performance degradation
+
+
+OpenStack projects used
+=======================
+
+..
+  Please provide a list of projects (OpenStack and otherwise) which
+  may be used in order to implement this use case.  If no
+  implementation exists yet, suggestions are sufficient here.
+
+* Zabbix
+* Vitrage
+* Mistral
+
+
+Remediation class
+=================
+
+..
+  Please choose which of these classes are relevant and delete the
+  others.  If you can think of a new class which should be listed
+  here, please update the template.
+
+  Proactive / preemptive
+  Predictive
+  Reactive
+
+
+Fault detection
+===============
+
+..
+  Describe the exact nature of the fault, which components
+  will be needed to automatically detect it, and how they
+  should be configured or used for the detection.
+
+  This may include details about relevant log streams, alarms,
+  error codes etc.
+
+
+Inputs and decision-making
+==========================
+
+..
+  Describe how decisions about the remediation action are taken.  In
+  particular list any other components or inputs which may provide
+  additional context to help determine appropriate remediation of the
+  fault.
+
+
+Remediation
+===========
+
+..
+  Describe how the fault may be remediated.  If there may be different
+  approaches available, please list them all.
+
+
+Existing implementation(s)
+==========================
+
+..
+  If there are one or more existing implementations of this use case,
+  please give as many details as possible, in order that operators can
+  re-implement the use case in their own clouds.  However any
+  information is better than no information!  Linking to external
+  documents is perfectly acceptable.
+
+
+Future work
+===========
+
+..
+  Please link from here to any relevant specs.  If a cross-project
+  spec is required, it can be placed under ../specs/ in this
+  repository.
+
+  Please also make sure that any linked specs contain back-links
+  to this use case for maximum discoverability.
+
+
+Dependencies
+============
+
+..
+  - Include specific references to specs and/or blueprints in
+    self-healing-sig, or in other projects, that this one either depends
+    on or is related to.
+
+  - Does this feature require any new library dependencies or code
+    otherwise not included in OpenStack? Or does it depend on a specific
+    version of library?