Fix package readme

The package was using the README.rst file that included a raw directive,
which is not allowed by PyPi, so the reame wasn't being rendered in
PyPi.

Makefile

@@ -26,7 +26,7 @@ BROWSER := python -c "$$BROWSER_PYSCRIPT"
 help:
 	@python -c "$$PRINT_HELP_PYSCRIPT" < $(MAKEFILE_LIST)
 
-clean: clean-build clean-pyc clean-test ## remove all build, test, coverage and Python artifacts
+clean: clean-build clean-pyc ## remove all build, coverage and Python artifacts
 
 
 clean-build: ## remove build artifacts
@@ -79,6 +79,13 @@ servedocs: docs ## compile the docs watching for changes
 register: ## register package in pypi
 	python setup.py register --repository pypi
 
+test-package:
+	python setup.py sdist
+
+test-release: clean
+	python setup.py sdist upload --repository pypitest
+	python setup.py bdist_wheel upload --repository pypitest
+
 release: clean ## package and upload a release
 	python setup.py sdist upload --repository pypi
 	python setup.py bdist_wheel upload --repository pypi

README.rst

@@ -1,75 +1,4 @@
-Cinder Library
+.. include:: readme_prefix.rst
-===============================
-
-.. image:: https://img.shields.io/pypi/v/cinderlib.svg
-   :target: https://pypi.python.org/pypi/cinderlib
-
-.. image:: https://readthedocs.org/projects/cinderlib/badge/?version=latest
-   :target: https://cinderlib.readthedocs.io/en/latest/?badge=latest
-   :alt: Documentation Status
-
-.. image:: https://img.shields.io/pypi/pyversions/cinderlib.svg
-   :target: https://pypi.python.org/pypi/cinderlib
-
-.. image:: https://img.shields.io/:license-apache-blue.svg
-   :target: http://www.apache.org/licenses/LICENSE-2.0
-
-
-Introduction
-------------
-
-Cinder Library is a Python library that allows using storage drivers outside of
-Cinder.
-
-* Free software: Apache Software License 2.0
-* Documentation: https://cinderlib.readthedocs.io.
-
-This library is currently in Alpha stage and is primarily intended as a proof
-of concept at this stage.  While some drivers have been manually validated most
-drivers have not, so there's a good chance that they could experience issues.
-
-When using this library one should be aware that this is in no way close to the
-robustness or feature richness that the Cinder project provides, for detailed
-information on the current limitations please refer to the documentation.
-
-Due to the limited access to Cinder backends and time constraints the list of
-drivers that have been manually tested are (I'll try to test more):
-
-- LVM with LIO
-- Dell EMC XtremIO
-- Dell EMC VMAX
-- Kaminario K2
-- Ceph/RBD
-- NetApp SolidFire
-
-If you try the library with another storage array I would appreciate a note on
-the library version, Cinder release, and results of your testing.
-
-Features
---------
-
-* Use a Cinder driver without running a DBMS, Message broker, or Cinder
-  service.
-* Using multiple simultaneous drivers on the same program.
-* Basic operations support:
-  - Create volume
-  - Delete volume
-  - Extend volume
-  - Clone volume
-  - Create snapshot
-  - Delete snapshot
-  - Create volume from snapshot
-  - Connect volume
-  - Disconnect volume
-  - Local attach
-  - Local detach
-  - Validate connector
-* Code should support multiple concurrent connections to a volume, though this
-  has not yet been tested.
-* Metadata persistence plugin:
-  - Stateless: Caller stores JSON serialization.
-  - Database: Metadata is stored in a database: MySQL, PostgreSQL, SQLite...
-  - Custom plugin: Metadata is stored in another metadata storage.
 
 Demo
 ----
@@ -80,108 +9,4 @@ Demo
   target="_blank"><img
   src="https://asciinema.org/a/TcTR7Lu7jI0pEsd9ThEn01l7n.png"/></a>
 
-Example
+.. include:: readme_postfix.rst
--------
-
-The following example uses CentOS 7 and the Cinder LVM driver, which should be
-the easiest to setup and test.
-
-First you need to setup your system:
-
-.. code-block:: shell
-
-    $ sudo yum install -y centos-release-openstack-pike
-    $ sudo yum install -y openstack-cinder targetcli python-pip
-    $ sudo pip install cinderlib
-    $ sudo dd if=/dev/zero of=cinder-volumes bs=1048576 seek=22527 count=1
-    $ sudo lodevice=`losetup --show -f ./cinder-volumes`
-    $ sudo pvcreate $lodevice
-    $ sudo vgcreate cinder-volumes $lodevice
-    $ sudo vgscan --cache
-
-Then you need to run `python`  with a passwordless sudo user (required to
-control LVM and do the attach) and execute:
-
-.. code-block:: python
-
-    import cinderlib as cl
-    from pprint import pprint as pp
-
-    # We setup the library to setup the driver configuration when serializing
-    cl.setup(output_all_backend_info=True)
-
-    # Initialize the LVM driver
-    lvm = cl.Backend(volume_driver='cinder.volume.drivers.lvm.LVMVolumeDriver',
-                     volume_group='cinder-volumes',
-                     iscsi_protocol='iscsi',
-                     iscsi_helper='lioadm',
-                     volume_backend_name='lvm_iscsi')
-
-    # Show the LVM backend stats
-    pp(lvm.stats())
-
-    # Create a 1GB volume
-    vol = lvm.create_volume(1, name='lvm-vol')
-
-    # Export, initialize, and do a local attach of the volume
-    attach = vol.attach()
-
-    pp('Volume %s attached to %s' % (vol.id, attach.path))
-
-    # Snapshot it
-    snap = vol.create_snapshot('lvm-snap')
-
-    # Show the JSON string
-    pp(vol.jsons)
-
-    # Save the whole environment to a file
-    with open('cinderlib-test.txt', 'w') as f:
-        f.write(cl.dumps())
-
-    # Exit python
-    exit()
-
-Now we can check that the logical volume is there, exported, and attached to
-our system:
-
-.. code-block:: shell
-
-    # lvdisplay
-    # targetcli ls
-    # iscsiadm -m session
-    # lsblk
-
-And now let's run a new `python` interpreter and clean things up:
-
-.. code-block:: python
-
-    import cinderlib as cl
-
-    # Get the whole environment up
-    with open('cinderlib-test.txt') as f:
-        backends = cl.load(f.read(), save=True)
-
-    # Get the volume reference we loaded from file and detach
-    vol = list(backends[0].volumes)[0]
-    vol.detach()
-
-    # Get the snapshot and delete it
-    snap = list(vol.snapshots)[0]
-    snap.delete()
-
-    # Finally delete the volume
-    vol.delete()
-
-We should confirm that the logical volume is no longer there, there's nothing
-exported or attached to our system:
-
-.. code-block:: shell
-
-    # lvdisplay
-    # targetcli ls
-    # iscsiadm -m session
-    # lsblk
-
-.. _GIGO: https://en.wikipedia.org/wiki/Garbage_in,_garbage_out
-.. _official project documentation: https://readthedocs.org/projects/cinderlib/badge/?version=latest
-.. _OpenStack's Cinder volume driver configuration documentation: https://docs.openstack.org/cinder/latest/configuration/block-storage/volume-drivers.html

readme_postfix.rst

@@ -0,0 +1,105 @@
+Example
+-------
+
+The following example uses CentOS 7 and the Cinder LVM driver, which should be
+the easiest to setup and test.
+
+First you need to setup your system:
+
+.. code-block:: shell
+
+    $ sudo yum install -y centos-release-openstack-pike
+    $ sudo yum install -y openstack-cinder targetcli python-pip
+    $ sudo pip install cinderlib
+    $ sudo dd if=/dev/zero of=cinder-volumes bs=1048576 seek=22527 count=1
+    $ sudo lodevice=`losetup --show -f ./cinder-volumes`
+    $ sudo pvcreate $lodevice
+    $ sudo vgcreate cinder-volumes $lodevice
+    $ sudo vgscan --cache
+
+Then you need to run `python`  with a passwordless sudo user (required to
+control LVM and do the attach) and execute:
+
+.. code-block:: python
+
+    import cinderlib as cl
+    from pprint import pprint as pp
+
+    # We setup the library to setup the driver configuration when serializing
+    cl.setup(output_all_backend_info=True)
+
+    # Initialize the LVM driver
+    lvm = cl.Backend(volume_driver='cinder.volume.drivers.lvm.LVMVolumeDriver',
+                     volume_group='cinder-volumes',
+                     iscsi_protocol='iscsi',
+                     iscsi_helper='lioadm',
+                     volume_backend_name='lvm_iscsi')
+
+    # Show the LVM backend stats
+    pp(lvm.stats())
+
+    # Create a 1GB volume
+    vol = lvm.create_volume(1, name='lvm-vol')
+
+    # Export, initialize, and do a local attach of the volume
+    attach = vol.attach()
+
+    pp('Volume %s attached to %s' % (vol.id, attach.path))
+
+    # Snapshot it
+    snap = vol.create_snapshot('lvm-snap')
+
+    # Show the JSON string
+    pp(vol.jsons)
+
+    # Save the whole environment to a file
+    with open('cinderlib-test.txt', 'w') as f:
+        f.write(cl.dumps())
+
+    # Exit python
+    exit()
+
+Now we can check that the logical volume is there, exported, and attached to
+our system:
+
+.. code-block:: shell
+
+    # lvdisplay
+    # targetcli ls
+    # iscsiadm -m session
+    # lsblk
+
+And now let's run a new `python` interpreter and clean things up:
+
+.. code-block:: python
+
+    import cinderlib as cl
+
+    # Get the whole environment up
+    with open('cinderlib-test.txt') as f:
+        backends = cl.load(f.read(), save=True)
+
+    # Get the volume reference we loaded from file and detach
+    vol = list(backends[0].volumes)[0]
+    vol.detach()
+
+    # Get the snapshot and delete it
+    snap = list(vol.snapshots)[0]
+    snap.delete()
+
+    # Finally delete the volume
+    vol.delete()
+
+We should confirm that the logical volume is no longer there, there's nothing
+exported or attached to our system:
+
+.. code-block:: shell
+
+    # lvdisplay
+    # targetcli ls
+    # iscsiadm -m session
+    # lsblk
+
+.. _GIGO: https://en.wikipedia.org/wiki/Garbage_in,_garbage_out
+.. _official project documentation: https://readthedocs.org/projects/cinderlib/badge/?version=latest
+.. _OpenStack's Cinder volume driver configuration documentation: https://docs.openstack.org/cinder/latest/configuration/block-storage/volume-drivers.html

readme_prefix.rst

@@ -0,0 +1,76 @@
+Cinder Library
+===============================
+
+.. image:: https://img.shields.io/pypi/v/cinderlib.svg
+   :target: https://pypi.python.org/pypi/cinderlib
+
+.. image:: https://readthedocs.org/projects/cinderlib/badge/?version=latest
+   :target: https://cinderlib.readthedocs.io/en/latest/?badge=latest
+   :alt: Documentation Status
+
+.. image:: https://img.shields.io/pypi/pyversions/cinderlib.svg
+   :target: https://pypi.python.org/pypi/cinderlib
+
+.. image:: https://img.shields.io/:license-apache-blue.svg
+   :target: http://www.apache.org/licenses/LICENSE-2.0
+
+
+Introduction
+------------
+
+Cinder Library is a Python library that allows using storage drivers outside of
+Cinder.
+
+* Free software: Apache Software License 2.0
+* Documentation: https://cinderlib.readthedocs.io.
+
+This library is currently in Alpha stage and is primarily intended as a proof
+of concept at this stage.  While some drivers have been manually validated most
+drivers have not, so there's a good chance that they could experience issues.
+
+When using this library one should be aware that this is in no way close to the
+robustness or feature richness that the Cinder project provides, for detailed
+information on the current limitations please refer to the documentation.
+
+Due to the limited access to Cinder backends and time constraints the list of
+drivers that have been manually tested are (I'll try to test more):
+
+- LVM with LIO
+- Dell EMC XtremIO
+- Dell EMC VMAX
+- Kaminario K2
+- Ceph/RBD
+- NetApp SolidFire
+
+If you try the library with another storage array I would appreciate a note on
+the library version, Cinder release, and results of your testing.
+
+Features
+--------
+
+* Use a Cinder driver without running a DBMS, Message broker, or Cinder
+  service.
+* Using multiple simultaneous drivers on the same program.
+* Basic operations support:
+
+  - Create volume
+  - Delete volume
+  - Extend volume
+  - Clone volume
+  - Create snapshot
+  - Delete snapshot
+  - Create volume from snapshot
+  - Connect volume
+  - Disconnect volume
+  - Local attach
+  - Local detach
+  - Validate connector
+
+* Code should support multiple concurrent connections to a volume, though this
+  has not yet been tested.
+* Metadata persistence plugin:
+
+  - Stateless: Caller stores JSON serialization.
+  - Database: Metadata is stored in a database: MySQL, PostgreSQL, SQLite...
+  - Custom plugin: Metadata is stored in another metadata storage.
+

requirements_dev.txt

@@ -2,11 +2,12 @@ unittest2
 pyyaml
 pip==8.1.2
 bumpversion==0.5.3
-wheel==0.29.0
+wheel==0.31.1
 watchdog==0.8.3
 flake8==2.6.0
 tox==2.3.1
 coverage==4.1
 Sphinx==1.6.5
 mock==2.0.0
+readme_renderer==21.0
 git+https://github.com/openstack/cinder.git@stable/pike

setup.py

@@ -3,9 +3,12 @@
 
 import setuptools
 
-with open('README.rst') as readme_file:
+with open('readme_prefix.rst') as readme_file:
     readme = readme_file.read()
 
+with open('readme_postfix.rst') as readme_file:
+    readme += readme_file.read()
+
 with open('HISTORY.rst') as history_file:
     history = history_file.read()
 
@@ -59,7 +62,7 @@ setuptools.setup(
     packages=setuptools.find_packages(exclude=['tmp', 'tests*']),
     include_package_data=False,
     install_requires=requirements,
-    extras_requires=extras,
+    extras_require=extras,
     license="Apache Software License 2.0",
     zip_safe=False,
     keywords='cinderlib',