Merge pull request #42 from jamescooke/doc-improvements

Documentation improvements

README.rst

@@ -22,7 +22,7 @@
 flake8-aaa
 ==========
 
-Extends `Flake8 <http://flake8.pycqa.org/en/latest/index.html>`_ to check
+A `Flake8 <http://flake8.pycqa.org/en/latest/index.html>`_ plugin that checks
 Python tests follow the `Arrange Act Assert pattern
 <http://jamescooke.info/arrange-act-assert-pattern-for-python-developers.html>`_.
 
@@ -42,6 +42,14 @@ version signature::
 
 The ``aaa: 0.4.0`` part of that output tells you ``flake8`` found this plugin.
 
+Usage
+-----
+
+Run ``flake8`` as usual against your project and ``flake8-aaa`` will check your
+tests::
+
+    $ flake8
+
 There is more information on invoking ``flake8`` on the `Invoking Flake8
 <http://flake8.pycqa.org/en/latest/user/invocation.html>`_ documentation page.
 

docs/discovery.rst

@@ -1,11 +1,29 @@
 Test discovery
 ==============
 
-* Filename must start with ``test_`` and have been collected for linting by
-  ``flake8``.
+The ``flake8-aaa`` plugin is triggered for files that look to it like test
+modules - anything that does not look like a test module is skipped.
 
-* Test must be a function or class method.
+The following rules are applied by ``flake8-aaa`` when discovering tests:
 
-* Test names must start with ``test``.
+* The module's filename must start with "test\_" and have been collected for
+  linting by Flake8.
 
-* Tests that contain only comments, docstrings or ``pass`` are skipped.
+* Every function in the module that has a name that starts with "test" is
+  checked.
+
+* Test functions can be class methods.
+
+* Test functions that contain only comments, docstrings or ``pass`` are
+  skipped.
+
+These rules are aimed to mirror pytest's default collection strategy as closely
+as possible.
+
+If you find that ``flake8-aaa`` is giving false positives (you have checks that
+you expected to fail, but they did not), then you should check that the plugin
+did not ignore or skip those tests which you expected to fail.
+
+.. note::
+
+    ``flake8-aaa`` does not check doctests.

docs/index.rst

@@ -1,11 +1,11 @@
-Welcome to Flake8-AAA's documentation!
-======================================
+Welcome to Flake8-AAA's documentation
+=====================================
 
 .. include:: ../README.rst
 
 .. toctree::
     :maxdepth: 2
-    :caption: Contents:
+    :caption: Contents
 
     discovery
     rules

docs/rules.rst

@@ -5,6 +5,14 @@ The rules applied by ``flake8-aaa`` are from the `Arrange Act Assert pattern
 for Python developers
 <https://jamescooke.info/arrange-act-assert-pattern-for-python-developers.html>`_.
 
+.. note::
+
+    The rules applied by ``flake8-aaa`` are only a subset of the rules and
+    guidelines of the Arrange Act Assert pattern itself. Please see `the
+    published guidelines for the pattern
+    <https://jamescooke.info/arrange-act-assert-pattern-for-python-developers.html>`_
+    and read these rules in the context of the definition there.
+
 AAA01: no Act block found in test
 ---------------------------------