diff options
| author | wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2006-01-09 20:44:25 +0000 |
|---|---|---|
| committer | wiemann <wiemann@929543f6-e4f2-0310-98a6-ba3bd3dd1d04> | 2006-01-09 20:44:25 +0000 |
| commit | d77fdfef70e08114f57cbef5d91707df8717ea9f (patch) | |
| tree | 49444e3486c0c333cb7b33dfa721296c08ee4ece /sandbox/dkuhlman/docutils | |
| parent | 53cd16ca6ca5f638cbe5956988e88f9339e355cf (diff) | |
| parent | 3993c4097756e9885bcfbd07cb1cc1e4e95e50e4 (diff) | |
| download | docutils-0.4.tar.gz | |
Release 0.4: tagging released revisiondocutils-0.4
git-svn-id: http://svn.code.sf.net/p/docutils/code/tags/docutils-0.4@4268 929543f6-e4f2-0310-98a6-ba3bd3dd1d04
Diffstat (limited to 'sandbox/dkuhlman/docutils')
6 files changed, 0 insertions, 3956 deletions
diff --git a/sandbox/dkuhlman/docutils/docs/rst/pythonlatex_quickref.html b/sandbox/dkuhlman/docutils/docs/rst/pythonlatex_quickref.html deleted file mode 100644 index 99bbd5611..000000000 --- a/sandbox/dkuhlman/docutils/docs/rst/pythonlatex_quickref.html +++ /dev/null @@ -1,1593 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<html> - <head> - <title>Quick reStructuredText</title> - - <style type="text/css"><!-- - a.backref { text-decoration: none ; color: black } - --></style> - - </head> - - <body> - <h1>Quick <i>re</i><font -size="+4"><tt>Structured</tt></font><i>Text</i> for "Documenting -Python"</h1> - - <!-- Caveat: if you're reading the HTML for the examples, --> - <!-- beware that it was hand-generated, not by Docutils/ReST. --> - - <p align="right"><em><a href="http://docutils.sourceforge.net/docs/rst/quickref.html" - >http://docutils.sourceforge.net/docs/rst/quickref.html</a></em> - <br align="right"><em>Being a cheat-sheet for reStructuredText</em> - <br align="right"><em>Updated 2003-06-10</em> - - <blockquote> - <p>Copyright: This document has been placed in the public domain. - </blockquote> - - - <p>The full details of the markup may be found on the - <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> - page. This document is just intended as a reminder. - - <p>Links that look like "(<a href="#details">details</a>)" point - into the HTML version of the full <a - href="../../spec/rst/reStructuredText.html">reStructuredText - specification</a> document. These are relative links; if they - don't work, please use the <a - href="http://docutils.sourceforge.net/docs/rst/quickref.html" - >master "Quick reStructuredText"</a> document. - - <h2><a name="contents">Contents</a></h2> - - <ul> - <li><a href="#docpy">"Documenting Python"</a></li> - <li><a href="#inline-markup">Inline Markup</a></li> - <li><a href="#escaping">Escaping with Backslashes</a></li> - <li><a href="#section-structure">Section Structure</a></li> - <li><a href="#paragraphs">Paragraphs</a></li> - <li><a href="#bullet-lists">Bullet Lists</a></li> - <li><a href="#enumerated-lists">Enumerated Lists</a></li> - <li><a href="#definition-lists">Definition Lists</a></li> - <li><a href="#field-lists">Field Lists</a></li> - <li><a href="#option-lists">Option Lists</a></li> - <li><a href="#literal-blocks">Literal Blocks</a></li> - <li><a href="#block-quotes">Block Quotes</a></li> - <li><a href="#doctest-blocks">Doctest Blocks</a></li> - <li><a href="#tables">Tables</a></li> - <li><a href="#transitions">Transitions</a></li> - <li><a href="#explicit-markup">Explicit Markup</a> - <ul> - <li><a href="#footnotes">Footnotes</a></li> - <li><a href="#citations">Citations</a></li> - <li><a href="#hyperlink-targets">Hyperlink Targets</a> - <ul> - <li><a href="#external-hyperlink-targets">External Hyperlink Targets</a></li> - <li><a href="#internal-hyperlink-targets">Internal Hyperlink Targets</a></li> - <li><a href="#indirect-hyperlink-targets">Indirect Hyperlink Targets</a></li> - <li><a href="#implicit-hyperlink-targets">Implicit Hyperlink Targets</a></li> - </ul></li> - <li><a href="#directives">Directives</a></li> - <li><a href="#substitution-references-and-definitions">Substitution References and Definitions</a></li> - <li><a href="#comments">Comments</a></li> - </ul></li> - <li><a href="#getting-help">Getting Help</a></li> - </ul> - - <h2><a href="#contents" name="docpy" class="backref" - >Documenting Python</a></h2> - - <h3>Introduction</h3> - - <p>What it does -- It generates LaTeX suitable as input to the - "Documenting Python" system.</p> - - <p>How to run it: - - <pre> - $ docutils/tools/documenting_python.py --documentclass=howto infile.rst - </pre> - - <h3>Command-line options</h3> - - <dl> - - <dt>documentclass</dt> - <dd> - <ul> - - <li> Controls rusulting document class.</li> - - <li>Allowed values are "manual" and "howto".</li> - - <li>Default is "howto".</li> - - <li>Generates "\documentclass{manual}" or - "\documentclass{howto}".</li> - - </ul> - </dd> - - </dl> - - <h3>The heading section and controlling it</h3> - - <p>The following docinfo items, fields, and topics are - supported:</p> - - <ul> - - <li>:author: -- Generates "\author{}"..</li> - - <li>:date: -- Generates "\date{}".</li> - - <li>:revisision: -- Generates "release{}".</li> - - <li>:copyright: -- Generated at the beginning of the document.</li> - - <li>:abstract: -- Generates: - - <pre> - \begin{abstract} - \noindent - - [stuff] - \end{abstract} - </pre> - </li> - - <li>[The first] title -- Generates "\title{}". Note: I don't - understand the title promotion stuff. I'm guessing that I - have a bug here that will be discovered when we try a - different input (rST) document.</li> - - </ul> - - <p><strong>Example:</strong> -- Here is (the first few lines - of) a sample input rST file:</p> - - <pre> - :author: Dave Kuhlman - :date: 2003/06/05 - :revision: 1.27 - - :copyright: This document has been placed in the public domain. You - may do with it as you wish. You may copy, modify, - redistribute, reattribute, sell, buy, rent, lease, - destroy, or improve it, quote it at length, excerpt, - incorporate, collate, fold, staple, or mutilate it, or do - anything else to it that your or anyone else's heart - desires. - - :abstract: This is a test document, containing at least one - example of each reStructuredText construct. - - ====================================== - reStructuredText Test Document (title) - ====================================== - o - o - o - </pre> - - <p>If we run the above through this command:</p> - - <pre> - $ ../docutils/tools/documenting_python.py --documentclass=howto testdocpy1.rst - </pre> - - <p>And, here is what the above rST would generate:</p> - - <pre> - \documentclass{howto} - %% generator Docutils: http://docutils.sourceforge.net/ - \title{reStructuredText Test Document (title)} - \release{1.27} - \date{2003/06/05} - \author{Dave Kuhlman} - \begin{document} - \maketitle - \ifhtml - \chapter*{Front Matter\label{front}} - \fi - - This document has been placed in the public domain. You - may do with it as you wish. You may copy, modify, - redistribute, reattribute, sell, buy, rent, lease, - destroy, or improve it, quote it at length, excerpt, - incorporate, collate, fold, staple, or mutilate it, or do - anything else to it that your or anyone else's heart - desires. - \begin{abstract} - \noindent - - This is a test document, containing at least one - example of each reStructuredText construct. - \end{abstract} - \tableofcontents - o - o - o - </pre> - - <h3>The "See Also" section</h3> - - <p>If a section title matches the string "see also" (case - insensitive, then hyperlinks are treated slightly differently. - In particular, we generate "\seeurl{}".</p> - - - <h2><a href="#contents" name="inline-markup" class="backref" - >Inline Markup</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#inline-markup">details</a>) - - <p>Inline markup allows words and phrases within text to have - character styles (like italics and boldface) and functionality - (like hyperlinks). - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th>Plain text - <th>Typical result - <th>Notes - <th>Doc Py - </thead> - <tbody> - <tr valign="top"> - <td nowrap><samp>*emphasis*</samp> - <td><em>emphasis</em> - <td>Normally rendered as italics. - <td><pre>\emph{some text}</pre></td> - - <tr valign="top"> - <td nowrap><samp>**strong emphasis**</samp> - <td><strong>strong emphasis</strong> - <td>Normally rendered as boldface. - <td><pre>\strong{some text}</pre></td> - - <tr valign="top"> - <td nowrap><samp>`interpreted text`</samp> - <td>(see note at right) - <td>The rendering and <em>meaning</em> of interpreted text is - domain- or application-dependent. It can be used for things - like index entries or explicit descriptive markup (like program - identifiers). - - <tr valign="top"> - <td nowrap><samp>``inline literal``</samp> - <td><code>inline literal</code> - <td>Normally rendered as monospaced text. Spaces should be - preserved, but line breaks will not be. - <td> - <p> Generates \code{word}, if no embedded whitespace. Generates - \samp{some text}, if there is embedded whitespace.</p> - </td> - - <tr valign="top"> - <td nowrap><samp>reference_</samp> - <td><a href="#hyperlink-targets">reference</a> - <td>A simple, one-word hyperlink reference. See <a - href="#hyperlinks" >Hyperlinks</a>. - <td> - <pre>\ulink{label}{url}</pre> - <p>In "See Also" section:</p> - <pre>\seeurl{url}{label}</pre> - </td> - - <tr valign="top"> - <td nowrap><samp>`phrase reference`_</samp> - <td><a href="#hyperlink-targets">phrase reference</a> - <td>A hyperlink reference with spaces or punctuation needs to be - quoted with backquotes. See <a - href="#hyperlink-targets">Hyperlinks</a>. - <td> - <pre>\ulink{label}{url}</pre> - <p>In "See Also" section:</p> - <pre>\seeurl{url}{label}</pre> - </td> - - <tr valign="top"> - <td nowrap><samp>anonymous__</samp> - <td><a href="#hyperlink-targets">anonymous</a> - <td>With two underscores instead of one, both simple and phrase - references may be anonymous (the reference text is not repeated - at the target). See <a - href="#hyperlink-targets">Hyperlinks</a>. - - <tr valign="top"> - <td nowrap><samp>_`inline internal target`</samp> - <td><a name="inline-internal-target">inline internal target</a> - <td>A crossreference target within text. - See <a href="#hyperlink-targets">Hyperlinks</a>. - - <tr valign="top"> - <td nowrap><samp>|substitution reference|</samp> - <td>(see note at right) - <td>The result is substituted in from the <a - href="#substitution-references-and-definitions">substitution - definition</a>. It could be text, an image, a hyperlink, or a - combination of these and others. - - <tr valign="top"> - <td nowrap><samp>footnote reference [1]_</samp> - <td>footnote reference <sup><a href="#footnotes">1</a></sup> - <td>See <a href="#footnotes">Footnotes</a>. - - <tr valign="top"> - <td nowrap><samp>citation reference [CIT2002]_</samp> - <td>citation reference <a href="#citations">[CIT2002]</a> - <td>See <a href="#citations">Citations</a>. - - <tr valign="top"> - <td nowrap><samp>http://docutils.sf.net/</samp> - <td><a href="http://docutils.sf.net/">http://docutils.sf.net/</a> - <td>A standalone hyperlink. - <td><pre>\url{http://docutils.sf.net/}</pre></td> - - </table> - - <p>Asterisk, backquote, vertical bar, and underscore are inline - delimiter characters. Asterisk, backquote, and vertical bar act - like quote marks; matching characters surround the marked-up word - or phrase, whitespace or other quoting is required outside them, - and there can't be whitespace just inside them. If you want to use - inline delimiter characters literally, <a href="#escaping">escape - (with backslash)</a> or quote them (with double backquotes; i.e. - use inline literals). - - <p>In detail, the reStructuredText specification says that in - inline markup, the following rules apply to start-strings and - end-strings (inline markup delimiters): - - <ol> - <li>The start-string must start a text block or be - immediately preceded by whitespace or any of - <samp>' " ( [ {</samp> or <samp><</samp>. - <li>The start-string must be immediately followed by non-whitespace. - <li>The end-string must be immediately preceded by non-whitespace. - <li>The end-string must end a text block (end of document or - followed by a blank line) or be immediately followed by whitespace - or any of <samp>' " . , : ; ! ? - ) ] } / \</samp> - or <samp>></samp>. - <li>If a start-string is immediately preceded by one of - <samp>' " ( [ {</samp> or <samp><</samp>, it must not be - immediately followed by the corresponding character from - <samp>' " ) ] }</samp> or <samp>></samp>. - <li>An end-string must be separated by at least one - character from the start-string. - <li>An <a href="#escaping">unescaped</a> backslash preceding a - start-string or end-string will disable markup recognition, except - for the end-string of inline literals. - </ol> - - <p>Also remember that inline markup may not be nested (well, - except that inline literals can contain any of the other inline - markup delimiter characters, but that doesn't count because - nothing is processed). - - <h2><a href="#contents" name="escaping" class="backref" - >Escaping with Backslashes</a></h2> - - <p>(<a - href="../../spec/rst/reStructuredText.html#backslashes">details</a>) - - <p>reStructuredText uses backslashes ("\") to override the special - meaning given to markup characters and get the literal characters - themselves. To get a literal backslash, use an escaped backslash - ("\\"). For example: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Raw reStructuredText - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"><td> - <samp>*escape* ``with`` "\"</samp> - <td><em>escape</em> <samp>with</samp> "" - <tr valign="top"><td> - <samp>\*escape* \``with`` "\\"</samp> - <td>*escape* ``with`` "\" - <td><pre>$\backslash$</pre></td> - </table> - - <p>In Python strings it will, of course, be necessary - to escape any backslash characters so that they actually - <em>reach</em> reStructuredText. - The simplest way to do this is to use raw strings: - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Python string - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"><td> - <samp>r"""\*escape* \`with` "\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\\*escape* \\`with` "\\\\""""</samp> - <td>*escape* `with` "\" - <tr valign="top"><td> - <samp> """\*escape* \`with` "\\""""</samp> - <td><em>escape</em> with "" - </table> - - <h2><a href="#contents" name="section-structure" class="backref" - >Section Structure</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#sections">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>=====</samp> -<br><samp>Title</samp> -<br><samp>=====</samp> -<br><samp>Subtitle</samp> -<br><samp>--------</samp> -<br><samp>Titles are underlined (or over-</samp> -<br><samp>and underlined) with a printing</samp> -<br><samp>nonalphanumeric 7-bit ASCII</samp> -<br><samp>character. Recommended choices</samp> -<br><samp>are "``= - ` : ' " ~ ^ _ * + # < >``".</samp> -<br><samp>The underline/overline must be at</samp> -<br><samp>least as long as the title text.</samp> - - <td> - <font size="+2"><strong>Title</strong></font> - <p><font size="+1"><strong>Subtitle</strong></font> - <p>Titles are underlined (or over- - and underlined) with a printing - nonalphanumeric 7-bit ASCII - character. Recommended choices - are "<samp>= - ` : ' " ~ ^ _ * + # < ></samp>". - The underline/overline must be at - least as long as the title text. -<td> -\chapter{Title}<br/> -\section{Subtitle}<br/> -\subsection{Subsubtitle} -</td> - </table> - - <h2><a href="#contents" name="paragraphs" class="backref" - >Paragraphs</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#paragraphs">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<p><samp>This is a paragraph.</samp> - -<p><samp>Paragraphs line up at their left</samp> -<br><samp>edges, and are normally separated</samp> -<br><samp>by blank lines.</samp> - - <td> - <p>This is a paragraph. - - <p>Paragraphs line up at their left edges, and are normally - separated by blank lines. - - <td> - <p>This is a paragraph. - - <p>Paragraphs line up at their left edges, and are normally - separated by blank lines. - </td> - - </table> - - <h2><a href="#contents" name="bullet-lists" class="backref" - >Bullet Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#bullet-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Bullet lists:</samp> - -<p><samp>- This is item 1</samp> -<br><samp>- This is item 2</samp> - -<p><samp>- Bullets are "-", "*" or "+".</samp> -<br><samp> Continuing text must be aligned</samp> -<br><samp> after the bullet and whitespace.</samp> - -<p><samp>Note that a blank line is required</samp> -<br><samp>before the first item and after the</samp> -<br><samp>last, but is optional between items.</samp> - <td>Bullet lists: - <ul> - <li>This is item 1 - <li>This is item 2 - <li>Bullets are "-", "*" or "+". - Continuing text must be aligned - after the bullet and whitespace. - </ul> - <p>Note that a blank line is required before the first - item and after the last, but is optional between items. -<td> -<pre> -\begin{itemize} - -\item This is item 1 - -\item This is item 2 - -\end{itemize} -</pre> -<p>Note: Embedded lists are supported.</p> -</td> - </table> - - <h2><a href="#contents" name="enumerated-lists" class="backref" - >Enumerated Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#enumerated-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Enumerated lists:</samp> - -<p><samp>3. This is the first item</samp> -<br><samp>4. This is the second item</samp> -<br><samp>5. Enumerators are arabic numbers,</samp> -<br><samp> single letters, or roman numerals</samp> -<br><samp>6. List items should be sequentially</samp> -<br><samp> numbered, but need not start at 1</samp> -<br><samp> (although not all formatters will</samp> -<br><samp> honour the first index).</samp> - <td>Enumerated lists: - <ol type="1"> - <li value="3">This is the first item - <li>This is the second item - <li>Enumerators are arabic numbers, single letters, - or roman numerals - <li>List items should be sequentially numbered, - but need not start at 1 (although not all - formatters will honour the first index). - </ol> -<td> -<pre> -\begin{enumerate} - -\item This is item 1 - -\item This is item 2 - -\end{enumerate} -</pre> -<p>Note: Embedded lists are supported.</p> -</td> - </table> - - <h2><a href="#contents" name="definition-lists" class="backref" - >Definition Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#definition-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Definition lists:</samp> -<br> -<br><samp>what</samp> -<br><samp> Definition lists associate a term with</samp> -<br><samp> a definition.</samp> -<br> -<br><samp>how</samp> -<br><samp> The term is a one-line phrase, and the</samp> -<br><samp> definition is one or more paragraphs or</samp> -<br><samp> body elements, indented relative to the</samp> -<br><samp> term. Blank lines are not allowed</samp> -<br><samp> between term and definition.</samp> - <td>Definition lists: - <dl> - <dt><strong>what</strong> - <dd>Definition lists associate a term with - a definition. - - <dt><strong>how</strong> - <dd>The term is a one-line phrase, and the - definition is one or more paragraphs or - body elements, indented relative to the - term. Blank lines are not allowed - between term and definition. - </dl> -<td><pre> -\begin{description} - -\item[label 1]Some descriptive text. - -\item[label 2]More descriptive text. - -\end{description} -</pre></td> - </table> - - <h2><a href="#contents" name="field-lists" class="backref" - >Field Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#field-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>:Authors:</samp> -<br><samp> Tony J. (Tibs) Ibbs,</samp> -<br><samp> David Goodger</samp> - -<p><samp> (and sundry other good-natured folks)</samp> - -<p><samp>:Version: 1.0 of 2001/08/08</samp> -<br><samp>:Dedication: To my father.</samp> - <td> - <table> - <tr valign="top"> - <td><strong>Authors:</strong> - <td>Tony J. (Tibs) Ibbs, - David Goodger - <tr><td><td>(and sundry other good-natured folks) - <tr><td><strong>Version:</strong><td>1.0 of 2001/08/08 - <tr><td><strong>Dedication:</strong><td>To my father. - </table> - </table> - - <p>Field lists are used as part of an extension syntax, such as - options for <a href="#directives">directives</a>, or database-like - records meant for further processing. Field lists may also be - used as generic two-column table constructs in documents. - - <h2><a href="#contents" name="option-lists" class="backref" - >Option Lists</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#option-lists">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp> --a command-line option "a" -<br>-b file options can have arguments -<br> and long descriptions -<br>--long options can be long also -<br>--input=file long options can also have -<br> arguments -<br>/V DOS/VMS-style options too -</samp> - - <td> - <table border="0" width="100%"> - <tbody valign="top"> - <tr> - <td width="30%"><p><samp>-a</samp> - <td><p>command-line option "a" - <tr> - <td><p><samp>-b <i>file</i></samp> - <td><p>options can have arguments and long descriptions - <tr> - <td><p><samp>--long</samp> - <td><p>options can be long also - <tr> - <td><p><samp>--input=<i>file</i></samp> - <td><p>long options can also have arguments - <tr> - <td><p><samp>/V</samp> - <td><p>DOS/VMS-style options too - </table> -<td><pre> -\programopt{-a} -\longprogramopt{long} -\programopt{/V} -</pre></td> - </table> - - <p>There must be at least two spaces between the option and the - description. - - <h2><a href="#contents" name="literal-blocks" class="backref" - >Literal Blocks</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#literal-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>A paragraph containing only two colons</samp> -<br><samp>indicates that the following indented</samp> -<br><samp>text is a literal block.</samp> -<br> -<br><samp>::</samp> -<br> -<br><samp> Whitespace, newlines, blank lines, and</samp> -<br><samp> all kinds of markup (like *this* or</samp> -<br><samp> \this) is preserved by literal blocks.</samp> -<br> -<br><samp> The paragraph containing only '::'</samp> -<br><samp> will be omitted from the result.</samp> -<br> -<br><samp>The ``::`` may be tacked onto the very</samp> -<br><samp>end of any paragraph. The ``::`` will be</samp> -<br><samp>omitted if it is preceded by whitespace.</samp> -<br><samp>The ``::`` will be converted to a single</samp> -<br><samp>colon if preceded by text, like this::</samp> -<br> -<br><samp> It's very convenient to use this form.</samp> -<br> -<br><samp>Literal blocks end when text returns to</samp> -<br><samp>the preceding paragraph's indentation.</samp> -<br><samp>This means that something like::</samp> -<br> -<br><samp> We start here</samp> -<br><samp> and continue here</samp> -<br><samp> and end here.</samp> -<br> -<br><samp>is possible.</samp> - - <td> - <p>A paragraph containing only two colons -indicates that the following indented -text is a literal block. - - <pre> - Whitespace, newlines, blank lines, and - all kinds of markup (like *this* or - \this) is preserved by literal blocks. - - The paragraph containing only '::' - will be omitted from the result.</pre> - - <p>The <samp>::</samp> may be tacked onto the very -end of any paragraph. The <samp>::</samp> will be -omitted if it is preceded by whitespace. -The <samp>::</samp> will be converted to a single -colon if preceded by text, like this: - - <pre> - It's very convenient to use this form.</pre> - - <p>Literal blocks end when text returns to -the preceding paragraph's indentation. -This means that something like: - - <pre> - We start here - and continue here - and end here.</pre> - - <p>is possible. -<td><pre> - - -A paragraph containing only two colons -indicates that the following indented -text is a literal block. - -\begin{verbatim} - Whitespace, newlines, blank lines, and - all kinds of markup (like *this* or - \this) is preserved by literal blocks. - - The paragraph containing only '::' - will be omitted from the result. -\end{verbatim} - -The <samp>::</samp> may be tacked onto the very -end of any paragraph. The <samp>::</samp> will be -omitted if it is preceded by whitespace. -The <samp>::</samp> will be converted to a single -colon if preceded by text, like this: - -\begin{verbatim} - It's very convenient to use this form. -\end{verbatim} - -Literal blocks end when text returns to -the preceding paragraph's indentation. -This means that something like: - -\begin{verbatim} - We start here - and continue here - and end here. -\end{verbatim} - -is possible. - - -</pre></td> - </table> - - <h2><a href="#contents" name="block-quotes" class="backref" - >Block Quotes</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#block-quotes">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<samp>Block quotes are just:</samp> - -<p><samp> Indented paragraphs,</samp> - -<p><samp> and they may nest.</samp> - <td> - Block quotes are just: - <blockquote> - <p>Indented paragraphs, - <blockquote> - <p>and they may nest. - </blockquote> - </blockquote> -<td><pre> -Block quotes are just: - -\begin{quotation} -Indented paragraphs -\end{quotation} -</pre></td> - </table> - - <h2><a href="#contents" name="doctest-blocks" class="backref" - >Doctest Blocks</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#doctest-blocks">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp>Doctest blocks are interactive -<br>Python sessions. They begin with -<br>"``>>>``" and end with a blank line.</samp> - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> - - <td> - <p>Doctest blocks are interactive - Python sessions. They begin with - "<samp>>>></samp>" and end with a blank line. - - <p><samp>>>> print "This is a doctest block." -<br>This is a doctest block.</samp> -<td><pre> -\begin{verbatim} -<samp>>>> print "This is a doctest block." -\end{verbatim} -</pre></td> - </table> - - <p>"The <a - href="http://www.python.org/doc/current/lib/module-doctest.html">doctest</a> - module searches a module's docstrings for text that looks like an - interactive Python session, then executes all such sessions to - verify they still work exactly as shown." (From the doctest docs.) - - <h2><a href="#contents" name="tables" class="backref" - >Tables</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#tables">details</a>) - - <p>There are two syntaxes for tables in reStructuredText. Grid - tables are complete but cumbersome to create. Simple tables are - easy to create but limited (no row spans, etc.).</p> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> -<p><samp>Grid table:</samp></p> - -<p><samp>+------------+------------+-----------+</samp> -<br><samp>| Header 1 | Header 2 | Header 3 |</samp> -<br><samp>+============+============+===========+</samp> -<br><samp>| body row 1 | column 2 | column 3 |</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 2 | Cells may span columns.|</samp> -<br><samp>+------------+------------+-----------+</samp> -<br><samp>| body row 3 | Cells may | - Cells |</samp> -<br><samp>+------------+ span rows. | - contain |</samp> -<br><samp>| body row 4 | | - blocks. |</samp> -<br><samp>+------------+------------+-----------+</samp></p> - <td> - <p>Grid table:</p> - <table border="1"> - <tr valign="top"> - <th>Header 1 - <th>Header 2 - <th>Header 3 - <tr> - <td>body row 1 - <td>column 2 - <td>column 3 - <tr> - <td>body row 2 - <td colspan="2">Cells may span columns. - <tr valign="top"> - <td>body row 3 - <td rowspan="2">Cells may<br>span rows. - <td rowspan="2"> - <ul> - <li>Cells - <li>contain - <li>blocks. - </ul> - <tr valign="top"> - <td>body row 4 - </table> - -<td><pre> -Two-column table: - -\begin{tableii}{l|l}{character}{Heading 1} - {Heading 2} -\lineii{value 1-1}{value 1-2} -\lineii{value 2-1}{value 2-2} -\end{tableii} - -Three-column table: - -\begin{tableiii}{l|l|l}{character} - {Heading 1}{Heading 2}{Heading 3} -\lineiii{value 1-1}{value 1-2}{value 1-3} -\lineiii{value 2-1}{value 2-2}{value 2-3} -\end{tableii} - -</pre></td> - - <tr valign="top"> - <td> -<p><samp>Simple table:</samp></p> - -<p><samp>===== ===== ======</samp> -<br><samp> Inputs Output</samp> -<br><samp>------------ ------</samp> -<br><samp> A B A or B</samp> -<br><samp>===== ===== ======</samp> -<br><samp>False False False</samp> -<br><samp>True False True</samp> -<br><samp>False True True</samp> -<br><samp>True True True</samp> -<br><samp>===== ===== ======</samp></p> - - <td> - <p>Simple table:</p> - <table frame="border" rules="all"> - <colgroup> - <col colwidth="31%" /> - <col colwidth="31%" /> - <col colwidth="38%" /> - </colgroup> - <thead valign="bottom"> - <tr> - <th colspan="2">Inputs - <th>Output - <tr> - <th>A - <th>B - <th>A or B - <tbody valign="top"> - <tr> - <td>False - <td>False - <td>False - <tr> - <td>True - <td>False - <td>True - <tr> - <td>False - <td>True - <td>True - <tr> - <td>True - <td>True - <td>True - </table> - - <td> - <p>Notes and limitations:</p> - <ul> - <li>Only regular tables supported. No COLSPAN or - ROWSPAN.</li> - <li>Tables with 2-columns, 3-columns, 4-columns, and - 5-columns are supported.</li> - <li>All columns are left-aligned.</li> - </ul> - </td> - </table> - - <h2><a href="#contents" name="transitions" class="backref" - >Transitions</a></h2> - - <p>(<a href="../../spec/rst/reStructuredText.html#transitions">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td> - <p><samp> -A transition marker is a horizontal line -<br>of 4 or more repeated punctuation -<br>characters.</samp> - - <p><samp>------------</samp> - - <p><samp>A transition should not begin or end a -<br>section or document, nor should two -<br>transitions be immediately adjacent.</samp> - - <td> - <p>A transition marker is a horizontal line - of 4 or more repeated punctuation - characters.</p> - - <hr> - - <p>A transition should not begin or end a - section or document, nor should two - transitions be immediately adjacent. -<td> - <p>A transition marker is a horizontal line - of 4 or more repeated punctuation - characters.</p> - - \hrule{} - - <p>A transition should not begin or end a - section or document, nor should two - transitions be immediately adjacent. -</td> - </table> - - <p>Transitions are commonly seen in novels and short fiction, as a - gap spanning one or more lines, marking text divisions or - signaling changes in subject, time, point of view, or emphasis. - - <h2><a href="#contents" name="explicit-markup" class="backref" - >Explicit Markup</a></h2> - - <p>Explicit markup blocks are used for constructs which float - (footnotes), have no direct paper-document representation - (hyperlink targets, comments), or require specialized processing - (directives). They all begin with two periods and whitespace, the - "explicit markup start". - - <h3><a href="#contents" name="footnotes" class="backref" - >Footnotes</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#footnotes">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Footnote references, like [5]_.</samp> - <br><samp>Note that footnotes may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [5] A numerical footnote. Note</samp> - <br><samp> there's no colon after the ``]``.</samp> - - <td> - Footnote references, like <sup><a href="#5">5</a></sup>. - Note that footnotes may get rearranged, e.g., to the bottom of - the "page". - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="5"><strong>[5]</strong></a><td> A numerical footnote. - Note there's no colon after the <samp>]</samp>. - </table> - <td> -Footnote references, like\footnote{A numerical footnote. -Note there's no colon after the <samp>]</samp>.}. -Note that footnotes may get -rearranged, e.g., to the bottom of -the "page". - <tr valign="top"> - <td> - <samp>Autonumbered footnotes are</samp> - <br><samp>possible, like using [#]_ and [#]_.</samp> - <p><samp>.. [#] This is the first one.</samp> - <br><samp>.. [#] This is the second one.</samp> - - <p><samp>They may be assigned 'autonumber</samp> - <br><samp>labels' - for instance, - <br>[#fourth]_ and [#third]_.</samp> - - <p><samp>.. [#third] a.k.a. third_</samp> - <p><samp>.. [#fourth] a.k.a. fourth_</samp> - <td> - Autonumbered footnotes are possible, like using <sup><a - href="#auto1">1</a></sup> and <sup><a href="#auto2">2</a></sup>. - - <p>They may be assigned 'autonumber labels' - for instance, - <sup><a href="#fourth">4</a></sup> and <sup><a - href="#third">3</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="auto1"><strong>[1]</strong></a><td> This is the first one. - <tr><td><a name="auto2"><strong>[2]</strong></a><td> This is the second one. - <tr><td><a name="third"><strong>[3]</strong></a><td> a.k.a. <a href="#third">third</a> - <tr><td><a name="fourth"><strong>[4]</strong></a><td> a.k.a. <a href="#fourth">fourth</a> - </table> - <td> -<p>Autonumbered footnotes are possible, like using\footnote{This is -the first one.} and \footnote{This is the second one.}. </p> - -<p>They may be assigned 'autonumber labels' - for instance, -\footnote{a.k.a. third} and \footnote{a.k.a. fourth}. </p> - -<p>[Note: Re-ordering of footnotes is not supported in DocPy.]</p> - - </br></td> - - <tr valign="top"> - <td> - <samp>Auto-symbol footnotes are also</samp> - <br><samp>possible, like this: [*]_ and [*]_.</samp> - <p><samp>.. [*] This is the first one.</samp> - <br><samp>.. [*] This is the second one.</samp> - - <td> - Auto-symbol footnotes are also - possible, like this: <sup><a href="#symbol1">*</a></sup> - and <sup><a href="#symbol2">†</a></sup>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Footnotes: --> - <tr><td><a name="symbol1"><strong>[*]</strong></a><td> This is the first symbol footnote - <tr><td><a name="symbol2"><strong>[†]</strong></a><td> This is the second one. - </table> - - <td> - [Not supported in DocPy.] - - </table> - - <p>The numbering of auto-numbered footnotes is determined by the - order of the footnotes, not of the references. For auto-numbered - footnote references without autonumber labels - ("<samp>[#]_</samp>"), the references and footnotes must be in the - same relative order. Similarly for auto-symbol footnotes - ("<samp>[*]_</samp>"). - - <h3><a href="#contents" name="citations" class="backref" - >Citations</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#citations">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Citation references, like [CIT2002]_.</samp> - <br><samp>Note that citations may get</samp> - <br><samp>rearranged, e.g., to the bottom of</samp> - <br><samp>the "page".</samp> - - <p><samp>.. [CIT2002] A citation</samp> - <br><samp> (as often used in journals).</samp> - - <p><samp>Citation labels contain alphanumerics,</samp> - <br><samp>underlines, hyphens and fullstops.</samp> - <br><samp>Case is not significant.</samp> - - <p><samp>Given a citation like [this]_, one</samp> - <br><samp>can also refer to it like this_.</samp> - - <p><samp>.. [this] here.</samp> - - <td> - Citation references, like <a href="#cit2002">[CIT2002]</a>. - Note that citations may get rearranged, e.g., to the bottom of - the "page". - - <p>Citation labels contain alphanumerics, underlines, hyphens - and fullstops. Case is not significant. - - <p>Given a citation like <a href="#this">[this]</a>, one - can also refer to it like <a href="#this">this</a>. - - <p><table> - <tr><td colspan="2"><hr> - <!-- <tr><td colspan="2">Citations: --> - <tr><td><a name="cit2002"><strong>[CIT2002]</strong></a><td> A citation - (as often used in journals). - <tr><td><a name="this"><strong>[this]</strong></a><td> here. - </table> - - </table> - - <h3><a href="#contents" name="hyperlink-targets" class="backref" - >Hyperlink Targets</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#hyperlink-targets">details</a>) - - <h4><a href="#contents" name="external-hyperlink-targets" class="backref" - >External Hyperlink Targets</a></h4> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>External hyperlinks, like Python_.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <tr><td>Indirect hyperlinks, like - <a href="http://www.python.org">Python</a>. - <tr bgcolor="#99CCFF"><td><em>Call-out form</em> - <tr><td>External hyperlinks, like - <a href="#labPython"><i>Python</i></a>. - - <p><table> - <tr><td colspan="2"><hr> - <tr><td><a name="labPython"><i>Python:</i></a> - <td> <a href="http://www.python.org/">http://www.python.org/</a> - </table> - </table> - <td> - <p>External hyperlinks, like - \ulink{Python}{http://www.python.org/}.</p> - </table> - - <p>"<em>Fold-in</em>" is the representation typically used in HTML - documents (think of the indirect hyperlink being "folded in" like - ingredients into a cake), and "<em>call-out</em>" is more suitable for - printed documents, where the link needs to be presented explicitly, for - example as a footnote. - - <h4><a href="#contents" name="internal-hyperlink-targets" class="backref" - >Internal Hyperlink Targets</a></h4> - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td><samp>Internal crossreferences, like example_.</samp> - - <p><samp>.. _example:</samp> - - <p><samp>This is an example crossreference target.</samp> - <td> - <table width="100%"> - <tr bgcolor="#99CCFF"><td><em>Fold-in form</em> - <!-- Note that some browsers may not like an "a" tag that --> - <!-- does not have any content, so we could arbitrarily --> - <!-- use the first word as content - *or* just trust to --> - <!-- luck! --> - <tr><td>Internal crossreferences, like <a href="#example-foldin">example</a> - <p><a name="example-foldin">This</a> is an example - crossreference target. - <tr><td bgcolor="#99CCFF"><em>Call-out form</em> - <tr><td>Internal crossreferences, like <a href="#example-callout">example</a> - - <p><a name="example-callout"><i>example:</i></a> - <br>This is an example crossreference target. - </table> - - </table> - - <h4><a href="#contents" name="indirect-hyperlink-targets" class="backref" - >Indirect Hyperlink Targets</a></h4> - - <p>(<a href="../../spec/rst/reStructuredText.html#indirect-hyperlink-targets">details</a>) - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Python_ is `my favourite -<br>programming language`__.</samp> - - <p><samp>.. _Python: http://www.python.org/</samp> - - <p><samp>__ Python_</samp> - - <td> - <p><a href="http://www.python.org/">Python</a> is - <a href="http://www.python.org/">my favourite - programming language</a>. - - </table> - - <p>The second hyperlink target (the line beginning with - "<samp>__</samp>") is both an indirect hyperlink target - (<i>indirectly</i> pointing at the Python website via the - "<samp>Python_</samp>" reference) and an <b>anonymous hyperlink - target</b>. In the text, a double-underscore suffix is used to - indicate an <b>anonymous hyperlink reference</b>. In an anonymous - hyperlink target, the reference text is not repeated. This is - useful for references with long text or throw-away references, but - the target should be kept close to the reference to prevent them - going out of sync. - - <h4><a href="#contents" name="implicit-hyperlink-targets" class="backref" - >Implicit Hyperlink Targets</a></h4> - - <p>(<a href="../../spec/rst/reStructuredText.html#implicit-hyperlink-targets">details</a>) - - <p>Section titles, footnotes, and citations automatically generate - hyperlink targets (the title text or footnote/citation label is - used as the hyperlink name). - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - - <tr valign="top"> - <td> - <samp>Titles are targets, too</samp> - <br><samp>=======================</samp> - <br><samp>Implict references, like `Titles are</samp> - <br><samp>targets, too`_.</samp> - <td> - <font size="+2"><strong><a name="title">Titles are targets, too</a></strong></font> - <p>Implict references, like <a href="#Title">Titles are - targets, too</a>. - </table> - - <h3><a href="#contents" name="directives" class="backref" - >Directives</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#directives">details</a>) - - <p>Directives are a general-purpose extension mechanism, a way of - adding support for new constructs without adding new syntax. For - a description of all standard directives, see <a - href="../../spec/rst/directives.html" >reStructuredText - Directives</a>. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp>For instance:</samp> - - <p><samp>.. image:: images/ball1.gif</samp> - - <td> - For instance: - <p><img src="images/ball1.gif" alt="ball1"> - </table> - - <h3><a href="#contents" name="substitution-references-and-definitions" - class="backref" >Substitution References and Definitions</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#substitution-definitions">details</a>) - - <p>Substitutions are like inline directives, allowing graphics and - arbitrary constructs within text. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="50%">Plain text - <th width="50%">Typical result - </thead> - <tbody> - <tr valign="top"> - <td><samp> -The |biohazard| symbol must be -used on containers used to -dispose of medical waste.</samp> - - <p><samp> -.. |biohazard| image:: biohazard.png</samp> - - <td> - - <p>The <img src="images/biohazard.png" align="bottom" alt="biohazard"> symbol - must be used on containers used to dispose of medical waste. - - </table> - - <h3><a href="#contents" name="comments" class="backref" - >Comments</a></h3> - - <p>(<a href="../../spec/rst/reStructuredText.html#comments">details</a>) - - <p>Any text which begins with an explicit markup start but doesn't - use the syntax of any of the constructs above, is a comment. - - <p><table border="1" width="100%" bgcolor="#ffffcc" cellpadding="3"> - <thead> - <tr align="left" bgcolor="#99CCFF"> - <th width="33%">Plain text - <th width="33%">Typical result - <th>Doc Py</th> - </thead> - <tbody> - <tr valign="top"> - <td><samp>.. This text will not be shown</samp> - <br><samp> (but, for instance, in HTML might be</samp> - <br><samp> rendered as an HTML comment)</samp> - - <td> - <!-- This text will not be shown --> - <!-- (but, for instance in HTML might be --> - <!-- rendered as an HTML comment) --> - -<td><pre> -% This text will not be shown -% (but, for instance, in HTML might be -% rendered as an HTML comment) -</pre></td> - <tr valign="top"> - <td> - <samp>An empty "comment" does not</samp> - <br><samp>"consume" following blocks.</samp> - <p><samp>..</samp> - <p><samp> So this block is not "lost",</samp> - <br><samp> despite its indentation.</samp> - <td> - An empty "comment" does not - "consume" following blocks. - <blockquote> - So this block is not "lost", - despite its indentation. - </blockquote> - </table> - - <h2><a href="#contents" name="getting-help" class="backref" - >Getting Help</a></h2> - - <p>Users who have questions or need assistance with Docutils or - reStructuredText should <a - href="mailto:docutils-users@lists.sourceforge.net" >post a - message</a> to the <a - href="http://lists.sourceforge.net/lists/listinfo/docutils-users" - >Docutils-Users mailing list</a>. The <a - href="http://docutils.sourceforge.net/" >Docutils project web - site</a> has more information. - - <p><hr> - <address> - <p>Authors: - <a href="http://www.tibsnjoan.co.uk/">Tibs</a> - (<a href="mailto:tony@lsl.co.uk"><tt>tony@lsl.co.uk</tt></a> or - <a href="mailto:tibs@tibsnjoan.co.uk"><tt>tibs@tibsnjoan.co.uk</tt></a>) - and David Goodger - (<a href="mailto:goodger@users.sourceforge.net">goodger@users.sourceforge.net</a>) - </address> - <!-- Created: Fri Aug 03 09:11:57 GMT Daylight Time 2001 --> - </body> -</html> diff --git a/sandbox/dkuhlman/docutils/docutils/writers/python_latex.py b/sandbox/dkuhlman/docutils/docutils/writers/python_latex.py deleted file mode 100644 index 62f4c0363..000000000 --- a/sandbox/dkuhlman/docutils/docutils/writers/python_latex.py +++ /dev/null @@ -1,1114 +0,0 @@ -#!/usr/bin/env python - -""" -:Author: Dave Kuhlman -:Contact: dkuhlman@rexx.com -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. - -LaTeX2e document tree Writer. -""" - -__docformat__ = 'reStructuredText' - -# convention deactivate code by two # e.g. ##. - -import sys -import time -import re -import string -import urllib, urlparse -from docutils import writers, nodes, languages - -## from IPython.Shell import IPShellEmbed -## args = '' -## ipshell = IPShellEmbed(args, -## banner = 'Dropping into IPython', -## exit_msg = 'Leaving Interpreter, back to program.') - - -# To turn off debug printing, set to 0. -DEBUG_FLAG = 1 - -# Constants and globals: - -COMMENT_RE_SUB = re.compile('\n').sub -PROGRAMOPT_RE = re.compile('(--[_\-a-zA-Z0-9]+)') -EMAILADDR_RE = re.compile(r'[_\-a-zA-Z0-9.]+@[_\-a-zA-Z0-9.]+') -WEBADDR_RE = re.compile(r'http://[_\-a-zA-Z0-9./~]+') - -TABLE_MODE_NONE = 0 -TABLE_MODE_HEAD = 1 -TABLE_MODE_BODY = 2 - -class TableSpec: - def __init__(self): - self.columnCount = 0 - self.mode = TABLE_MODE_NONE - def getColumnCount(self): return self.columnCount - def setColumnCount(self, columnCount): self.columnCount = columnCount - def getMode(self): return self.mode - def setMode(self, mode): self.mode = mode - - -class Writer(writers.Writer): - - supported = ('latex','latex2e') - """Formats this writer supports.""" - - settings_spec = ( - 'Documenting Python LaTeX Specific Options', - 'The LaTeX "--output-encoding" default is "latin-1:strict".', - (('Specify documentclass (one of howto, manual, module). Default is "howto".', -# (('Specify documentclass (one of howto, manual). Default is "howto".', - ['--documentclass'], - {'default': 'howto', }), - )) - - #settings_defaults = {} - settings_defaults = {'output_encoding': 'latin-1'} - - output = None - """Final translated form of `document`.""" - - def translate(self): - visitor = DocPyTranslator(self.document) - self.document.walkabout(visitor) - #import pdb - #pdb.run('self.document.walkabout(visitor)', globals(), locals()) - self.output = visitor.astext() - - -class DocPyTranslator(nodes.NodeVisitor): - latex_head = '\\documentclass{%s}\n' - # add a generated on day , machine by user using docutils version. - generator = '\n%% generator -- Docutils: http://docutils.sourceforge.net/\n' \ - '%% writer -- documenting_python\n' \ - '%% generated on -- %s\n\n' % time.ctime() - - def __init__(self, document): - nodes.NodeVisitor.__init__(self, document) - self.docinfo = {} - self.settings = settings = document.settings - if self.settings.documentclass == 'module': - raise NotImplementedError, 'Error: module document type not yet implemented.' - self.head_prefix = [ - self.latex_head % (self.settings.documentclass, ), - #self.encoding, - #self.linking % (self.colorlinks, self.hyperlink_color, self.hyperlink_color), - # geometry and fonts might go into style.tex. - #self.geometry % (self.d_paper, self.d_margins), - # - self.generator, - '\\usepackage{html}\n', - ] - - # NOTE: Latex wants a date and an author, rst puts this into - # docinfo, so normally we donot want latex author/date handling. - # latex article has its own handling of date and author, deactivate. - self.latex_docinfo = 0 - self.head = [ ] - self.body_prefix = [] - # separate title, so we can appen subtitle. - self.title = "" - self.body = [] - self.body_suffix = ['\n'] - self.section_level = 0 - self.context = [] - self.topic_class = '' - # Flags to encode - # --------------- - # verbatim: to tell encode not to encode. - self.verbatim = 0 - # insert_newline: to tell encode to replace blanks by "~". - self.insert_none_breaking_blanks = 0 - # insert_newline: to tell encode to add latex newline. - self.insert_newline = 0 - # mbox_newline: to tell encode to add mbox and newline. - self.mbox_newline = 0 - - # inside literal block: no quote mangling. - self.literal = 0 - self.seealso = 0 - self.title_before_section = 0 - self.seen_section = 0 - - def pdebug(self, msg): - if DEBUG_FLAG >= 1: - self.body.append(msg) - - def encode(self, text): - """ - Encode special characters in `text` & return. - # $ % & ~ _ ^ \ { } - Escaping with a backslash does not help with backslashes, ~ and ^. - - < > are only available in math-mode (really ?) - $ starts math- mode. - AND quotes: - - """ - if self.verbatim: - return text - # compile the regexps once. do it here so one can see them. - # - # first the braces. - if not self.__dict__.has_key('encode_re_braces'): - self.encode_re_braces = re.compile(r'([{}])') - text = self.encode_re_braces.sub(r'{\\\1}',text) - if not self.__dict__.has_key('encode_re_bslash'): - # find backslash: except in the form '{\{}' or '{\}}'. - self.encode_re_bslash = re.compile(r'(?<!{)(\\)(?![{}]})') - # then the backslash: except in the form from line above: - # either '{\{}' or '{\}}'. - text = self.encode_re_bslash.sub(r'{\\textbackslash}', text) - - # then dollar - text = text.replace("$", '{\\$}') - # then all that needs math mode - text = text.replace("<", '{$<$}') - text = text.replace(">", '{$>$}') - # then - text = text.replace("&", '{\\&}') - text = text.replace("_", '{\\_}') - # the ^: - # * verb|^| does not work in mbox. - # * mathmode has wedge. hat{~} would also work. - text = text.replace("^", '{\\ensuremath{^\\wedge}}') - text = text.replace("%", '{\\%}') - text = text.replace("#", '{\\#}') - text = text.replace("~", '{\\~{}}') - if self.insert_newline: - # HACK: insert a blank before the newline, to avoid - # ! LaTeX Error: There's no line here to end. - text = text.replace("\n", '~\\\\\n') - elif self.mbox_newline: - text = text.replace("\n", '}\\\\\n\\mbox{') - if self.insert_none_breaking_blanks: - text = text.replace(' ', '~') - # unicode !!! - text = text.replace(u'\u2020', '{$\\dagger$}') - return text - - def attval(self, text, - whitespace=re.compile('[\n\r\t\v\f]')): - """Cleanse, encode, and return attribute value text.""" - return self.encode(whitespace.sub(' ', text)) - - def replace_email_addr(self, mo): - addr = mo.group(0) - outtext = '\\ulink{%s}{mailto:%s}' % (addr, addr) - return outtext - - def replace_web_addr(self, mo): - addr = mo.group(0) - outtext = '\\ulink{%s}{%s}' % (addr, addr) - return outtext - - def linkify(self, intext): - # If it looks like an email address, convert it to a "mailto" URL. - text1 = EMAILADDR_RE.sub(self.replace_email_addr, intext) - # If it looks like a URL, convert it to a ulink. - text2 = WEBADDR_RE.sub(self.replace_web_addr, text1) - return text2 - - def astext(self): - title = '\\title{%s}\n' % self.title - if self.docinfo.has_key('revision'): - self.head.append('\\release{%s}\n' % self.docinfo['revision']) - if self.docinfo.has_key('date'): - self.head.append('\\date{%s}\n' % self.docinfo['date']) - if self.docinfo.has_key('author'): - self.head.append('\\author{%s}\n' % self.docinfo['author']) - if self.docinfo.has_key('address'): - self.pdebug('%% [(astext) text: %s]\n' % self.docinfo['address']) - self.head.append('\\authoraddress{%s}\n' % \ - #self.linkify(self.cleanHref(self.docinfo['address']))) - self.cleanHref(self.linkify( - self.docinfo['address'])).replace('\n', '\\\\\n')) - self.body_prefix.append('\\maketitle\n') - self.body_prefix.append('\\ifhtml\n') - self.body_prefix.append('\\chapter*{Front Matter\\label{front}}\n') - self.body_prefix.append('\\fi\n') - if self.docinfo.has_key('copyright'): - self.body_prefix.append('\n%s\n' % self.docinfo['copyright']) - if self.docinfo.has_key('abstract'): - self.body_prefix.append('\\begin{abstract}\n\\noindent\n') - self.body_prefix.append('%s\n' % self.docinfo['abstract']) - self.body_prefix.append('\\end{abstract}\n') - self.body_prefix.append('\\tableofcontents\n') - result = ''.join( - self.head_prefix + - [title] + - self.head + - self.body_prefix + - self.body + - self.body_suffix) - return result - - def visit_Text(self, node): - self.body.append(self.encode(node.astext())) - - def depart_Text(self, node): - pass - - def visit_address(self, node): - self.visit_docinfo_item(node, 'address') - raise nodes.SkipNode - - def depart_address(self, node): - self.depart_docinfo_item(node) - - def visit_admonition(self, node, name): - self.body.append('\\begin{center}\\begin{sffamily}\n') - self.body.append('\\fbox{\\parbox{\\admonitionwidth}{\n') - self.body.append('\\textbf{\\large '+ self.language.labels[name] + '}\n'); - self.body.append('\\vspace{2mm}\n') - - - def depart_admonition(self): - self.body.append('}}\n') # end parbox fbox - self.body.append('\\end{sffamily}\n\\end{center}\n'); - - def visit_attention(self, node): - self.visit_admonition(node, 'attention') - - def depart_attention(self, node): - self.depart_admonition() - - def visit_author(self, node): - #self.pdebug('%% [(visit_author) node: %s]\n' % str(node)) - self.visit_docinfo_item(node, 'author') - raise nodes.SkipNode - - def depart_author(self, node): - self.depart_docinfo_item(node) - - def visit_authors(self, node): - # ignore. visit_author is called for each one - # self.visit_docinfo_item(node, 'author') - pass - - def depart_authors(self, node): - # self.depart_docinfo_item(node) - pass - - def visit_block_quote(self, node): - # If the block quote contains a single object and that object - # is a list, then generate a list not a block quote. - # This lets us indent lists. - done = 0 - if len(node.children) == 1: - child = node.children[0] - if isinstance(child, nodes.bullet_list) or \ - isinstance(child, nodes.enumerated_list): - done = 1 - if not done: - self.body.append('\\begin{quote}\n') - - def depart_block_quote(self, node): - done = 0 - if len(node.children) == 1: - child = node.children[0] - if isinstance(child, nodes.bullet_list) or \ - isinstance(child, nodes.enumerated_list): - done = 1 - if not done: - self.body.append('\\end{quote}\n') - - def visit_bullet_list(self, node): - self.body.append('\\begin{itemize}\n' ) - - def depart_bullet_list(self, node): - self.body.append('\\end{itemize}\n' ) - - def visit_enumerated_list(self, node): - self.body.append('\\begin{enumerate}\n' ) - - def depart_enumerated_list(self, node): - self.body.append('\\end{enumerate}\n') - - def visit_caption(self, node): - self.body.append('\\caption{' ) - - def depart_caption(self, node): - self.body.append('}') - - def visit_caution(self, node): - self.visit_admonition(node, 'caution') - - def depart_caution(self, node): - self.depart_admonition() - - def visit_citation(self, node): - self.visit_footnote(node) - - def depart_citation(self, node): - self.depart_footnote(node) - - def visit_title_reference(self, node): - # BUG title-references are what? - pass - - def depart_title_reference(self, node): - pass - - def visit_citation_reference(self, node): - pass - - def depart_citation_reference(self, node): - pass - - def visit_classifier(self, node): - pass - - def depart_classifier(self, node): - pass - - def visit_colspec(self, node): - pass - - def depart_colspec(self, node): - pass - - def visit_comment(self, node): - """Escape end of line by a ne comment start in comment text.""" - self.body.append('\n%% %s \n' % COMMENT_RE_SUB('\n% ', node.astext())) - raise nodes.SkipNode - - def visit_contact(self, node): - self.visit_docinfo_item(node, 'contact') - - def depart_contact(self, node): - self.depart_docinfo_item(node) - - def visit_copyright(self, node): - self.visit_docinfo_item(node, 'copyright') - raise nodes.SkipNode - - def depart_copyright(self, node): - self.depart_docinfo_item(node) - - def visit_danger(self, node): - self.visit_admonition(node, 'danger') - - def depart_danger(self, node): - self.depart_admonition() - - def visit_date(self, node): - ## self.pdebug('%% [(visit_date) node: %s]\n' % str(node)) - self.visit_docinfo_item(node, 'date') - raise nodes.SkipNode - - def depart_date(self, node): - self.depart_docinfo_item(node) - - def visit_decoration(self, node): - pass - - def depart_decoration(self, node): - pass - - def visit_definition(self, node): - #self.body.append('% [(visit_definition)]\n') - pass - - def depart_definition(self, node): - self.body.append('\n') - #self.body.append('%[(depart_definition)]\n') - - def visit_definition_list(self, node): - self.body.append( '\n\\begin{description}\n' ) - - def depart_definition_list(self, node): - self.body.append( '\\end{description}\n' ) - - def visit_definition_list_item(self, node): - #self.body.append('%[(visit_definition_list_item)]\n') - pass - - def depart_definition_list_item(self, node): - #self.body.append('%[(depart_definition_list_item)]\n') - pass - - def visit_description(self, node): - self.body.append( ' ' ) - - def depart_description(self, node): - pass - - def visit_docinfo(self, node): - self.docinfo = {} - - def depart_docinfo(self, node): - pass - - def visit_docinfo_item(self, node, name): - self.docinfo[name] = node.astext() - - def depart_docinfo_item(self, node): - pass - - def visit_doctest_block(self, node): - self.body.append('\\begin{verbatim}\n' ) - self.verbatim = 1 - - def depart_doctest_block(self, node): - self.body.append( '\n\\end{verbatim}\n' ) - self.verbatim = 0 - - def visit_document(self, node): - self.body_prefix.append('\\begin{document}\n') - - def depart_document(self, node): - if self.seealso: - self.body.append('\\end{seealso}\n') - self.body_suffix.append('\\end{document}\n') - - def visit_emphasis(self, node): - self.body.append('\\emph{') - - def depart_emphasis(self, node): - self.body.append('}') - - def visit_error(self, node): - self.visit_admonition(node, 'error') - - def depart_error(self, node): - self.depart_admonition() - - def visit_field(self, node): - # real output is done in siblings: _argument, _body, _name - raise nodes.SkipNode - pass - - def depart_field(self, node): - self.body.append('\n') - ##self.body.append('%[depart_field]\n') - - def visit_field_argument(self, node): - #self.pdebug('%% [(visit_field_argument) node: %s]\n' % str(node)) - #self.pdebug('% [visit_field_argument]\n') - pass - - def depart_field_argument(self, node): - #self.pdebug('% [(depart_field_argument)]\n') - pass - - def visit_field_body(self, node): - #self.pdebug('%% [(visit_field_body) node: %s]\n' % str(node)) - # BUG by attach as text we loose references. -## if self.docinfo and self.current_field_name: -## self.docinfo[self.current_field_name] += '%s \\\\\n' % node.astext() -## raise nodes.SkipNode - pass - - def depart_field_body(self, node): -## self.body.append( '\n' ) - pass - - def visit_field_list(self, node): -## if not self.docinfo: -## self.body.append('\\begin{quote}\n') -## self.body.append('\\begin{description}\n') - pass - - def depart_field_list(self, node): -## if not self.docinfo: -## self.body.append('\\end{description}\n') -## self.body.append('\\end{quote}\n') - pass - - def visit_field_name(self, node): -## self.pdebug('%% [(visit_field_name) content: %s]\n' % node.astext()) -## self.pdebug('%% [(visit_field_name) node: %s\n' % str(node)) -## self.docinfo[node.astext()] = '' -## self.current_field_name = node.astext() - pass - - def depart_field_name(self, node): - pass - - def visit_figure(self, node): - self.body.append( '\\begin{figure}\n' ) - - def depart_figure(self, node): - self.body.append( '\\end{figure}\n' ) - - def visit_footer(self, node): - self.context.append(len(self.body)) - - def depart_footer(self, node): - start = self.context.pop() - footer = (['\n\\begin{center}\small\n'] - + self.body[start:] + ['\n\\end{center}\n']) - self.body_suffix[:0] = footer - del self.body[start:] - - def visit_footnote(self, node): - notename = node['id'] - self.body.append('\\begin{figure}[b]') - self.body.append('\\hypertarget{%s}' % notename) - - def depart_footnote(self, node): - self.body.append('\\end{figure}\n') - - def visit_footnote_reference(self, node): - href = '' - if node.has_key('refid'): - href = node['refid'] - elif node.has_key('refname'): - href = self.document.nameids[node['refname']] - format = self.settings.footnote_references - if format == 'brackets': - suffix = '[' - self.context.append(']') - elif format == 'superscript': - suffix = '\\raisebox{.5em}[0em]{\\scriptsize' - self.context.append('}') - else: # shouldn't happen - raise AssertionError('Illegal footnote reference format.') - self.body.append('%s\\hyperlink{%s}{' % (suffix,href)) - - def depart_footnote_reference(self, node): - self.body.append('}%s' % self.context.pop()) - - def visit_generated(self, node): - pass - - def depart_generated(self, node): - pass - - def visit_header(self, node): - self.body.append('%% [(visit_header) node: %s\n' % str(node)) - self.context.append(len(self.body)) - - def depart_header(self, node): - start = self.context.pop() - self.body_prefix.append('\n\\verb|begin_header|\n') - self.body_prefix.extend(self.body[start:]) - self.body_prefix.append('\n\\verb|end_header|\n') - del self.body[start:] - - def visit_hint(self, node): - self.visit_admonition(node, 'hint') - - def depart_hint(self, node): - self.depart_admonition() - - def visit_image(self, node): - atts = node.attributes.copy() - href = atts['uri'] - ##self.body.append('\\begin{center}\n') - self.body.append('\n\\includegraphics{%s}\n' % href) - ##self.body.append('\\end{center}\n') - - def depart_image(self, node): - pass - - def visit_important(self, node): - self.visit_admonition(node, 'important') - - def depart_important(self, node): - self.depart_admonition() - - def visit_interpreted(self, node): - # @@@ Incomplete, pending a proper implementation on the - # Parser/Reader end. - self.visit_literal(node) - - def depart_interpreted(self, node): - self.depart_literal(node) - - def visit_label(self, node): - # footnote/citation label - self.body.append('[') - - def depart_label(self, node): - self.body.append(']') - - def visit_legend(self, node): - self.body.append('{\\small ') - - def depart_legend(self, node): - self.body.append('}') - - def visit_line_block(self, node): - """line-block: - * whitespace (including linebreaks) is significant - * inline markup is supported. - * serif typeface - """ - self.body.append('\\begin{flushleft}\n') - self.insert_none_breaking_blanks = 1 - self.line_block_without_mbox = 1 - if self.line_block_without_mbox: - self.insert_newline = 1 - else: - self.mbox_newline = 1 - self.body.append('\\mbox{') - - def depart_line_block(self, node): - if self.line_block_without_mbox: - self.insert_newline = 0 - else: - self.body.append('}') - self.mbox_newline = 0 - self.insert_none_breaking_blanks = 0 - self.body.append('\n\\end{flushleft}\n') - - def visit_list_item(self, node): - self.body.append('\\item ') - - def depart_list_item(self, node): - self.body.append('\n') - - def visit_literal(self, node): - ## self.literal = 1 - content = node.astext().strip() - if re.search('[ \t\n]', content): - self.body.append('\\samp{%s}' % content) - else: - self.body.append('\\code{%s}' % content) - raise nodes.SkipNode - - def depart_literal(self, node): - pass - - def visit_literal_block(self, node): - self.verbatim = 1 - self.body.append('\n\\begin{verbatim}\n') - - def depart_literal_block(self, node): - self.body.append('\n\\end{verbatim}\n') - self.verbatim = 0 - - def visit_meta(self, node): - self.body.append('[visit_meta]\n') - - def depart_meta(self, node): - self.body.append('[depart_meta]\n') - - def visit_note(self, node): - self.visit_admonition(node, 'note') - - def depart_note(self, node): - self.depart_admonition() - - - def visit_option(self, node): - if self.context[-1]: - # this is not the first option - self.body.append(', ') - - def depart_option(self, node): - # flag tha the first option is done. - self.context[-1] += 1 - - def visit_option_argument(self, node): - """The delimiter betweeen an option and its argument.""" - self.body.append(node.get('delimiter', ' ')) - - def depart_option_argument(self, node): - pass - - def visit_option_group(self, node): - self.body.append('\\item [') - self.context.append(0) - - def depart_option_group(self, node): - self.context.pop() # the flag - self.body.append('] ') - - def visit_option_list(self, node): - self.body.append('\\begin{description}\n') - - def depart_option_list(self, node): - self.body.append('\\end{description}\n') - - def visit_option_list_item(self, node): - pass - - def depart_option_list_item(self, node): - pass - - def re_repl_long(self, mo): - result = '\\longprogramopt{%s}' % mo.group(0)[2:] - return result - - def visit_option_string(self, node): - content = node.astext() - content = re.sub(PROGRAMOPT_RE, self.re_repl_long, content) - self.body.append(content) - raise nodes.SkipNode - - def depart_option_string(self, node): - pass - - - def visit_organization(self, node): - self.visit_docinfo_item(node, 'organization') - - def depart_organization(self, node): - self.depart_docinfo_item(node) - - def visit_paragraph(self, node): - if not self.topic_class == 'contents': - self.body.append('\n') - - def depart_paragraph(self, node): - self.body.append('\n') - - def visit_problematic(self, node): - self.body.append('{\\color{red}\\bfseries{}') - - def depart_problematic(self, node): - self.body.append('}') - - def visit_raw(self, node): - if node.has_key('format') and node['format'].lower() == 'latex': - self.body.append(node.astext()) - raise nodes.SkipNode - - def cleanHref(self, href): - href = href.replace('~', '\\~{}') - href = href.replace('#', '\\#{}') - return href - -## def visit_reference(self, node): -## self.pdebug('%% [(visit_reference) node: %s]\n' % str(node)) -## if node.has_key('refuri'): -## self.href = node['refuri'] -## elif node.has_key('refid'): -## self.href = '#' + node['refid'] -## elif node.has_key('refname'): -## self.href = '#' + self.document.nameids[node['refname']] -## self.href = self.cleanHref(self.href) -## if self.seealso: -## self.body.append('\\seeurl{%s}{' % self.href) -## else: -## self.body.append('\\ulink{') -## -## def depart_reference(self, node): -## if self.seealso: -## self.body.append('}') -## else: -## self.body.append('}{%s}' % self.href) - - def visit_reference(self, node): - #self.pdebug('%% [(visit_reference) node: %s]\n' % str(node)) - if self.seealso: - if node.has_key('refuri'): - href = node['refuri'] - href = self.cleanHref(href) - self.body.append('\\seeurl{%s}{' % href) - else: - if node.has_key('refuri'): - # External hyperlink - self.body.append('\\ulink{') - elif node.has_key('refid'): - # Internal hyperlink - href = node['refid'] - href = self.cleanHref(href) - self.body.append('\\ref{%s}' % href) - raise nodes.SkipNode - - def depart_reference(self, node): - if self.seealso: - self.body.append('}') - else: - if node.has_key('refuri'): - # External hyperlink - href = node['refuri'] - href = self.cleanHref(href) - self.body.append('}{%s}' % href) - elif node.has_key('refid'): - # Internal hyperlink - pass - - def visit_revision(self, node): - ## self.pdebug('%% [(visit_revision) node: "%s"]\n' % str(node)) - self.visit_docinfo_item(node, 'revision') - raise nodes.SkipNode - - def depart_revision(self, node): - self.depart_docinfo_item(node) - - def visit_section(self, node): - # If the document title came before the first (outer-most) - # section, then the first section is really the first section. - # If the document title is *in* the first section, then - # the first section is a container that has the document title. - # So, if the document title came before the first section, - # then alwasy increment the section_level. - # But, if the document title is *in* the first section, then - # increment the section_level only on the *second* and - # subsequent sections. - ## self.pdebug('%% [(visit_section) node: %s]\n' % repr(node)) - if self.title_before_section or self.seen_section: - self.section_level += 1 - self.seen_section = 1 - - def depart_section(self, node): - ## self.pdebug('%% [(depart_section) node: %s]\n' % repr(node)) - if self.title_before_section: - self.section_level -= 1 - - def visit_sidebar(self, node): - # BUG: this is just a hack to make sidebars render something - self.body.append('\\begin{center}\\begin{sffamily}\n') - self.body.append('\\fbox{\\colorbox[gray]{0.80}{\\parbox{\\admonitionwidth}{\n') - - def depart_sidebar(self, node): - self.body.append('}}}\n') # end parbox colorbox fbox - self.body.append('\\end{sffamily}\n\\end{center}\n'); - - - attribution_formats = {'dash': ('---', ''), - 'parentheses': ('(', ')'), - 'parens': ('(', ')'), - 'none': ('', '')} - - def visit_attribution(self, node): - prefix, suffix = self.attribution_formats[self.settings.attribution] - self.body.append('\n\\begin{flushright}\n') - self.body.append(prefix) - self.context.append(suffix) - - def depart_attribution(self, node): - self.body.append(self.context.pop() + '\n') - self.body.append('\\end{flushright}\n') - - def visit_status(self, node): - self.visit_docinfo_item(node, 'status') - - def depart_status(self, node): - self.depart_docinfo_item(node) - - def visit_strong(self, node): - self.body.append('\\strong{') - - def depart_strong(self, node): - self.body.append('}') - - def visit_substitution_definition(self, node): - raise nodes.SkipNode - - def visit_substitution_reference(self, node): - self.unimplemented_visit(node) - - def visit_subtitle(self, node): - self.title = self.title + \ - '\\\\\n\\large{%s}\n' % self.encode(node.astext()) - raise nodes.SkipNode - - def depart_subtitle(self, node): - pass - - def visit_system_message(self, node): - if node['level'] < self.document.reporter['writer'].report_level: - raise nodes.SkipNode - - - def depart_system_message(self, node): - self.body.append('\n') - - def visit_target(self, node): - #self.pdebug('%% [(visit_target) node: %s]\n' % str(node)) - pass -## if not (node.has_key('refuri') or node.has_key('refid') -## or node.has_key('refname')): -## self.body.append('\\hypertarget{%s}{' % node['name']) -## self.context.append('}') -## else: -## self.context.append('') - - def depart_target(self, node): - pass -## self.body.append(self.context.pop()) - - def visit_table(self, node): - self.tableSpec = TableSpec() - - def depart_table(self, node): - self.tablSpec = None - - def visit_tgroup(self, node): - columnCount = int(node.get('cols', 0)) - self.tableSpec.setColumnCount(columnCount) - if columnCount == 2: - self.body.append('\\begin{tableii}{l|l}{textrm}') - elif columnCount == 3: - self.body.append('\\begin{tableiii}{l|l|l}{textrm}') - elif columnCount == 4: - self.body.append('\\begin{tableiv}{l|l|l|l}{textrm}') - elif columnCount == 5: - self.body.append('\\begin{tablev}{l|l|l|l|l}{textrm}') - - def depart_tgroup(self, node): - if self.tableSpec.getColumnCount() == 2: - self.body.append('\n\\end{tableii}\n') - elif self.tableSpec.getColumnCount() == 3: - self.body.append('\n\\end{tableiii}\n') - elif self.tableSpec.getColumnCount() == 4: - self.body.append('\n\\end{tableiv}\n') - elif self.tableSpec.getColumnCount() == 5: - self.body.append('\n\\end{tablev}\n') - - def visit_thead(self, node): - self.tableSpec.setMode(TABLE_MODE_HEAD) - - def depart_thead(self, node): - self.tableSpec.setMode(TABLE_MODE_NONE) - - def visit_tbody(self, node): - self.tableSpec.setMode(TABLE_MODE_BODY) - - def depart_tbody(self, node): - self.tableSpec.setMode(TABLE_MODE_NONE) - - def visit_row(self, node): - if self.tableSpec.getMode() == TABLE_MODE_HEAD: - pass - elif self.tableSpec.getMode() == TABLE_MODE_BODY: - if self.tableSpec.getColumnCount() == 2: - self.body.append('\n\\lineii') - elif self.tableSpec.getColumnCount() == 3: - self.body.append('\n\\lineiii') - elif self.tableSpec.getColumnCount() == 4: - self.body.append('\n\\lineiv') - elif self.tableSpec.getColumnCount() == 5: - self.body.append('\n\\linev') - - def depart_row(self, node): - if self.tableSpec.getMode() == TABLE_MODE_HEAD: - pass - elif self.tableSpec.getMode() == TABLE_MODE_BODY: - pass - - def visit_entry(self, node): - if self.tableSpec.getMode() == TABLE_MODE_HEAD: - #self.body.append('%% [(visit_entry) text: +%s+]' % node.astext()) - self.body.append('{%s}' % node.astext().strip(' ')) - raise nodes.SkipNode - elif self.tableSpec.getMode() == TABLE_MODE_BODY: - #self.body.append('%% [(visit_entry) text: +%s+]' % node.astext()) - self.body.append('{%s}' % node.astext().strip(' ')) - raise nodes.SkipNode - - def depart_entry(self, node): - pass -## if self.tableSpec.getMode() == TABLE_MODE_HEAD: -## self.body.append('}') -## elif self.tableSpec.getMode() == TABLE_MODE_BODY: -## self.body.append('}') - - def visit_term(self, node): - self.body.append('\\item[') - - def depart_term(self, node): - # definition list term. - self.body.append(':]\n') - - def visit_tip(self, node): - self.visit_admonition(node, 'tip') - - def depart_tip(self, node): - self.depart_admonition() - -## def string_to_label(self, text): -## text = text.replace(' ', '-') -## text = text.replace('_', '-') -## return text - - def visit_title(self, node): - #self.pdebug('%% [(visit_title) section_level: %d node.astext: "%s"]\n' % \ - # (self.section_level, node.astext())) - #self.pdebug('%% [(visit_title) section_level: %d node.astext.encode: "%s"]\n' % \ - # (self.section_level, self.encode(node.astext()))) - if self.section_level == 0: - self.title_before_section = 1 - if self.seealso: - self.body.append('\\end{seealso}\n') - self.seealso = 0 - if node.astext().lower() == 'see also': - self.body.append('\\begin{seealso}\n') - self.seealso = 1 - raise nodes.SkipNode - else: - if self.section_level == 0: - # It's the document title before any section. - self.title = self.encode(node.astext()) - else: - # It's a title for a section in-side the document. - self.body.append('\n\n') - self.body.append('%' + '_' * 75) - self.body.append('\n\n') - s1 = self.encode(node.astext()) - # Remove the non-breaking space character. - # Not needed. Using output-encoding=latin-1 fixes this. - #s1 = s1.replace(u'\xa0', ' ') - s2 = nodes.make_id(node.astext()) - - #ipshell('(visit_title) Entering ipshell.\nHit Ctrl-D to exit ipshell.') - - if (self.section_level == 1): - self.body.append('\\section{%s\\label{%s}}\n' % (s1, s2)) - #self.body.append( - # '\\section{\htmladdnormallink[%s]{%s}{}}\n' % \ - # (s2, s1)) - elif (self.section_level == 2): - self.body.append('\\subsection{%s\\label{%s}}\n' % (s1, s2)) - elif (self.section_level == 3): - self.body.append('\\subsubsection{%s\\label{%s}}\n' % (s1, s2)) - elif (self.section_level == 4): - self.body.append('\\paragraph{%s\\label{%s}}\n' % (s1, s2)) - else: - self.body.append('\\subparagraph{%s\\label{%s}}\n' % (s1, s2)) - raise nodes.SkipNode - - def depart_title(self, node): - pass - - def visit_topic(self, node): - topic_class = node.get('class') - if topic_class == 'abstract': - self.docinfo['abstract'] = node.astext()[9:] - raise nodes.SkipNode - else: - raise nodes.SkipNode - - def depart_topic(self, node): - pass - - def visit_rubric(self, node): - self.body.append('% [(visit_rubric)]\n') - - def depart_rubric(self, node): - self.body.append('% [(depart_rubric)]\n') - - def visit_transition(self, node): - self.body.append('\n\n') - self.body.append('%' + '_' * 75) - self.body.append('\n\\hrule{}\n\n') - - def depart_transition(self, node): - pass - - def visit_version(self, node): - self.visit_docinfo_item(node, 'version') - - def depart_version(self, node): - self.depart_docinfo_item(node) - - def visit_warning(self, node): - self.visit_admonition(node, 'warning') - - def depart_warning(self, node): - self.depart_admonition() - - def unimplemented_visit(self, node): - raise NotImplementedError('visiting unimplemented node type: %s' - % node.__class__.__name__) - diff --git a/sandbox/dkuhlman/docutils/test/DocutilsTestSupport.py b/sandbox/dkuhlman/docutils/test/DocutilsTestSupport.py deleted file mode 100644 index e40300984..000000000 --- a/sandbox/dkuhlman/docutils/test/DocutilsTestSupport.py +++ /dev/null @@ -1,698 +0,0 @@ -# Authors: David Goodger; Garth Kidd -# Contact: goodger@users.sourceforge.net -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Exports the following: - -:Modules: - - `statemachine` is 'docutils.statemachine' - - `nodes` is 'docutils.nodes' - - `urischemes` is 'docutils.urischemes' - - `utils` is 'docutils.utils' - - `transforms` is 'docutils.transforms' - - `states` is 'docutils.parsers.rst.states' - - `tableparser` is 'docutils.parsers.rst.tableparser' - -:Classes: - - `CustomTestSuite` - - `CustomTestCase` - - `TransformTestSuite` - - `TransformTestCase` - - `ParserTestSuite` - - `ParserTestCase` - - `PEPParserTestSuite` - - `PEPParserTestCase` - - `GridTableParserTestSuite` - - `GridTableParserTestCase` - - `SimpleTableParserTestSuite` - - `SimpleTableParserTestCase` - - 'LatexPublishTestSuite' - - 'LatexPublishTestCase' - - 'PythonLatexPublishTestSuite' - - 'PythonLatexPublishTestCase' - - `DevNull` (output sink) -""" -__docformat__ = 'reStructuredText' - -import sys -import os -import unittest -import difflib -import inspect -from pprint import pformat -from types import UnicodeType -import package_unittest -import docutils -import docutils.core -from docutils import frontend, nodes, statemachine, urischemes, utils -from docutils.transforms import universal -from docutils.parsers import rst -from docutils.parsers.rst import states, tableparser, directives, languages -from docutils.readers import standalone, pep, python -from docutils.statemachine import StringList, string2lines - -try: - from docutils.readers.python import moduleparser -except: - moduleparser = None - -try: - import mypdb as pdb -except: - import pdb - - -# Hack to make repr(StringList) look like repr(list): -StringList.__repr__ = StringList.__str__ - - -class DevNull: - - """Output sink.""" - - def write(self, string): - pass - - -class CustomTestSuite(unittest.TestSuite): - - """ - A collection of custom TestCases. - - """ - - id = '' - """Identifier for the TestSuite. Prepended to the - TestCase identifiers to make identification easier.""" - - next_test_case_id = 0 - """The next identifier to use for non-identified test cases.""" - - def __init__(self, tests=(), id=None): - """ - Initialize the CustomTestSuite. - - Arguments: - - id -- identifier for the suite, prepended to test cases. - """ - unittest.TestSuite.__init__(self, tests) - if id is None: - mypath = os.path.abspath( - sys.modules[CustomTestSuite.__module__].__file__) - outerframes = inspect.getouterframes(inspect.currentframe()) - for outerframe in outerframes[1:]: - if outerframe[3] != '__init__': - callerpath = outerframe[1] - if callerpath is None: - # It happens sometimes. Why is a mystery. - callerpath = os.getcwd() - callerpath = os.path.abspath(callerpath) - break - mydir, myname = os.path.split(mypath) - if not mydir: - mydir = os.curdir - if callerpath.startswith(mydir): - self.id = callerpath[len(mydir) + 1:] # caller's module - else: - self.id = callerpath - else: - self.id = id - - def addTestCase(self, test_case_class, method_name, input, expected, - id=None, run_in_debugger=0, short_description=None, - **kwargs): - """ - Create a custom TestCase in the CustomTestSuite. - Also return it, just in case. - - Arguments: - - test_case_class -- - method_name -- - input -- input to the parser. - expected -- expected output from the parser. - id -- unique test identifier, used by the test framework. - run_in_debugger -- if true, run this test under the pdb debugger. - short_description -- override to default test description. - """ - if id is None: # generate id if required - id = self.next_test_case_id - self.next_test_case_id += 1 - # test identifier will become suiteid.testid - tcid = '%s: %s' % (self.id, id) - # generate and add test case - tc = test_case_class(method_name, input, expected, tcid, - run_in_debugger=run_in_debugger, - short_description=short_description, - **kwargs) - self.addTest(tc) - return tc - - -class CustomTestCase(unittest.TestCase): - - compare = difflib.Differ().compare - """Comparison method shared by all subclasses.""" - - def __init__(self, method_name, input, expected, id, - run_in_debugger=0, short_description=None): - """ - Initialise the CustomTestCase. - - Arguments: - - method_name -- name of test method to run. - input -- input to the parser. - expected -- expected output from the parser. - id -- unique test identifier, used by the test framework. - run_in_debugger -- if true, run this test under the pdb debugger. - short_description -- override to default test description. - """ - self.id = id - self.input = input - self.expected = expected - self.run_in_debugger = run_in_debugger - # Ring your mother. - unittest.TestCase.__init__(self, method_name) - - def __str__(self): - """ - Return string conversion. Overridden to give test id, in addition to - method name. - """ - return '%s; %s' % (self.id, unittest.TestCase.__str__(self)) - - def __repr__(self): - return "<%s %s>" % (self.id, unittest.TestCase.__repr__(self)) - - def compare_output(self, input, output, expected): - """`input`, `output`, and `expected` should all be strings.""" - if type(input) == UnicodeType: - input = input.encode('raw_unicode_escape') - if type(output) == UnicodeType: - output = output.encode('raw_unicode_escape') - if type(expected) == UnicodeType: - expected = expected.encode('raw_unicode_escape') - try: - self.assertEquals('\n' + output, '\n' + expected) - except AssertionError: - print >>sys.stderr, '\n%s\ninput:' % (self,) - print >>sys.stderr, input - print >>sys.stderr, '-: expected\n+: output' - print >>sys.stderr, ''.join(self.compare(expected.splitlines(1), - output.splitlines(1))) - raise - - def skip_test(self): - print >>sys.stderr, '%s: Test skipped' % self - - -class TransformTestSuite(CustomTestSuite): - - """ - A collection of TransformTestCases. - - A TransformTestSuite instance manufactures TransformTestCases, - keeps track of them, and provides a shared test fixture (a-la - setUp and tearDown). - """ - - def __init__(self, parser): - self.parser = parser - """Parser shared by all test cases.""" - - CustomTestSuite.__init__(self) - - def generateTests(self, dict, dictname='totest', - testmethod='test_transforms'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type's name) maps to a list of transform - classes and list of tests. Each test is a list: input, expected - output, optional modifier. The optional third entry, a behavior - modifier, can be 0 (temporarily disable this test) or 1 (run this test - under the pdb debugger). Tests should be self-documenting and not - require external comments. - """ - for name, (transforms, cases) in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - TransformTestCase, testmethod, - transforms=transforms, parser=self.parser, - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class TransformTestCase(CustomTestCase): - - """ - Output checker for the transform. - - Should probably be called TransformOutputChecker, but I can deal with - that later when/if someone comes up with a category of transform test - cases that have nothing to do with the input and output of the transform. - """ - - option_parser = frontend.OptionParser(components=(rst.Parser,)) - settings = option_parser.get_default_values() - settings.report_level = 1 - settings.halt_level = 5 - settings.debug = package_unittest.debug - settings.warning_stream = DevNull() - - def __init__(self, *args, **kwargs): - self.transforms = kwargs['transforms'] - """List of transforms to perform for this test case.""" - - self.parser = kwargs['parser'] - """Input parser for this test case.""" - - del kwargs['transforms'], kwargs['parser'] # only wanted here - CustomTestCase.__init__(self, *args, **kwargs) - - def supports(self, format): - return 1 - - def test_transforms(self): - if self.run_in_debugger: - pdb.set_trace() - document = utils.new_document('test data', self.settings) - self.parser.parse(self.input, document) - # Don't do a ``populate_from_components()`` because that would - # enable the Transformer's default transforms. - document.transformer.add_transforms(self.transforms) - document.transformer.add_transform(universal.TestMessages) - document.transformer.components['writer'] = self - document.transformer.apply_transforms() - output = document.pformat() - self.compare_output(self.input, output, self.expected) - - def test_transforms_verbosely(self): - if self.run_in_debugger: - pdb.set_trace() - print '\n', self.id - print '-' * 70 - print self.input - document = utils.new_document('test data', self.settings) - self.parser.parse(self.input, document) - print '-' * 70 - print document.pformat() - for transformClass in self.transforms: - transformClass(document).apply() - output = document.pformat() - print '-' * 70 - print output - self.compare_output(self.input, output, self.expected) - - -class ParserTestCase(CustomTestCase): - - """ - Output checker for the parser. - - Should probably be called ParserOutputChecker, but I can deal with - that later when/if someone comes up with a category of parser test - cases that have nothing to do with the input and output of the parser. - """ - - parser = rst.Parser() - """Parser shared by all ParserTestCases.""" - - option_parser = frontend.OptionParser(components=(parser,)) - settings = option_parser.get_default_values() - settings.report_level = 5 - settings.halt_level = 5 - settings.debug = package_unittest.debug - - def test_parser(self): - if self.run_in_debugger: - pdb.set_trace() - document = utils.new_document('test data', self.settings) - self.parser.parse(self.input, document) - output = document.pformat() - self.compare_output(self.input, output, self.expected) - - -class ParserTestSuite(CustomTestSuite): - - """ - A collection of ParserTestCases. - - A ParserTestSuite instance manufactures ParserTestCases, - keeps track of them, and provides a shared test fixture (a-la - setUp and tearDown). - """ - - test_case_class = ParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: input, expected output, optional modifier. The - optional third entry, a behavior modifier, can be 0 (temporarily - disable this test) or 1 (run this test under the pdb debugger). Tests - should be self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - self.test_case_class, 'test_parser', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class PEPParserTestCase(ParserTestCase): - - """PEP-specific parser test case.""" - - parser = rst.Parser(rfc2822=1, inliner=pep.Inliner()) - """Parser shared by all PEPParserTestCases.""" - - option_parser = frontend.OptionParser(components=(parser, pep.Reader)) - settings = option_parser.get_default_values() - settings.report_level = 5 - settings.halt_level = 5 - settings.debug = package_unittest.debug - - -class PEPParserTestSuite(ParserTestSuite): - - """A collection of PEPParserTestCases.""" - - test_case_class = PEPParserTestCase - - -class GridTableParserTestCase(CustomTestCase): - - parser = tableparser.GridTableParser() - - def test_parse_table(self): - self.parser.setup(StringList(string2lines(self.input), 'test data')) - try: - self.parser.find_head_body_sep() - self.parser.parse_table() - output = self.parser.cells - except Exception, details: - output = '%s: %s' % (details.__class__.__name__, details) - self.compare_output(self.input, pformat(output) + '\n', - pformat(self.expected) + '\n') - - def test_parse(self): - try: - output = self.parser.parse(StringList(string2lines(self.input), - 'test data')) - except Exception, details: - output = '%s: %s' % (details.__class__.__name__, details) - self.compare_output(self.input, pformat(output) + '\n', - pformat(self.expected) + '\n') - - -class GridTableParserTestSuite(CustomTestSuite): - - """ - A collection of GridTableParserTestCases. - - A GridTableParserTestSuite instance manufactures GridTableParserTestCases, - keeps track of them, and provides a shared test fixture (a-la setUp and - tearDown). - """ - - test_case_class = GridTableParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: an input table, expected output from parse_table(), - expected output from parse(), optional modifier. The optional fourth - entry, a behavior modifier, can be 0 (temporarily disable this test) - or 1 (run this test under the pdb debugger). Tests should be - self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case) == 4: - if case[-1]: - run_in_debugger = 1 - else: - continue - self.addTestCase(self.test_case_class, 'test_parse_table', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - self.addTestCase(self.test_case_class, 'test_parse', - input=case[0], expected=case[2], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class SimpleTableParserTestCase(GridTableParserTestCase): - - parser = tableparser.SimpleTableParser() - - -class SimpleTableParserTestSuite(CustomTestSuite): - - """ - A collection of SimpleTableParserTestCases. - """ - - test_case_class = SimpleTableParserTestCase - - def generateTests(self, dict, dictname='totest'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type name) maps to a list of tests. Each - test is a list: an input table, expected output from parse(), optional - modifier. The optional third entry, a behavior modifier, can be 0 - (temporarily disable this test) or 1 (run this test under the pdb - debugger). Tests should be self-documenting and not require external - comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case) == 3: - if case[-1]: - run_in_debugger = 1 - else: - continue - self.addTestCase(self.test_case_class, 'test_parse', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class PythonModuleParserTestCase(CustomTestCase): - - def test_parser(self): - if self.run_in_debugger: - pdb.set_trace() - module = moduleparser.parse_module(self.input, 'test data') - output = str(module) - self.compare_output(self.input, output, self.expected) - - def test_token_parser_rhs(self): - if self.run_in_debugger: - pdb.set_trace() - tr = moduleparser.TokenParser(self.input) - output = tr.rhs(1) - self.compare_output(self.input, output, self.expected) - - -class PythonModuleParserTestSuite(CustomTestSuite): - - """ - A collection of PythonModuleParserTestCase. - """ - - if moduleparser is None: - PythonModuleParserTestCase.test_parser = CustomTestCase.skip_test - PythonModuleParserTestCase.test_token_parser_rhs = \ - CustomTestCase.skip_test - - def generateTests(self, dict, dictname='totest', - testmethod='test_parser'): - """ - Stock the suite with test cases generated from a test data dictionary. - - Each dictionary key (test type's name) maps to a list of tests. Each - test is a list: input, expected output, optional modifier. The - optional third entry, a behavior modifier, can be 0 (temporarily - disable this test) or 1 (run this test under the pdb debugger). Tests - should be self-documenting and not require external comments. - """ - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - PythonModuleParserTestCase, testmethod, - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -# @@@ These should be generalized to WriterPublishTestCase/Suite or -# just PublishTestCase/Suite, as per TransformTestCase/Suite. -class LatexPublishTestCase(CustomTestCase, docutils.SettingsSpec): - - """ - Test case for publish. - """ - - settings_default_overrides = {'_disable_config': 1} - - def test_publish(self): - if self.run_in_debugger: - pdb.set_trace() - output = docutils.core.publish_string( - source=self.input, - reader_name='standalone', - parser_name='restructuredtext', - writer_name='latex', - settings_spec=self) - self.compare_output(self.input, output, self.expected) - - -class LatexPublishTestSuite(CustomTestSuite): - - def __init__(self): - CustomTestSuite.__init__(self) - - def generateTests(self, dict, dictname='totest'): - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - LatexPublishTestCase, 'test_publish', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -class PythonLatexPublishTestCase(CustomTestCase, docutils.SettingsSpec): - - """ - Test case for publish. - """ - - settings_default_overrides = {'_disable_config': 1} - - def test_publish(self): - if self.run_in_debugger: - pdb.set_trace() - output = docutils.core.publish_string( - source=self.input, - reader_name='standalone', - parser_name='restructuredtext', - writer_name='python_latex', - settings_spec=self) - self.compare_output(self.input, output, self.expected) - - def compare_output(self, input, output, expected): - """`input`, `output`, and `expected` should all be strings.""" - if type(input) == UnicodeType: - input = input.encode('raw_unicode_escape') - if type(output) == UnicodeType: - output = output.encode('raw_unicode_escape') - if type(expected) == UnicodeType: - expected = expected.encode('raw_unicode_escape') - # Remove "generated on" lines. - output = self.remove_lines(output, ('generated on --',)) - expected = self.remove_lines(expected, ('generated on --',)) - try: - self.assertEquals('\n' + output, '\n' + expected) - except AssertionError: - print >>sys.stderr, '\n%s\ninput:' % (self,) - print >>sys.stderr, input - print >>sys.stderr, '-: expected\n+: output' - print >>sys.stderr, ''.join(self.compare(expected.splitlines(1), - output.splitlines(1))) - raise - - def remove_lines(self, inStr, targetList): - inLines = inStr.splitlines() - outLines = [] - for line in inLines: - remove = False - for target in targetList: - if line.find(target) > -1: - remove = True - break - if not remove: - outLines.append(line) - outStr = '\n'.join(outLines) - return outStr - -class PythonLatexPublishTestSuite(CustomTestSuite): - - def __init__(self): - CustomTestSuite.__init__(self) - - def generateTests(self, dict, dictname='totest'): - for name, cases in dict.items(): - for casenum in range(len(cases)): - case = cases[casenum] - run_in_debugger = 0 - if len(case)==3: - if case[2]: - run_in_debugger = 1 - else: - continue - self.addTestCase( - PythonLatexPublishTestCase, 'test_publish', - input=case[0], expected=case[1], - id='%s[%r][%s]' % (dictname, name, casenum), - run_in_debugger=run_in_debugger) - - -def exception_data(code): - """ - Execute `code` and return the resulting exception, the exception arguments, - and the formatted exception string. - """ - try: - exec(code) - except Exception, detail: - return (detail, detail.args, - '%s: %s' % (detail.__class__.__name__, detail)) diff --git a/sandbox/dkuhlman/docutils/test/README.test_python_latex b/sandbox/dkuhlman/docutils/test/README.test_python_latex deleted file mode 100644 index a8321744e..000000000 --- a/sandbox/dkuhlman/docutils/test/README.test_python_latex +++ /dev/null @@ -1,36 +0,0 @@ - -============================================= -Notes on Unit Test Additions for Python LaTeX -============================================= - - -DocutilsTestSupport.py -====================== - -Added two classes (PythonLatexPublishTestCase and -PythonLatexPublishTestSuite) that drive the tests. These classes -were modelled on classes LatexPublishTestCase and -LatexPublishTestSuite respectively. - -Note that class PythonLatexPublishTestCase overrides method -compare_output and adds method remove_lines. These methods remove -the "generated on" lines from both input and output because the -date will always differ. - -See file DocutilsTestSupport.patch - - -test_writers/test_python_latex.py -================================= - -Contains the tests. - - -test_writers/Data/* -=================== - -Contains reST source documents (*.txt) and generated LaTeX -documents (*.tex) that were used in the input and output strings -in test_python_latex.py. - - diff --git a/sandbox/dkuhlman/docutils/test/test_writers/test_python_latex.py b/sandbox/dkuhlman/docutils/test/test_writers/test_python_latex.py deleted file mode 100644 index 7aa5528ce..000000000 --- a/sandbox/dkuhlman/docutils/test/test_writers/test_python_latex.py +++ /dev/null @@ -1,490 +0,0 @@ -#! /usr/bin/env python - -# Author: Dave Kuhlman -# Contact: dkuhlman@rexx.com -# Revision: $Revision$ -# Date: $Date$ -# Copyright: This module has been placed in the public domain. - -""" -Tests for python_latex writer. -""" - -from __init__ import DocutilsTestSupport - -def suite(): - s = DocutilsTestSupport.PythonLatexPublishTestSuite() - s.generateTests(totest) - return s - - -rest_head = """\ - -========================== -Unit Test for Python LaTeX -========================== - - -:author: Dave Kuhlman -:address: dkuhlman@rexx.com \\\\ - http://www.rexx.com/~dkuhlman - -:revision: 1.0a -:date: Aug. 4, 2003 - -:copyright: Copyright (c) 2003 Dave Kuhlman. - [an Open Source copyright] - -:abstract: This document contains input for unit tests for the - Python LaTeX writer for Docutils. - -.. sectnum:: :depth: 2 - -.. contents:: - - -""" - -latex_head = r"""\documentclass{howto} - -% generator -- Docutils: http://docutils.sourceforge.net/ -% writer -- documenting_python -% generated on -- Wed Aug 13 16:08:04 2003 - -\usepackage{html} -\title{Unit Test for Python LaTeX} -\release{1.0a} -\date{Aug. 4, 2003} -\author{Dave Kuhlman} -\authoraddress{dkuhlman@rexx.com \ -http://www.rexx.com/\~{}dkuhlman} -\begin{document} -\maketitle -\ifhtml -\chapter*{Front Matter\label{front}} -\fi - -Copyright (c) 2003 Dave Kuhlman. -[an Open Source copyright] -\begin{abstract} -\noindent - -This document contains input for unit tests for the -Python LaTeX writer for Docutils. -\end{abstract} -\tableofcontents - -""" - -totest = {} - -totest['section_headers'] = [ -# input -[rest_head + r""" -Section #1 -========== - -Content for section #1. - -Subsection #1-1 ---------------- - -Content for sub-section #1-1. - -Subsection #1-2 ---------------- - -Content for sub-section #1-2. - -Section #2 -========== - -Content for section #2. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Section {\#}1\label{section-1}} - -Content for section {\#}1. - - -%___________________________________________________________________________ - -\subsection{1.1 Subsection {\#}1-1\label{subsection-1-1}} - -Content for sub-section {\#}1-1. - - -%___________________________________________________________________________ - -\subsection{1.2 Subsection {\#}1-2\label{subsection-1-2}} - -Content for sub-section {\#}1-2. - - -%___________________________________________________________________________ - -\section{2 Section {\#}2\label{section-2}} - -Content for section {\#}2. - -\end{document} -"""], -] - -# ============================================================== - -totest['enumerated_lists'] = [ -# input -[rest_head + r""" -Enumerated List Test Section -============================ - -Here is an enumerated list: - -1. This is an item. - -2. This is an item. - -3. This is an item. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Enumerated List Test Section\label{enumerated-list-test-section}} - -Here is an enumerated list: -\begin{enumerate} -\item -This is an item. - -\item -This is an item. - -\item -This is an item. - -\end{enumerate} - -\end{document} -"""], -] - - -# ============================================================== - -totest['itemized_lists'] = [ -# input -[rest_head + r""" -Itemized List Test Section -========================== - -Here is an itemized list: - -- This is an item. - -- This is an item. - -- This is an item. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Itemized List Test Section\label{itemized-list-test-section}} - -Here is an itemized list: -\begin{itemize} -\item -This is an item. - -\item -This is an item. - -\item -This is an item. - -\end{itemize} - -\end{document} -"""], -] - -# ============================================================== - -totest['links'] = [ -# input -[rest_head + r""" -Section #1 -========== - -Content for section #1. - -Subsection #1-1 ---------------- - -Content for sub-section #1-1. - -Subsection #1-2 ---------------- - -Content for sub-section #1-2. - -Section #2 -========== - -Content for section #2. - -Links Test Section -================== - -Here is a link to the section which is the target of this -internal link `Subsection #1-1`_. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Section {\#}1\label{section-1}} - -Content for section {\#}1. - - -%___________________________________________________________________________ - -\subsection{1.1 Subsection {\#}1-1\label{subsection-1-1}} - -Content for sub-section {\#}1-1. - - -%___________________________________________________________________________ - -\subsection{1.2 Subsection {\#}1-2\label{subsection-1-2}} - -Content for sub-section {\#}1-2. - - -%___________________________________________________________________________ - -\section{2 Section {\#}2\label{section-2}} - -Content for section {\#}2. - - -%___________________________________________________________________________ - -\section{3 Links Test Section\label{links-test-section}} - -Here is a link to the section which is the target of this -internal link \ref{subsection-1-1}. - -\end{document} -"""], -] - -# ============================================================== - -totest['seealso'] = [ -# input -[rest_head + r""" -See Also -======== - -`Docutils: Python Documentation Utilities`_ - -.. _`Docutils: Python Documentation Utilities`: - http://docutils.sourceforge.net/ - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 See Also\label{see-also}} - -\ulink{Docutils: Python Documentation Utilities}{http://docutils.sourceforge.net/} - -\end{document} -"""], -] - - -# ============================================================== - -totest['emphasis'] = [ -# input -[rest_head + r""" -Section #1 -========== - -This section contains *some emphaized text*. - -It **also has some bold text**. - -And ``this is sample text``, or, as it is known in reStructured -Text, an in-line literal. - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Section {\#}1\label{section-1}} - -This section contains \emph{some emphaized text}. - -It \strong{also has some bold text}. - -And \samp{this is sample text}, or, as it is known in reStructured -Text, an in-line literal. - -\end{document} -"""], -] - - -# ============================================================== - -totest['blockquote'] = [ -# input -[rest_head + r""" -Block Quote Test -================ - -This section contains a paragraph which is followed by a block -quote. The block quote is a simple paragraph that is indented. - - This is the block quoted paragraph. It has several sentences. - These sentences have empty content because they are only a - test. This is a test. This is a test. This is a test. This - is a test. This is a test. This is a test. - - -Python Iteractive Session Test -============================== - -This section has a Python interactive session. It is a test. -Here is the example session. - ->>> import sys ->>> print sys.version -2.3 (#1, Jul 31 2003, 15:26:15) -[GCC 3.2.3 20030415 (Debian prerelease)] ->>> a = [11,22,33] ->>> for x in a: -... print x -... -11 -22 -33 - - -Literal Block Test -================== - -This section has a literal block. In Python LaTeX it will be -formatted in a verbatim environment:: - - def remove_lines(self, inStr, targetList): - inLines = inStr.splitlines() - outLines = [] - for line in inLines: - remove = False - for target in targetList: - if line.find(target) > -1: - remove = True - if not remove: - outLines.append(line) - outStr = '\n'.join(outLines) - return outStr - -""", - -# expected output -latex_head + r""" -%___________________________________________________________________________ - -\section{1 Block Quote Test\label{block-quote-test}} - -This section contains a paragraph which is followed by a block -quote. The block quote is a simple paragraph that is indented. -\begin{quote} - -This is the block quoted paragraph. It has several sentences. -These sentences have empty content because they are only a -test. This is a test. This is a test. This is a test. This -is a test. This is a test. This is a test. -\end{quote} - - -%___________________________________________________________________________ - -\section{2 Python Iteractive Session Test\label{python-iteractive-session-test}} - -This section has a Python interactive session. It is a test. -Here is the example session. -\begin{verbatim} ->>> import sys ->>> print sys.version -2.3 (#1, Jul 31 2003, 15:26:15) -[GCC 3.2.3 20030415 (Debian prerelease)] ->>> a = [11,22,33] ->>> for x in a: -... print x -... -11 -22 -33 -\end{verbatim} - - -%___________________________________________________________________________ - -\section{3 Literal Block Test\label{literal-block-test}} - -This section has a literal block. In Python LaTeX it will be -formatted in a verbatim environment: - -\begin{verbatim} -def remove_lines(self, inStr, targetList): - inLines = inStr.splitlines() - outLines = [] - for line in inLines: - remove = False - for target in targetList: - if line.find(target) > -1: - remove = True - if not remove: - outLines.append(line) - outStr = '\n'.join(outLines) - return outStr -\end{verbatim} - -\end{document} -"""], -] - - -# ============================================================== - -if __name__ == '__main__': - import unittest - unittest.main(defaultTest='suite') - - - - - diff --git a/sandbox/dkuhlman/docutils/tools/python_latex.py b/sandbox/dkuhlman/docutils/tools/python_latex.py deleted file mode 100755 index 245f7aafa..000000000 --- a/sandbox/dkuhlman/docutils/tools/python_latex.py +++ /dev/null @@ -1,25 +0,0 @@ -#!/usr/bin/env python - -""" -:Author: Dave Kuhlman -:Contact: dkuhlman@rexx.com -:Revision: $Revision$ -:Date: $Date$ -:Copyright: This module has been placed in the public domain. - -A minimal front end to the Docutils Publisher, producing LaTeX -that conforms to Documenting Python -(http://www.python.org/dev/doc/devel/doc/doc.html). -""" - -#import locale -#locale.setlocale(locale.LC_ALL, '') - -from docutils.core import publish_cmdline, default_description - - -description = ('Generates LaTeX for "Documenting Python" documents ' - 'from standalone reStructuredText ' - 'sources. ' + default_description) - -publish_cmdline(writer_name='python_latex', description=description) |