Merge "[Docs] Final edits"

This commit is contained in:
Jenkins 2016-09-02 16:26:03 +00:00 committed by Gerrit Code Review
commit 08edf9379b
8 changed files with 30 additions and 171 deletions

View File

@ -1,4 +1,8 @@
fuel-plugin-murano
==================
The Murano Plugin for Fuel
==========================
Plugin description
The Murano plugin for Fuel is a plugin to install the Application Catalog
Service for OpenStack. The Murano plugin provides flexibility for the
OpenStack Application Catalog service by supporting multiple releases and
versions. Also, the plugin provides the capability to install and run
Murano services on a standalone node, other than a controller node.

View File

@ -1,138 +0,0 @@
# Table of Contents
1. [Overview](#id-section1)
* [How to use](#id-section2)
* [How to build documentation] (#id-section3)
2. [Check yourself](#id-section4)
* [Plugin Guide checklist](#id-section5)
<div id='id-section1'/>
# Overview
If you are developing your own plugin for Fuel, you will also need to prepare
the documentation set, which includes Test Plan, Test Report, and Plugin Guide.
<div id='id-section2'/>
## How to use
This repo is organized as the doc tree with 2 main folders:
- plugin guide
- testing documentation
- Test Plan
- Test Report
To use these doc templates, follow these steps:
#. Clone the repo::
git clone git@github.com:Mirantis/fuel-plugin-docs.git
#. Populate the placeholders of the conf.py files (for Plugin Guide, Test Plan,
and Report) with plugin-specific information (e.g. document name, plugin
release).
#. Populate the content of RST files which make up the document structure.
<div id='id-section3'/>
## How to build documentation
Once you're done with editing the conf.py and sample RST files, you should cd
into the corresponding doc dir and run ``make latexpdf``.
For example::
cd plugin guide
make latexpdf
The PDF will be found in /build subdir.
<div id='id-section4'/>
## Check yourself
Please use the checklists below to make sure you documentation
meets the acceptance criteria.
<div id='id-section5'/>
### Plugin Guide
* The Plugin Guide contains plugin version in <fuel-plugin-name>-XX-XXX-X format.
* The **Overview** section provides information on the following:
* high-level description of plugin functionality/use case
* schemes (optional)
* The **Requirements** section provides information on the following:
* target MOS release (e.g. should be 8.0 not 8.0 and/or higher)
* required compatible proprietary Partner product version
* required compatible proprietary hw/software (if applicable)
* The **Prerequisites** section provides information on what should be done
prior to the solution installation/configuration, specifically:
* List of required HW/SW and how to get it (where to order or how to download).
* Compatible firmware versions (for HW) and software versions (for SW).
* A link to official documentation and configuration guides of used HW/SH
should be provided.
* How to configure required external hardware/software (e.g. storage devices,
switches and so on) so that user could use them via the the application/driver.
A simple configuration would be enough.
* If the solution can use specific HW/SW in several modes, then there should
be instructions on how to properly configure the hw/software to use this
very mode
* The **Limitations** should outline the issues that might limit the plugin
usage. Those can be:
* specific networking option available for the plugin (e.g. it can only use
Neutron VXLAN)
* known issues that might affect the plugin's operability (e.g. it's
impossible to use non-ASCII characters)
* The **Release Notes** section should describe how this plugin version differs
from the previous one.
* The **Installing the plugin** section provides commands and estimated output.
* The **Configuring the plugin** section provides the following information:
* It's clarified which MOS environment configuration should be used
(how many controller, computes, which options/services should be enabled).
All links to the official Mirantis OpenStack documentation are present.
It's also okay to provide screenshots.
* It's clarified how to configure MOS environment properly for the plugin
usage (e.g. how to configure interfaces for different logical networks Fuel
uses). It's also okay to provide screenshots.
* If the plugin requires specific role/naming convention, then this is also
outlined.
* UI part of the plugin should have detailed description and instructions
on where to get specific params. This should be done for every field and
example values should be provided.
* If the plugin supports several modes of usage, then there should be a flow
for each mode (e.g. each mode should be presented as the step-by-step
instruction with screenshots with all required UI elements listed in the
correct order): e.g. Select plugin checkbox, click a radio button,
fill in the text fields
* Network verification check is specified as the obligatory step prior to
deployment. If its expected to fail, this fact should be explicitly stated
and a reason should be provided.
* The **User Guide** should contain:
* baseline commands (CLI reference) with the estimated output (e.g. create
volumes, list volumes etc)
* links to external documentation (e.g. if all baseline issues are covered
in open source/proprietary documentation)
* The **Verification** section should explain how to verify that the plugin
works as expected (CLI, expected output).
* The **Troubleshooting** section should deliver specific guidaince on:
* how to make sure that all services are running
* how to check network connectivity (if needed)
* logs (where to find those, what to pay attention to)

View File

@ -199,7 +199,7 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'murano.tex', u'Murano plugin for Fuel Documentation',
('index', 'murano.tex', u'The Murano Plugin for Fuel Documentation',
u'Mirantis Inc.', 'manual'),
]

View File

@ -1,15 +1,11 @@
.. _pg-configure:
=======================
Configure Murano plugin
=======================
Configuring the Murano plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Once the *Murano Plugin* is installed, follow the instruction below to create
Once the Murano plugin is installed, follow the instruction below to create
an OpenStack environment with Murano services.
Plugin configuration
--------------------
**To configure the plugin:**
#. Create an OpenStack environment as described in the
@ -25,7 +21,7 @@ Plugin configuration
#. Configure the Murano plugin as required selecting the following available
settings.
:guilabel:`Murano Repository URL` specifies the murano applications
:guilabel:`Murano Repository URL` specifies the Murano applications
repository to import a package.
:guilabel:`Install Murano service broker for Cloud Foundry` enables Cloud

View File

@ -1,6 +1,6 @@
============================
Murano Plugin for Fuel Guide
============================
================================
The Murano Plugin for Fuel Guide
================================
.. toctree::
:maxdepth: 2

View File

@ -1,17 +1,16 @@
.. _pg-install:
========================
Installing Murano plugin
========================
Installing the Murano plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Before you install Murano plugin, verify that your environment meets the
requirements described in :ref:`pg-prerequisites`. You must have the Fuel
Before you install the Murano plugin, verify that your environment meets the
requirements described in :ref:`prerequisites`. You must have the Fuel
Master node installed and configured before you can install the plugin.
Typically, you install a Fuel plugin before you deploy an OpenStack environment.
**To install Murano plugin:**
**To install the Murano plugin:**
#. Download Murano plugin from the `Fuel Plugins Catalog`_.
#. Download the Murano plugin from the `Fuel Plugins Catalog`_.
#. Copy the plugin ``.rpm`` package to the Fuel Master node:

View File

@ -1,8 +1,7 @@
.. _overview:
========
Overview
========
~~~~~~~~
Murano plugin for Fuel is a plugin to install the Application Catalog Service
for OpenStack.
@ -11,10 +10,10 @@ service by supporting multiple releases and versions (for some Fuel version).
Also, the plugin provides the capability to detach Murano from the controller
node as a separate node.
.. _pg-prerequisites:
.. _prerequisites:
Software prerequisites
~~~~~~~~~~~~~~~~~~~~~~
----------------------
To use Murano plugin, verify that your environment meets the following prerequisites:
@ -25,12 +24,12 @@ Fuel 9.0
======================= =================================
Limitations
~~~~~~~~~~~
-----------
Murano plugin has no issues or limitations of usage.
Licenses
~~~~~~~~
--------
================= ============
**Component** **License**
@ -39,7 +38,7 @@ Murano plugin Apache 2.0
================= ============
References
~~~~~~~~~~
----------
For more information about Murano plugin for Fuel described in this document,
see:
@ -48,4 +47,4 @@ see:
* `Launchpad project <https://launchpad.net/fuel-plugin-murano>`__
* `GitHub project <http://git.openstack.org/cgit/openstack/fuel-plugin-murano>`__
* `GitHub project <http://git.openstack.org/cgit/openstack/fuel-plugin-murano>`__

View File

@ -1,8 +1,7 @@
.. _pg-update:
======================
Updating Murano plugin
======================
Updating the Murano plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~
To update the plugin, follow the steps described in the
`Fuel Plugins Guide <https://wiki.openstack.org/wiki/Fuel/Plugins#Plugin_versioning_system>`_.