Added documentation

After migrating to the OpenStack infrastructure, the documentation
was missing. This patch re-adds it.

Closes-Bug: 1640285

Change-Id: I8f6f138b32483264d9ed8cdcc855b33f026097b6

doc/Makefile

@@ -0,0 +1,155 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+PAPER         =
+BUILDDIR      = build
+SOURCEDIR     = source
+
+# Internal variables.
+PAPEROPT_a4     = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+# the i18n builder cannot share the environment and doctrees with the others
+I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) source
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  autodoc    generate the autodoc templates"
+	@echo "  html       to make standalone HTML files"
+	@echo "  dirhtml    to make HTML files named index.html in directories"
+	@echo "  singlehtml to make a single large HTML file"
+	@echo "  pickle     to make pickle files"
+	@echo "  json       to make JSON files"
+	@echo "  htmlhelp   to make HTML files and a HTML help project"
+	@echo "  qthelp     to make HTML files and a qthelp project"
+	@echo "  devhelp    to make HTML files and a Devhelp project"
+	@echo "  epub       to make an epub"
+	@echo "  latex      to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+	@echo "  latexpdf   to make LaTeX files and run them through pdflatex"
+	@echo "  text       to make text files"
+	@echo "  man        to make manual pages"
+	@echo "  texinfo    to make Texinfo files"
+	@echo "  info       to make Texinfo files and run them through makeinfo"
+	@echo "  gettext    to make PO message catalogs"
+	@echo "  changes    to make an overview of all changed/added/deprecated items"
+	@echo "  linkcheck  to check all external links for integrity"
+	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+	-rm -rf $(BUILDDIR)/*
+
+html:
+	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+	$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+	@echo
+	@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+	$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+	@echo
+	@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+	@echo
+	@echo "Build finished; now you can process the pickle files."
+
+json:
+	$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+	@echo
+	@echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+	@echo
+	@echo "Build finished; now you can run HTML Help Workshop with the" \
+	      ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+	$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+	@echo
+	@echo "Build finished; now you can run "qcollectiongenerator" with the" \
+	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+	@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/mixmatch.qhcp"
+	@echo "To view the help file:"
+	@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/mixmatch.qhc"
+
+devhelp:
+	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+	@echo
+	@echo "Build finished."
+	@echo "To view the help file:"
+	@echo "# mkdir -p $$HOME/.local/share/devhelp/mixmatch"
+	@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/mixmatch"
+	@echo "# devhelp"
+
+epub:
+	$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+	@echo
+	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo
+	@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+	@echo "Run \`make' in that directory to run these through (pdf)latex" \
+	      "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+	@echo "Running LaTeX files through pdflatex..."
+	$(MAKE) -C $(BUILDDIR)/latex all-pdf
+	@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+	$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+	@echo
+	@echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+	$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+	@echo
+	@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+texinfo:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo
+	@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
+	@echo "Run \`make' in that directory to run these through makeinfo" \
+	      "(use \`make info' here to do that automatically)."
+
+info:
+	$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
+	@echo "Running Texinfo files through makeinfo..."
+	make -C $(BUILDDIR)/texinfo info
+	@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
+
+gettext:
+	$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
+	@echo
+	@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
+
+changes:
+	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+	@echo
+	@echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+	@echo
+	@echo "Link check complete; look for any errors in the above output " \
+	      "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+	$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+	@echo "Testing of doctests in the sources finished, look at the " \
+	      "results in $(BUILDDIR)/doctest/output.txt."

doc/README.rst

@@ -0,0 +1,9 @@
+Building Docs
+=============
+
+Developer documentation is generated using Sphinx. To build this documentation,
+run the following from the root of the repository::
+
+  $ tox -e docs
+
+The documentation will be built at ``doc/build/``.

doc/source/architecture.rst

@@ -0,0 +1,19 @@
+============
+Architecture
+============
+
+The proxy is designed to substitute an endpoint in the service catalog.
+When a user/service requests the proxied service for a specific resource
+(volume, image, etc), the proxy will analyze the URL of the request to
+figure out the type of the resource and the UUID of the resource and '
+forward the request to the correct service provider, getting a token through
+K2K and using that for the remote endpoint. It will then forward the response
+back.
+
+.. image:: images/SequenceDiagram.png
+
+To gather the information about the location of the resources, the proxy listens
+to the notifications message bus for messages which describe the creation of new
+resources, and stores that location information into the database.
+
+.. image:: images/Notifications.png

doc/source/conf.py

@@ -23,7 +23,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 extensions = [
     'sphinx.ext.autodoc',
     #'sphinx.ext.intersphinx',
-    'oslosphinx'
+    #'oslosphinx'
 ]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
@@ -38,7 +38,8 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'mixmatch'
-copyright = u'2016, OpenStack Foundation'
+copyright = u'2016, Massachusetts Open Cloud'
+author = u'Massachusetts Open Cloud'
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
@@ -55,8 +56,9 @@ pygments_style = 'sphinx'
 # 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_theme = 'alabaster'
 # html_static_path = ['static']
+html_logo = 'images/moc.png'
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
@@ -68,7 +70,7 @@ latex_documents = [
     ('index',
      '%s.tex' % project,
      u'%s Documentation' % project,
-     u'OpenStack Foundation', 'manual'),
+     u'Massachusetts Open Cloud', 'manual'),
 ]
 
 # Example configuration for intersphinx: refer to the Python standard library.

doc/source/index.rst

@@ -12,8 +12,8 @@ Contents:
    :maxdepth: 2
 
    readme
+   architecture
    installation
-   usage
    contributing
 
 Indices and tables

doc/source/installation.rst

@@ -2,11 +2,109 @@
 Installation
 ============
 
-At the command line::
+The proxy will be set up in one OpenStack installation, called the Identity
+Provider, or IdP, and it redirect API calls to either the local services, or
+remote services in one of several Service Provider installations (SP).
 
-    $ pip install mixmatch
+Install dependencies. ::
 
-Or, if you have virtualenvwrapper installed::
+    $ pip install -r requirements.txt
+    $ python setup.py install
+
+
+Web Server
+==========
+The recommended way is to run the proxy using uWSGI through the
+``run_proxy.sh`` script. ::
+
+    $ ./run_proxy.sh
+
+
+It is also possible to run the proxy with Apache2 and ``mod_wsgi``, but there
+are limitations compared to running it with uWSGI.
+
+- Image uploading with Glance doesn't work unless running Apache in embedded
+  mode.
+- Image API v1 uses underscores in the header keys, which are silently dropped
+  by Apache. Hacking the configuration to allow these through is required.
+
+To run the proxy with Apache in Ubuntu: ::
+
+    $ apt-get install libapache2-mod-wsgi
+    $ cp httpd/apache.conf /etc/apache2/sites-available/proxy.conf
+    $ cp etc/k2k-proxy.conf /etc/
+    $ a2ensite proxy
+    $ service apache2 reload
+
+
+Configuration
+=============
+The proxy searches for the configuration file ``k2k-proxy.conf`` in the
+current directory, the ``etc/`` directory relative to the current directory or
+``/etc/``
+
+A sample configuration file has been provided in the ``etc`` folder of the
+source code.
+
+The proxy will substitute the endpoint of the service it is proxying.
+Only Cinder and Glance are supported for now.
+
+For each SP, you must have a section in ``k2k-proxy.conf`` which contains the
+service provider name (as it is listed in Keystone's service catalog), and the
+URI for connecting to the notification messagebus in that OpenStack
+installation.  For instance::
+
+    [sp_one]
+    sp_name="keystone-sp1"
+    messagebus="rabbit://rabbituser:rabbitpassword@192.168.7.20"
+    image_endpoint="http://192.168.7.20:9292"
+    volume_endpoint="http://192.168.7.20:8776"
+
+Keystone Configuration
+----------------------
+
+Keystone maintains the service catalog with information about all the
+configured endpoints.
+
+In the IdP, delete and then recreate the endpoint which we will proxy. ::
+
+    $ openstack endpoint delete <endpoint_id>
+    $ openstack endpoint create \
+        --publicurl http://<proxy_host>:<proxy_port>/<service_type>/<api_version> \
+        --internalurl http://<proxy_host>:<proxy_port>/<service_type>/<api_version> \
+        --adminurl http://<proxy_host>:<proxy_port>/<service_type>/<api_version> \
+        --region RegionOne \
+        <endpoint_type>
+
+Where service_type is ``image`` if endpoint_type is ``image``
+and ``volume`` if endpoint_type is ``volume`` or ``volumev2``
+
+Nova Configuration
+------------------
+
+Nova reads the endpoint address for glance from the configuration file stored
+in ``/etc/nova/nova.conf``. So, in the IdP, add the following::
+
+    # /etc/nova/nova.conf
+    [glance]
+    api_servers=<proxy_url>/image
+
+Cinder Notification
+-------------------
+
+Cinder reads the endpoint address for glance from the configuration file stored
+in ``/etc/cinder/cinder.conf``. So, in the IdP, add the following::
+
+    # /etc/cinder/cinder.conf
+    [default]
+    glance_api_servers=<proxy_url>/image
+
+Every Cinder must be configured to emit notifications on the messagebus.  So,
+in both the IdP and every SP, add the following to
+``/etc/cinder/cinder.conf``::
+
+    # /etc/cinder/cinder.conf
+    [oslo_messaging_notifications]
+    driver = messaging
+    topics = notifications
 
-    $ mkvirtualenv mixmatch
-    $ pip install mixmatch

doc/source/usage.rst

@@ -1,7 +0,0 @@
-========
-Usage
-========
-
-To use mixmatch in a project::
-
-    import mixmatch