Finish developer documentation around formatter plugins

2 files changed, 36 insertions, 0 deletions

diff --git a/docs/source/dev/formatters.rst b/docs/source/dev/formatters.rst
index b96c40b..8f90892 100644
--- a/docs/source/dev/formatters.rst
+++ b/docs/source/dev/formatters.rst
@@ -14,3 +14,37 @@ Flake8 added the ability to develop custom formatting plugins in version
         """Flake8's example formatter."""
 
         pass
+
+We notice, as soon as we start, that we inherit from Flake8's
+:class:`~flake8.formatting.base.BaseFormatter` class. If we follow the
+:ref:`instructions to register a plugin <register-a-plugin>` and try to use
+our example formatter, e.g., ``flake8 --format=example`` then Flake8 will fail
+because we did not implement the ``format`` method. Let's do that next.
+
+.. code-block:: python
+
+    class Example(base.BaseFormatter):
+        """Flake8's example formatter."""
+
+        def format(self, error):
+            return 'Example formatter: {0!r}'.format(error)
+
+With that we're done. Obviously this isn't a very useful formatter, but it
+should highlight the simplicitly of creating a formatter with Flake8. If we
+wanted to instead create a formatter that aggregated the results and returned
+XML, JSON, or subunit we could also do that. Flake8 interacts with the
+formatter in two ways:
+
+#. It creates the formatter and provides it the options parsed from the
+   configuration files and command-line
+
+#. It uses the instance of the formatter and calls ``handle`` with the error.
+
+By default :meth:`flake8.formatting.base.BaseFormatter.handle` simply calls
+the ``format`` method and then ``write``. Any extra handling you wish to do
+for formatting purposes should override the ``handle`` method.
+
+API Documentation
+=================
+
+.. autoclass:: flake8.formatting.base.BaseFormatter
diff --git a/docs/source/dev/registering_plugins.rst b/docs/source/dev/registering_plugins.rst
index 1444af0..c0edf63 100644
--- a/docs/source/dev/registering_plugins.rst
+++ b/docs/source/dev/registering_plugins.rst
@@ -1,3 +1,5 @@
+.. _register-a-plugin:
+
 ==================================
  Registering a Plugin with Flake8
 ==================================