* 2dkZ?dkZEdZPdeii fdYZ hdeii fdYZ  deii fdYZdS(s0Docstring converter for StructuredText format. s)$RCSfile: docstring_StructuredText.py,v $s module_namesM$Id: docstring_StructuredText.py,v 1.2 2001/12/08 15:33:00 doughellmann Exp $srcs_ids(Doug Hellmann screators UNSPECIFIEDsprojectsWed, 26-Sep-2001 09:52:01 EDTscreateds$Author: doughellmann $sauthors$Revision: 1.2 $sversions$Date: 2001/12/08 15:33:00 $sdates is0.0Ncs5EFGhdd<td<dddgd(.*)csM||i|}| o |}n|id}|SdS(s*Clean converted text and return new value.iN(s extractBodyssearchs inputTextsmatchs clean_textsgroup(sselfs inputTexts extractBodysmatchs clean_text((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pys_cleanup|s   s&s&s<ss"s"csEx.|dr!\}}|i||}qW|SdS(s3Reverse the quoting process for character entities.iN(scharacter_entitiessregexs replacementssubstext(sselfstextscharacter_entitiess replacementsregex((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pys _unquoteHTMLs  csy|i}Wntj odSnrX|djo1|i}|i|i}||_n0x)|i dr}|i |qWdSdS(s@Unquote the characters in all example paragraphs in the ST tree.NsStructuredTextExamplei( ssts getTagNamestag_namesAttributeErrorsaq_selfs actual_parasselfs _unquoteHTMLs_srcstexts getChildNodesschilds_unquoteExamplesInST(sselfsstschildstexts actual_parastag_name((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pys_unquoteExamplesInSTs   ic sh|} |i||djo.h}|i|||d<t i dt i i iid| } t i dt i i iid| } t i dd| } t i i i| }|i|t i i ii} t| |f||}t|}|i|}|Sn|Sd S( sReturns the 'inputText' data translated into the 'outputFormat'. Parameters: 'inputText' -- String or other sequence of characters to be converted. This string should be in the format advertised by the docstring converter. 'outputFormat' -- String defined by the docstring converter class to represent a supported output scheme. This value is converter-specific, and not all converters will support the same output formats. 'level=3' -- Beginning indention level for the text. This controls what type of header elements are created among other behaviors. shtmlslevels[\000\n]\.\. \[([0-9_%s-]+)\]s\n [\1]s/([\000- ,])\[(?P[0-9_%s-]+)\]([\000- ,.:])s\1[\2]\3s)([\000- ,])\[([^]]+)\.html\]([\000- ,.:])s\1[\2]\3N(s inputTextstextsselfs_testOutputFormats outputFormatsapplyNamedArgssupdates namedArgsslevelsressubs happydoclibs docstringsStructuredTexts STletterssletterssDocumentssts_unquoteExamplesInSTs HTMLClassshtmlngsapplysargsshtml_representationsstrs_cleanup( sselfs inputTexts outputFormatslevelsargss namedArgsshtml_representationsstsapplyNamedArgsstextshtmlng((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pysconverts4           cs|i||djoTttiii|f||}t i dd|}|Sn |SdS(sReturns the 'inputText' quoted in a way that special characters are escaped. Parameters: 'inputText' -- String or other sequence of characters to be converted. This string should be in the format advertised by the docstring converter. 'outputFormat' -- String defined by the docstring converter class to represent a supported output scheme. This value is converter-specific, and not all converters will support the same output formats. '*args' -- Additional, converter-specific, positional arguments. '**namedArgs' -- Additional, converter-specific, named arguments. shtmls"([^&]+)":s"\1":N(sselfs_testOutputFormats outputFormatsapplys happydoclibs docstringsStructuredTexts html_quotes inputTextsargss namedArgss html_quotedsressub(sselfs inputTexts outputFormatsargss namedArgss html_quoted((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pysquotes     (s__doc__sStructuredTextFilesexternalDocumentFactorysRECOGNIZED_OUTPUT_FORMATSs_testOutputFormatsrescompiles MULTILINEsDOTALLs_cleanups _unquoteHTMLs_unquoteExamplesInSTsconvertsquote(((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pysStructuredTextConverterhs    % W ?sStructuredTextUnitTestcsw dZdZdZdZ"dZdZdZdZ d Zd Z d Z RS( Ns <>&"'[]{};s<>&"'[]{};s Structured Text With Links This "link":link.html points to link.html. This [1] reference points to an internal reference. .. [1] This is the internal reference. s0

Structured Text With Links

This link points to link.html.

This [1] reference points to an internal reference.

[1] This is the internal reference.

sStructured Text Manipulation Parse a structured text string into a form that can be used with structured formats, like html. Structured text is text that uses indentation and simple symbology to indicate the structure of a document. A structured string consists of a sequence of paragraphs separated by one or more blank lines. Each paragraph has a level which is defined as the minimum indentation of the paragraph. A paragraph is a sub-paragraph of another paragraph if the other paragraph is the last preceding paragraph that has a lower level. Special symbology is used to indicate special constructs: - A single-line paragraph whose immediately succeeding paragraphs are lower level is treated as a header. - A paragraph that begins with a '-', '*', or 'o' is treated as an unordered list (bullet) element. - A paragraph that begins with a sequence of digits followed by a white-space character is treated as an ordered list element. - A paragraph that begins with a sequence of sequences, where each sequence is a sequence of digits or a sequence of letters followed by a period, is treated as an ordered list element. - A paragraph with a first line that contains some text, followed by some white-space and '--' is treated as a descriptive list element. The leading text is treated as the element title. - Sub-paragraphs of a paragraph that ends in the word 'example' or the word 'examples', or '::' is treated as example code and is output as is. - Text enclosed single quotes (with white-space to the left of the first quote and whitespace or puctuation to the right of the second quote) is treated as example code. - Text surrounded by '*' characters (with white-space to the left of the first '*' and whitespace or puctuation to the right of the second '*') is emphasized. - Text surrounded by '**' characters (with white-space to the left of the first '**' and whitespace or puctuation to the right of the second '**') is made strong. - Text surrounded by '_' underscore characters (with whitespace to the left and whitespace or punctuation to the right) is made underlined. - Text encloded by double quotes followed by a colon, a URL, and concluded by punctuation plus white space, *or* just white space, is treated as a hyper link. For example: "Zope":http://www.zope.org/ is ... Is interpreted as 'Zope is ....' Note: This works for relative as well as absolute URLs. - Text enclosed by double quotes followed by a comma, one or more spaces, an absolute URL and concluded by punctuation plus white space, or just white space, is treated as a hyper link. For example: "mail me", mailto:amos@digicool.com. Is interpreted as 'mail me.' - Text enclosed in brackets which consists only of letters, digits, underscores and dashes is treated as hyper links within the document. For example: As demonstrated by Smith [12] this technique is quite effective. Is interpreted as '... by Smith [12] this ...'. Together with the next rule this allows easy coding of references or end notes. - Text enclosed in brackets which is preceded by the start of a line, two periods and a space is treated as a named link. For example: .. [12] "Effective Techniques" Smith, Joe ... Is interpreted as '[12] "Effective Techniques" ...'. Together with the previous rule this allows easy coding of references or end notes. - A paragraph that has blocks of text enclosed in '||' is treated as a table. The text blocks correspond to table cells and table rows are denoted by newlines. By default the cells are center aligned. A cell can span more than one column by preceding a block of text with an equivalent number of cell separators '||'. Newlines and '|' cannot be a part of the cell text. For example: |||| **Ingredients** || || *Name* || *Amount* || ||Spam||10|| ||Eggs||3|| is interpreted as::
Ingredients
Name Amount
Spam 10
Eggs 3
s

Structured Text Manipulation

Parse a structured text string into a form that can be used with structured formats, like html.

Structured text is text that uses indentation and simple symbology to indicate the structure of a document.

A structured string consists of a sequence of paragraphs separated by one or more blank lines. Each paragraph has a level which is defined as the minimum indentation of the paragraph. A paragraph is a sub-paragraph of another paragraph if the other paragraph is the last preceding paragraph that has a lower level.

Special symbology is used to indicate special constructs:

  • A single-line paragraph whose immediately succeeding paragraphs are lower level is treated as a header.

  • A paragraph that begins with a '-', *, or o is treated as an unordered list (bullet) element.

  • A paragraph that begins with a sequence of digits followed by a white-space character is treated as an ordered list element.

  • A paragraph that begins with a sequence of sequences, where each sequence is a sequence of digits or a sequence of letters followed by a period, is treated as an ordered list element.

  • A paragraph with a first line that contains some text, followed by some white-space and -- is treated as a descriptive list element. The leading text is treated as the element title.

  • Sub-paragraphs of a paragraph that ends in the word example or the word examples, or :: is treated as example code and is output as is.

  • Text enclosed single quotes (with white-space to the left of the first quote and whitespace or puctuation to the right of the second quote) is treated as example code.

  • Text surrounded by ' characters (with white-space to the left of the first ' and whitespace or puctuation to the right of the second *) is emphasized.

  • Text surrounded by ' characters (with white-space to the left of the first ' and whitespace or puctuation to the right of the second **) is made strong.

  • Text surrounded by _ underscore characters (with whitespace to the left and whitespace or punctuation to the right) is made underlined.

  • Text encloded by double quotes followed by a colon, a URL, and concluded by punctuation plus white space, or just white space, is treated as a hyper link. For example:

    Zope is ...

    Is interpreted as 'Zope is ....' Note: This works for relative as well as absolute URLs.

  • Text enclosed by double quotes followed by a comma, one or more spaces, an absolute URL and concluded by punctuation plus white space, or just white space, is treated as a hyper link. For example:

    mail me.

    Is interpreted as 'mail me.'

  • Text enclosed in brackets which consists only of letters, digits, underscores and dashes is treated as hyper links within the document. For example:

    As demonstrated by Smith [12] this technique is quite effective.

    Is interpreted as '... by Smith [12] this ...'. Together with the next rule this allows easy coding of references or end notes.

  • Text enclosed in brackets which is preceded by the start of a line, two periods and a space is treated as a named link. For example:

    .. [12] "Effective Techniques" Smith, Joe ...

    Is interpreted as '[12] "Effective Techniques" ...'. Together with the previous rule this allows easy coding of references or end notes.

  • A paragraph that has blocks of text enclosed in || is treated as a table. The text blocks correspond to table cells and table rows are denoted by newlines. By default the cells are center aligned. A cell can span more than one column by preceding a block of text with an equivalent number of cell separators ||. Newlines and | cannot be a part of the cell text. For example:

    |||| Ingredients || || Name || Amount || ||Spam||10|| ||Eggs||3||

    is interpreted as: 

        <TABLE BORDER=1 CELLPADDING=2>
     <TR>
      <TD ALIGN=CENTER COLSPAN=2> <strong>Ingredients</strong> </TD>
     </TR>
     <TR>
      <TD ALIGN=CENTER COLSPAN=1> <em>Name</em> </TD>
      <TD ALIGN=CENTER COLSPAN=1> <em>Amount</em> </TD>
     </TR>
     <TR>
      <TD ALIGN=CENTER COLSPAN=1>Spam</TD>
      <TD ALIGN=CENTER COLSPAN=1>10</TD>
     </TR>
     <TR>
      <TD ALIGN=CENTER COLSPAN=1>Eggs</TD>
      <TD ALIGN=CENTER COLSPAN=1>3</TD>
     </TR>
    </TABLE>

cs6|i|idd|iddSdS(NsStructuredTextshtmls)StructuredText-to-HTML conversion failed.(sselfs_testConversions st_test_textsst_expected_text(sself((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pystestConvertStructuredTextToHTMLs  cs6|i|idd|id dSdS(NsStructuredTextshtmls4StructuredText-to-HTML-with-links conversion failed.(sselfs_testConversionsst_test_text_with_linkssst_expected_text_with_links(sself((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pys(testConvertStructuredTextToHTMLWithLinkss  cs6  |i|idd |iddSdS(NsStructuredTextshtmlsST-to-HTML quote failed.(sselfs _testQuoteshtml_quote_textshtml_quote_expected_text(sself((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pystestQuoteStructuredTextToHTML s  cs~tddd|i}to|p tdd}to'|i|jptd|idSdS(Nsfilenamesinternalsbodys)Unable to create valid StructuredTextFilesStructured Text ManipulationsGot different one-liner "%s"(sStructuredTextFilesselfs st_test_textsstfs __debug__sAssertionErrorsexpected_onelinersoneLiner(sselfsexpected_onelinersstf((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pystestStructuredTextOneLiners  1csd}+d}8|i|:d;d<|=d@d}Qd}]|i|_d`da|bdddSdS(Ns~ any text first heading first section second heading second section third heading third section s

any text

first section

first heading

second section

second heading

third section

third heading

sStructuredTextshtmls?Converting Classic ST to HTML did not produce expected results.su first heading first section second heading second section third heading third section s

first heading

first section

second heading

second section

third heading

third section

(s input_text1sexpected_text1sselfs_testConversions input_text2sexpected_text2(sselfsexpected_text2s input_text2sexpected_text1s input_text1((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pys testBug471981s      ( shtml_quote_textshtml_quote_expected_textsst_test_text_with_linkssst_expected_text_with_linkss st_test_textsst_expected_textstestConvertStructuredTextToHTMLs(testConvertStructuredTextToHTMLWithLinksstestQuoteStructuredTextToHTMLstestStructuredTextOneLiners testBug471981(((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pysStructuredTextUnitTest s    x c    (s__doc__s __rcs_info__ssplits __version__sres$happydoclib.docstring.StructuredTexts happydoclibs entryPointshappydocstringsExternalDocumentationFileBasesStructuredTextFilesHappyDocStringConverterBasesStructuredTextConvertersDocStringConverterTestsStructuredTextUnitTest(s __rcs_info__s happydoclibs __version__sStructuredTextUnitTestsStructuredTextFilesStructuredTextConverters entryPointsre((sl/home/dhellmann/Personal/Devel/HappyDoc/dist/HappyDoc-r2_0/happydoclib/docstring/docstring_StructuredText.pys?s Q