David Goodger
Note
This document describes the traditional approach with hand-crafted front-end scripts. Since version 0.21, the package installer installs front-end scripts generated from "console_scripts" entry point definitions.
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.rst 9906 2024-08-15 08:43:38Z 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. 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='html', description=description)
That's it! The Docutils Publisher takes care of the rest.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4