From 3b1cec10be9d58f3f36a2b0a99dfb6978f8227ab Mon Sep 17 00:00:00 2001 From: Ruslan Kamaldinov Date: Thu, 17 Apr 2014 03:49:09 +0400 Subject: [PATCH] Added developer documentation * Updated README file * Updated contrib/devstack/README * Added documentation for Devstack installation * Added documentation for manual installation of the API and Engine services * Added basic contributing guide * Added extended contributing guide * Added HACKING.rst to the root of the project * Added development guidelines * Sets simple Sphinx theme Partially implements blueprint: murano-dev-doc-05 Change-Id: Ib7d7b416ccc61667ed96297555db2ef5dca9ae67 --- CONTRIBUTING.rst | 45 ++++++++ HACKING.rst | 4 + README.rst | 40 +++---- contrib/devstack/README.md | 18 --- contrib/devstack/README.rst | 24 ++++ doc/source/_templates/sidebarlinks.html | 11 ++ doc/source/_theme/layout.html | 4 + doc/source/_theme/theme.conf | 4 + doc/source/conf.py | 21 ++-- doc/source/contributing.rst | 1 + doc/source/guidelines.rst | 81 ++++++++++++++ doc/source/index.rst | 139 +++++++----------------- doc/source/install/development.rst | 29 +++++ doc/source/install/index.rst | 26 +++++ doc/source/install/manual.rst | 104 ++++++++++++++++++ 15 files changed, 403 insertions(+), 148 deletions(-) create mode 100644 CONTRIBUTING.rst create mode 100644 HACKING.rst delete mode 100644 contrib/devstack/README.md create mode 100644 contrib/devstack/README.rst create mode 100644 doc/source/_templates/sidebarlinks.html create mode 100644 doc/source/_theme/layout.html create mode 100644 doc/source/_theme/theme.conf create mode 100644 doc/source/contributing.rst create mode 100644 doc/source/guidelines.rst create mode 100644 doc/source/install/development.rst create mode 100644 doc/source/install/index.rst create mode 100644 doc/source/install/manual.rst diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst new file mode 100644 index 00000000..499e975c --- /dev/null +++ b/CONTRIBUTING.rst @@ -0,0 +1,45 @@ +====================== +Contributing to Murano +====================== + +If you're interested in contributing to the Murano project, +the following will help get you started. + +Contributor License Agreement +============================= + +In order to contribute to the Murano project, you need to have +signed OpenStack's contributor's agreement: + +* http://wiki.openstack.org/HowToContribute +* http://wiki.openstack.org/CLA + + +Project Hosting Details +======================= + +* Bug tracker + https://launchpad.net/murano + +* Mailing list (prefix subjects with ``[Murano]`` for faster responses) + http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev + +* Wiki + https://wiki.openstack.org/wiki/Murano + +* IRC channel + * #murano at FreeNode + + * https://wiki.openstack.org/wiki/Meetings#Murano_meeting + +* Code Hosting + * https://git.openstack.org/cgit/stackforge/murano-api + + * https://git.openstack.org/cgit/stackforge/murano-agent + + * https://git.openstack.org/cgit/stackforge/murano-dashboard + +* Code Review + * https://review.openstack.org/#/q/murano+AND+status:+open,n,z + + * https://wiki.openstack.org/wiki/GerritWorkflow diff --git a/HACKING.rst b/HACKING.rst new file mode 100644 index 00000000..cb074765 --- /dev/null +++ b/HACKING.rst @@ -0,0 +1,4 @@ +Style Commandments +================== + +Read the OpenStack Style Commandments http://docs.openstack.org/developer/hacking/ diff --git a/README.rst b/README.rst index 2c1429b2..2d155571 100644 --- a/README.rst +++ b/README.rst @@ -5,35 +5,25 @@ developers and cloud administrators to publish various cloud-ready applications in a browsable‎ categorised catalog, which may be used by the cloud users (including the inexperienced ones) to pick-up the needed applications and services and composes the reliable environments out of them -in a “push-the-button” manner. +in a "push-the-button" manner. -murano-api ----------- -murano-api is a project that serves as service endpoint for communication -with a client. It exposes API via HTTP protocol to manipulate with different -object model entities representing environment and environment components -like applications. Project Resources ----------------- -* `Murano at Launchpad `__ -* `Wiki `__ -* `Code Review `__ -* `Sources `__ -* `Developers Guide `__ -How To Participate ------------------- -If you would like to ask some questions or make proposals, feel free to reach -us on #murano IRC channel at FreeNode. Typically somebody from our team will -be online at IRC from 6:00 to 20:00 UTC. You can also contact Murano community -directly by openstack-dev@lists.openstack.org adding [Murano] to a subject. +Project status, bugs, and blueprints are tracked on Launchpad: -We’re holding public weekly meetings on Tuesdays at 17:00 UTC -on #openstack-meeting-alt IRC channel at FreeNode. + https://launchpad.net/murano -If you want to contribute either to docs or to code, simply send us change -request via `gerrit `__. -You can `file bugs `__ and -`register blueprints `__ on -Launchpad. +Developer documentation can be found here: + + https://murano-api.readthedocs.org + +Additional resources are linked from the project wiki page: + + https://wiki.openstack.org/wiki/Murano + +License +------- + +Apache License Version 2.0 http://www.apache.org/licenses/LICENSE-2.0 diff --git a/contrib/devstack/README.md b/contrib/devstack/README.md deleted file mode 100644 index ea4afc56..00000000 --- a/contrib/devstack/README.md +++ /dev/null @@ -1,18 +0,0 @@ -The contrib/devstack/ directory contains the files necessary to integrate Murano with Devstack. - -To install: - - $ DEVSTACK_DIR=.../path/to/devstack - $ cp lib/murano ${DEVSTACK_DIR}/lib - $ cp lib/murano-dashboard ${DEVSTACK_DIR}/lib - $ cp extras.d/70-murano.sh ${DEVSTACK_DIR}/extras.d - -To configure Devstack to run Murano: - - $ cd ${DEVSTACK_DIR} - $ echo "enable_service murano" >> localrc - $ echo "enable_service murano-api" >> localrc - -Run devstack as normal: - - $ ./stack.sh diff --git a/contrib/devstack/README.rst b/contrib/devstack/README.rst new file mode 100644 index 00000000..fbcb0f38 --- /dev/null +++ b/contrib/devstack/README.rst @@ -0,0 +1,24 @@ +1. Follow Devstack documentation to setup a host for Devstack. Then clone + Devstack source code. + +2. Copy Murano integration scripts to Devstack:: + + $ cp lib/murano ${DEVSTACK_DIR}/lib + $ cp lib/murano-dashboard ${DEVSTACK_DIR}/lib + $ cp extras.d/70-murano.sh ${DEVSTACK_DIR}/extras.d + +3. Create a ``localrc`` file as input to devstack. + +4. The Murano services are not enabled by default, so they must be + enabled in ``localrc`` before running ``stack.sh``. This example ``localrc`` + file shows all of the settings required for Murano:: + + # Enable Heat + enable_service heat h-api h-api-cfn h-api-cw h-eng + + # Enable Murano + enable_service murano murano-api murano-engine + +5. Deploy your OpenStack Cloud with Murano:: + + $ ./stack.sh diff --git a/doc/source/_templates/sidebarlinks.html b/doc/source/_templates/sidebarlinks.html new file mode 100644 index 00000000..c4b3e665 --- /dev/null +++ b/doc/source/_templates/sidebarlinks.html @@ -0,0 +1,11 @@ +

