Beggining of docs conversion to OpenStack format

This commit introduces initial infrastructure for building documentation
using the OpenStack's sphinx extension and tox. To demonstrate that
README.md is rewritten into README.rst and should appear in
documentation built by `tox -e docs`.

Partial-Implements: blueprint docs-to-rst

Change-Id: I08ebad1c572e248a8f474e785d3bf7a19dbc4340

.gitignore

@@ -1,9 +1,71 @@
+*.py[cod]
+
+# C extensions
+*.so
+
+# Packages
+*.egg*
+*.egg-info
+dist
+build
+eggs
+parts
+bin
+var
+sdist
+develop-eggs
+.installed.cfg
+lib
+lib64
+
+# Installer logs
+pip-log.txt
+
+# Unit test / coverage reports
+cover/
+.coverage*
+!.coveragerc
+.tox
+nosetests.xml
+.testrepository
+.venv
+
+# Translations
+*.mo
+
+# Mr Developer
+.mr.developer.cfg
+.project
+.pydevproject
+
+# Complexity
+output/*.html
+output/*/index.html
+
+# Sphinx
+doc/build
+
+# pbr generates these
+AUTHORS
+ChangeLog
+
+# Editors
+*~
+.*.swp
+.*sw?
+
+# Files created by releasenotes build
+releasenotes/build
+
+# Dev tools
+.idea/
+dev/.vagrant
+
+# Helm internals
 *.lock
 */*.lock
 *.tgz
 **/*.tgz
-.idea/
 **/_partials.tpl
 **/_globals.tpl
