Use autodoc for pygments.lexers

2 files changed, 52 insertions, 105 deletions

diff --git a/doc/docs/api.rst b/doc/docs/api.rst
index a1dd71e7..bf11b46c 100644
--- a/doc/docs/api.rst
+++ b/doc/docs/api.rst
@@ -21,85 +21,15 @@ Functions from the :mod:`pygments` module:
 
 Functions from :mod:`pygments.lexers`:
 
-.. function:: get_lexer_by_name(alias, **options)
-
-    Return an instance of a `Lexer` subclass that has `alias` in its
-    aliases list. The lexer is given the `options` at its
-    instantiation.
-
-    Will raise :exc:`pygments.util.ClassNotFound` if no lexer with that alias is
-    found.
-
-.. function:: get_lexer_for_filename(fn, **options)
-
-    Return a `Lexer` subclass instance that has a filename pattern
-    matching `fn`. The lexer is given the `options` at its
-    instantiation.
-
-    Will raise :exc:`pygments.util.ClassNotFound` if no lexer for that filename
-    is found.
-
-.. function:: get_lexer_for_mimetype(mime, **options)
-
-    Return a `Lexer` subclass instance that has `mime` in its mimetype
-    list. The lexer is given the `options` at its instantiation.
-
-    Will raise :exc:`pygments.util.ClassNotFound` if not lexer for that mimetype
-    is found.
-
-.. function:: load_lexer_from_file(filename, lexername="CustomLexer", **options)
-
-    Return a `Lexer` subclass instance loaded from the provided file, relative
-    to the current directory. The file is expected to contain a Lexer class
-    named `lexername` (by default, CustomLexer). Users should be very careful with
-    the input, because this method is equivalent to running eval on the input file.
-    The lexer is given the `options` at its instantiation.
-
-    :exc:`pygments.util.ClassNotFound` is raised if there are any errors loading the Lexer
-
-    .. versionadded:: 2.2
-
-.. function:: guess_lexer(text, **options)
-
-    Return a `Lexer` subclass instance that's guessed from the text in
-    `text`. For that, the :meth:`.analyse_text()` method of every known lexer
-    class is called with the text as argument, and the lexer which returned the
-    highest value will be instantiated and returned.
-
-    :exc:`pygments.util.ClassNotFound` is raised if no lexer thinks it can
-    handle the content.
-
-.. function:: guess_lexer_for_filename(filename, text, **options)
-
-    As :func:`guess_lexer()`, but only lexers which have a pattern in `filenames`
-    or `alias_filenames` that matches `filename` are taken into consideration.
-
-    :exc:`pygments.util.ClassNotFound` is raised if no lexer thinks it can
-    handle the content.
-
-.. function:: get_all_lexers()
-
-    Return an iterable over all registered lexers, yielding tuples in the
-    format::
-
-    	(longname, tuple of aliases, tuple of filename patterns, tuple of mimetypes)
-
-    .. versionadded:: 0.6
-
-.. function:: find_lexer_class_by_name(alias)
-
-    Return the `Lexer` subclass that has `alias` in its aliases list, without
-    instantiating it.
-
-    Will raise :exc:`pygments.util.ClassNotFound` if no lexer with that alias is
-    found.
-
-    .. versionadded:: 2.2
-
-.. function:: find_lexer_class(name)
-
-    Return the `Lexer` subclass that with the *name* attribute as given by
-    the *name* argument.
+.. autofunction:: get_lexer_by_name
+.. autofunction:: get_lexer_for_filename
+.. autofunction:: get_lexer_for_mimetype
+.. autofunction:: load_lexer_from_file
+.. autofunction:: guess_lexer
+.. autofunction:: guess_lexer_for_filename
+.. autofunction:: get_all_lexers
+.. autofunction:: find_lexer_class_by_name
+.. autofunction:: find_lexer_class
 
 
 .. module:: pygments.formatters
@@ -169,6 +99,7 @@ There are several base class derived from ``Lexer`` you can use to build your le
 .. autoclass:: pygments.lexer.ExtendedRegexLexer
 .. autoclass:: pygments.lexer.DelegatingLexer
 
+
 .. module:: pygments.formatter
 
 Formatters
@@ -181,7 +112,6 @@ A formatter is derived from this class:
    :members: __init__, get_style_defs, format
 
 
-
 .. module:: pygments.util
 
 Option processing
diff --git a/pygments/lexers/__init__.py b/pygments/lexers/__init__.py
index 35986b7d..efe99a0c 100644
--- a/pygments/lexers/__init__.py
+++ b/pygments/lexers/__init__.py
@@ -62,9 +62,9 @@ def get_all_lexers(plugins=True):
 
 
 def find_lexer_class(name):
