From 550fde3c91eb5e236c833b9cf921a8f5e1eefeea Mon Sep 17 00:00:00 2001 From: lvdongbing Date: Tue, 12 Jan 2016 04:03:38 -0500 Subject: [PATCH] Fix docs Missing conf.py makes gate-bilean-docs fail, this patch fixes this issue, and initialize some docs. Change-Id: I9f74bf4e7391d596a446f21ea4e4bf0247b395ce --- doc/source/conf.py | 121 ++++++++++++++++++++++++++++++++++++ doc/source/contributing.rst | 4 ++ doc/source/index.rst | 36 +++++++++++ doc/source/overview.rst | 63 +++++++++++++++++++ tox.ini | 3 + 5 files changed, 227 insertions(+) create mode 100755 doc/source/conf.py create mode 100644 doc/source/contributing.rst create mode 100644 doc/source/index.rst create mode 100644 doc/source/overview.rst diff --git a/doc/source/conf.py b/doc/source/conf.py new file mode 100755 index 0000000..f04f8ee --- /dev/null +++ b/doc/source/conf.py @@ -0,0 +1,121 @@ +# -*- 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 + +import openstackdocstheme + +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.todo' + '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 + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +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 + +# 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 -------------------------------------------------- + +# 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 + +# 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} + +[extensions] +# todo_include_todos = True diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 0000000..1728a61 --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1,4 @@ +============ +Contributing +============ +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst new file mode 100644 index 0000000..a0c0a23 --- /dev/null +++ b/doc/source/index.rst @@ -0,0 +1,36 @@ +.. + 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. + +==================================== +Welcome to the Bilean documentation! +==================================== + +Bilean is a billing service for OpenStack cloud, it provides trigger-type +billing based on other OpenStack services' notification. + +This documentation offers information on how Bilean works and how to +contribute to the project. + +.. toctree:: + :maxdepth: 1 + + overview + install + contributing + +Indices and tables +~~~~~~~~~~~~~~~~~~ + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/overview.rst b/doc/source/overview.rst new file mode 100644 index 0000000..7d367f2 --- /dev/null +++ b/doc/source/overview.rst @@ -0,0 +1,63 @@ +.. + 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. + +.. _guide-overview: + +======== +Overview +======== + +The mission for Bilean project is to provide a generic billing service for +an OpenStack cloud, it implements trigger-type billing based on other +OpenStack services' notification. + +Components +~~~~~~~~~~ + +The developers are focusing on creating an OpenStack style project using +OpenStack design tenets, implemented in Python. We have started with a close +interaction with Heat project. + +bilean +------ + +The :program:`bilean` tool is A CLI communicates with the :program:`bilean-api` +to manage rules, policies, users, resources, jobs and events. End developers +could also use the Bilean REST API directly. + +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 +------------------- + +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. + +bilean-engine +------------- + +The :program:`bilean-engine` does the main billing work, operates all users, +rules, policies, resources, jobs and events. + + +Installation +~~~~~~~~~~~~ + +You will need to make sure you have a suitable environment for deploying +Bilean. Please refer to :ref:`Installation ` for detailed +instructions on setting up an environment to use the Bilean service. diff --git a/tox.ini b/tox.ini index f70b708..a201b30 100644 --- a/tox.ini +++ b/tox.ini @@ -30,6 +30,9 @@ commands = [testenv:venv] commands = {posargs} +[testenv:docs] +commands = python setup.py build_sphinx + [flake8] ignore = exclude = .venv,.git,.tox,cover,dist,*lib/python*,*egg,tools,build