FAQ.txt

   1 =====================================
   2  Docutils Frequently Asked Questions
   3 =====================================
   4
   5 :Date: $Date$
   6 :Web site: http://docutils.sourceforge.net/
   7 :Copyright: This document has been placed in the public domain.
   8
   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.
  13
  14
  15 .. contents::
  16 .. sectnum::
  17
  18
  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 list`__
  21 [1]_.  Project members should feel free to edit the source text file
  22 directly.
  23
  24 .. [1] Due to overwhelming amounts of spam, the
  25    docutils-users@lists.sourceforge.net mailing list has been set up
  26    for subscriber posting only.  Non-subscribers who post to
  27    docutils-users will receive a message with "Subject: Your message
  28    to Docutils-users awaits moderator approval".  Legitimate messages
  29    are accepted and posted as soon as possible (a list administrator
  30    must verify the message manually).  If you'd like to subscribe to
  31    docutils-users, please visit
  32    <http://lists.sourceforge.net/lists/listinfo/docutils-users>.
  33
  34 .. _let us know:
  35 __ mailto:docutils-users@lists.sourceforge.net
  36 __ http://lists.sourceforge.net/lists/listinfo/docutils-users
  37
  38
  39 Docutils
  40 ========
  41
  42 What is Docutils?
  43 -----------------
  44
  45 Docutils_ is a system for processing plaintext documentation into
  46 useful formats, such as HTML, XML, and TeX.  It supports multiple
  47 types of input, such as standalone files (implemented), inline
  48 documentation from Python modules and packages (under development),
  49 `PEPs (Python Enhancement Proposals)`_ (implemented), and others as
  50 discovered.
  51
  52 For an overview of the Docutils project implementation, see `PEP
  53 258`_, "Docutils Design Specification".
  54
  55 Docutils is implemented in Python_.
  56
  57 .. _Docutils: http://docutils.sourceforge.net/
  58 .. _PEPs (Python Enhancement Proposals):
  59    http://www.python.org/peps/pep-0012.html
  60 .. _PEP 258: docs/peps/pep-0258.html
  61 .. _Python: http://www.python.org/
  62
  63
  64 Why is it called "Docutils"?
  65 ----------------------------
  66
  67 Docutils is short for "Python Documentation Utilities".  The name
  68 "Docutils" was inspired by "Distutils", the Python Distribution
  69 Utilities architected by Greg Ward, a component of Python's standard
  70 library.
  71
  72 The earliest known use of the term "docutils" in a Python context was
  73 a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in
  74 the Python Doc-SIG mailing list.  It was suggested `as a project
  75 name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to
  76 a question from Tony "Tibs" Ibbs: "What do we want to *call* this
  77 thing?".  This was shortly after David Goodger first `announced
  78 reStructuredText`__ on Doc-SIG.
  79
  80 Tibs used the name "Docutils" for `his effort`__ "to document what the
  81 Python docutils package should support, with a particular emphasis on
  82 documentation strings".  Tibs joined the current project (and its
  83 predecessors) and graciously donated the name.
  84
  85 For more history of reStructuredText and the Docutils project, see `An
  86 Introduction to reStructuredText`_.
  87
  88 Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
  89 or any other variation.
  90
  91 .. _An Introduction to reStructuredText: ref/rst/introduction.html
  92 __ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html
  93 __ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html
  94 __ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
  95 __ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html
  96
  97
  98 Is there a GUI authoring environment for Docutils?
  99 --------------------------------------------------
 100
 101 DocFactory_ is under development.  It uses wxPython and looks very
 102 promising.
 103
 104 .. _DocFactory:
 105    http://docutils.sf.net/sandbox/gschwant/docfactory/doc/
 106
 107
 108 What is the status of the Docutils project?
 109 -------------------------------------------
 110
 111 Although useful and relatively stable, Docutils is experimental code,
 112 with APIs and architecture subject to change.
 113
 114 Our highest priority is to fix bugs as they are reported.  So the
 115 latest code from CVS (or `development snapshots`_) is almost always
 116 the most stable (bug-free) as well as the most featureful.
 117
 118
 119 What is the Docutils project release policy?
 120 --------------------------------------------
 121
 122 It ought to be "release early & often", but official releases are a
 123 significant effort and aren't done that often.  We have
 124 automatically-generated `development snapshots`_ which always contain
 125 the latest code from CVS.  As the project matures, we may formalize on
 126 a stable/development-branch scheme, but we're not using anything like
 127 that yet.
 128
 129 If anyone would like to volunteer as a release coordinator, please
 130 `contact the project coordinator`_.
 131
 132 .. _development snapshots:
 133    http://docutils.sf.net/#development-snapshots
 134
 135 .. _contact the project coordinator:
 136    mailto:goodger@python.org
 137
 138
 139 reStructuredText
 140 ================
 141
 142 What is reStructuredText?
 143 -------------------------
 144
 145 reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
 146 plaintext markup syntax and parser system.  The reStructuredText
 147 parser is a component of Docutils_.  reStructuredText is a revision
 148 and reinterpretation of the StructuredText_ and Setext_ lightweight
 149 markup systems.
 150
 151 If you are reading this on the web, you can see for yourself.  `The
 152 source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open
 153 it in another window and compare them side by side.
 154
 155 `A ReStructuredText Primer <docs/user/rst/quickstart.html>`_ and the
 156 `Quick reStructuredText <docs/user/rst/quickref.html>`_ user reference
 157 are a good place to start.  The `reStructuredText Markup Specification
 158 <docs/ref/rst/restructuredtext.html>`_ is a detailed technical
 159 specification.
 160
 161 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
 162 .. _StructuredText:
 163    http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
 164 .. _Setext: mirror/setext.html
 165
 166
 167 Why is it called "reStructuredText"?
 168 ------------------------------------
 169
 170 The name came from a combination of "StructuredText", one of
 171 reStructuredText's predecessors, with "re": "revised", "reworked", and
 172 "reinterpreted", and as in the ``re.py`` regular expression module.
 173 For a detailed history of reStructuredText and the Docutils project,
 174 see `An Introduction to reStructuredText`_.
 175
 176
 177 What's the standard abbreviation for "reStructuredText"?
 178 --------------------------------------------------------
 179
 180 "RST" and "ReST" (or "reST") are both acceptable.  Care should be
 181 taken with capitalization, to avoid confusion with "REST__", an
 182 acronym for "Representational State Transfer".
 183
 184 The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
 185 they overemphasize reStructuredText's precedessor, Zope's
 186 StructuredText.
 187
 188 __ http://www.xml.com/pub/a/2002/02/06/rest.html
 189
 190
 191 What's the standard filename extension for a reStructuredText file?
 192 -------------------------------------------------------------------
 193
 194 It's ".txt".  Some people would like to use ".rest" or ".rst" or
 195 ".restx", but why bother?  ReStructuredText source files are meant to
 196 be readable as plaintext, and most operating systems already associate
 197 ".txt" with text files.  Using a specialized filename extension would
 198 require that users alter their OS settings, which is something that
 199 many users will not be willing or able to do.
 200
 201
 202 Are there any reStructuredText editor extensions?
 203 -------------------------------------------------
 204
 205 There is `some code under development for Emacs`__.
 206
 207 Extensions for other editors are welcome.
 208
 209 __ http://docutils.sf.net/tools/editors/emacs/
 210
 211
 212 How can I indicate the document title?  Subtitle?
 213 -------------------------------------------------
 214
 215 A uniquely-adorned section title at the beginning of a document is
 216 treated specially, as the document title.  Similarly, a
 217 uniquely-adorned section title immediately after the document title
 218 becomes the document subtitle.  For example::
 219
 220     This is the Document Title
 221     ==========================
 222
 223     This is the Document Subtitle
 224     -----------------------------
 225
 226     Here's an ordinary paragraph.
 227
 228 Counterexample::
 229
 230     Here's an ordinary paragraph.
 231
 232     This is *not* a Document Title
 233     ==============================
 234
 235     The "ordinary paragraph" above the section title
 236     prevents it from becoming the document title.
 237
 238 Another counterexample::
 239
 240     This is not the Document Title,  because...
 241     ===========================================
 242
 243     Here's an ordinary paragraph.
 244
 245     ... the title adornment is not unique
 246     =====================================
 247
 248     Another ordinary paragraph.
 249
 250
 251 How can I represent esoteric characters (e.g. character entities) in a document?
 252 --------------------------------------------------------------------------------
 253
 254 For example, say you want an em-dash (XML character entity &mdash;,
 255 Unicode character ``\u2014``) in your document: use a real em-dash.
 256 Insert concrete characters (e.g. type a *real* em-dash) into your
 257 input file, using whatever encoding suits your application, and tell
 258 Docutils the input encoding.  Docutils uses Unicode internally, so the
 259 em-dash character is a real em-dash internally.
 260
 261 ReStructuredText has no character entity subsystem; it doesn't know
 262 anything about XML charents.  To Docutils, "&mdash;" in input text is
 263 7 discrete characters; no interpretation happens.  When writing HTML,
 264 the "&" is converted to "&amp;", so in the raw output you'd see
 265 "&amp;mdash;".  There's no difference in interpretation for text
 266 inside or outside inline literals or literal blocks -- there's no
 267 character entity interpretation in either case.
 268
 269 If you can't use a Unicode-compatible encoding and must rely on 7-bit
 270 ASCII, there is a workaround.  Files containing character entity set
 271 substitution definitions using the "unicode" directive `are available
 272 <tmp/charents/>`__ (`tarball <tmp/charents.tgz>`__).  A description
 273 and instructions for use `are here <tmp/charents/README.html>`__.
 274 Thanks to David Priest for the original idea.  Incorporating these
 275 files into Docutils is on the `to-do list
 276 <docs/dev/todo.html>`_.
 277
 278 If you insist on using XML-style charents, you'll have to implement a
 279 pre-processing system to convert to UTF-8 or something.  That
 280 introduces complications though; you can no longer *write* about
 281 charents naturally; instead of writing "&mdash;" you'd have to write
 282 "&amp;mdash;".
 283
 284
 285 How can I generate backticks using a Scandinavian keyboard?
 286 -----------------------------------------------------------
 287
 288 The use of backticks in reStructuredText is a bit awkward with
 289 Scandinavian keyboards, where the backtick is a "dead" key.  To get
 290 one ` character one must press SHIFT-` + SPACE.
 291
 292 Unfortunately, with all the variations out there, there's no way to
 293 please everyone.  For Scandinavian programmers and technical writers,
 294 this is not limited to reStructuredText but affects many languages and
 295 environments.
 296
 297 Possible solutions include
 298
 299 * If you have to input a lot of backticks, simply type one in the
 300   normal/awkward way, select it, copy and then paste the rest (CTRL-V
 301   is a lot faster than SHIFT-` + SPACE).
 302
 303 * Use keyboard macros.
 304
 305 * Remap the keyboard.  The Scandinavian keyboard layout is awkward for
 306   other programming/technical characters too; for example, []{}
 307   etc. are a bit awkward compared to US keyboards.
 308
 309   According to Axel Kollmorgen,
 310
 311       Under Windows, you can use the `Microsoft Keyboard Layout Creator
 312       <http://www.microsoft.com/globaldev/tools/msklc.mspx>`__ to easily
 313       map the backtick key to a real backtick (no dead key). took me
 314       five minutes to load my default (german) keyboard layout, untick
 315       "Dead Key?" from the backtick key properties ("in all shift
 316       states"), "build dll and setup package", install the generated
 317       .msi, and add my custom keyboard layout via Control Panel >
 318       Regional and Language Options > Languages > Details > Add
 319       Keyboard layout (and setting it as default "when you start your
 320       computer").
 321
 322 If anyone knows of other/better solutions, please `let us know`_.
 323
 324
 325 Are there any tools for HTML/XML-to-reStructuredText?  (Round-tripping)
 326 -----------------------------------------------------------------------
 327
 328 People have tossed the idea around, but little if any actual work has
 329 ever been done.  There's no reason why reStructuredText should not be
 330 round-trippable to/from XML; any technicalities which prevent
 331 round-tripping would be considered bugs.  Whitespace would not be
 332 identical, but paragraphs shouldn't suffer.  The tricky parts would be
 333 the smaller details, like links and IDs and other bookkeeping.
 334
 335 For HTML, true round-tripping may not be possible.  Even adding lots
 336 of extra "class" attributes may not be enough.  A "simple HTML" to RST
 337 filter is possible -- for some definition of "simple HTML" -- but HTML
 338 is used as dumb formatting so much that such a filter may not be
 339 particularly useful.  No general-purpose filter exists.  An 80/20
 340 approach should work though: build a tool that does 80% of the work
 341 automatically, leaving the other 20% for manual tweaks.
 342
 343
 344 Are there any Wikis that use reStructuredText syntax?
 345 -----------------------------------------------------
 346
 347 There are several, with various degrees of completeness.  With no
 348 implied endorsement or recommendation, and in no particular order:
 349
 350 * `Ian Bicking's experimental code <sandbox/ianb/wiki/WikiPage.py>`__
 351 * `MoinMoin <http://moin.sf.net>`__ has some support; `here's a sample
 352   <http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample>`__
 353 * Zope-based `Zwiki <http://zwiki.org/>`__
 354 * Zope3-based Zwiki (in the Zope 3 source tree as ``zope.products.zwiki``)
 355 * `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
 356 * `Trac <http://projects.edgewall.com/trac/>`__ `supports using reStructuredText
 357   <http://projects.edgewall.com/trac/wiki/WikiRestructuredText>`__ as an
 358   alternative to wiki markup. This includes support for `TracLinks
 359   <http://projects.edgewall.com/trac/wiki/TracLinks>`__ from within RST
 360   text via a custom RST reference-directive or, even easier, an interpreted text
 361   role 'trac'
 362
 363 Please `let us know`_ of any other reStructuredText Wikis.
 364
 365 The example application for the `Web Framework Shootout
 366 <http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using
 367 reStructuredText.
 368
 369
 370 Are there any Weblog (Blog) projects that use reStructuredText syntax?
 371 ----------------------------------------------------------------------
 372
 373 With no implied endorsement or recommendation, and in no particular
 374 order:
 375
 376 * `Python Desktop Server <http://pyds.muensterland.org/>`__
 377 * `PyBloxsom <http://roughingit.subtlehints.net/pyblosxom>`__
 378 * `rst2ht <http://www.rutherfurd.net/articles/rst-ht2html.html>`__
 379 * `htmlnav <http://docutils.sourceforge.net/sandbox/gschwant/htmlnav/>`__
 380 * `restblog <http://docutils.sourceforge.net/sandbox/mly/restblog/>`__
 381 * `ReSTWeb <http://wingide.com/opensource/restweb>`__
 382 * `Lino WebMan <http://lino.sourceforge.net/webman.html>`__
 383
 384 Please `let us know`_ of any other reStructuredText Blogs.
 385
 386
 387 Can lists be indented without generating block quotes?
 388 ------------------------------------------------------
 389
 390 Some people like to write lists with indentation, without intending a
 391 block quote context, like this::
 392
 393     paragraph
 394
 395       * list item 1
 396       * list item 2
 397
 398 There has been a lot of discussion about this, but there are some
 399 issues that would need to be resolved before it could be implemented.
 400 There is a summary of the issues and pointers to the discussions in
 401 `the to-do list <docs/dev/todo.html#indented-lists>`__.
 402
 403
 404 Could the requirement for blank lines around lists be relaxed?
 405 --------------------------------------------------------------
 406
 407 Short answer: no.
 408
 409 In reStructuredText, it would be impossible to unambigously mark up
 410 and parse lists without blank lines before and after.  Deeply nested
 411 lists may look ugly with so many blank lines, but it's a price we pay
 412 for unambiguous markup.  Some other plaintext markup systems do not
 413 require blank lines in nested lists, but they have to compromise
 414 somehow, either accepting ambiguity or requiring extra complexity.
 415 For example, `Epytext <http://epydoc.sf.net/epytext.html#list>`__ does
 416 not require blank lines around lists, but it does require that lists
 417 be indented and that ambiguous cases be escaped.
 418
 419
 420 How can I include mathematical equations in documents?
 421 ------------------------------------------------------
 422
 423 There is no elegant built-in way, yet.  There are several ideas, but
 424 no obvious winner.  This issue requires a champion to solve the
 425 technical and aesthetic issues and implement a generic solution.
 426 Here's the `to-do list entry <docs/dev/todo.html#math-markup>`__.
 427
 428 There are several quick & dirty ways to include equations in
 429 documents:
 430
 431 * For HTML there is MathML but its rendering is still quite broken (or
 432   absent) on most browsers.  An example of raw MathML is `here
 433   <http://sf.net/mailarchive/message.php?msg_id=2177102>`__.
 434
 435 * If you use LaTeX output only, a simple way is to use the "raw"
 436   directive; examples are `here
 437   <http://article.gmane.org/gmane.text.docutils.devel/521>`__.
 438
 439 * Images of the equations can be used, typically generated by TeX.
 440   Beni Cherniavsky has written some `preprocessing scripts`__ for
 441   making inline TeX (for LaTeX and other [HTML etc.] output) math much
 442   easier; `instructions here`__.
 443
 444   __ http://docutils.sourceforge.net/sandbox/cben/rolehack/
 445   __ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html
 446
 447 * Here is an example of potential `itex math markup
 448   <http://article.gmane.org/gmane.text.docutils.user/118>`__.
 449
 450
 451 HTML Writer
 452 ===========
 453
 454 What is the status of the HTML Writer?
 455 --------------------------------------
 456
 457 The HTML Writer module, ``docutils/writers/html4css1.py``, is a
 458 proof-of-concept reference implementation.  While it is a complete
 459 implementation, some aspects of the HTML it produces may be
 460 incompatible with older browsers or specialized applications (such as
 461 web templating).  Alternate implementations are welcome.
 462
 463
 464 What kind of HTML does it produce?
 465 ----------------------------------
 466
 467 It produces XHTML compatible with the `HTML 4.01`_ and `XHTML 1.0`_
 468 specifications.  A cascading style sheet ("default.css" by default) is
 469 required for proper viewing with a modern graphical browser.  Correct
 470 rendering of the HTML produced depends on the CSS support of the
 471 browser.
 472
 473 .. _HTML 4.01: http://www.w3.org/TR/html4/
 474 .. _XHTML 1.0: http://www.w3.org/TR/xhtml1/
 475
 476
 477 What browsers are supported?
 478 ----------------------------
 479
 480 No specific browser is targeted; all modern graphical browsers should
 481 work.  Some older browsers, text-only browsers, and browsers without
 482 full CSS support are known to produce inferior results.  Mozilla
 483 (version 1.0 and up) and MS Internet Explorer (version 5.0 and up) are
 484 known to give good results.  Reports of experiences with other
 485 browsers are welcome.
 486
 487
 488 Unexpected results from tools/html.py: H1, H1 instead of H1, H2.  Why?
 489 ----------------------------------------------------------------------
 490
 491 Here's the question in full:
 492
 493     I have this text::
 494
 495         Heading 1
 496         =========
 497
 498         All my life, I wanted to be H1.
 499
 500         Heading 1.1
 501         -----------
 502
 503         But along came H1, and so shouldn't I be H2?
 504         No!  I'm H1!
 505
 506         Heading 1.1.1
 507         *************
 508
 509         Yeah, imagine me, I'm stuck at H3!  No?!?
 510
 511     When I run it through tools/html.py, I get unexpected results
 512     (below).  I was expecting H1, H2, then H3; instead, I get H1, H1,
 513     H2::
 514
 515         ...
 516         <html lang="en">
 517         <head>
 518         ...
 519         <title>Heading 1</title>
 520         <link rel="stylesheet" href="default.css" type="text/css" />
 521         </head>
 522         <body>
 523         <div class="document" id="heading-1">
 524         <h1 class="title">Heading 1</h1>                <-- first H1
 525         <p>All my life, I wanted to be H1.</p>
 526         <div class="section" id="heading-1-1">
 527         <h1><a name="heading-1-1">Heading 1.1</a></h1>        <-- H1
 528         <p>But along came H1, and so now I must be H2.</p>
 529         <div class="section" id="heading-1-1-1">
 530         <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
 531         <p>Yeah, imagine me, I'm stuck at H3!</p>
 532         ...
 533
 534     What gives?
 535
 536 Check the "class" attribute on the H1 tags, and you will see a
 537 difference.  The first H1 is actually ``<h1 class="title">``; this is
 538 the document title, and the default stylesheet renders it centered.
 539 There can also be an ``<h2 class="subtitle">`` for the document
 540 subtitle.
 541
 542 If there's only one highest-level section title at the beginning of a
 543 document, it is treated specially, as the document title.  (Similarly, a
 544 lone second-highest-level section title may become the document
 545 subtitle.)  See `How can I indicate the document title?  Subtitle?`_ for
 546 details.  Rather than use a plain H1 for the document title, we use ``<h1
 547 class="title">`` so that we can use H1 again within the document.  Why
 548 do we do this?  HTML only has H1-H6, so by making H1 do double duty, we
 549 effectively reserve these tags to provide 6 levels of heading beyond the
 550 single document title.
 551
 552 HTML is being used for dumb formatting for nothing but final display.
 553 A stylesheet *is required*, and one is provided:
 554 tools/stylesheets/default.css.  Of course, you're welcome to roll your
 555 own.  The default stylesheet provides rules to format ``<h1
 556 class="title">`` and ``<h2 class="subtitle">`` differently from
 557 ordinary ``<h1>`` and ``<h2>``::
 558
 559     h1.title {
 560       text-align: center }
 561
 562     h2.subtitle {
 563       text-align: center }
 564
 565 If you don't want the top section heading to be interpreted as a
 566 title at all, disable the `doctitle_xform`_ setting
 567 (``--no-doc-title`` option).  This will interpret your document
 568 differently from the standard settings, which might not be a good
 569 idea.  If you don't like the reuse of the H1 in the HTML output, you
 570 can tweak the `initial_header_level`_ setting
 571 (``--initial-header-level`` option) -- but unless you match its value
 572 to your specific document, you might end up with bad HTML (e.g. H3
 573 without H2).
 574
 575 .. _doctitle_xform: docs/user/config.html#doctitle-xform
 576 .. _initial_header_level: docs/user/config.html#initial-header-level
 577
 578 (Thanks to Mark McEahern for the question and much of the answer.)
 579
 580
 581 Why do enumerated lists only use numbers (no letters or roman numerals)?
 582 ------------------------------------------------------------------------
 583
 584 The rendering of enumerators (the numbers or letters acting as list
 585 markers) is completely governed by the stylesheet, so either the
 586 browser can't find the stylesheet (try using the "--embed-stylesheet"
 587 option), or the browser can't understand it (try a recent Mozilla or
 588 MSIE).
 589
 590
 591 Python Source Reader
 592 ====================
 593
 594 Can I use Docutils for Python auto-documentation?
 595 -------------------------------------------------
 596
 597 Yes, in conjunction with other projects.
 598
 599 Docstring extraction functionality from within Docutils is still under
 600 development.  There is most of a source code parsing module in
 601 docutils/readers/python/moduleparser.py.  We do plan to finish it
 602 eventually.  Ian Bicking wrote an initial front end for the
 603 moduleparser.py module, in sandbox/ianb/extractor/extractor.py.  Ian
 604 also did some work on the Python Source Reader
 605 (docutils.readers.python) component at PyCon DC 2004.
 606
 607 Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_
 608 supports reStructuredText-format docstrings for HTML output.  Docutils
 609 0.3 or newer is required.  Development of a Docutils-specific
 610 auto-documentation tool will continue.  Epydoc works by importing
 611 Python modules to be documented, whereas the Docutils-specific tool,
 612 described above, will parse modules without importing them (as with
 613 `HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support
 614 reStructuredText).
 615
 616 The advantages of parsing over importing are security and flexibility;
 617 the disadvantage is complexity/difficulty.
 618
 619 * Security: untrusted code that shouldn't be executed can be parsed;
 620   importing a module executes its top-level code.
 621 * Flexibility: comments and unofficial docstrings (those not supported
 622   by Python syntax) can only be processed by parsing.
 623 * Complexity/difficulty: it's a lot harder to parse and analyze a
 624   module than it is to ``import`` and analyze one.
 625
 626 For more details, please see "Docstring Extraction Rules" in `PEP
 627 258`_, item 3 ("How").
 628
 629
 630 Miscellaneous
 631 =============
 632
 633 Is the Docutils document model based on any existing XML models?
 634 ----------------------------------------------------------------
 635
 636 Not directly, no.  It borrows bits from DocBook, HTML, and others.  I
 637 (David Goodger) have designed several document models over the years,
 638 and have my own biases.  The Docutils document model is designed for
 639 simplicity and extensibility, and has been influenced by the needs of
 640 the reStructuredText markup.