openstack/os-brick
Code Issues Proposed changes

Update the documentation for os-brick

Browse Source 
This patch intends to update the base documenation that is built
for the os-brick library.  It includes the API documentation,
changelog, tutorial.

You can generate the documentation by running:
tox -edocs

DocImpact
Change-Id: Ia0fe0118207bbdc3cf698dfe09c0b71ebddd57f3
This commit is contained in:
Walter A. Boring IV 2015-02-17 16:55:34 -08:00
parent 2dc39e83d0
commit b3a392e5a2
16 changed files with 202 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
CONTRIBUTING.rst
View File

@ -13,4 +13,4 @@ Pull requests submitted through GitHub will be ignored.
Bugs should be filed on Launchpad, not GitHub:
https://bugs.launchpad.net/brick
https://bugs.launchpad.net/os-brick

7
README.rst
View File

@ -5,11 +5,12 @@ brick
OpenStack Cinder brick library for managing local volume attaches
* Free software: Apache license
* Documentation: http://docs.openstack.org/developer/brick
* Source: http://git.openstack.org/cgit/openstack/brick
* Documentation: http://docs.openstack.org/developer/os-brick
* Source: http://git.openstack.org/cgit/openstack/os-brick
* Bugs: http://bugs.launchpad.net/cinder
Features
--------
* TODO
* Discovery of volumes being attached to a host for many transport protocols.
* Removal of volumes from a host.

10
doc/source/api/index.rst Normal file
View File

@ -0,0 +1,10 @@
API Documentation
=================
The **os-brick** package provides the ability to collect host initiator
information as well as discovery volumes and removal of volumes from a host.
.. toctree::
:maxdepth: 2
os_brick/index

14
doc/source/api/os_brick/exception.rst Normal file
View File

@ -0,0 +1,14 @@
:mod:`exception` -- Exceptions
==============================
.. automodule:: os_brick.exception
:synopsis: Exceptions generated by os-brick
.. autoclass:: os_brick.exception.BrickException
.. autoclass:: os_brick.exception.NotFound
.. autoclass:: os_brick.exception.Invalid
.. autoclass:: os_brick.exception.InvalidParameterValue
.. autoclass:: os_brick.exception.NoFibreChannelHostsFound
.. autoclass:: os_brick.exception.NoFibreChannelVolumeDeviceFound
.. autoclass:: os_brick.exception.VolumeDeviceNotFound
.. autoclass:: os_brick.exception.ProtocolNotSupported

14
doc/source/api/os_brick/index.rst Normal file
View File

@ -0,0 +1,14 @@
:mod:`os_brick` -- OpenStack Brick library
==========================================
.. automodule:: os_brick
:synopsis: OpenStack Brick library
Sub-modules:
.. toctree::
:maxdepth: 2
initiator/index
exception

39
doc/source/api/os_brick/initiator/connector.rst Normal file
View File

@ -0,0 +1,39 @@
:mod:`connector` -- Connector
=============================
.. automodule:: os_brick.initiator.connector
:synopsis: Connector module for os-brick
.. autoclass:: os_brick.initiator.connector.InitiatorConnector
.. automethod:: factory
.. autoclass:: os_brick.initiator.connector.ISCSIConnector
.. automethod:: connect_volume
.. automethod:: disconnect_volume
.. autoclass:: os_brick.initiator.connector.ISERConnector
.. automethod:: connect_volume
.. automethod:: disconnect_volume
.. autoclass:: os_brick.initiator.connector.FibreChannelConnector
.. automethod:: connect_volume
.. automethod:: disconnect_volume
.. autoclass:: os_brick.initiator.connector.AoEConnector
.. automethod:: connect_volume
.. automethod:: disconnect_volume
.. autoclass:: os_brick.initiator.connector.LocalConnector
.. automethod:: connect_volume
.. automethod:: disconnect_volume
.. autoclass:: os_brick.initiator.connector.HuaweiStorHyperConnector
.. automethod:: connect_volume
.. automethod:: disconnect_volume

13
doc/source/api/os_brick/initiator/index.rst Normal file
View File

@ -0,0 +1,13 @@
:mod:`initiator` -- Initiator
=============================
.. automodule:: os_brick.initiator
:synopsis: Initiator module
Sub-modules:
.. toctree::
:maxdepth: 2
connector

6
doc/source/changelog.rst Normal file
View File

@ -0,0 +1,6 @@
os-brick Changelog history
==========================
1.0.0
-----
* First version of the library

4
doc/source/conf.py
View File

@ -37,8 +37,8 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = u'brick'
copyright = u'2013, OpenStack Foundation'
project = u'os-brick'
copyright = u'2015, OpenStack Foundation'
# If true, '()' will be appended to :func: etc. cross-reference text.
add_function_parentheses = True

14
doc/source/index.rst
View File

@ -1,10 +1,10 @@
Brick |release| Documenation
============================
os-brick |release| Documenation
===============================
Overview
--------
**Brick** is a Python package containing classes that help
with volume discover and creation for local storage.
**os-brick** is a Python package containing classes that help
with volume discovery and removal from a host.
:doc:`installation`
Instructions on how to get the distribution.
@ -18,15 +18,15 @@ with volume discover and creation for local storage.
Changes
-------
see the :doc:`changelog` for a full list of changes to **Brick**.
see the :doc:`changelog` for a full list of changes to **os-brick**.
About This Documentation
------------------------
This documentation is generated using the `Sphinx
<http://sphinx.pocoo.org/>`_ documentation generator. The source files
for the documentation are located in the *doc/* directory of the
**Brick** distribution. To generate the docs locally run the
following command from the root directory of the **Brick** source.
**os-brick** distribution. To generate the docs locally run the
following command from the root directory of the **os-brick** source.
.. code-block:: bash

12
doc/source/installation.rst
View File

@ -4,9 +4,15 @@ Installation
At the command line::
$ pip install brick
$ pip install os-brick
Or, if you have virtualenvwrapper installed::
$ mkvirtualenv brick
$ pip install brick
$ mkvirtualenv os-brick
$ pip install os-brick
Or, from source::
$ git clone https://github.com/openstack/os-brick
$ cd os-brick
$ python setup.py install

36
doc/source/tutorial.rst Normal file
View File

@ -0,0 +1,36 @@
Tutorial
========
This tutorial is intended as an introduction to working with
**os-brick**.
Prerequisites
-------------
Before we start, make sure that you have the **os-brick** distribution
:doc:`installed <installation>`. In the Python shell, the following
should run without raising an exception:
.. code-block:: bash
>>> import os_brick
Fetch all of the initiator information from the host
----------------------------------------------------
An example of how to collect the initiator information that is needed
to export a volume to this host.
.. code-block:: python
from os_brick.initiator import connector
# what helper do you want to use to get root access?
root_helper = "sudo"
# The ip address of the host you are running on
my_ip = "192.168.1.1"
# Do you want to support multipath connections?
multipath = True
# Do you want to enforce that multipath daemon is running?
enforce_multipath = False
initiator = connector.get_connector_properties(root_helper, my_ip,
multipath,
enforce_multipath)

7
doc/source/usage.rst
View File

@ -1,7 +0,0 @@
========
Usage
========
To use brick in a project::
import brick

19
os_brick/__init__.py
View File

@ -0,0 +1,19 @@
# 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.
"""
:mod:`os_brick` -- OpenStack host based volume management
=========================================================
.. autmodule:: os_brick
:synopsis: OpenStack host based volume management.
.. moduleauthor:: Walter A. Boring IV <walter.boring@hp.com>
"""

21
os_brick/initiator/__init__.py
View File

@ -0,0 +1,21 @@
# Copyright 2015 OpenStack Foundation
# All Rights Reserved.
#
# 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.
"""
Brick's Initiator module.
The initator module contains the capabilities for discovering the initiator
information as well as discovering and removing volumes from a host.
"""

7
os_brick/initiator/connector.py
View File

@ -12,6 +12,13 @@
# WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
# License for the specific language governing permissions and limitations
# under the License.
""" Brick Connector objects for each supported transport protocol.
.. module: connector
The connectors here are responsible for discovering and removing volumes for
each of the supported transport protocols.
"""
import copy
import os