1 .. include:: docs/header0.txt
3 .. NOTE TO MAINTAINERS: Please add new questions to the end of their
4 sections, so section/question numbers remain stable.
6 ===========================================
7 Docutils FAQ (Frequently Asked Questions)
8 ===========================================
12 :Web site: https://docutils.sourceforge.io/
13 :Copyright: This document has been placed in the public domain.
19 This is a work in progress. If you are reading a local copy, the
20 `master copy`_ might be newer. This document uses relative links;
21 if they don't work, please use the master copy.
23 Please feel free to ask questions and/or provide answers; send email
24 to the `Docutils-users`_ mailing list. Project members should feel
25 free to edit the source text file directly.
27 .. _master copy: https://docutils.sourceforge.io/FAQ.html
29 .. _Docutils-users: docs/user/mailing-lists.html#docutils-users
39 Docutils_ is a system for processing plaintext documentation into
40 useful formats, such as HTML, XML, and LaTeX. It supports multiple
41 types of input, such as standalone files, `PEPs (Python Enhancement
42 Proposals)`_, and string input. Client code may add other input types,
43 e.g. Sphinx_ comes with an extension to extract inline documentation
44 from Python modules and packages.
46 The Docutils distribution consists of:
48 * a library (the "docutils" package), which `can be used by client
50 * several `front-end tools`_ (such as ``rst2html``, which converts
51 reStructuredText input into HTML output);
52 * a `test suite`_; and
55 For an overview of the Docutils project implementation,
56 see :PEP:`258`, "Docutils Design Specification".
58 Docutils is implemented in Python_.
60 .. _Docutils: https://docutils.sourceforge.io/
61 .. _PEPs (Python Enhancement Proposals):
62 https://peps.python.org/pep-0012
63 .. _can be used by client code: docs/api/publisher.html
64 .. _front-end tools: docs/user/tools.html
65 .. _test suite: docs/dev/testing.html
66 .. _documentation: docs/index.html
67 .. _Python: https://www.python.org/
70 Why is it called "Docutils"?
71 ----------------------------
73 Docutils is short for "Python Documentation Utilities". The name
74 "Docutils" was inspired by "Distutils", the Python Distribution
75 Utilities architected by Greg Ward, a component of Python's standard
78 The earliest known use of the term "docutils" in a Python context was
79 a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in
80 the Python Doc-SIG mailing list. It was suggested `as a project
81 name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to
82 a question from Tony "Tibs" Ibbs: "What do we want to *call* this
83 thing?". This was shortly after David Goodger first `announced
84 reStructuredText`__ on Doc-SIG.
86 Tibs used the name "Docutils" for `his effort`__ "to document what the
87 Python docutils package should support, with a particular emphasis on
88 documentation strings". Tibs joined the current project (and its
89 predecessors) and graciously donated the name.
91 For more history of reStructuredText and the Docutils project, see `An
92 Introduction to reStructuredText`_.
94 Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
95 or any other variation. It is pronounced as in "DOCumentation
96 UTILitieS", with emphasis on the first syllable.
98 .. _An Introduction to reStructuredText: docs/ref/rst/introduction.html
99 __ https://mail.python.org/pipermail/doc-sig/1999-December/000878.html
100 __ https://mail.python.org/pipermail/doc-sig/2000-November/001252.html
101 __ https://mail.python.org/pipermail/doc-sig/2000-November/001239.html
102 __ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html
105 Is there a GUI authoring environment for Docutils?
106 --------------------------------------------------
108 See the links to editors_ supporting reStructuredText.
110 .. _editors: docs/user/links.html#editors
113 What is the status of the Docutils project?
114 -------------------------------------------
116 Docutils is mainly stable, with documented APIs and architecture
117 subject to change after announcement and a transition period.
119 We fix bugs as they are reported. This means the code from the
120 repository_ (or the snapshots_) is the most stable as well as the most
121 featureful most of the time.
124 What is the Docutils project release policy?
125 --------------------------------------------
127 Besides the regular releases_, we provide automatically-generated
128 snapshots_ which always contain the latest code from the repository_.
129 As the project matures, we may formalize on a
130 stable/development-branch scheme, but we're not using anything like
133 .. _releases: https://pypi.org/project/docutils/#history
134 .. _snapshots: https://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/
135 .. _repository: docs/dev/repository.html
138 How can I get a new feature into Docutils?
139 ------------------------------------------
141 * Present your idea at the docutils-develop_ mailing list or file a
142 ticket at Docutils' `feature request tracker`_.
143 Convince the Docutils developers that this is a valuable addition.
147 * Be patient, and be persistent. None of us are paid to do this,
148 it's all in our spare time, which is precious and rare.
150 .. _docutils-develop: docs/user/mailing-lists.html#docutils-develop
151 .. _extensions and related projects:
152 docs/dev/policies.html#extensions-and-related-projects
153 .. _feature request tracker:
154 https://sourceforge.net/p/docutils/feature-requests/
160 What is reStructuredText?
161 -------------------------
163 reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
164 plaintext markup syntax and parser system. The reStructuredText
165 parser is a component of Docutils_. reStructuredText is a revision
166 and reinterpretation of the StructuredText_ and Setext_ lightweight
169 If you are reading this on the web, you can see for yourself. `The
170 source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open
171 it in another window and compare them side by side.
173 `A ReStructuredText Primer`_ and the `Quick reStructuredText`_ user
174 reference are a good place to start. The `reStructuredText Markup
175 Specification`_ is a detailed technical specification.
177 .. _A ReStructuredText Primer: docs/user/rst/quickstart.html
178 .. _Quick reStructuredText: docs/user/rst/quickref.html
179 .. _reStructuredText Markup Specification:
180 docs/ref/rst/restructuredtext.html
181 .. _reStructuredText: https://docutils.sourceforge.io/rst.html
183 http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
184 .. _Setext: https://docutils.sourceforge.io/mirror/setext.html
187 Why is it called "reStructuredText"?
188 ------------------------------------
190 The name came from a combination of "StructuredText", one of
191 reStructuredText's predecessors, with "re": "revised", "reworked", and
192 "reinterpreted", and as in the ``re.py`` regular expression module.
193 For a detailed history of reStructuredText and the Docutils project,
194 see `An Introduction to reStructuredText`_.
196 "reStructuredText" is **ONE** word, *not two!*
199 What's the standard abbreviation for "reStructuredText"?
200 --------------------------------------------------------
202 "RST" and "ReST" (or "reST") are both acceptable. Care should be
203 taken with capitalization, to avoid confusion with "REST__", an
204 acronym for "Representational State Transfer".
206 The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
207 they overemphasize reStructuredText's predecessor, Zope's
210 __ https://en.wikipedia.org/wiki/Representational_State_Transfer
213 What's the standard filename extension for a reStructuredText file?
214 -------------------------------------------------------------------
216 It's ".txt". ReStructuredText source files are meant to be readable as
217 plaintext, and most operating systems already associate ".txt" with text
220 That said, we see an increasing number of projects settling on
221 the extension ".rst".
223 Also see `What's the official MIME type for reStructuredText data?`_
226 Are there any reStructuredText editor extensions?
227 -------------------------------------------------
229 See the list of editors_ supporting reStructuredText.
232 How can I indicate the document title? Subtitle?
233 -------------------------------------------------
235 A uniquely-adorned section title at the beginning of a document is
236 treated specially, as the document title. Similarly, a
237 uniquely-adorned section title immediately after the document title
238 becomes the document subtitle. For example::
240 This is the Document Title
241 ==========================
243 This is the Document Subtitle
244 -----------------------------
246 Here's an ordinary paragraph.
250 Here's an ordinary paragraph.
252 This is *not* a Document Title
253 ==============================
255 The "ordinary paragraph" above the section title
256 prevents it from becoming the document title.
258 Another counterexample::
260 This is not the Document Title, because...
261 ===========================================
263 Here's an ordinary paragraph.
265 ... the title adornment is not unique
266 =====================================
268 Another ordinary paragraph.
271 How can I represent esoteric characters (e.g. character entities) in a document?
272 --------------------------------------------------------------------------------
274 For example, say you want an em-dash (XML character entity —,
275 Unicode character U+2014) in your document: use a real em-dash.
276 Insert literal characters (e.g. type a *real* em-dash) into your
277 input file, using whatever encoding suits your application, and tell
278 Docutils the input encoding. Docutils uses Unicode internally, so the
279 em-dash character is U+2014 internally.
281 Emacs users should refer to the `Emacs Support for reStructuredText`__
282 document. Tips for other editors are welcome.
284 __ tools/editors/emacs/README.html
286 ReStructuredText has no character entity subsystem; it doesn't know
287 anything about XML character entities.
288 To Docutils, "—" in input text is
289 7 discrete characters; no interpretation happens. When writing HTML,
290 the "&" is converted to "&", so in the raw output you'd see
291 "&mdash;". There's no difference in interpretation for text
292 inside or outside inline literals or literal blocks -- there's no
293 character entity interpretation in either case.
295 If you can't use a Unicode-compatible encoding and must rely on 7-bit
296 ASCII, there is a workaround:
297 `Standard Substitution Definition Sets`_ provide equivalents of
298 XML & HTML character entity sets as substitution definitions. [#]_
299 For example, the Japanese yen currency symbol can be used as follows::
301 .. include:: <xhtml1-lat1.txt>
303 |yen| 600 for a complete meal? That's cheap!
305 .. [#] Thanks to David Priest for the original idea.
307 You can create custom `substitution definitions`_ in your document
308 using the "unicode_" directive, e.g.::
310 .. |--| unicode:: U+2013 .. en dash
311 .. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace
314 .. |--| unicode:: U+2013 .. en dash
315 .. |---| unicode:: U+2014 .. em dash, trimming surrounding whitespace
318 Now you can write dashes using pure ASCII: "``foo |--| bar; foo |---|
319 bar``", rendered as "foo |--| bar; foo |---| bar".
320 The ``:trim:`` option for
321 the em dash is necessary because you cannot write "``foo|---|bar``";
322 thus you need to add spaces ("``foo |---| bar``") and advise the
323 reStructuredText parser to trim the spaces.
325 .. _Standard Substitution Definition Sets: docs/ref/rst/definitions.html
326 .. _substitution definitions: docs/ref/rst/restructuredtext.html
327 #substitution-definitions
328 .. _unicode: docs/ref/rst/directives.html#unicode-character-codes
331 How can I generate backticks using a Scandinavian keyboard?
332 -----------------------------------------------------------
334 The use of backticks in reStructuredText is a bit awkward with
335 Scandinavian keyboards, where the backtick is a "dead" key. To get
336 one ` character one must press SHIFT-` + SPACE.
338 Unfortunately, with all the variations out there, there's no way to
339 please everyone. For Scandinavian programmers and technical writers,
340 this is not limited to reStructuredText but affects many languages and
343 Possible solutions include
345 * If you have to input a lot of backticks, simply type one in the
346 normal/awkward way, select it, copy and then paste the rest (CTRL-V
347 is a lot faster than SHIFT-` + SPACE).
349 * Use keyboard macros.
351 * Remap the keyboard. The Scandinavian keyboard layout is awkward for
352 other programming/technical characters too; for example, []{}
353 etc. are a bit awkward compared to US keyboards.
355 According to Axel Kollmorgen,
357 Under Windows, you can use the `Microsoft Keyboard Layout Creator
358 <http://www.microsoft.com/globaldev/tools/msklc.mspx>`__ to easily
359 map the backtick key to a real backtick (no dead key). took me
360 five minutes to load my default (german) keyboard layout, untick
361 "Dead Key?" from the backtick key properties ("in all shift
362 states"), "build dll and setup package", install the generated
363 .msi, and add my custom keyboard layout via Control Panel >
364 Regional and Language Options > Languages > Details > Add
365 Keyboard layout (and setting it as default "when you start your
368 * Use a virtual/screen keyboard or character palette, such as:
370 - `Web-based keyboards <http://keyboard.lab.co.il/>`__ (IE only
372 - Windows: `Click-N-Type <http://www.lakefolks.org/cnt/>`__.
373 - Mac OS X: the Character Palette can store a set of favorite
374 characters for easy input. Open System Preferences,
375 International, Input Menu tab, enable "Show input menu in menu
376 bar", and be sure that Character Palette is enabled in the list.
378 If anyone knows of other/better solutions, please `let us know`_.
381 Are there any tools for HTML/XML-to-reStructuredText? (Round-tripping)
382 -----------------------------------------------------------------------
384 People have tossed the idea around, and some implementations of
385 reStructuredText-generating tools can be found in the `Docutils Link
388 There's no reason why reStructuredText should not be round-trippable
389 to/from XML; any technicalities which prevent round-tripping would be
390 considered bugs. Whitespace would not be identical, but paragraphs
391 shouldn't suffer. The tricky parts would be the smaller details, like
392 links and IDs and other bookkeeping.
394 For HTML, true round-tripping may not be possible. Even adding lots
395 of extra "class" attributes may not be enough. A "simple HTML" to RST
396 filter is possible -- for some definition of "simple HTML" -- but HTML
397 is used as dumb formatting so much that such a filter may not be
398 particularly useful. An 80/20 approach should work though: build a
399 tool that does 80% of the work automatically, leaving the other 20%
402 .. _Docutils Link List: docs/user/links.html
405 Are there any Wikis that use reStructuredText syntax?
406 -----------------------------------------------------
408 There are several, with various degrees of completeness. With no
409 implied endorsement or recommendation, and in no particular order:
411 * `Ian Bicking's experimental code
412 <https://docutils.sourceforge.io/sandbox/ianb/wiki/Wiki.py>`__
414 * `MoinMoin <http://moinmoin.wikiwikiweb.de/>`__ has some support;
415 `here's a sample <http://moinmoin.wikiwikiweb.de/RestSample>`__
417 * Zope-based `Zwiki <http://zwiki.org/>`__
419 * Zope3-based Zwiki (in the Zope 3 source tree as
420 ``zope.products.zwiki``)
422 * `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
424 * `Trac <http://trac.edgewall.com//>`__ `supports using
426 <http://trac.edgewall.com//wiki/WikiRestructuredText>`__ as
427 an alternative to wiki markup. This includes support for `TracLinks
428 <http://trac.edgewall.com//wiki/TracLinks>`__ from within
429 RST text via a custom RST reference-directive or, even easier, an
430 interpreted text role 'trac'
432 Please `let us know`_ of any other reStructuredText Wikis.
435 .. The example application for the `Web Framework Shootout
436 .. <http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using
440 Are there any Weblog (Blog) projects that use reStructuredText syntax?
441 ----------------------------------------------------------------------
443 With no implied endorsement or recommendation, and in no particular
446 * `Firedrop <http://www.voidspace.org.uk/python/firedrop2/>`__
447 * `PyBloxsom <http://pyblosxom.github.io/>`__
448 * `Lino WebMan <http://lino.sourceforge.net/webman.html>`__
449 * `Pelican <http://blog.getpelican.com/>`__
450 (also listed `on PyPi <http://pypi.python.org/pypi/pelican>`__)
452 Please `let us know`_ of any other reStructuredText Blogs.
455 .. _Can lists be indented without generating block quotes?:
457 How should I mark up lists?
458 ---------------------------
460 Bullet_ & enumerated_ list markup is very intuitive but there are 2
461 points that must be noted:
463 .. _bullet: docs/ref/rst/restructuredtext.html#bullet-lists
464 .. _enumerated: docs/ref/rst/restructuredtext.html#enumerated-lists
466 1. Lists should **not** be indented. This is correct::
477 while this is probably incorrect::
488 The extra indentation (of the list containing items 1.1 and 1.2) is
489 recognized as a block quote. This is usually not what you mean and
490 it causes the list in the output to be indented too much.
492 2. There **must** be blank lines around list items, except between
493 items of the same level, where blank lines are optional. The
494 example above shows this.
496 Note that formatting of the *output* is independent of the input, and
497 is decided by the writer and the stylesheet. For instance, lists
498 *are* indented in HTML output by default. See `How are lists
499 formatted in HTML?`_ for details.
502 Could lists be indented without generating block quotes?
503 --------------------------------------------------------
505 Some people like to write lists with indentation but don't intend a
506 blockquote context. There has been a lot of discussion about allowing
507 this in reStructuredText, but there are some issues that would need to
508 be resolved before it could be implemented. There is a summary of the
509 issues and pointers to the discussions in `the to-do list`__.
511 __ docs/dev/todo.html#indented-lists
514 Could the requirement for blank lines around lists be relaxed?
515 --------------------------------------------------------------
519 In reStructuredText, it would be impossible to unambiguously mark up
520 and parse lists without blank lines before and after. Deeply nested
521 lists may look ugly with so many blank lines, but it's a price we pay
522 for unambiguous markup. Some other plaintext markup systems do not
523 require blank lines in nested lists, but they have to compromise
524 somehow, either accepting ambiguity or requiring extra complexity.
525 For example, `Epytext <http://epydoc.sourceforge.net/epytext.html#list>`__ does
526 not require blank lines around lists, but it does require that lists
527 be indented and that ambiguous cases be escaped.
530 How can I include mathematical equations in documents?
531 ------------------------------------------------------
533 Use `LaTeX math syntax`_ in a `math directive`_ or `math role`_.
535 .. _LaTeX math syntax: docs/ref/rst/mathematics.html
536 .. _math directive: docs/ref/rst/directives.html#math
537 .. _math role: docs/ref/rst/roles.html#math
540 Is nested inline markup possible?
541 ---------------------------------
543 Not currently, no. It's on the `to-do list`__ (`details here`__), and
544 hopefully will be part of the reStructuredText parser soon. At that
545 time, markup like this will become possible::
547 Here is some *emphasized text containing a `hyperlink`_ and
548 ``inline literals``*.
550 __ docs/dev/todo.html#nested-inline-markup
551 __ docs/dev/rst/alternatives.html#nested-inline-markup
553 There are workarounds, but they are either convoluted or ugly or both.
554 They are not recommended.
556 * Inline markup can be combined with hyperlinks using `substitution
557 definitions`__ and references__ with the `"replace" directive`__.
560 Here is an |emphasized hyperlink|_.
562 .. |emphasized hyperlink| replace:: *emphasized hyperlink*
563 .. _emphasized hyperlink: https://example.org
565 It is not possible for just a portion of the replacement text to be
566 a hyperlink; it's the entire replacement text or nothing.
568 __ docs/ref/rst/restructuredtext.html#substitution-definitions
569 __ docs/ref/rst/restructuredtext.html#substitution-references
570 __ docs/ref/rst/directives.html#replace
572 * The `"raw" directive`__ can be used to insert raw HTML into HTML
575 Here is some |stuff|.
577 .. |stuff| raw:: html
579 <em>emphasized text containing a
580 <a href="https://example.org">hyperlink</a> and
581 <tt>inline literals</tt></em>
583 Raw LaTeX is supported for LaTeX output, etc.
585 __ docs/ref/rst/directives.html#raw
588 How to indicate a line break or a significant newline?
589 ------------------------------------------------------
591 `Line blocks`__ are designed for address blocks, verse, and other
592 cases where line breaks are significant and must be preserved. Unlike
593 literal blocks, the typeface is not changed, and inline markup is
594 recognized. For example::
596 | A one, two, a one two three four
598 | Half a bee, philosophically,
599 | must, *ipso facto*, half not be.
600 | But half the bee has got to be,
601 | *vis a vis* its entity. D'you see?
603 | But can a bee be said to be
604 | or not to be an entire bee,
605 | when half the bee is not a bee,
606 | due to some ancient injury?
610 __ docs/ref/rst/restructuredtext.html#line-blocks
612 Here's a workaround for manually inserting explicit line breaks in
619 I want to break this line here: |br| this is after the break.
621 If the extra whitespace bothers you, |br|\ backslash-escape it.
624 A URL containing asterisks doesn't work. What to do?
625 -----------------------------------------------------
627 Asterisks are valid URL characters (see :RFC:`2396`), sometimes used
628 in URLs. For example::
630 http://cvs.example.org/viewcvs.py/*checkout*/module/file
632 Unfortunately, the parser thinks the asterisks are indicating
633 emphasis. The slashes serve as delineating punctuation, allowing the
634 asterisks to be recognized as markup. The example above is separated
635 by the parser into a truncated URL, an emphasized word, and some
638 http://cvs.example.org/viewcvs.py/
642 To turn off markup recognition, use a backslash to escape at least the
643 first asterisk, like this::
645 http://cvs.example.org/viewcvs.py/\*checkout*/module/file
647 Escaping the second asterisk doesn't hurt, but it isn't necessary.
650 How can I make a literal block with *some* formatting?
651 ------------------------------------------------------
653 Use the `parsed-literal`_ directive.
655 .. _parsed-literal: docs/ref/rst/directives.html#parsed-literal
657 Scenario: a document contains some source code, which calls for a
658 literal block to preserve linebreaks and whitespace. But part of the
659 source code should be formatted, for example as emphasis or as a
660 hyperlink. This calls for a *parsed* literal block::
664 print "Hello world!" # *tricky* code [1]_
666 The emphasis (``*tricky*``) and footnote reference (``[1]_``) will be
670 Can reStructuredText be used for web or generic templating?
671 -----------------------------------------------------------
673 Docutils and reStructuredText can be used with or as a component of a
674 templating system, but they do not themselves include templating
675 functionality. Templating should simply be left to dedicated
676 templating systems. Users can choose a templating system to apply to
677 their reStructuredText documents as best serves their interests.
679 There are many good templating systems for Python (ht2html_, YAPTU_,
680 Quixote_'s PTL, Cheetah_, etc.; see this non-exhaustive list of `some
681 other templating systems`_), and many more for other languages, each
682 with different approaches. We invite you to try several and find one
683 you like. If you adapt it to use Docutils/reStructuredText, please
684 consider contributing the code to Docutils or `let us know`_ and we'll
687 One reST-specific web templating system is `rest2web
688 <http://www.voidspace.org.uk/python/rest2web>`_, a tool for
689 automatically building websites, or parts of websites.
691 .. _ht2html: http://ht2html.sourceforge.net/
693 http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305
694 .. _Quixote: http://www.mems-exchange.org/software/quixote/
695 .. _Cheetah: http://www.cheetahtemplate.org/
696 .. _some other templating systems:
697 http://webware.sourceforge.net/Papers/Templates/
700 How can I mark up a FAQ or other list of questions & answers?
701 -------------------------------------------------------------
703 There is no specific syntax for FAQs and Q&A lists. Here are two
706 1. For a FAQ (Frequently Asked Questions, usually with answers), a
707 convenient way to mark up the questions is as section titles, with
708 the answer(s) as section content. This document is marked up in
711 The advantages of using section titles for questions are: sections
712 can be numbered automatically, and a table of contents can be
713 generated automatically. One limitation of this format is that
714 questions must fit on one line (section titles may not wrap, in the
715 source text). For very long questions, the title may be a summary
716 of the question, with the full question in the section body.
718 2. Field lists work well as Q&A lists::
720 :Q: What kind of questions can we
723 :A: Any kind we like!
725 In order to separate questions, lists can be used:
727 1. :Q: What kind of question can we
729 :A: Any kind we like!
731 2. :Q: How many answers can a question have?
734 :A3: Answers can be numbered like this.
738 If you don't want to number or otherwise mark questions, you can
739 use an empty comment between individual field lists to separate
753 Can I produce documents in right-to-left languages?
754 ---------------------------------------------------
756 Languages written from right to left, such as Arabic and Hebrew, must
757 be reordered according to the `Unicode Bidi Algorithm`_. This
758 requires support from the editor and special markup in the output
761 The source format of reStructuredText is relatively bidi-friendly:
762 most constructs are denoted by punctuation without intrusion of
763 English and when you must write in English, it's usually on a separate
764 line. So any editor that auto-detects direction per-line (like gedit
765 or geresh_) will suffice.
767 Moreover, it's possible to translate_ all reStructuredText keywords.
768 Docutils 0.17 includes translations for Arab, Hebrew, and
769 Persian/Farsi. This should allow reasonable use of editors limited to
770 a single base direction for the whole document (like Notepad, Vim and
771 text boxes in Firefox).
773 .. _Unicode Bidi Algorithm: https://www.unicode.org/reports/tr9/
774 .. _geresh: http://www.typo.co.il/~mooffie/geresh/
775 .. _translate: docs/howto/i18n.html
777 The second problem is bidi markup of the output. There is an almost
778 transparent implicit solution for HTML:
780 * Grab http://cben-hacks.sourceforge.net/bidi/hibidi.py and
781 http://cben-hacks.sourceforge.net/bidi/rst2html_hibidi.py.
782 Put them both in the same directory and make them executable.
784 * Use ``rst2html_hibidi.py`` instead of ``rst2html``.
786 * It infers dir attributes in the HTML from the text. It does it
787 hierachically, giving much better results than usual. You can still
788 use LRM/RLM and LRE/RLE/PDF control codes to help it.
790 * If you want the gory details: See the full theory_, and note the
791 incomplete practice_ (this is still a partial implementation - but
792 sufficient for most needs).
794 .. _theory: http://cben-hacks.sourceforge.net/bidi/hibidi.html
795 .. _practice: http://cben-hacks.sourceforge.net/bidi/hibidi.html#practice
797 There is also an explicit way to set directions through CSS and
800 * Copy ``default.css`` to a new file and add relevant parts of the
803 /* Use these two if the main document direction is RTL */
804 body { direction: rtl; }
805 div.sidebar { float: left !important; }
807 /* The next 3 rules are very useful in documents containing pieces
808 of code in english */
809 /* Use this if you all your literal blocks (::) are LTR */
810 pre {direction: ltr; unicode-bidi: embed; }
811 /* Use this if you all your inline literals (``) are LTR */
812 tt {direction: ltr; unicode-bidi: embed; }
813 /* Use this if you all your interpreted text (`) is LTR */
814 cite {direction: ltr; unicode-bidi: embed; }
816 /* Allow manual direction override by class directive and roles */
817 .rtl { direction: rtl; }
818 .ltr { direction: ltr; }
820 * Select this new stylesheet with ``--stylesheet=<file>`` or the
823 * Now if you need to override the direction of some element (from a
824 paragraph to a whole section), write::
832 before it (see the class_ directive for details).
834 * To change the direction of some inline text fragment, you can use
835 RLE/LRE/PDF control characters, or write ``:rtl:`RTL text``` /
836 ``:ltr:`RTL text```. To use the latter syntax, you must write this
837 once at the beginning of your document::
842 .. _stylesheet: docs/user/config.html#stylesheet
843 .. _class: docs/ref/rst/directives.txt#class
845 LaTeX is quite hard to implement (it doesn't support the bidi
846 algorithm, so all direction changes - even numbers in RTL text - must
847 be explicitly marked). Other formats are more-or-less easy.
849 If you have any questions/problems/bugs related to bidi with docutils,
850 ask `Beni Cherniavsky`__ directly or the `Docutils-users`_ mailing
853 __ mailto:cben@users.sf.net
856 What's the official MIME type for reStructuredText data?
857 --------------------------------------------------------
859 While there is no registered MIME type for reStructuredText, the
860 "official unofficial" standard MIME type is "text/x-rst". [#]_ This was
861 invented for the build system for PEPs (Python Enhancement Proposals),
862 and it's used by the python.org web site build system.
864 Also see `What's the standard filename extension for a
865 reStructuredText file?`_
867 .. [#] The "x-" prefix means it's an unregistered MIME type.
870 How can I mark up a TODO list?
871 ------------------------------
873 You may use a field list with class argument and some CSS styling.
874 For an example see `Docutils TODO lists`_ and its source todo-lists.txt_.
876 .. _Docutils TODO lists: docs/user/todo-lists.html
877 .. _todo-lists.txt: docs/user/todo-lists.txt
880 How can I specify an image grid?
881 --------------------------------
883 In order to arrange images (or other content) in a grid,
884 a borderless `list table`_ can be used. For example::
889 * - .. image:: rst/images/title-scaling.svg
890 - .. image:: rst/images/biohazard.svg
891 * - .. image:: rst/images/biohazard.svg
892 - .. image:: rst/images/biohazard.svg
894 Use figures, if you want also captions::
899 * - .. figure:: rst/images/title-scaling.svg
903 - .. figure:: rst/images/biohazard.svg
907 .. _list table: docs/ref/rst/directives.html#list-table
913 What is the status of the HTML Writer?
914 --------------------------------------
916 The default HTML Writer module, `html4css1`_, is
917 a proof-of-concept reference implementation. While it is a complete
918 implementation, some aspects of the HTML it produces may be outdated or
919 incompatible with older browsers or specialized applications (such as
922 The `html5 writer`_ generates semantic HTML output compatible with HTML5.
923 For the full selection see `Docutils HTML writers`_
925 .. _html4css1: docs/user/html.html#html4css1
926 .. _HTML5 writer: docs/user/html.html#html5
927 .. _Docutils HTML writers: docs/user/html.html
930 What browsers are supported?
931 ----------------------------
933 No specific browser is targeted; all modern graphical browsers should
934 work. Some older browsers, text-only browsers, and browsers without
935 full CSS support are known to produce inferior results. Firefox,
936 Safari, Opera, Chrome, Edge, and MS Internet Explorer (version 5.0 and up)
937 are known to give good results. Reports of experiences with other
938 browsers are welcome.
941 Unexpected results from ``rst2html``: H1, H1 instead of H1, H2. Why?
942 --------------------------------------------------------------------------
944 This only regards output from the `html4css1`_ writer and is configurable
945 via the initial_header_level_ setting.
950 Here's the question in full:
957 All my life, I wanted to be H1.
962 But along came H1, and so shouldn't I be H2?
968 Yeah, imagine me, I'm stuck at H3! No?!?
970 When I run it through ``rst2html4``, I get unexpected results
971 (below). I was expecting H1, H2, then H3; instead, I get H1, H1,
978 <title>Heading 1</title>
981 <div class="document" id="heading-1">
982 <h1 class="title">Heading 1</h1> <-- first H1
983 <p>All my life, I wanted to be H1.</p>
984 <div class="section" id="heading-1-1">
985 <h1><a name="heading-1-1">Heading 1.1</a></h1> <-- H1
986 <p>But along came H1, and so now I must be H2.</p>
987 <div class="section" id="heading-1-1-1">
988 <h2><a name="heading-1-1-1">Heading 1.1.1</a></h2>
989 <p>Yeah, imagine me, I'm stuck at H3!</p>
994 Check the "class" attribute on the H1 tags, and you will see a
995 difference. The first H1 is actually ``<h1 class="title">``; this is
996 the document title, and the default stylesheet renders it centered.
997 There can also be an ``<h2 class="subtitle">`` for the document
1000 If there's only one highest-level section title at the beginning of a
1001 document, it is treated specially, as the document title. (Similarly, a
1002 lone second-highest-level section title may become the document
1003 subtitle.) See `How can I indicate the document title? Subtitle?`_ for
1004 details. Rather than use a plain H1 for the document title, we use ``<h1
1005 class="title">`` so that we can use H1 again within the document. Why
1006 do we do this? HTML only has H1-H6, so by making H1 do double duty, we
1007 effectively reserve these tags to provide 6 levels of heading beyond the
1008 single document title.
1010 With "html4css1", HTML is being used for dumb formatting for nothing
1011 but final display. A stylesheet *is required*, and one is provided;
1012 see `Docutils HTML writers`_. Of course, you're
1013 welcome to roll your own. The default stylesheet provides rules to
1014 format ``<h1 class="title">`` and ``<h2 class="subtitle">``
1015 differently from ordinary ``<h1>`` and ``<h2>``::
1018 text-align: center }
1021 text-align: center }
1023 If you don't want the top section heading to be interpreted as a
1024 title at all, disable the `doctitle_xform`_ setting
1025 (``--no-doc-title`` option). This will interpret your document
1026 differently from the standard settings, which might not be a good
1027 idea. If you don't like the reuse of the H1 in the HTML output, you
1028 can tweak the `initial_header_level`_ setting
1029 (``--initial-header-level`` option) -- but unless you match its value
1030 to your specific document, you might end up with bad HTML (e.g. H3
1033 .. _doctitle_xform: docs/user/config.html#doctitle-xform
1034 .. _initial_header_level: docs/user/config.html#initial-header-level
1036 (Thanks to Mark McEahern for the question and much of the answer.)
1038 .. note:: For the `html5 writer`_, `initial_header_level`_ defaults to
1039 ``2`` because this is what the `HTML5 standard`__ expects as
1040 start value for headings nested in <section> elements.
1042 .. Sectioning content elements are always considered subsections of
1043 their nearest ancestor *sectioning root* [#]_ or their nearest
1044 ancestor element of *sectioning content* [#]_, whichever is nearest,
1047 .. [#] <blockquote>, <body>, <details>, <dialog>, <fieldset>,
1049 .. [#] <article>, <aside>, <nav>, <section>
1051 I.e., a top-level <section> is a subsection of <body>.
1053 __ https://www.w3.org/TR/html53/sections.html#headings-and-sections
1056 How are lists formatted in HTML?
1057 --------------------------------
1059 If list formatting looks strange, first check that you understand
1062 __ `How should I mark up lists?`_
1064 * By default, HTML browsers indent lists relative to their context.
1065 This follows a long tradition in browsers (but isn't so established
1066 in print). If you don't like it, you should change the stylesheet.
1068 This is different from how lists look in reStructuredText source.
1069 Extra indentation in the source indicates a blockquote, resulting in
1070 too much indentation in the browser.
1072 * A list item can contain multiple paragraphs etc. In complex cases
1073 list items are separated by vertical space. By default this spacing
1074 is omitted in "simple" lists. A list is simple if every item
1075 contains a simple paragraph and/or a "simple" nested list. For
1087 text after a nested list
1093 In this example the nested lists are simple (and should appear
1094 compacted) but the outer list is not.
1096 If you want all lists to have equal spacing, disable the
1097 `compact_lists`_ setting (``--no-compact-lists`` option). The
1098 precise spacing can be controlled in the stylesheet.
1100 Note again that this is not exactly WYSIWYG: it partially resembles
1101 the rules about blank lines being optional between list items in
1102 reStructuredText -- but adding/removing optional blank lines does
1103 not affect spacing in the output! It's a feature, not a bug: you
1104 write it as you like but the output is styled consistently.
1106 .. _compact_lists: docs/user/config.html#compact-lists
1109 Why do enumerated lists only use numbers (no letters or roman numerals)?
1110 ------------------------------------------------------------------------
1112 The rendering of enumerators (the numbers or letters acting as list
1113 markers) is completely governed by the stylesheet, so either the
1114 browser can't find the stylesheet (try enabling the
1115 `embed_stylesheet`_ setting [``--embed-stylesheet`` option]), or the
1116 browser can't understand it (try a not too old Firefox, Chrome, Opera,
1117 Safari, Edge, or even MSIE).
1119 .. _embed_stylesheet: docs/user/config.html#embed-stylesheet
1122 There appear to be garbage characters in the HTML. What's up?
1123 --------------------------------------------------------------
1125 What you're seeing is most probably not garbage, but the result of a
1126 mismatch between the actual encoding of the HTML output and the
1127 encoding your browser is expecting. Your browser is misinterpreting
1128 the HTML data, which is encoded text. A discussion of text encodings
1129 is beyond the scope of this FAQ; see one or more of these documents
1132 * `UTF-8 and Unicode FAQ for Unix/Linux
1133 <http://www.cl.cam.ac.uk/~mgk25/unicode.html>`_
1135 * Chapters 3 and 4 of `Introduction to i18n [Internationalization]
1136 <http://www.debian.org/doc/manuals/intro-i18n/>`_
1138 * `Python Unicode Tutorial
1139 <http://www.reportlab.com/i18n/python_unicode_tutorial.html>`_
1141 The common case is with the default output encoding (UTF-8), when
1142 either numbered sections are used (via the "sectnum_" directive) or
1143 symbol-footnotes. Three non-breaking spaces are inserted in each numbered
1144 section title, between the generated number and the title text. Most
1145 footnote symbols are not available in ASCII, nor are non-breaking
1146 spaces. When encoded with UTF-8 and viewed with ordinary ASCII tools,
1147 these characters will appear to be multi-character garbage.
1149 You may have an decoding problem in your browser (or editor, etc.).
1150 The encoding of the output is set to UTF-8, but your browser isn't
1151 recognizing that. You can either try to fix your browser (enable
1152 "UTF-8 character set", sometimes called "Unicode"), or choose a
1153 different `output-encoding`_. You can also try
1154 ``--output-encoding=ascii:xmlcharrefreplace`` for HTML or XML, but not
1155 applicable to non-XMLish outputs.
1157 If you're generating document fragments, the "Content-Type" metadata
1158 (between the HTML ``<head>`` and ``</head>`` tags) must agree with the
1159 encoding of the rest of the document. For UTF-8, it should be::
1161 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1163 Also, Docutils normally generates an XML declaration as the first line
1164 of the output. It must also match the document encoding. For UTF-8::
1166 <?xml version="1.0" encoding="utf-8" ?>
1168 .. _sectnum: docs/ref/rst/directives.html#sectnum
1169 .. _output-encoding: docs/user/config.html#output-encoding
1172 How can I retrieve the body of the HTML document?
1173 -------------------------------------------------
1175 (This is usually needed when using Docutils in conjunction with a
1178 You can use the `docutils.core.publish_parts()`_ function, which
1179 returns a dictionary containing an 'html_body_' entry.
1181 .. _docutils.core.publish_parts(): docs/api/publisher.html#publish-parts
1182 .. _html_body: docs/api/publisher.html#html-body
1185 Why is the Docutils XHTML served as "Content-type: text/html"?
1186 --------------------------------------------------------------
1190 Docutils' HTML output looks like XHTML and is advertised as such::
1192 <?xml version="1.0" encoding="utf-8" ?>
1193 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
1194 "https://www.w3.org/TR/xht ml1/DTD/xhtml1-transitional.dtd">
1196 But this is followed by::
1198 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1200 Shouldn't this be "application/xhtml+xml" instead of "text/html"?
1202 Short answer: if we didn't serve XHTML as "text/html" (which is a
1203 perfectly valid thing to do), it couldn't be viewed in Internet
1206 Long answer: In a perfect web, the Docutils XHTML output would be 100%
1207 strict XHTML. But it's not a perfect web, and a major source of
1208 imperfection is Internet Explorer. When the "html4css1"
1209 writer was created, IE represented the overwhelming majority of web
1210 browsers "in the wild".
1211 The behaviour is kept for backwards compatibility while
1212 modern, semantic HTML output is available with the "html5" writer.
1214 (Thanks to Martin F. Krafft, Robert Kern, Michael Foord, and Alan
1218 Python Source Reader
1219 ====================
1221 Can I use Docutils for Python auto-documentation?
1222 -------------------------------------------------
1224 Yes, in conjunction with other projects.
1226 The Sphinx_ documentation generator includes an autodoc module.
1228 .. _Sphinx: http://www.sphinx-doc.org
1230 Version 2.0 of Ed Loper's `Epydoc <http://epydoc.sourceforge.net/>`_
1231 supports reStructuredText-format docstrings for HTML output. Docutils
1232 0.3 or newer is required.
1234 Development of a Docutils-specific auto-documentation tool is suspended.
1236 .. Epydoc works by importing
1237 Python modules to be documented, whereas the Docutils-specific tool,
1238 described above, will parse modules without importing them (as with
1239 `HappyDoc <http://happydoc.sourceforge.net/>`_, which doesn't support
1242 The advantages of parsing over importing are security and flexibility;
1243 the disadvantage is complexity/difficulty.
1245 * Security: untrusted code that shouldn't be executed can be parsed;
1246 importing a module executes its top-level code.
1247 * Flexibility: comments and unofficial docstrings (those not supported
1248 by Python syntax) can only be processed by parsing.
1249 * Complexity/difficulty: it's a lot harder to parse and analyze a
1250 module than it is to ``import`` and analyze one.
1252 For more details, please see "Docstring Extraction Rules"
1253 in :PEP:`258`, item 3 ("How").
1259 Is the Docutils document model based on any existing XML models?
1260 ----------------------------------------------------------------
1262 Not directly, no. It borrows bits from DocBook, HTML, and others. I
1263 (David Goodger) have designed several document models over the years,
1264 and have my own biases. The Docutils document model is designed for
1265 simplicity and extensibility, and has been influenced by the needs of
1266 the reStructuredText markup.
1271 How to make code contributions that are easily accepted
1272 -------------------------------------------------------
1274 * Follow the `Python coding conventions`_ and `documentation
1275 conventions`_ in the Docutils Policies.
1276 Ensure the addition works with all `supported Python versions`_.
1278 Look at the Docutils sources to see how similar features are
1279 implemented, learn to do it "the Docutils way".
1281 * Prepare tests_. Test cases are also examples and showcases for new
1284 * Include documentation.
1286 * For larger changes, consider creating a `feature branch`_ in a
1287 Docutils repository_ checkout. [#]_
1289 * Mail your patch to the Docutils-develop_ mailing list or attach it to the
1290 relevant ticket at Docutils' `bug tracker`_ or `feature request tracker`_.
1291 We accept patches created with diff, SVN, or Git.
1293 The developers will make sure that contributions fit nicely into Docutils.
1294 This might involve discussing (and compromising on) design and
1295 implementation details. It might also lead to the conclusion that the
1296 addition fits better in the `extensions and related projects`_.
1298 .. [#] Working with branches is much easier with Git_. You can get a Git
1299 clone of the repository from http://repo.or.cz/w/docutils.git or with
1302 .. _Python coding conventions: docs/dev/policies.html#python-coding-conventions
1303 .. _documentation conventions: docs/dev/policies.html#documentation-conventions
1304 .. _tests: docs/dev/testing.html
1305 .. _supported Python versions: README.html#requirements
1306 .. _feature branch: docs/dev/policies.html#feature-branch
1307 .. _Git: http://git-scm.com/
1308 .. _bug tracker: https://sourceforge.net/p/docutils/bugs/
1315 indent-tabs-mode: nil
1316 sentence-end-double-space: t
1320 .. Here's a code css to make a table colourful::
1325 background-color: #ede;
1328 /* alternating colors in table rows */
1329 table.docutils tr:nth-child(even) {
1330 background-color: #F3F3FF;
1332 table.docutils tr:nth-child(odd) {
1333 background-color: #FFFFEE;
1337 border-style: solid none solid none;
1338 border-width: 1px 0 1px 0;
1339 border-color: #AAAAAA;