Split out error code docs into one per code (#191)

docs/error_codes/AAA01-no-act-block-found-in-test.rst

@@ -0,0 +1,50 @@
+AAA01: no Act block found in test
+---------------------------------
+
+An Act block is usually a line like ``result =`` or a check that an exception
+is raised. Flake8-AAA could not find an Act block in the indicated test
+function.
+
+.. _aaa01-resolution:
+
+Resolution
+..........
+
+Add an Act block to the test or mark a line that should be considered the
+action.
+
+Even if the result of a test action is ``None``, assign that result and
+pin it with a test:
+
+.. code-block:: python
+
+    result = action()
+
+    assert result is None
+
+However, if your action's ``None`` return value is type-hinted ``action() ->
+None``, then ``mypy`` will complain if you try to assign a result. In this
+case, or any other where a you can not assign a ``result``, then mark the end
+of the line considered the Act block with ``# act`` (case insensitive):
+
+.. code-block:: python
+
+    data['new_key'] = 1  # act
+
+If the action spans multiple lines, then it can be marked with ``# act`` on the
+first or last line. Both of the following will work:
+
+.. code-block:: python
+
+    validate_row(  # act
+        {"total_number_of_users": "1", "number_of_new_users": "0"},
+        ["total_number_of_users", "number_of_new_users"],
+    )
+
+    validate_row(
+        {"total_number_of_users": "1", "number_of_new_users": "0"},
+        ["total_number_of_users", "number_of_new_users"],
+    )  # act
+
+Code blocks wrapped in ``pytest.raises()`` and ``unittest.assertRaises()``
+context managers are recognised as Act blocks.

docs/error_codes/AAA02-multiple-act-blocks-found-in-test.rst

@@ -0,0 +1,14 @@
+AAA02: multiple Act blocks found in test
+----------------------------------------
+
+There must be one and only one Act block in every test but Flake8-AAA found
+more than one potential Act block. This error is usually triggered when a test
+contains more than one ``result =`` statement or more than one line marked ``#
+act``. Multiple Act blocks create ambiguity and raise this error code.
+
+Resolution
+..........
+
+Split the failing test into multiple tests. Where there is complicated or
+reused set-up code then apply the DRY principle and extract the reused code
+into one or more fixtures.

docs/error_codes/AAA03-expected-1-blank-line-before-act-block.rst

@@ -0,0 +1,17 @@
+AAA03: expected 1 blank line before Act block, found none
+---------------------------------------------------------
+
+For tests that have an Arrange block, there must be a blank line between the
+Arrange and Act blocks, but Flake8-AAA could not find one.
+
+This blank line creates separation between the arrangement and the action and
+makes the Act block easy to spot.
+
+This rule works best with `pycodestyle
+<https://pypi.org/project/pycodestyle/>`_'s ``E303`` rule enabled because it
+ensures that there are not multiple blank lines between the blocks.
+
+Resolution
+..........
+
+Add a blank line before the Act block.

docs/error_codes/AAA04-expected-1-blank-line-before-assert-block.rst

@@ -0,0 +1,15 @@
+AAA04: expected 1 blank line before Assert block, found none
+------------------------------------------------------------
+
+For tests that have an Assert block, there must be a blank line between the Act
+and Assert blocks, but Flake8-AAA could not find one.
+
+This blank line creates separation between the action and the assertions and
+makes the Act block easy to spot.
+
+As with rule ``AAA03``, this rule works best with ``E303`` enabled.
+
+Resolution
+..........
+
+Add a blank line before the Assert block.

docs/error_codes/AAA05-blank-line-in-block.rst

@@ -0,0 +1,11 @@
+AAA05: blank line in block
+--------------------------
+
+The only blank lines in the test must be around the Act block making it easy to
+spot. Flake8-AAA found additional blank lines which break up the block's
+layout.
+
+Resolution
+..........
+
+Remove the blank line.

docs/error_codes/AAA06-comment-in-act-block.rst

@@ -0,0 +1,63 @@
+AAA06: comment in Act block
+---------------------------
+
+Problematic code
+................
+
+.. code-block:: python
+
+    def test() -> None:
+        shopping = ['apples', 'bananas', 'cabbages']
+
+        # Reverse shopping list operates in place
+        shopping.reverse()  # act
+
+        assert shopping == ['cabbages', 'bananas', 'apples']
+
+Correct code
+............
+
+.. code-block:: python
+
+    def test() -> None:
+        """
+        Reverse shopping list operates in place
+        """
+        shopping = ['apples', 'bananas', 'cabbages']
+
+        shopping.reverse()  # act
+
+        assert shopping == ['cabbages', 'bananas', 'apples']
+
+Rationale
+.........
+
+The Act block carries out a single action on an object. It is the focus of each
+test. Therefore any comments on this single action are really comments on the
+test itself and so should be moved to the test docstring.
+
+By placing these important comments in the docstring we can:
+
+* Make it easier to keep the Act block simple.
+
+* Help to distinguish the Act block from the rest of the test.
+
+* Improve the documentation of tests because any important comments and notes
+  are lifted to the top of the test.
+
+Exceptions
+..........
+
+Inline comments used to pass information to linters are OK:
+
+* Marking the Act block:
+
+  .. code-block:: python
+
+      shopping.reverse()  # act
+
+* Marking lines in the action for linting reasons:
+
+  .. code-block:: python
+
+      result = shopping.reverse()  # type: ignore

docs/error_codes/AAA99-collision-when-marking-this-line.rst

@@ -0,0 +1,17 @@
+AAA99: collision when marking this line as NEW_CODE, was already OLD_CODE
+-------------------------------------------------------------------------
+
+This is an error code that is raised when Flake8 tries to mark a single line as
+occupied by two different types of block. It *should* never happen. The values
+for ``NEW_CODE`` and ``OLD_CODE`` are from the list of :ref:`line-markers`.
+
+Resolution
+..........
+
+Please open a `new issue
+<https://github.com/jamescooke/flake8-aaa/issues/new>`_ containing the output
+for the failing test as generated by the :ref:`command-line` tool.
+
+You could hack around with your test to see if you can get it to work while
+waiting for someone to reply to your issue. If you're able to adjust the test
+to get it to work, that updated test would also be helpful for debugging.

docs/error_codes/all.rst

@@ -0,0 +1,15 @@
+Error codes
+===========
+
+.. note::
+
+    Flake8-AAA works best with the following Flake8 rules enabled:
+
+    * ``E303`` "too many blank lines"
+    * ``E702`` "Multiple statements on one line"
+
+.. toctree::
+    :maxdepth: 2
+    :glob:
+
+    AAA*

docs/index.rst

@@ -18,6 +18,6 @@ Continue here for more detail about using Flake8-AAA.
 
     compatibility
     discovery
-    rules
+    error_codes/all
     commands
     release_checklist