You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
66 lines
2.3 KiB
66 lines
2.3 KiB
=============================================== |
|
Inside A Docutils Command-Line Front-End Tool |
|
=============================================== |
|
|
|
:Author: David Goodger |
|
:Contact: docutils-develop@lists.sourceforge.net |
|
:Date: $Date: 2012-01-03 20:23:53 +0100 (Di, 03 Jan 2012) $ |
|
:Revision: $Revision: 7302 $ |
|
:Copyright: This document has been placed in the public domain. |
|
|
|
`The Docutils Publisher`_ class was set up to make building |
|
command-line tools easy. All that's required is to choose components |
|
and supply settings for variations. Let's take a look at a typical |
|
command-line front-end tool, ``tools/rst2html.py``, from top to |
|
bottom. |
|
|
|
On Unixish systems, it's best to make the file executable (``chmod +x |
|
file``), and supply an interpreter on the first line, the "shebang" or |
|
"hash-bang" line:: |
|
|
|
#!/usr/bin/env python |
|
|
|
Windows systems can be set up to associate the Python interpreter with |
|
the ``.py`` extension. |
|
|
|
Next are some comments providing metadata:: |
|
|
|
# $Id: cmdline-tool.txt 7302 2012-01-03 19:23:53Z grubert $ |
|
# Author: David Goodger <goodger@python.org> |
|
# Copyright: This module has been placed in the public domain. |
|
|
|
The module docstring describes the purpose of the tool:: |
|
|
|
""" |
|
A minimal front end to the Docutils Publisher, producing HTML. |
|
""" |
|
|
|
This next block attempts to invoke locale support for |
|
internationalization services, specifically text encoding. It's not |
|
supported on all platforms though, so it's forgiving:: |
|
|
|
try: |
|
import locale |
|
locale.setlocale(locale.LC_ALL, '') |
|
except: |
|
pass |
|
|
|
The real work will be done by the code that's imported here:: |
|
|
|
from docutils.core import publish_cmdline, default_description |
|
|
|
We construct a description of the tool, for command-line help:: |
|
|
|
description = ('Generates (X)HTML documents from standalone ' |
|
'reStructuredText sources. ' + default_description) |
|
|
|
Now we call the Publisher convenience function, which takes over. |
|
Most of its defaults are used ("standalone" Reader, |
|
"reStructuredText" Parser, etc.). The HTML Writer is chosen by name, |
|
and a description for command-line help is passed in:: |
|
|
|
publish_cmdline(writer_name='html', description=description) |
|
|
|
That's it! `The Docutils Publisher`_ takes care of the rest. |
|
|
|
.. _The Docutils Publisher: ./publisher.html
|
|
|