1 =====================================
2 Docutils Frequently Asked Questions
3 =====================================
6 :Web site: http://docutils.sourceforge.net/
7 :Copyright: This document has been placed in the public domain.
9 .. Please note that until there's a Q&A-specific construct available,
10 this FAQ will use section titles for questions. Therefore
11 questions must fit on one line. The title may be a summary of the
12 question, with the full question in the section body.
19 This is a work in progress. Please feel free to ask questions and/or
20 provide answers; `send email`__ to the `Docutils-Users mailing
21 list`__. Project members should feel free to edit the source text
25 __ mailto:docutils-users@lists.sourceforge.net
26 __ http://lists.sourceforge.net/lists/listinfo/docutils-users
35 Docutils_ is a system for processing plaintext documentation into
36 useful formats, such as HTML, XML, and TeX. It supports multiple
37 types of input, such as standalone files (implemented), inline
38 documentation from Python modules and packages (under development),
39 `PEPs (Python Enhancement Proposals)`_ (implemented), and others as
42 For an overview of the Docutils project implementation, see `PEP
43 258`_, "Docutils Design Specification".
45 Docutils is implemented in Python_.
47 .. _Docutils: http://docutils.sourceforge.net/
48 .. _PEPs (Python Enhancement Proposals):
49 http://www.python.org/peps/pep-0012.html
50 .. _PEP 258: spec/pep-0258.html
51 .. _Python: http://www.python.org/
54 Why is it called "Docutils"?
55 ----------------------------
57 Docutils is short for "Python Documentation Utilities". The name
58 "Docutils" was inspired by "Distutils", the Python Distribution
59 Utilities architected by Greg Ward, a component of Python's standard
62 The earliest known use of the term "docutils" in a Python context was
63 a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in
64 the Python Doc-SIG mailing list. It was suggested `as a project
65 name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to
66 a question from Tony "Tibs" Ibbs: "What do we want to *call* this
67 thing?". This was shortly after David Goodger first `announced
68 reStructuredText`__ on Doc-SIG.
70 Tibs used the name "Docutils" for `his effort`__ "to document what the
71 Python docutils package should support, with a particular emphasis on
72 documentation strings". Tibs joined the current project (and its
73 predecessors) and graciously donated the name.
75 For more history of reStructuredText and the Docutils project, see `An
76 Introduction to reStructuredText`_.
78 Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
79 or any other variation.
81 .. _An Introduction to reStructuredText: spec/rst/introduction.html
82 __ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html
83 __ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html
84 __ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
85 __ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html
88 Is there a GUI authoring environment for Docutils?
89 --------------------------------------------------
91 DocFactory_ is under development. It uses wxPython and looks very
95 http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
98 What is the status of the Docutils project?
99 -------------------------------------------
101 Although useful and relatively stable, Docutils is experimental code,
102 with APIs and architecture subject to change.
104 Our highest priority is to fix bugs as they are reported. So the
105 latest code from CVS (or `development snapshots`_) is almost always
106 the most stable (bug-free) as well as the most featureful.
109 What is the Docutils project release policy?
110 --------------------------------------------
112 It ought to be "release early & often", but official releases are a
113 significant effort and aren't done that often. We have
114 automatically-generated `development snapshots`_ which always contain
115 the latest code from CVS. As the project matures, we may formalize on
116 a stable/development-branch scheme, but we're not using anything like
119 If anyone would like to volunteer as a release coordinator, please
120 `contact the project coordinator`_.
122 .. _development snapshots:
123 http://docutils.sf.net/#development-snapshots
125 .. _contact the project coordinator:
126 mailto:goodger@python.org
132 What is reStructuredText?
133 -------------------------
135 reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
136 plaintext markup syntax and parser system. The reStructuredText
137 parser is a component of Docutils_. reStructuredText is a revision
138 and reinterpretation of the StructuredText_ and Setext_ lightweight
141 If you are reading this on the web, you can see for yourself. `The
142 source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open
143 it in another window and compare them side by side.
145 `A ReStructuredText Primer <docs/rst/quickstart.html>`_ and the `Quick
146 reStructuredText <docs/rst/quickref.html>`_ user reference are a good
147 place to start. The `reStructuredText Markup Specification
148 <spec/rst/reStructuredText.html>`_ is a detailed technical
151 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
153 http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
154 .. _Setext: mirror/setext.html
157 Why is it called "reStructuredText"?
158 ------------------------------------
160 The name came from a combination of "StructuredText", one of
161 reStructuredText's predecessors, with "re": "revised", "reworked", and
162 "reinterpreted", and as in the ``re.py`` regular expression module.
163 For a detailed history of reStructuredText and the Docutils project,
164 see `An Introduction to reStructuredText`_.
167 What's the standard abbreviation for "reStructuredText"?
168 --------------------------------------------------------
170 "RST" and "ReST" (or "reST") are both acceptable. Care should be
171 taken with capitalization, to avoid confusion with "REST__", an
172 acronym for "Representational State Transfer".
174 The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
175 they overemphasize reStructuredText's precedessor, Zope's
178 __ http://www.xml.com/pub/a/2002/02/06/rest.html
181 What's the standard filename extension for a reStructuredText file?
182 -------------------------------------------------------------------
184 It's ".txt". Some people would like to use ".rest" or ".rst" or
185 ".restx", but why bother? ReStructuredText source files are meant to
186 be readable as plaintext, and most operating systems already associate
187 ".txt" with text files. Using a specialized filename extension would
188 require that users alter their OS settings, which is something that
189 many users will not be willing or able to do.
192 Are there any reStructuredText editor extensions?
193 -------------------------------------------------
195 There is `some code under development for Emacs`__.
197 Extensions for other editors are welcome.
199 __ http://docutils.sf.net/tools/editors/emacs/
202 How can I indicate the document title? Subtitle?
203 -------------------------------------------------
205 A uniquely-adorned section title at the beginning of a document is
206 treated specially, as the document title. Similarly, a
207 uniquely-adorned section title immediately after the document title
208 becomes the document subtitle. For example::
210 This is the Document Title
211 ==========================
213 This is the Document Subtitle
214 -----------------------------
216 Here's an ordinary paragraph.
220 Here's an ordinary paragraph.
222 This is *not* a Document Title
223 ==============================
225 The "ordinary paragraph" above the section title
226 prevents it from becoming the document title.
229 How can I represent esoteric characters (e.g. character entities) in a document?
230 --------------------------------------------------------------------------------
232 For example, say you want an em-dash (XML character entity —,
233 Unicode character ``\u2014``) in your document: use a real em-dash.
234 Insert concrete characters (e.g. type a *real* em-dash) into your
235 input file, using whatever encoding suits your application, and tell
236 Docutils the input encoding. Docutils uses Unicode internally, so the
237 em-dash character is a real em-dash internally.
239 ReStructuredText has no character entity subsystem; it doesn't know
240 anything about XML charents. "—" in input text is 7 discrete
241 characters to Docutils; no interpretation happens. When writing HTML,
242 the "&" is converted to "&", so in the output you'd see
243 "&mdash;". There's no difference in interpretation for text
244 inside or outside inline literals or literal blocks -- no character
245 entity interpretation in either case.
247 If you can't use a Unicode-compatible encoding and must rely on 7-bit
248 ASCII, there is a workaround, although ugly. David Priest developed a
249 substitution table for character entities; see
250 <http://article.gmane.org/gmane.comp.python.documentation/432> and
251 David's other March Doc-SIG posts. Incorporating this into Docutils
252 is on the `to-do list <spec/notes.html#to-do>`_.
254 If you insist on using XML-style charents, you'll have to implement a
255 pre-processing system to convert to UTF-8 or something. That opens a
256 can of worms though; you can no longer *write* about charents
257 naturally; you'd have to write "&mdash;".
260 How can I generate backticks using a Scandinavian keyboard?
261 -----------------------------------------------------------
263 The use of backticks in reStructuredText is a bit awkward with
264 Scandinavian keyboards, where the backtick is a "dead" key. To get
265 one ` character one must press SHIFT-` + SPACE.
267 Unfortunately, with all the variations out there, there's no way to
268 please everyone. For Scandinavian programmers and technical writers,
269 this is not limited to reStructuredText but affects many languages and
272 Possible solutions include
274 * If you have to input a lot of backticks, simply type one in the
275 normal/awkward way, select it, copy and then paste the rest (CTRL-V
276 is a lot faster than SHIFT-` + SPACE).
278 * Use keyboard macros.
280 * Remap the keyboard. The Scandinavian keyboard layout is awkward for
281 other programming/technical characters too; for example, []{}
282 etc. are a bit awkward compared to US keyboards.
284 If anyone knows of other/better solutions, please `let us know`_.
287 Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping)
288 -----------------------------------------------------------------------
290 People have tossed the idea around, but little if any actual work has
291 ever been done. There's no reason why reStructuredText should not be
292 round-trippable to/from XML; any technicalities which prevent
293 round-tripping would be considered bugs. Whitespace would not be
294 identical, but paragraphs shouldn't suffer. The tricky parts would be
295 the smaller details, like links and IDs and other bookkeeping.
297 For HTML, true round-tripping may not be possible. Even adding lots
298 of extra "class" attributes may not be enough. A "simple HTML" to RST
299 filter is possible -- for some definition of "simple HTML" -- but HTML
300 is used as dumb formatting so much that such a filter may not be
301 particularly useful. No general-purpose filter exists. An 80/20
302 approach should work though: build a tool that does 80% of the work
303 automatically, leaving the other 20% for manual tweaks.
306 Are there any Wikis that use reStructuredText syntax?
307 -----------------------------------------------------
309 There are several, with various degrees of completeness. With no
310 implied endorsement or recommendation, and in no particular order:
312 * `Ian Bicking's experimental code <sandbox/ianb/wiki/WikiPage.py>`__
313 * `MoinMoin <http://moin.sf.net>`__ has some support; `here's a sample
314 <http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample>`__
315 * Zope-based `Zwiki <http://zwiki.org/>`__
316 * `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
318 Please `let us know`_ of any other reStructuredText Wikis.
320 The example application for the `Web Framework Shootout
321 <http://colorstudy.com/docs/shootout.html>` article is a Wiki using
325 Are there any Weblog (Blog) projects that use reStructuredText syntax?
326 ----------------------------------------------------------------------
328 With no implied endorsement or recommendation, and in no particular
331 * `Python Desktop Server <http://pyds.muensterland.org/>`__
332 * `PyBloxsom <http://roughingit.subtlehints.net/pyblosxom>`__
334 Please `let us know`_ of any other reStructuredText Blogs.
340 What is the status of the HTML Writer?
341 --------------------------------------
343 The HTML Writer module, ``docutils/writers/html4css1.py``, is a
344 proof-of-concept reference implementation. While it is a complete
345 implementation, some aspects of the HTML it produces may be
346 incompatible with older browsers or specialized applications (such as
347 web templating). Alternate implementations are welcome.
350 What kind of HTML does it produce?
351 ----------------------------------
353 It produces XHTML compatible with the `HTML 4.01`_ and `XHTML 1.0`_
354 specifications. A cascading style sheet ("default.css" by default) is
355 required for proper viewing with a modern graphical browser. Correct
356 rendering of the HTML produced depends on the CSS support of the
359 .. _HTML 4.01: http://www.w3.org/TR/html4/
360 .. _XHTML 1.0: http://www.w3.org/TR/xhtml1/
363 What browsers are supported?
364 ----------------------------
366 No specific browser is targeted; all modern graphical browsers should
367 work. Some older browsers, text-only browsers, and browsers without
368 full CSS support are known to produce inferior results. Mozilla
369 (version 1.0 and up) and MS Internet Explorer (version 5.0 and up) are
370 known to give good results. Reports of experiences with other
371 browsers are welcome.
374 Unexpected results from tools/html.py: H1, H1 instead of H1, H2. Why?
375 ----------------------------------------------------------------------
377 Here's the question in full:
384 All my life, I wanted to be H1.
389 But along came H1, and so shouldn't I be H2?
395 Yeah, imagine me, I'm stuck at H3! No?!?
397 When I run it through tools/html.py, I get unexpected results
398 (below). I was expecting H1, H2, then H3; instead, I get H1, H1,
405 <title>Heading 1</title>
406 <link rel="stylesheet" href="default.css" type="text/css" />
409 <div class="document" id="heading-1">
410 <h1 class="title">Heading 1</h1> <-- first H1
411 <p>All my life, I wanted to be H1.</p>
412 <div class="section" id="heading-1-1">
413 <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1
414 <p>But along came H1, and so now I must be H2.</p>
415 <div class="section" id="heading-1-1-1">
416 <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
417 <p>Yeah, imagine me, I'm stuck at H3!</p>
422 Check the "class" attribute on the H1 tags, and you will see a
423 difference. The first H1 is actually ``<h1 class="title">``; this is
424 the document title, and the default stylesheet renders it centered.
425 There can also be an ``<h2 class="subtitle">`` for the document
428 If there's only one highest-level section title at the beginning of a
429 document, it is treated specially, as the document title. (Similarly,
430 a lone second-highest-level section title may become the document
431 subtitle.) Rather than use a plain H1 for that, we use ``<h1
432 class="title">`` so that we can use H1 again within the document. Why
433 do we do this? HTML only has H1-H6, so by making H1 do double duty,
434 we effectively reserve these tags to provide 6 levels of heading
435 beyond the single document title.
437 HTML is being used for dumb formatting for nothing but final display.
438 A stylesheet *is required*, and one is provided:
439 tools/stylesheets/default.css. Of course, you're welcome to roll your
442 (Thanks to Mark McEahern for the question and much of the answer.)
445 Why do enumerated lists only use numbers (no letters or roman numerals)?
446 ------------------------------------------------------------------------
448 The rendering of enumerators (the numbers or letters acting as list
449 markers) is completely governed by the stylesheet, so either the
450 browser can't find the stylesheet (try using the "--embed-stylesheet"
451 option), or the browser can't understand it (try a recent Mozilla or
458 Can I use Docutils for Python auto-documentation?
459 -------------------------------------------------
461 Docstring extraction is still under development. There is most of a
462 source code parsing module in docutils/readers/python/moduleparser.py.
463 I (David Goodger) haven't worked on it in a while, but I do plan to
464 finish it eventually. Ian Bicking wrote an initial front end for my
465 moduleparser module, in sandbox/ianb/extractor/extractor.py.
471 Is the Docutils document model based on any existing XML models?
472 ----------------------------------------------------------------
474 Not directly, no. It borrows bits from DocBook, HTML, and others. I
475 (David Goodger) have designed several document models over the years,
476 and have my own biases. The Docutils document model is designed for
477 simplicity and extensibility, and has been influenced by the needs of
478 the reStructuredText markup.