Useful Links

+ + +{% if READTHEDOCS %} + +{% endif %} diff --git a/doc/source/_theme/layout.html b/doc/source/_theme/layout.html new file mode 100644 index 00000000..cd7ade1d --- /dev/null +++ b/doc/source/_theme/layout.html @@ -0,0 +1,4 @@ +{% extends "basic/layout.html" %} +{% set css_files = css_files + ['_static/tweaks.css'] %} + +{% block relbar1 %}{% endblock relbar1 %} \ No newline at end of file diff --git a/doc/source/_theme/theme.conf b/doc/source/_theme/theme.conf new file mode 100644 index 00000000..8c44b0ce --- /dev/null +++ b/doc/source/_theme/theme.conf @@ -0,0 +1,4 @@ +[theme] +inherit = nature +stylesheet = nature.css +pygments_style = tango \ No newline at end of file diff --git a/doc/source/conf.py b/doc/source/conf.py index 4ddfdb84..062ebba6 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -36,13 +36,12 @@ from muranoapi import __version_info as version # 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.intersphinx', -] +extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.todo', + 'sphinx.ext.coverage', 'sphinx.ext.pngmath', + 'sphinx.ext.viewcode'] -intersphinx_mapping = { - 'sphinx': ('http://sphinx.pocoo.org', None) -} +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] # The suffix of source filenames. source_suffix = '.rst' @@ -74,7 +73,15 @@ show_authors = False # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'default' +html_theme_path = ['.'] +html_theme = '_theme' + +# Custom sidebar templates, maps document names to template names. +html_sidebars = { + 'index': ['sidebarlinks.html', 'localtoc.html', 'searchbox.html', 'sourcelink.html'], + '**': ['localtoc.html', 'relations.html', + 'searchbox.html', 'sourcelink.html'] +} # -- Options for man page output -------------------------------------------- diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst new file mode 100644 index 00000000..ac7b6bcf --- /dev/null +++ b/doc/source/contributing.rst @@ -0,0 +1 @@ +.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/guidelines.rst b/doc/source/guidelines.rst new file mode 100644 index 00000000..f6e02759 --- /dev/null +++ b/doc/source/guidelines.rst @@ -0,0 +1,81 @@ +====================== +Development Guidelines +====================== + +Coding Guidelines +----------------- + +For all the code in Murano we have a rule - it should pass `PEP 8`_. + +To check your code against PEP 8 run: + +:: + + $ tox -e pep8 + + +.. seealso:: + + * https://pep8.readthedocs.org/en/latest/ + * https://flake8.readthedocs.org + * http://docs.openstack.org/developer/hacking/ + + +Testing Guidelines +------------------ + +Murano has a suite of tests that are run on all submitted code, +and it is recommended that developers execute the tests themselves to +catch regressions early. Developers are also expected to keep the +test suite up-to-date with any submitted code changes. + +Unit tests are located at ``muranoapi/tests``. + +Murano's suite of unit tests can be executed in an isolated environment +with `Tox`_. To execute the unit tests run the following from the root of +Murano repo on Python 2.7: + +:: + + $ tox -e py27 + +For Python 2.6: + +:: + + $ tox -e py26 + + +Documentation Guidelines +------------------------ + +Murano dev-docs are written using Sphinx / RST and located in the main repo +in ``doc`` directory. + +The documentation in docstrings should follow the `PEP 257`_ conventions +(as mentioned in the `PEP 8`_ guidelines). + +More specifically: + +1. Triple quotes should be used for all docstrings. +2. If the docstring is simple and fits on one line, then just use + one line. +3. For docstrings that take multiple lines, there should be a newline + after the opening quotes, and before the closing quotes. +4. `Sphinx`_ is used to build documentation, so use the restructured text + markup to designate parameters, return values, etc. Documentation on + the sphinx specific markup can be found here: + + + +Run the following command to build docs locally. + +:: + + $ tox -e docs + + +.. _PEP 8: http://www.python.org/dev/peps/pep-0008/ +.. _PEP 257: http://www.python.org/dev/peps/pep-0257/ +.. _Tox: http://tox.testrun.org/ +.. _Sphinx: http://sphinx.pocoo.org/markup/index.html diff --git a/doc/source/index.rst b/doc/source/index.rst index 23a870a4..063cbb77 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,11 +1,11 @@ .. - Copyright (c) 2013 Mirantis, Inc. + Copyright 2014 Mirantis, Inc. 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 + 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 @@ -13,112 +13,55 @@ License for the specific language governing permissions and limitations under the License. -============================================== -Welcome to Murano API Service! -============================================== - -Murano API is a project that provides access to engine via API. - -This document describes Murano API for contributors of the project, -and assumes that you are already familiar with Murano API from an -`end-user perspective`_. - -.. _`end-user perspective`: http://murano.mirantis.com/ - -This documentation is generated by the Sphinx toolkit and lives in the source -tree. - -Installation Guide ================== -Install -------- -1. Check out sources to some directory (/murano):: +Welcome to Murano! +================== - user@work:~/$ git clone https://github.com/Mirantis/murano-api.git +Introduction +============ -2. Install Murano API:: +Murano Project introduces an application catalog, which allows application +developers and cloud administrators to publish various cloud-ready applications +in a browsable categorised catalog. It may be used by the cloud users +(including the unexperienced ones) to pick-up the needed applications and +services and composes the reliable environments out of them in a +"push-the-button" manner. - user@work:~/$ cd murano/api && sudo python setup.py install +Key goal is to provide UI and API which allows to compose and deploy composite +environments on the Application abstraction level and then manage their +lifecycle. -Configure ---------- -1. Open first configuration file for editing:: - - user@work:~/$ cd murano/api/etc && nano murano-api.conf - -2. Configure according to you environment (please note rabbitmq section):: - - [DEFAULT] - # Show more verbose log output (sets INFO log level output) - verbose = True - # Show debugging output in logs (sets DEBUG log level output) - debug = True - # Address to bind the server to - bind_host = 0.0.0.0 - # Port the bind the server to - bind_port = 8082 - # Log to this file. Make sure the user running skeleton-api has - # permissions to write to this file! - log_file = /tmp/murano-api.log - #A valid SQLAlchemy connection string for the metadata database - sql_connection = sqlite:///murano.sqlite - - [reports] - results_exchange = task-results - results_queue = task-results - reports_exchange = task-reports - reports_queue = task-reports - - [rabbitmq] - host = localhost - port = 5672 - - # RabbitMQ credentials. Fresh RabbitMQ installation has "guest" account with "guest" password. - # It is recommended to create dedicated user account for Murano using RabbitMQ web console or command line utility - login = guest - password = guest - - # RabbitMQ virtual host (vhost). Fresh RabbitMQ installation has "/" vhost preconfigured. - # It is recommended to create dedicated vhost for Murano using RabbitMQ web console or command line utility - virtual_host = / - - ssl = False - ca_certs = +Murano consists of three source code repositories: + * `murano-api`_ - is the main repository. It contains code for Murano API + server, Murano engine and MuranoPL + * `murano-agent`_ - agent which runs on guest VMs and executes deployment + plan + * `murano-dashboard`_ - Murano UI implemented as a plugin for OpenStack + Dashboard -3. Open second configuration file for editing:: +.. _murano-api: https://git.openstack.org/cgit/stackforge/murano-api/ +.. _murano-agent: https://git.openstack.org/cgit/stackforge/murano-agent/ +.. _murano-dashboard: https://git.openstack.org/cgit/stackforge/murano-dashboard/ - smelikyan@work:~/cd murano/api/etc && nano murano-api.conf -4. Configure according to you environment (please note filter:authtoken section):: +This documentation offers information on how Murano works and how to +contribute to the project. - [pipeline:murano-api] - pipeline = authtoken context apiv1app - [app:apiv1app] - paste.app_factory = muranoapi.api.v1.router:API.factory - [filter:context] - paste.filter_factory = muranoapi.api.middleware.context:ContextMiddleware.factory - - [filter:authtoken] - paste.filter_factory = keystoneclient.middleware.auth_token:filter_factory - auth_host = localhost - auth_port = 35357 - auth_protocol = http - admin_tenant_name = admin - admin_user = admin - admin_password = password - signing_dir = /tmp/keystone-signing-muranoapi - -Run ----- -Run Murano API and supply valid configuration file:: - - user@work:~/$ murano-api --config-file=./murano/api/etc/murano-api.conf - -Man Pages -========= +Table of contents +================= .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - man/muranoapi + contributing + guidelines + install/index + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/doc/source/install/development.rst b/doc/source/install/development.rst new file mode 100644 index 00000000..bfef081b --- /dev/null +++ b/doc/source/install/development.rst @@ -0,0 +1,29 @@ +.. + Copyright 2014 2014 Mirantis, Inc. + + 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. + +================================================ + Installing and Running the Development Version +================================================ + +The `contrib/devstack`_ directory contains the files necessary to integrate +Murano with `Devstack`_. + + +.. include:: ../../../contrib/devstack/README.rst + + + +.. _Devstack: http://www.devstack.org/ +.. _contrib/devstack: https://git.openstack.org/cgit/stackforge/murano-api/tree/contrib/devstack diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 00000000..ea603a4d --- /dev/null +++ b/doc/source/install/index.rst @@ -0,0 +1,26 @@ +.. + Copyright 2014 Mirantis, Inc. + + 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. + +.. _install: + +================== + Installing Murano +================== + +.. toctree:: + :maxdepth: 2 + + development + manual diff --git a/doc/source/install/manual.rst b/doc/source/install/manual.rst new file mode 100644 index 00000000..4df7742c --- /dev/null +++ b/doc/source/install/manual.rst @@ -0,0 +1,104 @@ +.. + Copyright 2014 Mirantis, Inc. + + 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. + +.. _installing_manually: + +================================ + Installing and Running Manually +================================ + +Installing prerequisites +======================== + +First you need to install a number of packages with your OS package manager. +The list of packages depends on the OS you use. + +* For Ubuntu run: + + :: + + $ sudo apt-get install python-setuptools python-dev + +* For Fedora: + + :: + + $ sudo yum install gcc python-setuptools python-devel + + + .. note:: + Fedora support wasn't thoroughly tested. We do not guarantee that Murano + will work on Fedora. + +* For CentOS: + + :: + + $ sudo yum install gcc python-setuptools python-devel + $ sudo easy_install pip + + +Installing the API service and Engine +===================================== + +1. Clone the Murano git repository to the management server: + + :: + + $ cd /opt/stack + $ git clone https://git.openstack.org/stackforge/murano-api.git + +2. Configure the database. Murano can run with MySQL and SQLite. MySQL is + required for produciton installation, SQLite can be used for developemnt + purposes only. Let's setup MySQL database for Murano: + + :: + + $ apt-get install python-mysqldb mysql-server + $ mysql -u root -p + mysql> CREATE DATABASE murano; + mysql> GRANT ALL PRIVILEGES ON murano.* TO 'murano'@'localhost' \ + IDENTIFIED BY 'MURANO_DBPASS'; + mysql> exit; + +3. Copy the sample configuration from the source tree to their final location: + + :: + + $ mkdir -p /etc/murano + $ cp etc/murano/murano-api.conf.sample /etc/murano/murano-api.conf + $ cp etc/murano/murano-api-paste.ini /etc/murano/ + +4. Edit ``/etc/murano/murano-api.conf`` + + TODO(ruhe): document configuration options + +5. Create database tables for Murano: + + :: + + $ tox -e venv -- murano-manage --config-file /etc/murano/murano-api.conf db-sync + +6. Launch Murano API service: + + :: + + $ tox -e venv -- murano-api --config-file /etc/murano/murano-api.conf + +7. Launch Murano Engine service: + + :: + + $ tox -e venv -- murano-engine --config-file /etc/murano/murano-api.conf