diff --git a/doc/source/changelog.rst b/doc/source/changelog.rst deleted file mode 100644 index 69ed4fe6c..000000000 --- a/doc/source/changelog.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../ChangeLog diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst deleted file mode 100644 index 1728a61ca..000000000 --- a/doc/source/contributing.rst +++ /dev/null @@ -1,4 +0,0 @@ -============ -Contributing -============ -.. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index 2f224ee28..496779343 100644 --- a/doc/source/index.rst +++ b/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. - -:doc:`installation` - Instructions on how to get the distribution. - -: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 -`_ 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 - - $ python setup.py doc +`os-brick` is a Python package containing classes that help with volume +discovery and removal from a host. +Installation Guide +------------------ .. toctree:: - :hidden: + :maxdepth: 2 - installation - tutorial - changelog - api/index + install/index +Usage Guide +----------- -Indices and tables -================== +.. toctree:: + :maxdepth: 2 -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + user/tutorial + +Reference +--------- + +.. toctree:: + :maxdepth: 2 + + reference/index diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst new file mode 100644 index 000000000..b80e4bb89 --- /dev/null +++ b/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 diff --git a/doc/source/installation.rst b/doc/source/installation.rst deleted file mode 100644 index b7509d80b..000000000 --- a/doc/source/installation.rst +++ /dev/null @@ -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 diff --git a/doc/source/readme.rst b/doc/source/readme.rst deleted file mode 100644 index a6210d3d8..000000000 --- a/doc/source/readme.rst +++ /dev/null @@ -1 +0,0 @@ -.. include:: ../../README.rst diff --git a/doc/source/api/index.rst b/doc/source/reference/index.rst similarity index 100% rename from doc/source/api/index.rst rename to doc/source/reference/index.rst diff --git a/doc/source/api/os_brick/exception.rst b/doc/source/reference/os_brick/exception.rst similarity index 100% rename from doc/source/api/os_brick/exception.rst rename to doc/source/reference/os_brick/exception.rst diff --git a/doc/source/api/os_brick/index.rst b/doc/source/reference/os_brick/index.rst similarity index 100% rename from doc/source/api/os_brick/index.rst rename to doc/source/reference/os_brick/index.rst diff --git a/doc/source/api/os_brick/initiator/connector.rst b/doc/source/reference/os_brick/initiator/connector.rst similarity index 100% rename from doc/source/api/os_brick/initiator/connector.rst rename to doc/source/reference/os_brick/initiator/connector.rst diff --git a/doc/source/api/os_brick/initiator/index.rst b/doc/source/reference/os_brick/initiator/index.rst similarity index 100% rename from doc/source/api/os_brick/initiator/index.rst rename to doc/source/reference/os_brick/initiator/index.rst diff --git a/doc/source/tutorial.rst b/doc/source/tutorial.rst deleted file mode 100644 index 140d6adc4..000000000 --- a/doc/source/tutorial.rst +++ /dev/null @@ -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 `. 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) diff --git a/doc/source/user/tutorial.rst b/doc/source/user/tutorial.rst new file mode 100644 index 000000000..eb66e6e97 --- /dev/null +++ b/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 `. 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) diff --git a/os_brick/initiator/connectors/local.py b/os_brick/initiator/connectors/local.py index 4741bcd0c..a018f141d 100644 --- a/os_brick/initiator/connectors/local.py +++ b/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 """ diff --git a/setup.cfg b/setup.cfg index 9fb46861f..28a7faa0f 100644 --- a/setup.cfg +++ b/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