Improve README file and add an initial Sphinx environment

Change-Id: I06e892f2259ab29698b100145e57c9410fba8eea

README.rst

@@ -1,36 +1,70 @@
-ospurge: OpenStack project resources cleaner
+OpenStack project resources cleaner
-********************************************
+===================================
 
-``ospurge`` is a standalone, client-side, Python script that aims at
+* ``ospurge`` is a standalone, client-side, operators tool that aims at
-deleting all resources (taking into account their interdependencies)
+  deleting all resources, taking into account their interdependencies,
-in a specified OpenStack project. OSPurge ensures in a quick and
+  in a specified OpenStack project.
-automated way that no resource is left behind when a project is
+
-deleted.
+* ``ospurge`` ensures in a quick and automated way that no resource is
+  left behind when a project is deleted.
+
+* ``ospurge`` can be used by a cloud administrator, this means a user with the
+  admin role, to cleanup any project or by a non-privileged user to cleanup his
+  own project.
+
+
+Supported resources
+-------------------
+
+At the moment it is possible to purge the following resources from a project:
+
+* Ceilometer alarms
+* floating IP addresses
+* images / snapshots
+* instances
+* networks
+* routers
+* security groups
+* Swift containers
+* Swift objects
+* volumes / snapshots
+
+
+Error codes
+-----------
+
+The following error codes are returned when ``ospurge`` encounters
+an error:
+
+* ``Code 0``: Process exited sucessfully
+* ``Code 1``: Unknown error
+* ``Code 2``: Project doesn't exist
+* ``Code 3``: Authentication failed (e.g. bad username or password)
+* ``Code 4``: Resource deletion failed
+* ``Code 5``: Connection error while deleting a resource (e.g. service not
+  available)
+* ``Code 6``: Connection to endpoint failed (e.g. wrong authentication URL)
 
-``ospurge`` can be used by a cloud administrator (with the admin role)
-to cleanup any project or by a non-privileged user to cleanup his own
-project.
 
 Installation
-============
+------------
 
-Create a Python virtual environment (requires package virtualenvwrapper)::
+Create a Python virtual environment (requires the
+`virtualenvwrapper <https://virtualenvwrapper.readthedocs.org/>`_):
+
+.. code-block:: console
 
     $ mkvirtualenv ospurge
 
-Install ``ospurge``::
+Install ``ospurge`` with ``pip``:
+
+.. code-block:: console
 
     $ pip install ospurge
 
-The script is installed and can be launched::
+Available options can be displayed by using ``ospurge -h``:
 
-    $ ospurge -h
+.. code-block:: console
-
-
-Usage
-=====
-
-Available options can be displayed by using ``ospurge -h``::
 
     $ ospurge -h
     usage: ospurge [-h] [--verbose] [--dry-run] [--dont-delete-project]
@@ -80,23 +114,8 @@ Available options can be displayed by using ``ospurge -h``::
                             with caution.
 
 
-Error codes
+Example usage
-===========
+-------------
-
-The following error codes are returned when ``ospurge`` encounters
-an error:
-
-* Code 2: Project doesn't exist
-* Code 3: Authentication failed (e.g. Bad username or password)
-* Code 4: Resource deletion failed
-* Code 5: Connection error while deleting a resource (e.g. Service not available)
-* Code 6: Connection to endpoint failed (e.g. authentication url)
-* Code 1: Unknown error
-* Code 0: Process exited sucessfully
-
-
-Example
-=======
 
 To remove a project, credentials have to be
 provided. The usual OpenStack environment variables can be used. When
@@ -105,16 +124,20 @@ to be provided, by using either the ``--cleanup-project`` option or the
 ``--own-project`` option. When the command returns, any resources associated
 to the project will have been definitively deleted.
 
-Setting OpenStack credentials::
+* Setting OpenStack credentials:
+
+.. code-block:: console
 
     $ export OS_USERNAME=admin
     $ export OS_PASSWORD=password
     $ export OS_TENANT_NAME=admin
     $ export OS_AUTH_URL=http://localhost:5000/v2.0
 
-Checking resources of the target project::
+* Checking resources of the target project:
 
-    $ ./ospurge --dry-run --cleanup-project florent-demo
+.. code-block:: console
+
+    $ ./ospurge --dry-run --cleanup-project demo
     * Resources type: CinderSnapshots
 
     * Resources type: NovaServers
@@ -142,11 +165,13 @@ Checking resources of the target project::
 
     * Resources type: CeilometerAlarms
 
