Restructure index, readme and acknowledgments.

README.rst

@@ -0,0 +1,56 @@
+xlrd
+====
+
+|Build Status|_ |Coverage Status|_ |Documentation|_ |PyPI version|_
+
+.. |Build Status| image:: https://circleci.com/gh/python-excel/xlrd/tree/master.svg?style=shield
+.. _Build Status: https://circleci.com/gh/python-excel/xlrd/tree/master
+
+.. |Coverage Status| image:: https://codecov.io/gh/python-excel/xlrd/branch/master/graph/badge.svg?token=lNSqwBBbvk
+.. _Coverage Status: https://codecov.io/gh/python-excel/xlrd
+
+.. |Documentation| image:: https://readthedocs.org/projects/xlrd/badge/?version=latest
+.. _Documentation: http://xlrd.readthedocs.io/en/latest/?badge=latest
+
+.. |PyPI version| image:: https://badge.fury.io/py/xlrd.svg
+.. _PyPI version: https://badge.fury.io/py/xlrd
+
+
+xlrd is a library for reading data and formatting information from Excel
+files in the historical ``.xls`` format.
+
+.. warning::
+
+  This library will no longer read anything other than ``.xls`` files. For
+  alternatives that read newer file formats, please see http://www.python-excel.org/.
+
+The following are also not supported but will safely and reliably be ignored:
+
+*   Charts, Macros, Pictures, any other embedded object, **including** embedded worksheets.
+*   VBA modules
+*   Formulas, but results of formula calculations are extracted.
+*   Comments
+*   Hyperlinks
+*   Autofilters, advanced filters, pivot tables, conditional formatting, data validation
+
+Password-protected files are not supported and cannot be read by this library.
+
+Quick start:
+
+.. code-block:: python
+
+    import xlrd
+    book = xlrd.open_workbook("myfile.xls")
+    print("The number of worksheets is {0}".format(book.nsheets))
+    print("Worksheet name(s): {0}".format(book.sheet_names()))
+    sh = book.sheet_by_index(0)
+    print("{0} {1} {2}".format(sh.name, sh.nrows, sh.ncols))
+    print("Cell D30 is {0}".format(sh.cell_value(rowx=29, colx=3)))
+    for rx in range(sh.nrows):
+        print(sh.row(rx))
+
+From the command line, this will show the first, second and last rows of each sheet in each file:
+
+.. code-block:: bash
+
+    python PYDIR/scripts/runxlrd.py 3rows *blah*.xls

docs/acknowledgements.rst

@@ -1,6 +1,18 @@
 Acknowledgements
 ================
 
+Many thanks to to John Machin for originally writing :mod:`xlrd` and tirelessly
+supporting it for many years before retiring.
+
+*   This package started life as a translation from C into Python of parts of a utility called "xlreader" developed by David Giffin. "This product includes software developed by David Giffin <[email protected]>."
+*   OpenOffice.org has truly excellent documentation of the Microsoft Excel file formats and Compound Document file format, authored by Daniel Rentz. See http://sc.openoffice.org
+*   U+5F20 U+654F: over a decade of inspiration, support, and interesting decoding opportunities.
+*   Ksenia Marasanova: sample Macintosh and non-Latin1 files, alpha testing
+*   Backporting to Python 2.1 was partially funded by Journyx - provider of timesheet and project accounting solutions (http://journyx.com/).
+*   Provision of formatting information in version 0.6.1 was funded by `Simplistix Ltd`__.
+
+__ http://www.simplistix.co.uk
+
 Development of this package would not have been possible without the document
 OpenOffice.org's Documentation of the Microsoft Excel File Format"
 ("OOo docs" for short).
@@ -18,8 +30,3 @@ Backporting to Python 2.1 was partially funded by
 `Journyx - provider of timesheet and project accounting solutions`__.
 
 __ http://journyx.com/
-
-Provision of formatting information in version 0.6.1 was funded by
-`Simplistix Ltd`__.
-
-__ http://www.simplistix.co.uk

docs/index.rst

@@ -1,8 +1,10 @@
-xlrd documentation
-==================
+.. include:: ../README.rst
+
+You may also wish to consult the `tutorial`__.
+
+__ https://github.com/python-excel/tutorial
 
-xlrd is a library for reading data and formatting information from Excel
-files, whether they are .xls or .xlsx files.
+Details:
 
 .. toctree::
    :maxdepth: 1
@@ -14,12 +16,8 @@ files, whether they are .xls or .xlsx files.
    on_demand.rst
    api.rst
 
-You may also wish to consult the `tutorial`__.
-
-__ https://github.com/python-excel/tutorial
-
-For details of how to install the package or get involved in its
-development, please see the sections below:
+For details of how to get involved in development of this package,
+and other meta-information, please see the sections below:
 
 .. toctree::
    :maxdepth: 1