Use autodoc for Formatter class

2 files changed, 41 insertions, 57 deletions

diff --git a/doc/docs/api.rst b/doc/docs/api.rst
index b38ca8b0..6260fde7 100644
--- a/doc/docs/api.rst
+++ b/doc/docs/api.rst
@@ -177,53 +177,8 @@ Formatters
 A formatter is derived from this class:
 
 
-.. class:: Formatter(**options)
-
-    As with lexers, this constructor processes options and then must call the
-    base class :meth:`__init__`.
-
-    The :class:`Formatter` class recognizes the options `style`, `full` and
-    `title`.  It is up to the formatter class whether it uses them.
-
-    .. method:: get_style_defs(arg='')
-
-        This method must return statements or declarations suitable to define
-        the current style for subsequent highlighted text (e.g. CSS classes
-        in the `HTMLFormatter`).
-
-        The optional argument `arg` can be used to modify the generation and
-        is formatter dependent (it is standardized because it can be given on
-        the command line).
-
-        This method is called by the ``-S`` :doc:`command-line option <cmdline>`,
-        the `arg` is then given by the ``-a`` option.
-
-    .. method:: format(tokensource, outfile)
-
-        This method must format the tokens from the `tokensource` iterable and
-        write the formatted version to the file object `outfile`.
-
-        Formatter options can control how exactly the tokens are converted.
-
-    .. versionadded:: 0.7
-       A formatter must have the following attributes that are used by the
-       builtin lookup mechanism.
-
-    .. attribute:: name
-
-        Full name for the formatter, in human-readable form.
-
-    .. attribute:: aliases
-
-        A list of short, unique identifiers that can be used to lookup
-        the formatter from a list, e.g. using :func:`.get_formatter_by_name()`.
-
-    .. attribute:: filenames
-
-        A list of :mod:`fnmatch` patterns that match filenames for which this
-        formatter can produce output. The patterns in this list should be unique
-        among all formatters.
-
+.. autoclass:: Formatter
+   :members: __init__, get_style_defs, format
 
 .. module:: pygments.util
 
diff --git a/pygments/formatter.py b/pygments/formatter.py
index c464073d..2f991c76 100644
--- a/pygments/formatter.py
+++ b/pygments/formatter.py
@@ -26,7 +26,20 @@ class Formatter:
     """
     Converts a token stream to text.
 
-    Options accepted:
+    Formatters should have attributes to help selecting them. These
+    are similar to the corresponding :class:`lexer.Lexer` attributes.
+
+    .. autoattribute:: name
+       :no-value:
+
+    .. autoattribute:: aliases
+       :no-value:
+
+    .. autoattribute:: filenames
+       :no-value:
+
+    You can pass options as keyword arguments to the constructor.
+    All formatters accept these basic options:
 
     ``style``
         The style to use, can be a string or a Style subclass
@@ -47,15 +60,19 @@ class Formatter:
         support (default: None).
     ``outencoding``
         Overrides ``encoding`` if given.
+
     """
 
-    #: Name of the formatter
+    #: Full name for the formatter, in human-readable form.
     name = None
 
-    #: Shortcuts for the formatter
+    #: A list of short, unique identifiers that can be used to lookup
+    #: the formatter from a list, e.g. using :func:`.get_formatter_by_name()`.
     aliases = []
 
-    #: fn match rules
+    #: A list of :mod:`fnmatch` patterns that match filenames for which this
+    #: formatter can produce output. The patterns in this list should be unique
+    #: among all formatters.
     filenames = []
 
     #: If True, this formatter outputs Unicode strings when no encoding
@@ -63,6 +80,11 @@ class Formatter:
     unicodeoutput = True
 
     def __init__(self, **options):
+        """
+        As with lexers, this constructor takes arbitrary optional arguments,
+        and if you override it, you should first process your own options, then
+        call the base class implementation.
+        """
         self.style = _lookup_style(options.get('style', 'default'))
         self.full = get_bool_opt(options, 'full', False)
         self.title = options.get('title', '')
@@ -75,18 +97,25 @@ class Formatter:
 
     def get_style_defs(self, arg=''):
         """
-        Return the style definitions for the current style as a string.
+        This method must return statements or declarations suitable to define
+        the current style for subsequent highlighted text (e.g. CSS classes
+        in the `HTMLFormatter`).
 
-        ``arg`` is an additional argument whose meaning depends on the
-        formatter used. Note that ``arg`` can also be a list or tuple
-        for some formatters like the html formatter.
+        The optional argument `arg` can be used to modify the generation and
+        is formatter dependent (it is standardized because it can be given on
+        the command line).
+
+        This method is called by the ``-S`` :doc:`command-line option <cmdline>`,
+        the `arg` is then given by the ``-a`` option.
         """
         return ''
 
     def format(self, tokensource, outfile):
         """
-        Format ``tokensource``, an iterable of ``(tokentype, tokenstring)``
-        tuples and write it into ``outfile``.
+        This method must format the tokens from the `tokensource` iterable and
+        write the formatted version to the file object `outfile`.
+
+        Formatter options can control how exactly the tokens are converted.
         """
         if self.encoding:
             # wrap the outfile in a StreamWriter