Update doc minimally for release

Signed-off-by: Philippe Ombredanne <pombredanne@nexb.com>

Author: pombredanne

CHANGELOG.rst

@@ -1,5 +1,13 @@
-Release notes
--------------
-### Version 0.0.1 2020-10-29
+Changelog
+=========
 
-Initial release
+
+v (next, future)
+-----------------------
+
+
+v0.1.0
+---------
+
+First, initial release.
+ 

README.rst

@@ -1,36 +1,69 @@
-*********
-Fetchcode
-*********
-It is a library to reliably fetch code via HTTP, FTP and version control systems.
+FetchCode: Utilities to fetch code from purls, URLs and version control repos. 
+================================================================================
 
-Installation
-############
-Clone the repo using
+FetchCode is a library to reliably fetch code via HTTP, FTP and version control
+systems. It can work using plain HTTP and FTP URLs, as well as 
+`Package URLs <https://github.com/package-url>`_ and version control (VCS) URLs
+as used in Python pip and as specified in `SPDX Package Download Location
+<https://spdx.github.io/spdx-spec/3-package-information/#37-package-download-location>`_
 
-:code:`git clone https://github.com/nexB/fetchcode`
+Homepage and support: https://github.com/nexB/fetchcode
 
-Then install all the requirements using
 
-:code:`pip3 install -r requirements.txt`
+Why FetchCode?
+--------------
 
-Running test suite
-##################
+It is surprisingly difficult to have a simple API to consistently fetch code
+from package repositories, version control repositories and APIs: each site
+and each package manager has its own unique and peculiar ways. FetchCode goal
+is to abstract all these details and make it easy to fetch things reliably.
 
-To run test suite
 
-:code:`python3 -m pytest`
+Development installation
+--------------------------
 
-Usage of API to fetch HTTP/S and FTP URLs
-#########################################
+Clone the repo::
 
-.. code-block:: python
+    git clone https://github.com/nexB/fetchcode
 
-    from fetchcode import fetch
-    url = 'A Http or FTP URL'
-    # This returns a response object which has attributes
-    # 'content_type' content type of the file
-    # 'location' the absolute location of the files that was fetched
-    # 'scheme' scheme of the URL
-    # 'size' size of the retrieved content in bytes
-    # 'url' fetched URL
-    resp = fetch(url = url)
+Then install all the requirements using::
+
+    configure --dev
+
+
+Running tests
+----------------
+
+To run test suite use::
+
+    pytest -vvs
+
+
+Usage
+--------
+
+Fetch a code archive and get a ``fetchcode.fetch.Reposnse`` object back::
+
+    >>> from fetchcode import fetch
+    >>> f = fetch('https://github.com/nexB/fetchcode/archive/ab65b2e645c889887227ea49eb3332d885fd0a54.zip')
+    >>> f.location
+    '/tmp/tmp_cm02xsg'
+    >>> f.content_type
+    'application/zip'
+    >>> f.url
+    'https://github.com/nexB/fetchcode/archive/ab65b2e645c889887227ea49eb3332d885fd0a54.zip'
+
+Fetch some package metadata and get a ``fetchcode.packagedcode_models.Package`` object back::
+
+    >>> from fetchcode import package
+    >>> list(package.info('pkg:rubygems/files'))
+    [Package(type='rubygems', namespace=None, name='files', version=None)]
+
+
+
+License
+--------
+
+- SPDX-License-Identifier: Apache-2.0
+
+Copyright (c) nexB Inc. and others.