Add docstring validation

This introduces a linter for PEP257 to avoid trivial nitpicking of
docstrings in code reviews. Because flake8_docstrings simply provides a
plugin to add pep257 to flake8, you can run it via `tox -e pep8`.

PEP257 checks which we are currently violating are ignored in tox.ini.
We can remove them from the ignored list as they are fixed.

Change-Id: I01ebad7b70cf61dd80d3c06c6808d8178fbdd634
Related-Bug: 1501544
Depends-On: I60adf0dca4aa32f4ef6bca61250b375c8a3703c6

test-requirements.txt

@@ -3,6 +3,7 @@
 # process, which may cause wedges in the gate later.
 
 hacking<0.11,>=0.10.0
+flake8_docstrings==0.2.1.post1
 
 coverage>=3.6
 discover

tox.ini

@@ -40,7 +40,24 @@ commands = bandit -c bandit.yaml -r keystoneclient -n5 -p keystone_conservative
 
 [flake8]
 # H405: multi line docstring summary not separated with an empty line
-ignore = H405
+# D100: Missing docstring in public module
+# D101: Missing docstring in public class
+# D102: Missing docstring in public method
+# D103: Missing docstring in public function
+# D104: Missing docstring in public package
+# D105: Missing docstring in magic method
+# D200: One-line docstring should fit on one line with quotes
+# D202: No blank lines allowed after function docstring
+# D203: 1 blank required before class docstring.
+# D204: 1 blank required after class docstring
+# D205: Blank line required between one-line summary and description.
+# D207: Docstring is under-indented
+# D208: Docstring is over-indented
+# D211: No blank lines allowed before class docstring
+# D301: Use r”“” if any backslashes in a docstring
+# D400: First line should end with a period.
+# D401: First line should be in imperative mood.
+ignore = H405,D100,D101,D102,D103,D104,D105,D200,D202,D203,D204,D205,D207,D208,D211,D301,D400,D401
 show-source = True
 exclude = .venv,.tox,dist,doc,*egg,build,*openstack/common*