Revise install doc

As devstack plugin is added, this commit revises install doc about
installing bilean via devstack.

Change-Id: I6052e83a3d503b941e8fc44a0db9f1f0d73b5816

CONTRIBUTING.rst

@@ -1,28 +1,43 @@
-Before You Start
+======================
-================
+Contributing to Bilean
+======================
 
-If you would like to contribute to the development of OpenStack,
+If you're interested in contributing to the Bilean project,
-you must follow the steps in this page:
+the following will help get you started.
 
-   http://docs.openstack.org/infra/manual/developers.html
+Contributor License Agreement
+=============================
 
-Once those steps have been completed, changes to OpenStack
+In order to contribute to the Bilean project, you need to have
-should be submitted for review via the Gerrit tool, following
+signed OpenStack's contributor's agreement:
-the workflow documented at:
 
-   http://docs.openstack.org/infra/manual/developers.html#development-workflow
+* http://docs.openstack.org/infra/manual/developers.html
+* http://wiki.openstack.org/CLA
 
-Reporting Bugs
-==============
 
-Pull requests submitted through Github will be ignored.
+Project Hosting Details
+=======================
 
-Bugs should be filed on Launchpad, not Github:
+* Bug trackers
+    * General bilean tracker: https://launchpad.net/bilean
 
-   https://bugs.launchpad.net/bilean
+    * Python client tracker: https://launchpad.net/python-bileanclient
 
-Meet the Developers
+* Mailing list (prefix subjects with ``[Bilean]`` for faster responses)
-===================
+    http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
 
-Real-time communication among developers are mostly done via IRC.
+* Wiki
-The team is using the #openstack-bilean channel on freenode.net.
+    https://wiki.openstack.org/wiki/Bilean
+
+* IRC channel
+    * #openstack-bilean at FreeNode
+
+* Code Hosting
+    * https://git.openstack.org/cgit/openstack/bilean
+
+    * https://git.openstack.org/cgit/openstack/python-bileanclient
+
+* Code Review
+    * https://review.openstack.org/#/q/bilean+AND+status:+open,n,z
+
+    * http://docs.openstack.org/infra/manual/developers.html#development-workflow

devstack/README.rst

@@ -2,25 +2,32 @@
 Enabling Bilean in DevStack
 ===========================
 
-1. Download DevStack:
+1. Download DevStack.
+
+  ::
+
     git clone https://git.openstack.org/openstack-dev/devstack
     cd devstack
 
-2. Add this repo as an external repository::
+2. Add this repo as an external repository.
+
+  ::
 
     cat > /opt/stack/devstack/local.conf << END
     [[local|localrc]]
     enable_plugin bilean https://github.com/openstack/bilean master
     END
 
-3. Add Plugin Configuration Hooks
+3. Add Plugin Configuration Hooks.
 
-Bilean service is driven using a plugin mechanism for integrating to other
+   Bilean service is driven using a plugin mechanism for integrating to other
-services. Each integrated service may require additional configuration
+   services. Each integrated service may require additional configuration
-settings. For example, typically, you will need to add the
+   settings. For example, typically, you will need to add the
-``billing_notifications`` notification topic to each service's configuration.
+   ``billing_notifications`` notification topic to each service's configuration.
 
-4. Then run devstack normally::
+4. Then run devstack normally.
+
+  ::
 
     cd /opt/stack/devstack
     ./stack.sh

doc/source/conf.py

@@ -15,8 +15,6 @@
 import os
 import sys
 
-import openstackdocstheme
-
 sys.path.insert(0, os.path.abspath('../..'))
 # -- General configuration ----------------------------------------------------
 
@@ -24,8 +22,7 @@ sys.path.insert(0, os.path.abspath('../..'))
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     'sphinx.ext.autodoc',
-    # 'sphinx.ext.todo'
+    # 'sphinx.ext.intersphinx',
-    'sphinx.ext.intersphinx',
     'oslosphinx'
 ]
 
