Rewrite the README0.11

And link to the docs on RTD.

3 files changed, 38 insertions, 170 deletions

diff --git a/MANIFEST.in b/MANIFEST.in
index 1170660..29a34fd 100644
--- a/MANIFEST.in
+++ b/MANIFEST.in
@@ -1,3 +1,3 @@
-include README.md COPYING AUTHORS ChangeLog requirements.txt test-requirements.txt
+include COPYING AUTHORS ChangeLog requirements.txt test-requirements.txt
 include tox.ini .testr.conf
 recursive-include tools *
diff --git a/README.md b/README.md
deleted file mode 100644
index 3516f7a..0000000
--- a/README.md
+++ /dev/null
@@ -1,169 +0,0 @@
-## Python GitLab
-
-python-gitlab is a Python package providing access to the GitLab server API.
-
-It supports the v3 api of GitLab.
-
-A CLI tool is also provided (called **gitlab**).
-
-## Installation
-
-### Requirements
-
-python-gitlab depends on:
-
-* [python-requests](http://docs.python-requests.org/en/latest/)
-* [six](https://pythonhosted.org/six/)
-
-### Install with pip
-
-`````
-pip install python-gitlab
-`````
-
-## State
-
-python-gitlab is considered stable.
-
-## Bug reports
-
-Please report bugs and feature requests at
-https://github.com/gpocentek/python-gitlab/issues
-
-## Documentation
-
-See http://python-gitlab.readthedocs.org/en/stable/
-
-## Code snippet
-
-`````python
-# See https://github.com/gitlabhq/gitlabhq/tree/master/doc/api for the source.
-from gitlab import Gitlab
-
-# Register a connection to a gitlab instance, using its URL and a user private
-# token
-gl = Gitlab('http://192.168.123.107', 'JVNSESs8EwWRx5yDxM5q')
-# Connect to get the current user
-gl.auth()
-# Print the user informations
-print(gl.user)
-
-# Get a list of projects
-for p in gl.projects.list():
-    print(p.name)
-    # get associated issues
-    issues = p.issues.list()
-    for issue in issues:
-        closed = 0 if not issue.closed else 1
-        print("  %d => %s (closed: %d)" % (issue.id, issue.title, closed))
-        # and close them all
-        issue.state_event = "close"
-        issue.save()
-
-# Get the first 10 groups (pagination)
-for g in gl.groups.list(page=1, per_page=10):
-    print(g)
-
-# To use pagination and retrieve all the items
-for g in gl.groups.list(all=True):
-    print(g)
-
-# Create a new project (as another_user)
-p = gl.project.create({'name': 'myCoolProject', 'wiki_enabled': False},
-                      sudo="another_user")
-print(p)
-`````
-
-## Command line use
-
-To use the command line tool, you need to define which GitLab server(s) can be
-accessed. This can be done in 2 files:
-
-* /etc/python-gitlab.cfg
-* ~/.python-gitlab.cfg
-
-Here's an example of the syntax:
-
-`````
-[global]
-# required setting
-default = local
-
-# optional settings
-ssl_verify = true
-timeout = 5
-
-[local]
-url = http://10.0.3.2:8080
-# get the private token from the gitlab web interface
-private_token = vTbFeqJYCY3sibBP7BZM
-
-[remote]
-url = https://some.whe.re
-private_token = thisisaprivatetoken
-ssl_verify = false
-`````
-
-The [global] section defines which server is accessed by default.
-Each other section defines how to access a server. Only private token
-authentication is supported (not user/password).
-
-The `ssl_verify` option defines if the server SSL certificate should be
-validated (use false for self signed certificates, only useful with https).
-
-The `timeout` option defines after how many seconds a request to the Gitlab
-server should be abandonned.
-
-You can choose a different server than the default one at run time:
-
-`````
-gitlab --gitlab remote [command]
-`````
-
-gitlab always requires 2 mandatory arguments.
-
-The first argument is the object type on which the program will act, the second
-one is the action:
-
-`````
-gitlab project list
-`````
-
-Get help with:
-
-`````
-# global help
-gitlab --help
-
-# object help
-gitlab project --help
-`````
-
-Some examples:
-
-`````bash
-# list all the projects:
-gitlab project list
-
-# limit to 5 items per request, display the 1st page only
-gitlab project list --page 1 --per-page 5
-
-# get a specific project (id 2):
-gitlab project get --id 2
-
-# get a list of snippets for this project:
-gitlab project-issue list --project-id 2
-
-# delete a Snippet (id 3):
-gitlab project-snippet delete --id 3 --project-id 2
-
-# update a Snippet:
-gitlab project-snippet update --id 4 --project-id 2 --code "My New Code"
-
-# create a Snippet:
-gitlab project-snippet create --project-id 2
-Impossible to create object (Missing attribute(s): title, file-name, code)
-
-# oops, let's add the attributes:
-gitlab project-snippet create --project-id 2 --title "the title" --file-name "the name" --code "the code"
-`````
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..2fe702e
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,37 @@
+Python GitLab
+=============
+
+``python-gitlab`` is a Python package providing access to the GitLab server API.
+
+It supports the v3 api of GitLab, and provides a CLI tool (``gitlab``).
+
+Installation
+============
+
+Requirements
+------------
+
+python-gitlab depends on:
+
+* `python-requests <http://docs.python-requests.org/en/latest/>`_
+* `six <https://pythonhosted.org/six/>`_
+
+Install with pip
+----------------
+
+.. code-block:: console
+
+   pip install python-gitlab
+
+Bug reports
+===========
+
+Please report bugs and feature requests at
+https://github.com/gpocentek/python-gitlab/issues.
+
+
+Documentation
+=============
+
+The documentation for CLI and API is available on `readthedocs
+<http://python-gitlab.readthedocs.org/en/stable/>`_.