From f7f2dafb1e3d09017de6968a2a553d3e8b6c765c Mon Sep 17 00:00:00 2001
From: Prashanth Pai <ppai@redhat.com>
Date: Thu, 9 Jun 2016 15:19:57 +0530
Subject: Revamp and complete API documentation

Created .rst files that sphinx can use to auto-generate entire
API documentation from doc strings present in code. This can be easily
rendered and hosted on ReadTheDocs website.

Change-Id: If1a569bdeaaba21919ac77ba8bd4967dfec22603
Signed-off-by: Prashanth Pai <ppai@redhat.com>
---
 README.md | 68 +++++++++++++++++++++++++++++++--------------------------------
 1 file changed, 33 insertions(+), 35 deletions(-)

(limited to 'README.md')

diff --git a/README.md b/README.md
index 3720fcb..656a67e 100644
--- a/README.md
+++ b/README.md
@@ -1,59 +1,57 @@
-# Overview
+### Overview
 
-Python bindings for the [GlusterFS](http://www.gluster.org) libgfapi interface
+This is the official python bindings for the
+[GlusterFS](http://www.gluster.org) libgfapi C library interface.
 
-# Installation
+Complete API reference and documentation can be found at
+[ReadTheDocs](http://libgfapi-python.readthedocs.io/)
 
-1) Clone the git repo
+### Installation
 
 ```
 $ git clone https://review.gluster.org/libgfapi-python
 $ cd libgfapi-python
-```
-
-2) Run the setup script
-
-```
 $ sudo python setup.py install
 ```
-# Usage
+
+### Example Usage
 
 ```python
 from gluster import gfapi
-import os
 
-## Create virtual mount
-volume = gfapi.Volume(....)
+# Create virtual mount
+volume = gfapi.Volume('10.7.1.99', 'datavolume')
 volume.mount()
 
-## Create a new directory
-volume.mkdir('newdir', 0755)
+# Create directory
+volume.mkdir('dir1', 0755)
 
-## Create a new directory recursively
-volume.makedirs('/somedir/dir',0755)
+# List directories
+volume.listdir('/')
 
-## Delete a directory
-volume.rmdir('/somedir/dir')
+# Create new file and write to it
+with volume.fopen('somefile.txt', 'w+') as f:
+    f.write("Winter is coming.")
 
-## Create a file from a string using fopen.  w+: open file for reading and writing
-with volume.fopen('somefile.txt', 'w+') as fd:
-    fd.write("shadowfax")
+# Open and read file
+with volume.fopen('somefile.txt', 'r') as f:
+  print f.read()
 
-## Read a file.  r: open file for only reading
-with volume.fopen('somefile.txt', 'r') as fd:
-  print fd.read()
-
-## Write to an existing file. a+:  open a file for reading and appending
-with volume.fopen('somefile.txt','a+') as fd:
-  fd.write("\n some new line in our file")
-
-## Delete a file
+# Delete file
 volume.unlink('somefile.txt')
 
-## Unmount a volume
+# Unmount the volume
 volume.unmount()
-
 ```
-# Development
 
-* [Developer Guide](doc/markdown/dev_guide.md)
+### TODOs
+
+* Submit to pypy to enable installing using pip
+* Add support for py3
+* Implement async I/O APIs
+* Implement file locking APIs
+* Implement os.scandir() like API that leverages d\_type
+* Improve Volume.walk() by leveraging scandir.
+* Test and allow protocols other than TCP such as rdma and socket.
+
+Please follow the [Developer Guide](doc/markdown/dev_guide.md) to contribute code.
-- 
cgit