cmlenz@2: .. -*- mode: rst; encoding: utf-8 -*-
cmlenz@2: 
cmlenz@2: ================================
cmlenz@2: Distutils/Setuptools Integration
cmlenz@2: ================================
cmlenz@2: 
cmlenz@2: Babel provides commands for integration into ``setup.py`` scripts, based on
cmlenz@2: either the ``distutils`` package that is part of the Python standard library,
cmlenz@2: or the third-party ``setuptools`` package.
cmlenz@2: 
cmlenz@2: These commands are available by default when Babel has been properly installed,
cmlenz@2: and ``setup.py`` is using ``setuptools``. For projects that use plain old
cmlenz@40: ``distutils``, the commands need to be registered explicitly, for example:
cmlenz@40: 
cmlenz@40: .. code-block:: python
cmlenz@2: 
cmlenz@2:     from distutils.core import setup
cmlenz@2:     from babel.catalog import frontend as babel
cmlenz@2:     
cmlenz@2:     setup(
cmlenz@2:         ...
cmlenz@2:         cmd_class = {'extract_messages': babel.extract_messages}
cmlenz@2:     )
cmlenz@2: 
cmlenz@2: 
cmlenz@2: .. contents:: Contents
cmlenz@2:    :depth: 2
cmlenz@2: .. sectnum::
cmlenz@2: 
cmlenz@2: 
cmlenz@2: extract_messages
cmlenz@2: ================
cmlenz@2: 
cmlenz@2: The ``extract_messages`` command is comparabe to the GNU ``xgettext`` program:
cmlenz@2: it can extract localizable messages from a variety of difference source files,
cmlenz@2: and generate a PO (portable object) template file from the collected messages.
cmlenz@2: 
cmlenz@2: If the command has been correctly installed or registered, another project's
cmlenz@2: ``setup.py`` script should allow you to use the command::
cmlenz@2: 
cmlenz@2:     $ ./setup.py extract_messages --help
cmlenz@2:     Global options:
cmlenz@2:       --verbose (-v)  run verbosely (default)
cmlenz@2:       --quiet (-q)    run quietly (turns verbosity off)
cmlenz@2:       --dry-run (-n)  don't actually do anything
cmlenz@2:       --help (-h)     show detailed help message
cmlenz@2: 
cmlenz@2:     Options for 'extract_messages' command:
cmlenz@2:       --charset        charset to use in the output
cmlenz@2:       --keywords (-k)  comma-separated list of keywords to look for in addition
cmlenz@2:                        to the defaults
cmlenz@2:       --no-location    do not write filename/lineno location comments
cmlenz@2:       --output-file    filename of the output PO file
cmlenz@2: 
cmlenz@2: Running the command will produce a PO file::
cmlenz@2: 
cmlenz@2:     $ ./setup.py extract_messages --output-file webapp/locales/messages.pot
cmlenz@2:     running extract_messages
cmlenz@2:     extracting messages from 'webapp'
cmlenz@2:     extracting messages from 'webparts'
cmlenz@2:     writing PO file to webapp/locales/messages.pot
cmlenz@2: 
cmlenz@2: 
cmlenz@2: Options
cmlenz@2: -------
cmlenz@2: 
cmlenz@2: As shown in the ``--help`` output above, the ``extract_messages`` command
cmlenz@2: accepts the following options:
cmlenz@2: 
cmlenz@2: ``--charset``
cmlenz@2:   The character set / encoding to use in the generated PO file.
cmlenz@2: ``--keywords``
cmlenz@2:   A comma-separated list of keywords (function names) to look for in addition
cmlenz@2:   to the default keywords
cmlenz@2: ``--no-location``
cmlenz@2:   If this flag is set, location comments will not be included in the generated
cmlenz@2:   PO file.
cmlenz@2: ``--output-file`` or ``-o``
cmlenz@2:   The path to the PO file that should be generated
cmlenz@2: