diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst
index 3c0d8244d..a3e931e60 100644
--- a/CONTRIBUTING.rst
+++ b/CONTRIBUTING.rst
@@ -1,16 +1,18 @@
-If you would like to contribute to the development of OpenStack,
-you must follow the steps documented at:
+The source repository for this project can be found at:
- https://docs.openstack.org/infra/manual/developers.html
+ https://opendev.org/openstack/python-manilaclient
-Once those steps have been completed, changes to OpenStack
-should be submitted for review via the Gerrit tool, following
-the workflow documented at:
+Pull requests submitted through GitHub are not monitored.
- https://docs.openstack.org/infra/manual/developers.html#development-workflow
+To start contributing to OpenStack, follow the steps in the contribution guide
+to set up and use Gerrit:
-Pull requests submitted through GitHub will be ignored.
-
-Bugs should be filed on Launchpad, not GitHub:
+ https://docs.openstack.org/contributors/code-and-documentation/quick-start.html
+Bugs should be filed on Launchpad
https://bugs.launchpad.net/python-manilaclient
+
+For more specific information about contributing to this repository, see the
+python-manilaclient contributor guide:
+
+ https://docs.openstack.org/python-manilaclient/latest/contributor/contributing.html
diff --git a/doc/source/contributor/contributing.rst b/doc/source/contributor/contributing.rst
new file mode 100644
index 000000000..45bcb6c34
--- /dev/null
+++ b/doc/source/contributor/contributing.rst
@@ -0,0 +1,56 @@
+============================
+So You Want to Contribute...
+============================
+
+For general information on contributing to OpenStack, check out the
+`contributor guide `_ to get started.
+It covers all the basics that are common to all OpenStack projects: the
+accounts you need, the basics of interacting with our Gerrit review system,
+how we communicate as a community, etc.
+
+This project contains a python SDK and command line clients to interact with
+the API exposed by `Manila `_,
+the OpenStack Shared File Systems service. Refer to the `Contributor guide
+for Manila `_
+for information regarding the team's task trackers, communicating with other
+project developers and contacting the core team.
+
+Bugs
+~~~~
+
+You found an issue and want to make sure we are aware of it? You can do so on
+`Launchpad `_.
+
+If you're looking to contribute, search for the `low-hanging-fruit`_ tag to
+see issues that are easier to get started with.
+
+.. _project-structure:
+
+Project Structure
+~~~~~~~~~~~~~~~~~
+
+This project includes three distinct components:
+
+- manilaclient SDK: python bindings for Manila API `version V1`_ and
+ `version V2`_
+- manilaclient shell: A `command line utility`_ (``manila``)
+- OpenStack client shell: A `plugin to support the OpenStack Client`_
+ Command Line Interface.
+
+The version 2 of the API for Manila supports microversions. The manilaclient
+library is expected to handle these for complete backwards compatibility.
+All versions of the Manila API are currently supported, however, future
+releases of manilaclient may drop support for older versions of the API.
+
+If you're working on the OpenStack Client command line interface plugin that
+exists in this project, do read the `OpenStack Client Developer
+Documentation`_. This includes the Human Interface Guide and some design
+priciples including command structure and command specs that you will find
+helpful.
+
+.. _low-hanging-fruit: https://bugs.launchpad.net/python-manilaclient/+bugs?field.tag=low-hanging-fruit
+.. _version V1: https://opendev.org/openstack/python-manilaclient/src/branch/master/manilaclient/v1
+.. _version V2: https://opendev.org/openstack/python-manilaclient/src/branch/master/manilaclient/v2
+.. _command line utility: https://opendev.org/openstack/python-manilaclient/src/branch/master/manilaclient/shell.py
+.. _plugin to support the OpenStack Client: https://opendev.org/openstack/python-manilaclient/src/branch/master/manilaclient/osc
+.. _OpenStack Client Developer Documentation: https://docs.openstack.org/python-openstackclient/latest/contributor/index.html
\ No newline at end of file
diff --git a/doc/source/contributor/functional-tests.rst b/doc/source/contributor/functional-tests.rst
index d03c7e5ef..0425acd5a 100644
--- a/doc/source/contributor/functional-tests.rst
+++ b/doc/source/contributor/functional-tests.rst
@@ -1,8 +1,9 @@
Functional tests
================
-Manila contains a suite of functional tests under the
-python-manilaclient/tests/functional directory.
+There is a suite of functional tests under the
+python-manilaclient/tests/functional directory. Unlike unit tests, these
+tests perform API calls to Manila and are designed to run on a DevStack.
Adding functional tests to your changes is not mandatory but it's certainly
a good practice and it's encouraged.
@@ -10,10 +11,22 @@ a good practice and it's encouraged.
Prerequisite
------------
-You need to have manila running somewhere. If you are using devstack, you can enable
-manila by enabling the manila plugin and selecting the backend you want to use.
+You need to have manila running somewhere. If you wish to use DevStack to
+run manila, a good place to start would be the `manila contributor guide`_.
-As an example, you can use the following local.conf file
+.. note::
+
+ We absolutely recommend using a ``fake shared file system back end`` as
+ opposed to a real storage system, because our tests are written with the
+ assumption that all APIs manila exposes are usable. In reality,
+ different real world storage back ends have `different capabilities`_ and
+ this project doesn't need to worry about them to provide a general purpose
+ interface to Manila. A fake driver provides fake storage, so don't
+ expect to be able to mount or use the shared file systems that you
+ create with it.
+
+You can use the following local.conf file to configure DevStack including
+Manila using a few fake back ends:
.. code-block:: console
@@ -21,15 +34,15 @@ As an example, you can use the following local.conf file
# auth
ADMIN_PASSWORD=nomoresecret
- DATABASE_PASSWORD=stackdb
- RABBIT_PASSWORD=stackqueue
+ DATABASE_PASSWORD=$ADMIN_PASSWORD
+ RABBIT_PASSWORD=$ADMIN_PASSWORD
SERVICE_PASSWORD=$ADMIN_PASSWORD
- # enable logging
+ # enable logging for DevStack
LOGFILE=/opt/stack/logs/stack.sh.log
+
+ # Logging mode for DevStack services
VERBOSE=True
- LOG_COLOR=True
- LOGDIR=/opt/stack/logs
# manila
enable_plugin manila https://opendev.org/openstack/manila
@@ -37,10 +50,6 @@ As an example, you can use the following local.conf file
# python-manilaclient
LIBS_FROM_GIT=python-manilaclient
- # versioning
- PYTHON3_VERSION=3.6
- IDENTITY_API_VERSION=3
-
# share driver
SHARE_DRIVER=manila.tests.share.drivers.dummy.DummyDriver
@@ -96,24 +105,23 @@ As an example, you can use the following local.conf file
MANILA_OPTGROUP_adminnet_standalone_network_plugin_allowed_ip_ranges=11.0.0.10-11.0.0.19,11.0.0.30-11.0.0.39,11.0.0.50-11.0.0.199
MANILA_OPTGROUP_adminnet_network_plugin_ipv4_enabled=True
-In this example we enable manila with the DummyDriver.
-
Configuration
-------------
-The functional tests require a couple of configuration files, so you will need to generate them yourself.
+The functional tests require a couple of configuration files, so you will need
+to generate them before running the tests.
-For devstack
+For DevStack
^^^^^^^^^^^^
-If you are using devstack, you can run the following script
+On your DevStack machine, you can run the following script. It assumes that
+``devstack`` is cloned onto your base folder.
.. code-block:: console
- export HOME=${LOCAL:-/home/}
- export DEST=${DEST:-/opt/stack}
- export MANILACLIENT_DIR=${MANILACLIENT_DIR:-$DEST/python-manilaclient}
- export MANILACLIENT_CONF="$MANILACLIENT_DIR/etc/manilaclient/manilaclient.conf"
+ DEST=${DEST:-/opt/stack}
+ MANILACLIENT_DIR=${MANILACLIENT_DIR:-$DEST/python-manilaclient}
+ MANILACLIENT_CONF="$MANILACLIENT_DIR/etc/manilaclient/manilaclient.conf"
# Go to the manilaclient dir
cd $MANILACLIENT_DIR
# Give permissions
@@ -177,15 +185,18 @@ If you are using devstack, you can run the following script
fi
-Change to the correct user value.
-
Running the tests
-----------------
-To run all functional tests make sure you are in the top level of your python-manilaclient
-module (e.g. /opt/stack/python-manilaclient/) and simply run::
+To run all functional tests make sure you are in the top level of your
+python-manilaclient module (e.g. /opt/stack/python-manilaclient/) and simply
+run::
tox -e functional
This will create a virtual environment, load all the packages from
-test-requirements.txt and run all functional tests.
\ No newline at end of file
+test-requirements.txt and run all functional tests.
+
+
+.. _manila contributor guide: https://docs.openstack.org/manila/latest/contributor/development-environment-devstack.html
+.. _different capabilities: https://docs.openstack.org/manila/latest/admin/share_back_ends_feature_support_mapping.html
\ No newline at end of file
diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst
index 25e912c2e..2b6fd9439 100644
--- a/doc/source/contributor/index.rst
+++ b/doc/source/contributor/index.rst
@@ -1,13 +1,13 @@
Contributing
============
-Code is hosted at `opendev.org`_. Submit bugs to the
-python-manilaclient project on `Launchpad`_. Submit code to the
-openstack/python-manilaclient project using `Gerrit`_.
+Basic Information
+-----------------
-.. _opendev.org: https://opendev.org/openstack/python-manilaclient
-.. _Launchpad: https://launchpad.net/python-manilaclient
-.. _Gerrit: https://docs.openstack.org/infra/manual/developers.html#development-workflow
+.. toctree::
+ :maxdepth: 3
+
+ contributing
Testing
-------
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 54a5cd22c..9df60f13a 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -4,39 +4,39 @@ Python bindings to the OpenStack Manila API
This is a client for OpenStack Manila API. There's :doc:`a Python API
` (the :mod:`manilaclient` module), and a :doc:`command-line script
` (installed as :program:`manila`). Each implements the entire
-OpenStack Manila API.
+OpenStack Manila API. See :ref:`project-structure` for more information.
You'll need credentials for an OpenStack cloud that implements the
Manila API in order to use the manila client.
Command-Line Reference
-======================
+~~~~~~~~~~~~~~~~~~~~~~
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
user/shell
-API
-===
+Using the python module
+~~~~~~~~~~~~~~~~~~~~~~~
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
user/api
Contributing
-============
+~~~~~~~~~~~~
.. toctree::
- :maxdepth: 1
+ :maxdepth: 2
contributor/index
.. only:: html
Indices and tables
- ==================
+ ~~~~~~~~~~~~~~~~~~
* :ref:`genindex`
* :ref:`search`
diff --git a/doc/source/user/api.rst b/doc/source/user/api.rst
index c923520bf..8c67f998d 100644
--- a/doc/source/user/api.rst
+++ b/doc/source/user/api.rst
@@ -22,7 +22,7 @@ done so, you can use the API like so::
ce06d0a8-5c1b-4e2c-81d2-39eca6bbfb70
>>> manila.shares.list()
[]
- >>>share.delete
+ >>> share.delete
In addition to creating and deleting shares, the manilaclient can manage
share-types, access controls, and more! Using CephFS with Ganesha for NFS