Noissue - Added usage of flake8-docstrings to our coding practices

pages/coding-style.html

 title=Coding Style
 
 
 <h2 id="precedence">{{s1 Precedence}}</h2>
 
 <p>{{s2 The Adblock Plus coding style is based on others. Our rules (both general and language specific) always overrule referenced style guides. The language specific sections overrule the general section.}}</p>
 
 <h2 id="consistency">{{s3 Consistency}}</h2>
 
 <p>{{s4 Consistency is most important: Be consistent within functions, files, modules and projects. Making existing code conform with this style guide is fine, but it should happen in dedicated commits, preferably for a whole module or project at once.}}</p>
@@ skipping 47 matching lines @@
 <ul>
   <li>{{python-general Follow <a href="https://www.python.org/dev/peps/pep-0008/"><fix>PEP-8</fix></a> and the recommendations in the offical <fix>Python</fix> documentation.}}</li>
   <li>{{python-version Make the code compatible with both <fix>Python 2.7</fix> and <fix>Python 3.5+</fix> (see <a href="https://docs.python.org/dev/howto/pyporting.html">this guide</a>). Use <a href="https://docs.python.org/2/library/__future__.html"><fix>__future__</fix> imports</a> to address syntactic differences but avoid <a href="https://pythonhosted.org/six/"><fix>six</fix></a>, <a href="http://python-future.org/compatible_idioms.html"><fix>python-future</fix></a>, etc. to not introduce additional dependencies.}}</li>
   <li>{{python-strings Write string literals so that they match the behaviour of <a href="https://docs.python.org/3/library/functions.html#ascii"><code><fix>ascii()</fix></code></a>, i.e. use single quotes except to avoid escaping of embedded quotes and use <code><fix>\u</fix></code> escapes for non-ascii characters but don't prefix strings with <code><fix>u</fix></code>. For docstrings, however, follow <a href="https://www.python.org/dev/peps/pep-0257/">PEP-257</a>.}}</li>
   <li>{{python-prefix In modules, prefix private functions and variables with a single underscore.}}</li>
   <li>{{python-concatenation Use the <code><fix>+</fix></code> operator when concatenating exactly two strings, use the <a href="https://docs.python.org/2/library/stdtypes.html#str.format"><code><fix>format()</fix></code> method</a> for more complex string formatting, use the <a href="https://docs.python.org/2/library/stdtypes.html#str.join"><code><fix>join()</fix></code> method</a> when concatenating pre-existing sequences.}}</li>
   <li>{{python-tuple-vs-list Use tuples for data that have structure, use lists for data that have order.}}</li>
   <li>{{python-builtins Don't override builtins except for <a href="https://docs.python.org/2/library/functions.html#non-essential-built-in-funcs">non-essential builtins</a> and <code><fix>file</fix></code> which is superfluos in modern code as well.}}</li>
   <li>{{python-map-filter Use list comprehensions or generator expressions instead of calling <code><fix>map()</fix></code> or <code><fix>filter()</fix></code> with a lambda function.}}</li>
   <li>{{python-regexp Use <a href="https://docs.python.org/2/library/re.html#re.search"><code><fix>re.search()</fix></code></a> instead of <code><fix>re.match()</fix></code> to avoid <a href="https://docs.python.org/2/library/re.html#search-vs-match">confusion</a> about implied beginning of the string but not the ending.}}</li>
-  <li>{{python-flake8 Run <a href="https://pypi.python.org/pypi/flake8"><fix>flake8</fix></a> with the <a href="https://hg.adblockplus.org/codingtools/file/tip/flake8-eyeo"><fix>flake8-eyeo</fix></a> and <a href="https://pypi.python.org/pypi/pep8-naming"><fix>pep8-naming</fix></a> extensions and fix any warning.}}</li>
+  <li>
+    {{python-flake8 Run <a href="https://pypi.python.org/pypi/flake8"><fix>flake8</fix></a> with following extensions and fix all reported errors:}}
+    <ul>
+      <li><a href="https://hg.adblockplus.org/codingtools/file/tip/flake8-eyeo">flake8-eyeo</a></li>
+      <li><a href="https://pypi.python.org/pypi/flake8-docstrings">flake8-docstrings</a> ({{python-flake8-docstring-exception with <code><fix>D1</fix></code> ignored}})</li>
+      <li><a href="https://pypi.python.org/pypi/pep8-naming">pep8-naming</a></li>
+    </ul>
+  </li>
   <li>{{python-tests Write tests and have them run along <fix>flake8</fix> using <a href="https://pypi.python.org/pypi/tox"><fix>tox</fix></a>.}}</li>
 </ul>
 
 <h2 id="java">{{s22 Java}}</h2>
 <ul>
   <li>{{s23 Follow the Mozilla Coding Style's <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#Java_practices">Java practices</a>.}}</li>
   <li>{{s24 Imports should be organised consistently per file, we don't use global rules.}}</li>
 </ul>
 
 <h2 id="cpp">{{s25 C++}}</h2>
 <ul>
   <li>{{s26 Follow the Mozilla Coding Style's <a href="https://developer.mozilla.org/en-US/docs/Developer_Guide/Coding_Style#C.2FC.2B.2B_practices">C++ practices</a>.}}</li>
   <li>{{s27 Indent namespace bodies.}}</li>
   <li>{{s28 Avoid manual memory management: Use references and values when possible, smart pointers when necessary, raw pointers only for weak references.}}</li>
   <li>{{s29 Don't use C-style casts unless its exact semantics are required.}}</li>
   <li>{{s30 We tend to use anonymous namespaces instead of static.}}</li>
 </ul>
 
 <h2 id="objc">{{objective-c Objective-C}}</h2>
 <ul>
   <li>{{objc-conventions Follow Apple's <a href="https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Conventions/Conventions.html">conventions</a>}}.</li>
 </ul>
 
 <h2 id="puppet">{{s31 Puppet}}</h2>
 <ul>
   <li>{{s32 Follow the <a href="http://docs.puppetlabs.com/guides/style_guide.html">Puppet Style Guide</a>.}}</li>
   <li>{{s33 Opening braces don't go on their own line.}}</li>
   <li>{{s34 Arrows should not be aligned.}}</li>
 </ul>