Added better messages API docs

diff --git a/babel/messages/extract.py b/babel/messages/extract.py
index ccb1cfca7f4aa5abae6a3866c4c141be8d22767b..44b1eb38ce2b36d63afb88e31e3721869edc44be 100644 (file)
--- a/babel/messages/extract.py
+++ b/babel/messages/extract.py
@@ -59,14 +59,13 @@ def _strip_comment_tags(comments, tags):
     comments[:] = map(_strip, comments)
 
 
-def extract_from_dir(dirname=os.getcwd(), method_map=DEFAULT_MAPPING,
+def extract_from_dir(dirname=None, method_map=DEFAULT_MAPPING,
                      options_map=None, keywords=DEFAULT_KEYWORDS,
                      comment_tags=(), callback=None, strip_comment_tags=False):
     """Extract messages from any source files found in the given directory.
 
-    This function generates tuples of the form:
-
-        ``(filename, lineno, message, comments, context)``
+    This function generates tuples of the form ``(filename, lineno, message,
+    comments, context)``.
 
     Which extraction method is used per file is determined by the `method_map`
     parameter, which maps extended glob patterns to extraction method names.
@@ -109,7 +108,8 @@ def extract_from_dir(dirname=os.getcwd(), method_map=DEFAULT_MAPPING,
     ...     }
     ... }
 
-    :param dirname: the path to the directory to extract messages from
+    :param dirname: the path to the directory to extract messages from.  If
+                    not given the current working directory is used.
     :param method_map: a list of ``(pattern, method)`` tuples that maps of
                        extraction method names to extended glob patterns
     :param options_map: a dictionary of additional options (optional)
@@ -128,6 +128,8 @@ def extract_from_dir(dirname=os.getcwd(), method_map=DEFAULT_MAPPING,
                                tags to be removed from the collected comments.
     :see: `pathmatch`
     """
+    if dirname is None:
+        dirname = os.getcwd()
     if options_map is None:
         options_map = {}
 
@@ -167,9 +169,8 @@ def extract_from_file(method, filename, keywords=DEFAULT_KEYWORDS,
                       comment_tags=(), options=None, strip_comment_tags=False):
     """Extract messages from a specific file.
 
-    This function returns a list of tuples of the form:
-
-        ``(lineno, funcname, message)``
+    This function returns a list of tuples of the form ``(lineno, funcname,
+    message)``.
 
     :param filename: the path to the file to extract messages from
     :param method: a string specifying the extraction method (.e.g. "python")
@@ -196,9 +197,7 @@ def extract(method, fileobj, keywords=DEFAULT_KEYWORDS, comment_tags=(),
     """Extract messages from the given file-like object using the specified
     extraction method.
 
-    This function returns tuples of the form:
-
-        ``(lineno, message, comments)``
+    This function returns tuples of the form ``(lineno, message, comments)``.
 
     The implementation dispatches the actual extraction to plugins, based on the
     value of the ``method`` parameter.
@@ -325,9 +324,8 @@ def extract_nothing(fileobj, keywords, comment_tags, options):
 def extract_python(fileobj, keywords, comment_tags, options):
     """Extract messages from Python source code.
 
-    It returns an iterator yielding tuples in the following form::
-
-        (lineno, funcname, message, comments)
+    It returns an iterator yielding tuples in the following form ``(lineno,
+    funcname, message, comments)``.
 
     :param fileobj: the seekable, file-like object the messages should be
                     extracted from

diff --git a/docs/api/index.rst b/docs/api/index.rst
index 208d4decc84d39987ad5ecdd81a39be0f3fb3add..e21fa74ed52f16bb5f5d447ee97f370ca4f25c70 100644 (file)
--- a/docs/api/index.rst
+++ b/docs/api/index.rst
@@ -9,7 +9,7 @@ public API of Babel.
 
    core
    dates
-   messages
+   messages/index
    numbers
    plural
    support

diff --git a/docs/api/messages.rst b/docs/api/messages.rst
deleted file mode 100644 (file)
index aed231e..0000000
--- a/docs/api/messages.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-Messages and Catalogs
-=====================
-
-.. module:: babel.messages
-
-Babel provides functionality to work with message catalogs.  There is more
-functionality than that available but some of it is currently only
-documented in the sourcecode as we have to decide what part of the API
-will become public and what should stay internal.
-
-Basic Interface
----------------
-
-.. autoclass:: Message
-   :members:
-
-.. autoclass:: Catalog
-   :members:
-
-Exceptions
-----------
-
-.. autoexception:: TranslationError

diff --git a/docs/api/messages/catalog.rst b/docs/api/messages/catalog.rst
new file mode 100644 (file)
index 0000000..8a905bc
--- /dev/null
+++ b/docs/api/messages/catalog.rst
@@ -0,0 +1,25 @@
+Messages and Catalogs
+=====================
+
+.. module:: babel.messages.catalog
+
+This module provides a basic interface to hold catalog and message
+information.  It's generally used to modify a gettext catalog but it is
+not being used to actually use the translations.
+
+Catalogs
+--------
+
+.. autoclass:: Catalog
+   :members:
+
+Messages
+--------
+
+.. autoclass:: Message
+   :members:
+
+Exceptions
+----------
+
+.. autoexception:: TranslationError

diff --git a/docs/api/messages/extract.rst b/docs/api/messages/extract.rst
new file mode 100644 (file)
index 0000000..805aaff
--- /dev/null
+++ b/docs/api/messages/extract.rst
@@ -0,0 +1,36 @@
+Low-Level Extraction Interface
+==============================
+
+.. module:: babel.messages.extract
+
+The low level extraction interface can be used to extract from directories
+or files directly.  Normally this is not needed as the command line tools
+can do that for you.
+
+Extraction Functions
+--------------------
+
+The extraction functions are what the command line tools use internally to
+extract strings.
+
+.. autofunction:: extract_from_dir
+
+.. autofunction:: extract_from_file
+
+.. autofunction:: extract
+
+Language Parsing
+----------------
+
+The language parsing functions are used to extract strings out of source
+files.  These are automatically being used by the extraction functions but
+sometimes it can be useful to register wrapper functions, then these low
+level functions can be invoked.
+
+New functions can be registered through the setuptools entrypoint system.
+
+.. autofunction:: extract_python
+
+.. autofunction:: extract_javascript
+
+.. autofunction:: extract_nothing

diff --git a/docs/api/messages/index.rst b/docs/api/messages/index.rst
new file mode 100644 (file)
index 0000000..f9b13e4
--- /dev/null
+++ b/docs/api/messages/index.rst
@@ -0,0 +1,13 @@
+Messages and Catalogs
+=====================
+
+Babel provides functionality to work with message catalogs.  This part of
+the API documentation shows those parts.
+
+.. toctree::
+   :maxdepth: 2
+
+   catalog
+   extract
+   mofile
+   pofile

diff --git a/docs/api/messages/mofile.rst b/docs/api/messages/mofile.rst
new file mode 100644 (file)
index 0000000..ee023ab
--- /dev/null
+++ b/docs/api/messages/mofile.rst
@@ -0,0 +1,12 @@
+MO File Support
+===============
+
+.. module:: babel.messages.mofile
+
+The MO file support can read and write MO files.  It reads them into
+:class:`~babel.messages.catalog.Catalog` objects and also writes catalogs
+out.
+
+.. autofunction:: read_mo
+
+.. autofunction:: write_mo

diff --git a/docs/api/messages/pofile.rst b/docs/api/messages/pofile.rst
new file mode 100644 (file)
index 0000000..1a4ef08
--- /dev/null
+++ b/docs/api/messages/pofile.rst
@@ -0,0 +1,12 @@
+PO File Support
+===============
+
+.. module:: babel.messages.pofile
+
+The PO file support can read and write PO and POT files.  It reads them
+into :class:`~babel.messages.catalog.Catalog` objects and also writes
+catalogs out.
+
+.. autofunction:: read_po
+
+.. autofunction:: write_po