Improve introductory documentation

- pitch as a "validator", not a "lint"
- add badges to GitHub page (README)
- update instructions for installation on Windows

README.rst

@@ -1,5 +1,19 @@
-HTTPolice is a **lint for HTTP requests and responses**.
-It checks them for conformance to standards and best practices.
+HTTPolice
+=========
+
+.. status:
+.. image:: https://img.shields.io/pypi/v/HTTPolice.svg?color=green
+   :target: https://pypi.python.org/pypi/HTTPolice
+.. image:: https://img.shields.io/pypi/pyversions/HTTPolice.svg?
+   :target: https://pypi.python.org/pypi/HTTPolice
+.. image:: https://readthedocs.org/projects/httpolice/badge/?version=stable
+   :target: http://httpolice.readthedocs.io/
+.. image:: https://travis-ci.org/vfaronov/httpolice.svg?branch=master
+   :target: https://travis-ci.org/vfaronov/httpolice
+
+HTTPolice is a **validator for HTTP requests and responses**. It can spot bad
+header syntax, inappropriate status codes, and other interoperability problems
+in your HTTP server or client.
 
 See `example report`__.
 
@@ -43,5 +57,3 @@ __ https://github.com/vfaronov/httpolice
 `BrowserStack`__ kindly provide a free subscription for testing HTTPolice.
 
 __ https://www.browserstack.com/
-
-Problems, suggestions? Feel free to email the author at vfaronov@gmail.com.

doc/conf.py

@@ -157,7 +157,7 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 html_theme_options = {
-     'description': 'Lint for HTTP',
+     'description': 'Validator for HTTP',
      'github_button': 'true',
      'github_user': 'vfaronov',
      'github_repo': 'httpolice',

doc/index.rst

@@ -1,11 +1,14 @@
 HTTPolice user manual
 =====================
 
-HTTPolice is a lint for HTTP requests and responses.
-It checks them for conformance to standards and best practices.
+`HTTPolice`__ is a validator for HTTP requests and responses. It can spot bad
+header syntax, inappropriate status codes, and other interoperability problems
+in your HTTP server or client.
+
+__ https://github.com/vfaronov/httpolice
 
 This manual explains all features of HTTPolice in detail.
-For a brief hands-on introduction, jump to the :doc:`quickstart`.
+For a hands-on introduction, jump to the :doc:`quickstart`.
 
 Contents
 --------

doc/install.rst

@@ -60,8 +60,8 @@ and to get them, you may need specific versions of Python, lxml and brotlipy.
 __ https://pypi.python.org/pypi/lxml
 __ https://pypi.python.org/pypi/brotlipy
 
-For example, at the time of writing, you can `install Python 3.5`__
-(**not** 3.6) and then simply do::
+For example, at the time of writing, you can `install Python 3.6`__
+and then simply do::
 
   C:\Users\Vasiliy\...\Python35>Scripts\pip install HTTPolice
 
@@ -70,7 +70,7 @@ Check that the installation was successful::
   C:\Users\Vasiliy\...\Python35>Scripts\httpolice --version
   HTTPolice 0.4.0
 
-__ https://www.python.org/downloads/release/python-352/
+__ https://www.python.org/downloads/
 
 However, it’s possible that new versions of lxml and brotlipy
 might not have precompiled binaries for your version of Python,

setup.py

@@ -2,6 +2,7 @@
 
 import io
 import os
+import re
 
 from setuptools import setup
 
@@ -13,11 +14,16 @@
 with io.open('README.rst') as f:
     long_description = f.read()
 
+# I prefer not to have shields in my package description. Shields reflect
+# current status; they are good in a README when viewed on Git master,
+# but not in versions published on PyPI.
+long_description = re.sub(r'^\.\. status:.*?\n\n', u'', long_description,
+                          flags=re.DOTALL | re.MULTILINE)
 
 setup(
     name='HTTPolice',
     version=metadata['version'],
-    description='Lint for HTTP',
+    description='Validator for HTTP',
     long_description=long_description,
     url=metadata['homepage'],
     author='Vasiliy Faronov',
@@ -72,5 +78,5 @@
         'Topic :: Internet :: WWW/HTTP',
         'Topic :: Software Development :: Quality Assurance',
     ],
-    keywords='HTTP message request response standards RFC lint check',
+    keywords='HTTP message request response standards RFC lint validator',
 )