Merge pull request #150 from jamescooke/more-docs

Improve compatibility and release checklist docs

CHANGELOG.rst

@@ -14,6 +14,14 @@ Unreleased_
 See also `latest documentation
 <https://flake8-aaa.readthedocs.io/en/latest/#__unreleased_marker__>`_.
 
+Changed
+.......
+
+* README rewritten and expanded to be more friendly to readers that are not
+  aware of the AAA pattern. Template from `The Documentation Compendium
+  <https://github.com/kylelobo/The-Documentation-Compendium>`_.  `#141
+  <https://github.com/jamescooke/flake8-aaa/issues/141>`_.
+
 0.9.0_ - 2020/03/07
 -------------------
 

README.rst

@@ -131,8 +131,7 @@ Further reading:
 Prerequisites
 .............
 
-Install Flake8 with `pip <https://pip.pypa.io/en/stable/installing/>`_, if you
-don't have it already:
+Install Flake8 with `pip <https://pip.pypa.io/en/stable/installing/>`_:
 
 .. code-block:: shell
 

docs/commands.rst

@@ -88,6 +88,14 @@ And once the error above is fixed, the return value returns to zero::
     $ echo "$?"
     0 
 
+Only one file can be passed to the command line at a time. So to test all files
+in a test suite, ``find`` should be used:
+
+.. code-block:: shell
+
+    $ find tests -name '*.py' | xargs -n 1 python -m flake8_aaa
+
+
 noqa and command line
 .....................
 

docs/compatibility.rst

@@ -1,35 +1,36 @@
 Compatibility list
 ==================
 
-The stable version of Flake8-AAA is compatible with the following software.
-
-Future versions will maintain this compatibility, unless an item is deprecated.
+Flake8-AAA is compatible with the following software. Future versions will
+maintain this compatibility as closely as possible.
 
 Python
 ------
 
 Works with Python 3.
 
-We fully test against the latest versions of Python 3 - currently that's 3.6,
-3.7 and 3.8.
+Flake8-AAA is fully compatible and tested against the latest versions of Python
+3. Currently that's 3.6, 3.7 and 3.8.
+
+The following versions of Python are no longer supported:
 
 Python 3.5
 ..........
 
-Python 3.5 is supported up to ``v0.7.2``
+Python 3.5 was supported up to ``v0.7.2``
 
-  * `PyPI <https://pypi.org/project/flake8-aaa/0.7.2/>`_
-  * `Documentation <https://flake8-aaa.readthedocs.io/en/v0.7.2/>`_
-  * `Github v0.4.0 tag
+  * `v0.7.2 on PyPI <https://pypi.org/project/flake8-aaa/0.7.2/>`_
+  * `v0.7.2 Documentation <https://flake8-aaa.readthedocs.io/en/v0.7.2/>`_
+  * `Github v0.7.2 tag
     <https://github.com/jamescooke/flake8-aaa/releases/tag/v0.7.2>`_
 
 Python 2
 ........
 
-Python 2 is supported up to ``v0.4.0``
+Python 2 was supported up to ``v0.4.0``
 
-  * `PyPI <https://pypi.org/project/flake8-aaa/0.4.0/>`_
-  * `Documentation <https://flake8-aaa.readthedocs.io/en/v0.4.0/>`_
+  * `v0.4.0 on PyPI <https://pypi.org/project/flake8-aaa/0.4.0/>`_
+  * `v0.4.0 Documentation <https://flake8-aaa.readthedocs.io/en/v0.4.0/>`_
   * `Github v0.4.0 tag
     <https://github.com/jamescooke/flake8-aaa/releases/tag/v0.4.0>`_
 
@@ -50,23 +51,27 @@ version signature::
 
 The ``aaa: 0.7.0`` part of that output tells you Flake8 found this plugin.
 
+Yapf
+----
+
+Yapf is used to format Flake8-AAA code and tests. It is the primary formatter
+focused on for compatibility.
+
 Black
 -----
 
-Tests formatted with latest Black version will pass.
+Flake8-AAA is compatible with tests formatted with Black.
 
     The coding style used by Black can be viewed as a strict subset of PEP8.
 
-Given that the AAA pattern is PEP8 compatible it makes sense that Flake8-AAA
-must work with test code that is formatted with PEP8 compatible formatters.
-Therefore we'll maintain Flake8-AAA to pass with AAA-style tests formatted with
-Black.
+The AAA pattern is PEP8 compatible so it makes sense that Flake8-AAA should
+work with PEP8 compatible formatters.
 
 This compatibility is pinned by the test examples in the `examples/good/black
 directory
-<https://github.com/jamescooke/flake8-aaa/tree/master/examples/good/black>`_ -
-we assert that these tests pass the latest version of Black's formatting and
-Flake8-AAA's linting.
+<https://github.com/jamescooke/flake8-aaa/tree/master/examples/good/black>`_.
+These tests are formatted with the latest version of Black in default mode.
+They are then checked to pass Flake8-AAA's linting.
 
 Pytest
 ------

docs/index.rst

@@ -1,7 +1,16 @@
-Welcome to Flake8-AAA's documentation
-=====================================
+Flake8-AAA documentation
+========================
 
-.. include:: ../README.rst
+Overview
+--------
+
+Flake8-AAA is a Flake8 plugin that checks Python tests follow the
+Arrange-Act-Assert pattern.
+
+Please see the `README on GitHub <https://github.com/jamescooke/flake8-aaa>`_
+for a general introduction to this project and AAA.
+
+Continue here for more detail about using Flake8-AAA.
 
 .. toctree::
     :maxdepth: 2

docs/release_checklist.rst

@@ -1,10 +1,11 @@
 Release checklist
 =================
 
-Items to be completed before and after each release.
+The following tasks need to be completed for each release of Flake8-AAA. They
+are mainly for the maintainer's use.
 
-Pre-release steps
------------------
+Versioning
+----------
 
 Given a new version called ``x.y.z``:
 
@@ -15,26 +16,41 @@ Given a new version called ``x.y.z``:
 
 * Commit changes and push ``bump-vx.y.z`` branch for testing.
 
-* Now is a good time to build and check the documentation locally.
+Documentation
+-------------
 
-  - Ensure that command line output examples are up to date. They can be
-    updated using the output of the ``cmd`` and ``cmdbad`` ``tox``
-    environments.
+Now is a good time to build and check the documentation locally:
+
+.. code-block:: shell
+
+    $ make doc
+    $ firefox docs/_build/html/index.html
+
+
+Ensure that command line output examples are up to date. They can be updated
+using the output of the ``cmd`` and ``cmdbad`` ``tox`` environments.
+
+Merge
+-----
 
 * When branch ``bump-vx.y.z`` is green, then merge it to ``master``.
 
 * Update master locally and ensure that you remain on master for the rest of
   the process.
 
-* Test that a build can be shipped to test PyPI with ``make testpypi``. (Every
-  build runs the full clean test suite locally to ensure that nothing has
-  broken before building)
+Test PyPI
+---------
+
+* Test that a build can be shipped to test PyPI with ``make testpypi``.
 
 * After successful push, check the `TestPyPI page
-  <https://test.pypi.org/project/flake8-aaa/>`_.
+  <https://test.pypi.org/project/flake8-aaa/>`_.  
+
+Tag and push
+------------
 
-* Then tag the repo with ``make tag``. Add a short message about what the key
-  change is.
+* Tag the repo with ``make tag``. Add a short message describing the key
+  feature of this release.
 
 * Make the new tag public with ``git push origin --tags``.