@@ -33,9 +30,6 @@ extensions = [
 # text edit cycles.
 # execute "export SPHINX_DEBUG=1" in your terminal to disable
 
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
-
 # The suffix of source filenames.
 source_suffix = '.rst'
 
@@ -46,40 +40,6 @@ master_doc = 'index'
 project = u'bilean'
 copyright = u'2015, OpenStack Foundation'
 
-# The version infor for the project you're documenting, acts as replacement for
-# |version| and |release|, also used in various other places throughout the
-# built documents
-#
-# "version" and "release" are used by the "log-a-bug" feature
-#
-# The short X.Y version.
-version = '1.0'
-
-# The full version, including alpha/beta/rc tags.
-release = '1.0'
-
-# A few variables have to be set for the log-a-bug feature.
-#   giturl: The location of conf.py on Git. Must be set manually.
-#   gitsha: The SHA checksum of the bug description. Extracted from git log.
-#   bug_tag: Tag for categorizing the bug. Must be set manually.
-#   bug_project: Launchpad project to file bugs against.
-# These variables are passed to the logabug code via html_context.
-giturl = u'http://git.openstack.org/cgit/openstack/bilean/tree/doc/source'
-git_cmd = "/usr/bin/git log | head -n1 | cut -f2 -d' '"
-gitsha = os.popen(git_cmd).read().strip('\n')
-bug_tag = "docs"
-
-# source tree
-pwd = os.getcwd()
-
-# html_context allows us to pass arbitrary values into the html template
-html_context = {"pwd": pwd,
-                "gitsha": gitsha,
-                "bug_tag": bug_tag,
-                "giturl": giturl,
-                "bug_project": "bilean"}
-
-
 # If true, '()' will be appended to :func: etc. cross-reference text.
 add_function_parentheses = True
 
@@ -92,15 +52,12 @@ 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']
 
-# The theme to use for HTML and HTML Help pages. See the documentation for a
-# list of builtin themes.
-html_theme = 'openstackdocs'
-
-# Add any paths that contain custom themes here, relative to this directory
-html_theme_path = [openstackdocstheme.get_html_theme_path()]
-
 # Output file base name for HTML help builder.
 htmlhelp_basename = '%sdoc' % project
 
@@ -116,6 +73,3 @@ latex_documents = [
 
 # Example configuration for intersphinx: refer to the Python standard library.
 # intersphinx_mapping = {'http://docs.python.org/': None}
-
-[extensions]
-# todo_include_todos = True

doc/source/contributing.rst

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

doc/source/install.rst

@@ -17,16 +17,61 @@
 Installation
 ============
 
-1. Get Bilean source code from Github
+There are in general two ways to isntall Bilean service: install via DevStack
+or install manually.
 
-::
+Install via DevStack
+~~~~~~~~~~~~~~~~~~~~
+
+This is the recommended way to install the Bilean service. Please refer to
+following detailed instructions.
+
+1. Download DevStack.
+
+  ::
+
+    git clone https://git.openstack.org/openstack-dev/devstack
+    cd devstack
+
+2. Add this repo as an external repository.
+
+  ::
+
+    cat > /opt/stack/devstack/local.conf << END
+    [[local|localrc]]
+    enable_plugin bilean https://github.com/openstack/bilean master
+    END
+
+3. Add Plugin Configuration Hooks.
+
+   Bilean service is driven using a plugin mechanism for integrating to other
+   services. Each integrated service may require additional configuration
+   settings. For example, typically, you will need to add the
+   ``billing_notifications`` notification topic to each service's configuration.
+
+4. Then run devstack normally.
+
+  ::
+
+    cd /opt/stack/devstack
+    ./stack.sh
+
+Manual Installation
+~~~~~~~~~~~~~~~~~~~
+
+Install Bilean Server
+---------------------
+
+1. Get Bilean source code from Github.
+
+  ::
 
     $ cd /opt/stack
     $ git clone https://github.com/lvdongbing/bilean.git
 
-2. Install Bilean with required packages
+2. Install Bilean with required packages.
 
-::
+  ::
 
     $ cd /opt/stack/bilean
     $ sudo pip install -e .
@@ -34,9 +79,7 @@ Installation
 3. Register Bilean service with keystone.
 
    This can be done using the :command:`setup-service` script under the
-   :file:`tools` folder.
+   :file:`tools` folder::
-
-::
 
     $ source ~/devstack/openrc admin
     $ cd /opt/stack/bilean/tools
@@ -44,20 +87,20 @@ Installation
 
 4. Generate configuration file for the Bilean service.
 
-::
+  ::
 
     $ cd /opt/stack/bilean
-  $ tools/gen-config
+    $ tox -e genconfig
     $ sudo mkdir /etc/bilean
     $ sudo cp etc/bilean/api-paste.ini /etc/bilean
     $ sudo cp etc/bilean/policy.json /etc/bilean
     $ sudo cp etc/bilean/resource_definitions.yaml /etc/bilean
     $ sudo cp etc/bilean/bilean.conf.sample /etc/bilean/bilean.conf
 
-Edit file :file:`/etc/bilean/bilean.conf` according to your system settings.
+5. Modify configuration file. 
-The most common options to be customized include:
 
-::
+   Edit file :file:`/etc/bilean/bilean.conf` according to your system settings.
+   The most common options to be customized include::
 
     [database]
     connection = mysql://root:<DB PASSWORD>@127.0.0.1/bilean?charset=utf8
@@ -82,21 +125,57 @@ The most common options to be customized include:
     rabbit_hosts = <HOST>
     rabbit_password = <RABBIT PASSWORD>
 
-5. Create Bilean Database
+6. Create Bilean Database
 
    Create Bilean database using the :command:`bilean-db-recreate` script under
- the :file:`tools` subdirectory.
+   the :file:`tools` subdirectory::
-
-::
 
     $ cd /opt/stack/bilean/tools
     $ ./bilean-db-recreate <DB PASSWORD>
 
-6. Start bilean engine and api service.
+7. Start bilean services.
 
- You may need two consoles for the services each.
+   You may need four consoles for the services each::
-
-::
 
     $ bilean-engine --config-file /etc/bilean/bilean.conf
     $ bilean-api --config-file /etc/bilean/bilean.conf
+    $ bilean-scheduler --config-file /etc/bilean/bilean.conf
+    $ bilean-notification --config-file /etc/bilean/bilean.conf
+
+Install Bilean Client
+---------------------
+
+1. Get Bilean client code from OpenStack git repository.
+
+  ::
+
+    $ cd /opt/stack
+    $ git clone https://git.openstack.org/openstack/python-bileanclient.git
+
+2. Install Bilean client.
+
+  ::
+  
+    $ cd python-bileanclient
+    $ sudo pip install -e .
+
+Verify Installation
+-------------------
+
+To check whether Bilean server and Bilean client have been installed
+successfully, run command ``bilean user-list`` in a console. The installation
+is successful if the command output looks similar to the following.
+
+::
+
+  $ bilean user-list
+  +----------------------------------+--------------------+---------+--------+------+--------+
+  | id                               | name               | balance | credit | rate | status |
+  +----------------------------------+--------------------+---------+--------+------+--------+
+  | 675f42b2dd3a456c9890350403bce8cf | admin              | 0.0     | 0      | 0.0  | INIT   |
+  | 927fef3da8194718a9179f4775f5f5ce | service            | 0.0     | 0      | 0.0  | INIT   |
+  | c688c64711a64d06b90c2b3c5d513dde | demo               | 0.0     | 0      | 0.0  | INIT   |
+  | e0504e51bd0d4e8886d06bb3cc3e6e80 | alt_demo           | 0.0     | 0      | 0.0  | INIT   |
+  | e9950cf337be47e68a21c9b20b291142 | invisible_to_admin | 0.0     | 0      | 0.0  | INIT   |
+  +----------------------------------+--------------------+---------+--------+------+--------+
+

doc/source/overview.rst

@@ -41,12 +41,11 @@ bilean-api
 The :program:`bilean-api` component provides an OpenStack-native REST API that
 processes API requests by sending them to the :program:`bilean-engine` over RPC.
 
-bilean-notification
+bilean-scheduler
--------------------
+----------------
 
-The :program:`bilean-notification` component monitors the message bus for data
+The :program:`bilean-scheduler` manages jobs related to users and scheduler job
-provided by other OpenStack components such as Nova, then converts notifications
+to engine to execute it.
-into billing resources and sends to :program:`bilean-engine` over AMQP.
 
 bilean-engine
 -------------
@@ -54,6 +53,13 @@ bilean-engine
 The :program:`bilean-engine` does the main billing work, operates all users,
 rules, policies, resources, jobs and events.
 
+bilean-notification
+-------------------
+
+The :program:`bilean-notification` component monitors the message bus for data
+provided by other OpenStack components such as Nova, then converts notifications
+into billing resources and sends to :program:`bilean-engine` over AMQP.
+
 
 Installation
 ~~~~~~~~~~~~