-    """Lookup a lexer class by name.
-
-    Return None if not found.
+    """
+    Return the `Lexer` subclass that with the *name* attribute as given by
+    the *name* argument.
     """
     if name in _lexer_cache:
         return _lexer_cache[name]
@@ -80,10 +80,15 @@ def find_lexer_class(name):
 
 
 def find_lexer_class_by_name(_alias):
-    """Lookup a lexer class by alias.
+    """
+    Return the `Lexer` subclass that has `alias` in its aliases list, without
+    instantiating it.
 
     Like `get_lexer_by_name`, but does not instantiate the class.
 
+    Will raise :exc:`pygments.util.ClassNotFound` if no lexer with that alias is
+    found.
+
     .. versionadded:: 2.2
     """
     if not _alias:
@@ -102,9 +107,13 @@ def find_lexer_class_by_name(_alias):
 
 
 def get_lexer_by_name(_alias, **options):
-    """Get a lexer by an alias.
+    """
+    Return an instance of a `Lexer` subclass that has `alias` in its
+    aliases list. The lexer is given the `options` at its
+    instantiation.
 
-    Raises ClassNotFound if not found.
+    Will raise :exc:`pygments.util.ClassNotFound` if no lexer with that alias is
+    found.
     """
     if not _alias:
         raise ClassNotFound('no lexer for alias %r found' % _alias)
@@ -203,10 +212,15 @@ def find_lexer_class_for_filename(_fn, code=None):
 def get_lexer_for_filename(_fn, code=None, **options):
     """Get a lexer for a filename.
 
-    If multiple lexers match the filename pattern, use ``analyse_text()`` to
-    figure out which one is more appropriate.
+    Return a `Lexer` subclass instance that has a filename pattern
+    matching `fn`. The lexer is given the `options` at its
+    instantiation.
 
-    Raises ClassNotFound if not found.
+    Raise :exc:`pygments.util.ClassNotFound` if no lexer for that filename
+    is found.
+
+    If multiple lexers match the filename pattern, use their ``analyse_text()``
+    methods to figure out which one is more appropriate.
     """
     res = find_lexer_class_for_filename(_fn, code)
     if not res:
@@ -215,9 +229,12 @@ def get_lexer_for_filename(_fn, code=None, **options):
 
 
 def get_lexer_for_mimetype(_mime, **options):
-    """Get a lexer for a mimetype.
+    """
+    Return a `Lexer` subclass instance that has `mime` in its mimetype
+    list. The lexer is given the `options` at its instantiation.
 
-    Raises ClassNotFound if not found.
+    Will raise :exc:`pygments.util.ClassNotFound` if not lexer for that mimetype
+    is found.
     """
     for modname, name, _, _, mimetypes in LEXERS.values():
         if _mime in mimetypes:
@@ -243,19 +260,11 @@ def _iter_lexerclasses(plugins=True):
 
 def guess_lexer_for_filename(_fn, _text, **options):
     """
-    Lookup all lexers that handle those filenames primary (``filenames``)
-    or secondary (``alias_filenames``). Then run a text analysis for those
-    lexers and choose the best result.
-
-    usage::
-
-        >>> from pygments.lexers import guess_lexer_for_filename
-        >>> guess_lexer_for_filename('hello.html', '<%= @foo %>')
-        <pygments.lexers.templates.RhtmlLexer object at 0xb7d2f32c>
-        >>> guess_lexer_for_filename('hello.html', '<h1>{{ title|e }}</h1>')
-        <pygments.lexers.templates.HtmlDjangoLexer object at 0xb7d2f2ac>
-        >>> guess_lexer_for_filename('style.css', 'a { color: <?= $link ?> }')
-        <pygments.lexers.templates.CssPhpLexer object at 0xb7ba518c>
+    As :func:`guess_lexer()`, but only lexers which have a pattern in `filenames`
+    or `alias_filenames` that matches `filename` are taken into consideration.
+
+    :exc:`pygments.util.ClassNotFound` is raised if no lexer thinks it can
+    handle the content.
     """
     fn = basename(_fn)
     primary = {}
@@ -293,7 +302,15 @@ def guess_lexer_for_filename(_fn, _text, **options):
 
 
 def guess_lexer(_text, **options):
-    """Guess a lexer by strong distinctions in the text (eg, shebang)."""
+    """
+    Return a `Lexer` subclass instance that's guessed from the text in
+    `text`. For that, the :meth:`.analyse_text()` method of every known lexer
+    class is called with the text as argument, and the lexer which returned the
+    highest value will be instantiated and returned.
+
+    :exc:`pygments.util.ClassNotFound` is raised if no lexer thinks it can
+    handle the content.
+    """
 
     if not isinstance(_text, str):
         inencoding = options.get('inencoding', options.get('encoding'))