[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,
|
||||
# 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'),
|
||||
]
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -1,6 +1,6 @@
|
|||
============================
|
||||
Murano Plugin for Fuel Guide
|
||||
============================
|
||||
================================
|
||||
The Murano Plugin for Fuel Guide
|
||||
================================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
|
|
@ -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:
|
||||
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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>`_.
|
||||
|
|
Loading…
Reference in New Issue