docs/api/cmdline-tool.txt

   1 ===============================================
   2  Inside A Docutils Command-Line Front-End Tool
   3 ===============================================
   4
   5 :Author: David Goodger
   6 :Contact: goodger@python.org
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 `The Docutils Publisher`_ class was set up to make building
  12 command-line tools easy.  All that's required is to choose components
  13 and supply settings for variations.  Let's take a look at a typical
  14 command-line front-end tool, ``tools/rst2html.py``, from top to
  15 bottom.
  16
  17 On Unixish systems, it's best to make the file executable (``chmod +x
  18 file``), and supply an interpreter on the first line, the "shebang" or
  19 "hash-bang" line::
  20
  21     #!/usr/bin/env python
  22
  23 Windows systems can be set up to associate the Python interpreter with
  24 the ``.py`` extension.
  25
  26 Next are some comments providing metadata::
  27
  28     # $Id$
  29     # Author: David Goodger <goodger@python.org>
  30     # Copyright: This module has been placed in the public domain.
  31
  32 The module docstring describes the purpose of the tool::
  33
  34     """
  35     A minimal front end to the Docutils Publisher, producing HTML.
  36     """
  37
  38 This next block attempts to invoke locale support for
  39 internationalization services, specifically text encoding.  It's not
  40 supported on all platforms though, so it's forgiving::
  41
  42     try:
  43         import locale
  44         locale.setlocale(locale.LC_ALL, '')
  45     except:
  46         pass
  47
  48 The real work will be done by the code that's imported here::
  49
  50     from docutils.core import publish_cmdline, default_description
  51
  52 We construct a description of the tool, for command-line help::
  53
  54     description = ('Generates (X)HTML documents from standalone '
  55                    'reStructuredText sources.  ' + default_description)
  56
  57 Now we call the Publisher convenience function, which takes over.
  58 Most of it's defaults are used ("standalone" Reader,
  59 "reStructuredText" Parser, etc.).  The HTML Writer is chosen by name,
  60 and a description for command-line help is passed in::
  61
  62     publish_cmdline(writer_name='html', description=description)
  63
  64 That's it!  `The Docutils Publisher`_ takes care of the rest.
  65
  66 .. _The Docutils Publisher: ./publisher.html