-dev/.vagrant
 dev/*.log

README.md

@@ -1,23 +0,0 @@
-# Openstack-Helm
-
-**Join us on [Slack](http://slack.k8s.io/):** `#openstack-helm`<br>
-**Join us on [Freenode](https://freenode.net/):** `#openstack-helm`<br>
-**Community Meetings:** Every other Tuesday @ 3PM UTC in the `#openstack-helm` channel<br>
-**Community Agenda Items:** [Google Docs](https://docs.google.com/document/d/1Vm2OnMzjSru3cuvxh4Oa7R_z7staU-7ivGy8foOzDCs/edit#heading=h.bfc0dkav9gk2)<br>
-**Community Roadmap Items:** [Roadmap Docs](https://docs.google.com/spreadsheets/d/1N5AdAdLbvpZ9Tzi1TuqeJbHyczfZRysBIYE_ndnZx6c/edit?usp=sharing)
-
-Openstack-Helm is a fully self-contained Helm-based OpenStack deployment on Kubernetes. It will provide baremetal provisioning, persistent storage, full-stack resiliency, full-stack scalability, performance monitoring and tracing, and an optional development pipeline (using Jenkins). This project, along with the tools used within are community-based and open sourced.
-
-# Mission
-
-The goal for Openstack-Helm is to provide an incredibly customizable *framework* for operators and developers alike. This framework will enable end-users to deploy, maintain, and upgrade a fully functioning Openstack environment for both simple and complex environments. Administrators or developers can either deploy all or individual Openstack components along with their required dependancies. It heavily borrows concepts from [Stackanetes](https://github.com/stackanetes/stackanetes) and [other complex Helm application deployments](https://github.com/sapcc/openstack-helm). This project is meant to be a collaborative project that brings Openstack applications into a [Cloud-Native](https://www.cncf.io/about/charter) model.
-
-# Open Releases
-
-Until a 1.0.0 release, this collection is a work in progress and components will continue to be added or modified over time. Please review our [Milestones](https://launchpad.net/openstack-helm), and  [Releases](https://github.com/openstack/openstack-helm/releases) for more information.
-
-# Installation and Development
-
-This project is under heavy development. We encourage anyone who is interested in Openstack-Helm to review our [Installation](https://github.com/openstack/openstack-helm/blob/master/docs/guides-install/readme.md) documentation, complete with verification procedures. Feel free to ask questions or check out our current [Issues and Bugs](https://bugs.launchpad.net/openstack-helm).
-
-Openstack-Helm is intended to be packaged and served from your own Helm [repository](https://github.com/kubernetes/helm/blob/master/docs/chart_repository.md). However, for quick installation, evaluation, and convenience, you can use our online Helm repository. After you've configured your environment for [Minikube](https://github.com/openstack/openstack-helm/blob/master/docs/guides-install/developer/install-minikube.md#openstack-helm-minikube-deployment) (for hostPath) or [Bare Metal](https://github.com/openstack/openstack-helm/blob/master/docs/guides-install/install-multinode.md#overview).

README.rst

@@ -0,0 +1,62 @@
+==============
+Openstack-Helm
+==============
+
+Openstack-Helm is a fully self-contained Helm-based OpenStack deployment on
+Kubernetes. It will provide baremetal provisioning, persistent storage,
+full-stack resiliency, full-stack scalability, performance monitoring and
+tracing, and an optional development pipeline (using Jenkins). This project,
+along with the tools used within are community-based and open sourced.
+
+Mission
+-------
+
+The goal for Openstack-Helm is to provide an incredibly customizable
+*framework* for operators and developers alike. This framework will enable
+end-users to deploy, maintain, and upgrade a fully functioning Openstack
+environment for both simple and complex environments. Administrators or
+developers can either deploy all or individual Openstack components along with
+their required dependancies. It heavily borrows concepts from
+`Stackanetes <https://github.com/stackanetes/stackanetes>`_ and `other complex
+Helm application deployments <https://github.com/sapcc/openstack-helm>`_. This
+project is meant to be a collaborative project that brings Openstack
+applications into a `Cloud-Native <https://www.cncf.io/about/charter>`_ model.
+
+Communication
+-------------
+
+* Join us on `Slack <http://slack.k8s.io/>`_ - #openstack-helm
+* Join us on `IRC <irc://chat.freenode.net:6697/openstack-helm>`_:
+  #openstack-helm on freenode
+* Community IRC Meetings: [Every Tuesday @ 3PM UTC],
+  #openstack-meeting-5 on freenode
+* Meeting Agenda Items: `Agenda
+  <https://etherpad.openstack.org/p/openstack-helm-meeting-agenda>`_
+* Community Roadmap Items: `Roadmap Docs
+  <https://docs.google.com/spreadsheets/d/1N5AdAdLbvpZ9Tzi1TuqeJbHyczfZRysBIYE_ndnZx6c/edit?usp=sharing>`_
+
+Open Releases
+-------------
+
+Until a 1.0.0 release, this collection is a work in progress and components
+will continue to be added or modified over time. Please review our
+`Milestones <https://launchpad.net/openstack-helm>`_, and `Releases
+<https://github.com/openstack/openstack-helm/releases>`_ for more information.
+
+Installation and Development
+----------------------------
+
+This project is under heavy development. We encourage anyone who is interested
+in Openstack-Helm to review our `Installation
+<https://github.com/openstack/openstack-helm/blob/master/doc/source/guides-install/readme.md>`_
+documentation, complete with verification procedures. Feel free to ask
+questions or check out our current `Issues and Bugs
+<https://bugs.launchpad.net/openstack-helm>`_.
+
+Openstack-Helm is intended to be packaged and served from your own Helm
+`repository <https://github.com/kubernetes/helm/blob/master/docs/chart_repository.md>`_.
+However, for quick installation, evaluation, and convenience, you can use our
+online Helm repository. After you've configured your environment for `Minikube
+<https://github.com/openstack/openstack-helm/blob/master/doc/source/guides-install/developer/install-minikube.md#openstack-helm-minikube-deployment>`_
+(for hostPath) or `Bare Metal
+<https://github.com/openstack/openstack-helm/blob/master/doc/source/guides-install/install-multinode.md#overview>`_.

doc/source/conf.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+# 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.
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('../..'))
+# -- General configuration ----------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    'sphinx.ext.autodoc',
+    #'sphinx.ext.intersphinx',
+    'oslosphinx'
+]
+
+# autodoc generation is a bit aggressive and a nuisance when doing heavy
+# text edit cycles.
+# execute "export SPHINX_DEBUG=1" in your terminal to disable
+
+# The suffix of source filenames.
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'openstack-helm'
+copyright = u'2016, OpenStack Foundation'
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = True
+
+# The name of the Pygments (syntax highlighting) style to use.
+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

@@ -0,0 +1,4 @@
+============
+Contributing
+============
+.. include:: ../../CONTRIBUTING.rst

doc/source/index.rst

@@ -0,0 +1,23 @@
+.. openstack-helm 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.
+
+Welcome to openstack-helm's documentation!
+========================================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 3
+
+   readme
+   contributing
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
+

doc/source/readme.rst

@@ -0,0 +1 @@
+.. include:: ../../README.rst

docs/old_readme.md

@@ -1,57 +0,0 @@
-# Openstack-Helm Documentation
-
-
-## Table of Contents
-
-##  1. Openstack-Helm Design Principles
-###    1.1 [Mission](mission.md)
-#####      1.1.1 [Resiliency](mission.md#resiliency)
-#####      1.1.2 [Scaling](mission.md#scaling)
-###    1.2 Helm Overrides
-#####      1.2.1 [Values Philosophy](helm_overrides.md#values)
-#####      1.2.1 [Replicas](helm_overrides.md#replicas)
-#####      1.2.1 [Labels](helm_overrides.md#labels)
-#####      1.2.1 [Images](helm_overrides.md#images)
-#####      1.2.1 [Upgrades](helm_overrides.md#upgrades)
-#####      1.2.1 [Resource Limits](helm_overrides.md#resource limits)
-#####      1.2.2 [Endpoints](#helm_overrides.md#endpoints)
-#####      1.2.2 [Common Conditionals](helm_overrides.md#common conditionals)
-###    1.3 Init-Containers
-#####      1.3.1 Dependency Checking
-###    1.4 Kubernetes Jobs
-#####      1.4.1 Service Registration
-#####      1.4.2 User Registration
-#####      1.4.3 Database Creation
-#####      1.4.4 Database Migration
-###    1.5 Complimentary Efforts
-####      1.5.1 Image-Based Project Considerations
-###    1.6 Kubernetes State
-####      1.6.1 Third Party Resources
-####      1.6.2 Add-Ons
-##  2. Repository Structure
-###    2.1 Infrastructure Components
-###    2.2 Openstack-Helm Core Services
-###    2.3 Openstack-Helm Add-Ons
-##  3. Operator Resources
-###     3.1 [Installation](https://github.com/att-comdev/openstack-helm/blob/master/docs/installation/getting-started.md)
-###     3.2 Openstack-Helm Chart Definition Overrides
-###     3.2 Openstacak-Helm Upgrades
-##  4. Openstack-Helm Networking
-###    4.1 Kubernetes Control Plane
-####     4.1.1 CNI SDN Considerations
-####     4.1.2 Calico Networking
-###    4.2 Ingress Philosophy
-###    4.3 Openstack Networking
-####     4.3.1 Flat Networking
-####     4.3.1 L2 Networking
-##  5. Security Guidelines
-###    5.1 Network Policies
-###    5.2 Advanced Network Policies
-###    5.3 Role-Based Access Controls
-###    5.4 Security Contexts
-###    5.5 Security Add-Ons
-##  6. Developer Resources
-###    6.1 Contributions and Guidelines
-###    6.2 Development Tools
-####     6.2.1 [Minikube Development](https://github.com/att-comdev/openstack-helm/blob/master/docs/developer/minikube.md)
-###    6.3 Tips and Considerations

setup.cfg

@@ -0,0 +1,23 @@
+[metadata]
+name = openstack-helm
+summary = Helm charts for OpenStack services
+description-file =
+    README.rst
+author = OpenStack
+author-email = openstack-dev@lists.openstack.org
+home-page = http://www.openstack.org/
+classifier =
+    Intended Audience :: Developers
+    License :: OSI Approved :: Apache Software License
+    Operating System :: POSIX :: Linux
+
+[build_sphinx]
+all_files = 1
+build-dir = doc/build
+source-dir = doc/source
+
+[pbr]
+warnerrors = True
+
+[wheel]
+universal = 1

setup.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python
+# 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.
+
+# THIS FILE IS MANAGED BY THE GLOBAL REQUIREMENTS REPO - DO NOT EDIT
+import setuptools
+
+setuptools.setup(
+    setup_requires=['pbr'],
+    pbr=True)

test-requirements.txt

@@ -0,0 +1,3 @@
+sphinx>=1.5.1 # BSD
+oslosphinx>=4.7.0 # Apache-2.0
+

tox.ini

@@ -0,0 +1,16 @@
+[tox]
+minversion = 2.0
+envlist = docs
+skipsdist = True
+
+[testenv]
+install_command = pip install -U {opts} {packages}
+setenv = VIRTUAL_ENV={envdir}
+deps = -r{toxinidir}/test-requirements.txt
+passenv = *_proxy *_PROXY
+
+[testenv:venv]
+commands = {posargs}
+
+[testenv:docs]
+commands = python setup.py build_sphinx