-Removing resources without deleting the project::
+* Removing resources without deleting the project:
 
-    $ ./ospurge --verbose --dont-delete-project --cleanup-project florent-demo
+.. code-block:: console
+
+    $ ./ospurge --verbose --dont-delete-project --cleanup-project demo
     INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): keystone.usr.lab0.aub.cw-labs.net
-    INFO:root:* Granting role admin to user e7f562a29da3492baba2cc7c5a1f2d84 on project florent-demo.
+    INFO:root:* Granting role admin to user e7f562a29da3492baba2cc7c5a1f2d84 on project demo.
     INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): keystone-admin.usr.lab0.aub.cw-labs.net
     INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): keystone-admin.usr.lab0.aub.cw-labs.net
     INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): keystone-admin.usr.lab0.aub.cw-labs.net
@@ -174,9 +199,11 @@ Removing resources without deleting the project::
     INFO:requests.packages.urllib3.connectionpool:Starting new HTTP connection (1): cinder.usr.lab0.aub.cw-labs.net
     INFO:root:* Purging CeilometerAlarms
 
-Checking that resources have been correctly removed::
+* Checking that resources have been correctly removed:
 
-    $ ./ospurge --dry-run --cleanup-project florent-demo
+.. code-block:: console
+
+    $ ./ospurge --dry-run --cleanup-project demo
     * Resources type: CinderSnapshots
 
     * Resources type: NovaServers
@@ -201,41 +228,26 @@ Checking that resources have been correctly removed::
 
     * Resources type: CeilometerAlarms
 
-Removing project::
+* Removing project:
 
-    $ ./ospurge --cleanup-project florent-demo
+.. code-block:: console
-    $ ./ospurge --cleanup-project florent-demo
-    Project florent-demo doesn't exist
 
+    $ ./ospurge --cleanup-project demo
+    $ ./ospurge --cleanup-project demo
+    Project demo doesn't exist
 
-Deleted resources
+* Users can be deleted by using the ``python-keystoneclient`` command-line
-=================
+  interface:
 
-The following resources will be removed:
+.. code-block:: console
-
-* ceilometer alarms
-* floating IPs
-* images / snapshots
-* instances
-* networks
-* routers
-* security groups
-* swift containers
-* swift objects
-* volumes / snapshots
-
-
-Notes
-=====
-
-Users can be deleted by using the ``python-keystoneclient`` CLI::
 
     $ keystone user-delete <username_or_userid>
 
 
 How to contribute
-=================
+-----------------
 
-Ospurge is hosted on Stackforge and is using Gerrit to manage
+OSpurge is hosted on the OpenStack infrastructure and is using
-contributions. You can contribute to the project by following the
+`Gerrit <https://review.openstack.org>`_ to manage contributions. You can
-following workflow: http://docs.openstack.org/infra/manual/developers.html#development-workflow
+contribute to the project by following the
+`OpenStack Development workflow <http://docs.openstack.org/infra/manual/developers.html#development-workflow>`_.

doc/source/conf.py

@@ -0,0 +1,28 @@
+# 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.
+
+import os
+import sys
+import openstackdocstheme
+
+copyright = u'2015, OpenStack contributors'
+html_copy_source = False
+html_last_updated_fmt = '%Y-%m-%d %H:%M'
+html_show_sourcelink = False
+html_theme = 'openstackdocs'
+html_theme_path = [openstackdocstheme.get_html_theme_path()]
+html_use_index = False
+master_doc = 'index'
+project = u'OpenStack project resources cleaner'
+pygments_style = 'sphinx'
+source_suffix = '.rst'

doc/source/index.rst

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

doc/source/readme.rst

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

test-requirements.txt

@@ -4,3 +4,6 @@ testtools
 nose
 requests
 testrepository
+sphinx>=1.1.2,!=1.2.0,!=1.3b1,<1.3
+doc8
+openstackdocstheme>=1.0.3

tox.ini

@@ -15,15 +15,19 @@ deps = -r{toxinidir}/requirements.txt
 commands = python setup.py testr --testr-args='{posargs}'
 whitelist_externals = flake8
 
-[testenv:pep8]
-commands = flake8
-
 [testenv:venv]
 commands = {posargs}
 
+[testenv:pep8]
+commands = flake8
+
 [flake8]
 # E501 line too long
 ignore = E501
 show-source = True
 exclude = .venv,.tox,dist,doc,*egg,build
 
+[testenv:docs]
+commands =
+  doc8 -e .rst doc README.rst
+  python setup.py build_sphinx -b html