docs tweaks

README.rst

@@ -20,7 +20,7 @@ Status
     :target: https://pypi.python.org/pypi/bidict
     :alt: Latest release
 
-.. image:: https://img.shields.io/badge/VersionEye-follow-brightgreen.svg
+.. image:: https://img.shields.io/badge/VersionEye-follow-yellow.svg
     :target: https://www.versioneye.com/python/bidict
     :alt: Follow on VersionEye
 
@@ -57,12 +57,16 @@ The bidict codebase is mature, well-tested, and well-reviewed.
 It is in use by several teams at Google, Bank of America Merill Lynch,
 and other developers all over the world.
 
-If you have a question or find an issue,
+If you are thinking of using bidict in your work,
-please don't hesitate to
+or if you have any questions, comments, or suggested improvements,
-`ask in the chat room <https://gitter.im/jab/bidict>`_,
+`please let me know <https://gitter.im/jab/bidict>`_!
-`file an issue <https://github.com/jab/bidict/issues/new>`_,
+I'd love to know about and be able to support
-or submit a pull request
+your use case as much as possible.
-(but first see the contributing_ section below).
+
+Please also feel free to
+file an issue or submit a pull request.
+All contributions are gratefully received:)
+(See contributing_ below.)
 
 
 Installation
@@ -75,32 +79,36 @@ Usage Documentation
 -------------------
 
 For usage documentation, please start at the :doc:`intro`
-and proceed from there. *Problems with that link? Note the following:*
+and proceed from there.
 
-If you're reading this on GitHub, PyPI, in your code editor,
+.. NOTE::
-or in some other place that can't render/link the full docs properly,
+   If you're reading this on GitHub, PyPI, in your code editor,
-you can find the bidict documentation on Read the Docs at:
+   or in some other place that can't render/link the full docs properly,
-
+   you can find the bidict documentation on Read the Docs at:
-    `<https://bidict.readthedocs.io>`_
+   
-
+       `<https://bidict.readthedocs.io>`_
-*Note: multiple versions of the documentation are published on Read the Docs,
+   
-and by default you will be taken to the version built from the master branch.
+   Also note: multiple versions of the documentation are published on Read the Docs,
-You can choose different versions from the pop-up menu in the lower-right.*
+   and by default you will be taken to the version built from the master branch.
-
+   You can choose different versions from the pop-up menu in the lower-right.
-If you have the `bidict source code <https://github.com/jab/bidict>`_  handy,
+   
-you can also browse the docs inside the ``docs`` directory,
+   If you have the `bidict source code <https://github.com/jab/bidict>`_  handy,
-and build them yourself by running ``make html`` from within that directory
+   you can also browse the docs inside the ``docs`` directory,
-(requires `Sphinx <https://pypi.python.org/pypi/Sphinx>`_).
+   and build them yourself by running ``make html`` from within that directory
+   (requires `Sphinx <https://pypi.python.org/pypi/Sphinx>`_).
 
 
 Contributing
 ------------
 
-Contributions are gratefully received!
 For information about contributing,
-please see the :doc:`contributors-guide`.
+please see the :doc:`contributors-guide`
-If that link does not work, see ``CONTRIBUTING.rst`` or
+(`<CONTRIBUTING.rst>`_ |
-`<https://bidict.readthedocs.io/contributors-guide.html>`_.
+`<https://bidict.readthedocs.io/contributors-guide.html>`_)
+
+If bidict has helped you accomplish your work,
+especially work you've been paid for,
+please consider supporting bidict's maintenance and development.
 
 .. image:: https://raw.githubusercontent.com/jab/bidict/master/_static/support-on-gumroad.png
     :target: https://gumroad.com/l/bidict
@@ -111,6 +119,6 @@ Changelog
 ---------
 
 For a history of notable changes to bidict,
-check out the :doc:`changelog`.
+check out the :doc:`changelog`
-If that link does not work, see ``CHANGELOG.rst`` or
+(`<CHANGELOG.rst>`_ |
-`<https://bidict.readthedocs.io/changelog.html>`_.
+`<https://bidict.readthedocs.io/changelog.html>`_).

setup.py

@@ -2,20 +2,20 @@ from io import open
 from setuptools import setup
 from warnings import warn
 
-try:
+
-    with open('bidict/VERSION', encoding='utf8') as f:
+def from_file(filename, fallback):
-        version = f.read().strip()
+    try:
-except Exception as e:
+        with open(filename, encoding='utf8') as f:
-    version = '0.0.0'
+            return f.read().strip()
-    warn('Could not open bidict/VERSION, using bogus version (%s): %r' %
+    except Exception as e:
-         (version, e))
+        warn('Error opening file %r, using fallback %r: %s' % (filename, fallback, e))
-try:
+        return fallback
-    with open('README.rst', encoding='utf8') as f:
+
-        long_description = f.read()
+
-except Exception as e:
+version = from_file('bidict/VERSION', '0.0.0')
-    long_description = 'See https://bidict.readthedocs.org'
+long_description = from_file('README.rst', 'See https://bidict.readthedocs.org').replace(
-    warn('Could not open README.rst, using provisional long_description '
+    ':doc:', '')  # :doc: breaks long_description rendering on PyPI
-         '(%r): %r' % (long_description, e))
+
 
 tests_require = [
     'coverage==4.3.4',