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