Browse Source

doc: Restructure docs for doc-migration

We have three populated sections:

- install
- user
- reference

There are three docs removed, as they served little useful purpose and
were mostly unreferenced.

Sphinx's 'warning-is-error' option is enabled to catch the few issues
that has snuck into the docs.

Change-Id: I04e426faf337f0b03175f439c80b3369d4066733
changes/01/490901/3
Stephen Finucane 4 years ago
parent
commit
4fc0a51a17
  1. 1
      doc/source/changelog.rst
  2. 4
      doc/source/contributing.rst
  3. 58
      doc/source/index.rst
  4. 24
      doc/source/install/index.rst
  5. 18
      doc/source/installation.rst
  6. 1
      doc/source/readme.rst
  7. 0
      doc/source/reference/index.rst
  8. 0
      doc/source/reference/os_brick/exception.rst
  9. 0
      doc/source/reference/os_brick/index.rst
  10. 0
      doc/source/reference/os_brick/initiator/connector.rst
  11. 0
      doc/source/reference/os_brick/initiator/index.rst
  12. 36
      doc/source/tutorial.rst
  13. 38
      doc/source/user/tutorial.rst
  14. 8
      os_brick/initiator/connectors/local.py
  15. 1
      setup.cfg

1
doc/source/changelog.rst

@ -1 +0,0 @@
.. include:: ../../ChangeLog

4
doc/source/contributing.rst

@ -1,4 +0,0 @@
============
Contributing
============
.. include:: ../../CONTRIBUTING.rst

58
doc/source/index.rst

@ -1,50 +1,30 @@
os-brick |release| Documenation
===============================
========
os-brick
========
Overview
--------
**os-brick** is a Python package containing classes that help
with volume discovery and removal from a host.
`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.
Installation Guide
------------------
:doc:`tutorial`
Start here for a quick overview.
:doc:`api/index`
The complete API Documenation, organized by module.
Changes
-------
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
**os-brick** distribution. To generate the docs locally run the
following command from the root directory of the **os-brick** source.
.. code-block:: bash
.. toctree::
:maxdepth: 2
$ python setup.py doc
install/index
Usage Guide
-----------
.. toctree::
:hidden:
:maxdepth: 2
installation
tutorial
changelog
api/index
user/tutorial
Reference
---------
Indices and tables
==================
.. toctree::
:maxdepth: 2
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`
reference/index

24
doc/source/install/index.rst

@ -0,0 +1,24 @@
============
Installation
============
At the command line:
.. code-block:: shell
$ pip install os-brick
Or, if you have virtualenvwrapper installed:
.. code-block:: shell
$ mkvirtualenv os-brick
$ pip install os-brick
Or, from source:
.. code-block:: shell
$ git clone https://github.com/openstack/os-brick
$ cd os-brick
$ python setup.py install

18
doc/source/installation.rst

@ -1,18 +0,0 @@
============
Installation
============
At the command line::
$ pip install os-brick
Or, if you have virtualenvwrapper installed::
$ 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

1
doc/source/readme.rst

@ -1 +0,0 @@
.. include:: ../../README.rst

0
doc/source/api/index.rst → doc/source/reference/index.rst

0
doc/source/api/os_brick/exception.rst → doc/source/reference/os_brick/exception.rst

0
doc/source/api/os_brick/index.rst → doc/source/reference/os_brick/index.rst

0
doc/source/api/os_brick/initiator/connector.rst → doc/source/reference/os_brick/initiator/connector.rst

0
doc/source/api/os_brick/initiator/index.rst → doc/source/reference/os_brick/initiator/index.rst

36
doc/source/tutorial.rst

@ -1,36 +0,0 @@
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)

38
doc/source/user/tutorial.rst

@ -0,0 +1,38 @@
========
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 </install/index>`. 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)

8
os_brick/initiator/connectors/local.py

@ -45,10 +45,10 @@ class LocalConnector(base.BaseLinuxConnector):
def connect_volume(self, connection_properties):
"""Connect to a volume.
:param connection_properties: The dictionary that describes all
of the target volume attributes.
connection_properties must include:
device_path - path to the volume to be connected
:param connection_properties: The dictionary that describes all of the
target volume attributes. ``connection_properties`` must include:
- ``device_path`` - path to the volume to be connected
:type connection_properties: dict
:returns: dict
"""

1
setup.cfg

@ -35,6 +35,7 @@ tag_date = 0
tag_svn_revision = 0
[build_sphinx]
warning-is-error = 1
source-dir = doc/source
build-dir = doc/build
all_files = 1

Loading…
Cancel
Save