[Docs] Final edits
Edits the plugin guide. Change-Id: Ice2cc8dd6991eaa3678c070c5faec68646502f08
This commit is contained in:
parent
3c078ac700
commit
e9821df117
10
README.md
10
README.md
|
@ -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.
|
138
docs/README.md
138
docs/README.md
|
@ -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 it’s 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)
|
|
|
@ -199,7 +199,7 @@ latex_elements = {
|
||||||
# (source start file, target name, title,
|
# (source start file, target name, title,
|
||||||
# author, documentclass [howto, manual, or own class]).
|
# author, documentclass [howto, manual, or own class]).
|
||||||
latex_documents = [
|
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'),
|
u'Mirantis Inc.', 'manual'),
|
||||||
]
|
]
|
||||||
|
|
||||||
|
|
|
@ -1,15 +1,11 @@
|
||||||
.. _pg-configure:
|
.. _pg-configure:
|
||||||
|
|
||||||
=======================
|
Configuring the Murano plugin
|
||||||
Configure 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.
|
an OpenStack environment with Murano services.
|
||||||
|
|
||||||
Plugin configuration
|
|
||||||
--------------------
|
|
||||||
|
|
||||||
**To configure the plugin:**
|
**To configure the plugin:**
|
||||||
|
|
||||||
#. Create an OpenStack environment as described in the
|
#. Create an OpenStack environment as described in the
|
||||||
|
@ -25,7 +21,7 @@ Plugin configuration
|
||||||
#. Configure the Murano plugin as required selecting the following available
|
#. Configure the Murano plugin as required selecting the following available
|
||||||
settings.
|
settings.
|
||||||
|
|
||||||
:guilabel:`Murano Repository URL` specifies the murano applications
|
:guilabel:`Murano Repository URL` specifies the Murano applications
|
||||||
repository to import a package.
|
repository to import a package.
|
||||||
|
|
||||||
:guilabel:`Install Murano service broker for Cloud Foundry` enables Cloud
|
:guilabel:`Install Murano service broker for Cloud Foundry` enables Cloud
|
||||||
|
|
|
@ -1,6 +1,6 @@
|
||||||
============================
|
================================
|
||||||
Murano Plugin for Fuel Guide
|
The Murano Plugin for Fuel Guide
|
||||||
============================
|
================================
|
||||||
|
|
||||||
.. toctree::
|
.. toctree::
|
||||||
:maxdepth: 2
|
:maxdepth: 2
|
||||||
|
|
|
@ -1,17 +1,16 @@
|
||||||
.. _pg-install:
|
.. _pg-install:
|
||||||
|
|
||||||
========================
|
Installing the Murano plugin
|
||||||
Installing Murano plugin
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
========================
|
|
||||||
|
|
||||||
Before you install Murano plugin, verify that your environment meets the
|
Before you install the Murano plugin, verify that your environment meets the
|
||||||
requirements described in :ref:`pg-prerequisites`. You must have the Fuel
|
requirements described in :ref:`prerequisites`. You must have the Fuel
|
||||||
Master node installed and configured before you can install the plugin.
|
Master node installed and configured before you can install the plugin.
|
||||||
Typically, you install a Fuel plugin before you deploy an OpenStack environment.
|
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:
|
#. Copy the plugin ``.rpm`` package to the Fuel Master node:
|
||||||
|
|
||||||
|
|
|
@ -1,8 +1,7 @@
|
||||||
.. _overview:
|
.. _overview:
|
||||||
|
|
||||||
========
|
|
||||||
Overview
|
Overview
|
||||||
========
|
~~~~~~~~
|
||||||
|
|
||||||
Murano plugin for Fuel is a plugin to install the Application Catalog Service
|
Murano plugin for Fuel is a plugin to install the Application Catalog Service
|
||||||
for OpenStack.
|
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
|
Also, the plugin provides the capability to detach Murano from the controller
|
||||||
node as a separate node.
|
node as a separate node.
|
||||||
|
|
||||||
.. _pg-prerequisites:
|
.. _prerequisites:
|
||||||
|
|
||||||
Software prerequisites
|
Software prerequisites
|
||||||
~~~~~~~~~~~~~~~~~~~~~~
|
----------------------
|
||||||
|
|
||||||
To use Murano plugin, verify that your environment meets the following prerequisites:
|
To use Murano plugin, verify that your environment meets the following prerequisites:
|
||||||
|
|
||||||
|
@ -25,12 +24,12 @@ Fuel 9.0
|
||||||
======================= =================================
|
======================= =================================
|
||||||
|
|
||||||
Limitations
|
Limitations
|
||||||
~~~~~~~~~~~
|
-----------
|
||||||
|
|
||||||
Murano plugin has no issues or limitations of usage.
|
Murano plugin has no issues or limitations of usage.
|
||||||
|
|
||||||
Licenses
|
Licenses
|
||||||
~~~~~~~~
|
--------
|
||||||
|
|
||||||
================= ============
|
================= ============
|
||||||
**Component** **License**
|
**Component** **License**
|
||||||
|
@ -39,7 +38,7 @@ Murano plugin Apache 2.0
|
||||||
================= ============
|
================= ============
|
||||||
|
|
||||||
References
|
References
|
||||||
~~~~~~~~~~
|
----------
|
||||||
|
|
||||||
For more information about Murano plugin for Fuel described in this document,
|
For more information about Murano plugin for Fuel described in this document,
|
||||||
see:
|
see:
|
||||||
|
@ -48,4 +47,4 @@ see:
|
||||||
|
|
||||||
* `Launchpad project <https://launchpad.net/fuel-plugin-murano>`__
|
* `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>`__
|
|
@ -1,8 +1,7 @@
|
||||||
.. _pg-update:
|
.. _pg-update:
|
||||||
|
|
||||||
======================
|
Updating the Murano plugin
|
||||||
Updating Murano plugin
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
======================
|
|
||||||
|
|
||||||
To update the plugin, follow the steps described in the
|
To update the plugin, follow the steps described in the
|
||||||
`Fuel Plugins Guide <https://wiki.openstack.org/wiki/Fuel/Plugins#Plugin_versioning_system>`_.
|
`Fuel Plugins Guide <https://wiki.openstack.org/wiki/Fuel/Plugins#Plugin_versioning_system>`_.
|
||||||
|
|
Loading…
Reference in New Issue