Add pep257 as a requirement

PEP257 [1] "documents semantics and conventions associated with Python
docstrings." The pep257 package [2] is "static analysis tool for
checking compliance with Python PEP 257." The flake8_docstrings module
allows us to consume the pep257 package as a flake8 plugin.

[1]: https://www.python.org/dev/peps/pep-0257/
[2]: https://pypi.python.org/pypi/pep257
[3]: https://pypi.python.org/pypi/flake8-docstrings

Consuming projects
==================

Adoption has been proposed to the several keystone projects
including:

- openstack/pycadf
- openstack/keystone
- openstack/keystonemiddleware
- openstack/keystoneauth-saml2
- openstack/keystoneauth
- openstack/python-keystoneclient
- openstack/python-keystoneclient-kerberos

Each of these proposed changes shares the same Change-Id:

    http://bit.ly/1jMJvpe

Each of the above patches adds flake8_docstrings as a dependency, but
ignores PEP257 checks which the project is currently failing (in the
near term, this gates against introducing regressions on the subset of
checks which we are currently passing).

The following series of patches proposed against keystone proceeds to
fix one violation at a time and results in increased coverage by pep257:

- https://review.openstack.org/#/c/229689/
- https://review.openstack.org/#/c/229837/
- https://review.openstack.org/#/c/229839/
- https://review.openstack.org/#/c/229853/
- https://review.openstack.org/#/c/229855/
- https://review.openstack.org/#/c/229857/
- https://review.openstack.org/#/c/229865/
- https://review.openstack.org/#/c/229887/
- https://review.openstack.org/#/c/229898/
- https://review.openstack.org/#/c/229916/

Is the library actively maintained?
===================================

flake8_docstrings is maintained by Ian Cordasco (sigmavirus24), a
glance-core reviewer. Given that this project is a wrapper around
pep257, I wouldn't expect much activity in this project, but the latest
release was January 2015. Commit history:

  https://gitlab.com/pycqa/flake8-docstrings/commits/master

pep257's last release was July 2015 and it's commit history shows that
it is actively maintained by a small group of contributors:

  https://github.com/GreenSteam/pep257/commits/master

Is the library good code?
=========================

flake8_docstrings is comprised of a single, trivial class to expose
pep257 to flake8 (there are no tests written directly against the plugin
that I'm aware of):

  http://bit.ly/1MXu9Yv

Nearly half of pep257's codebase is actually tests. The tests, and code
are well written, well documented and easy to read, IMO.

Is the library python 3 compatible?
===================================

flake8_docstrings claims support for both Python 2 and 3.

pep257 claims support for Python 2.6, 2.7, 3.2, 3.3, 3.4, pypy and
pypy3.

Is the library license compatible?
==================================

flake8_docstrings LICENSE is MIT:

  http://bit.ly/1MXuaM2

pep257 LICENSE is MIT:

  https://github.com/GreenSteam/pep257/blob/master/LICENSE-MIT

Is the library already packaged in the distros we target?
=========================================================

I don't believe either is packaged for Ubuntu or Fedora.

Is the function of this library already covered by other libraries?
===================================================================

All of openstack/hacking's docstrings checks (hacking.checks.docstrings)
are redundant with pep257 standards and can potentially be deprecated in
favor of the more comprehensive coverage provided by pep257. Further, I
don't believe any of hacking's checks assert any direct conflicts with
pep257 (I've written a file that exercises all of pep257's checks and it
passes against hacking as well).

Change-Id: I60adf0dca4aa32f4ef6bca61250b375c8a3703c6
Related-Bug: 1501544

blacklist.txt

@@ -1,6 +1,8 @@
 flake8
+flake8_docstrings
 hacking
 mccabe
+pep257
 pep8
 pyflakes
 pylint

global-requirements.txt

@@ -326,8 +326,10 @@ zake>=0.1.6 # Apache-2.0
 # next hacking release). Only these versions will be selected, because hacking
 # specifies the concrete version to choose.
 flake8>=2.2.4,<=2.4.1
+flake8_docstrings==0.2.1.post1
 hacking>=0.10.2,<0.11
 mccabe==0.2.1 # MIT License
+pep257==0.7.0 # MIT License
 pep8==1.5.7
 pyflakes==0.8.1
 pylint==1.4.4  # GNU GPL v2