Change interface of add_source_parser() and add add_source_suffix()

doc/extdev/appapi.rst

@@ -85,7 +85,9 @@ package.
 
 .. automethod:: Sphinx.add_search_language(cls)
 
-.. automethod:: Sphinx.add_source_parser(suffix, parser)
+.. automethod:: Sphinx.add_source_suffix(suffix, filetype)
+
+.. automethod:: Sphinx.add_source_parser(parser)
 
 .. automethod:: Sphinx.add_env_collector(collector)
 

doc/extdev/parserapi.rst

@@ -3,6 +3,35 @@
 Parser API
 ==========
 
+`The docutils documentation describes`__ parsers as follows:
+
+    The Parser analyzes the input document and creates a node tree
+    representation.
+
+__ http://docutils.sourceforge.net/docs/dev/hacking.html#parsing-the-document
+
+In Sphinx, the parser modules works as same as docutils.  The parsers are
+registered to Sphinx by extensions using Application APIs;
+:meth:`Sphinx.add_source_suffix()` and :meth:`Sphinx.add_source_parsers()`.
+
+The *source suffix* is a mapping from file suffix to file type.  For example,
+``.rst`` file is mapped to ``'restructuredtext'`` type.  Sphinx uses the
+file type to looking for parsers from registered list.  On searching,
+Sphinx refers to the ``Parser.supported`` attribute and picks up a parser
+which contains the file type in the attribute.
+
+The users can override the source suffix mappings using
+:confval:`source_suffix` like following::
+
+    # a mapping from file suffix to file types
+    source_suffix = {
+        '.rst': 'restructuredtext',
+        '.md': 'markdown',
+    }
+
+You should indicate file types your parser supports. This will allow users
+to configure their settings appropriately.
+
 .. module:: sphinx.parsers
 
 .. autoclass:: Parser