- Renamed AsciiDoc API class to AsciiDocAPI.

- Added AsciiDoc API documentation file.

Author: Stuart Rackham

MANIFEST

@@ -1,5 +1,6 @@
 a2x
 asciidoc.py
+asciidocapi.py
 BUGS
 BUGS.txt
 common.aap
@@ -36,6 +37,7 @@ doc/music-filter.pdf
 doc/source-highlight-filter.pdf
 doc/*.txt
 doc/asciidoc.dict
+doc/asciidocapi.txt
 examples/website/ASCIIMathML.js
 examples/website/LaTeXMathML.js
 examples/website/build-website.sh

asciidocapi.py

@@ -2,11 +2,11 @@
 """
 asciidocapi - AsciiDoc API wrapper class.
 
-The AsciiDoc class provides an API for executing asciidoc. Minimal example
+The AsciiDocAPI class provides an API for executing asciidoc. Minimal example
 compiles `mydoc.txt` to `mydoc.html`:
 
   import asciidocapi
-  asciidoc = asciidocapi.AsciiDoc()
+  asciidoc = asciidocapi.AsciiDocAPI()
   asciidoc.execute('mydoc.txt')
 
 - Full documentation in asciidocapi.txt.
@@ -19,7 +19,7 @@
    >>> import StringIO
    >>> infile = StringIO.StringIO('Hello *{author}*')
    >>> outfile = StringIO.StringIO()
-   >>> asciidoc = AsciiDoc()
+   >>> asciidoc = AsciiDocAPI()
    >>> asciidoc.options('--no-header-footer')
    >>> asciidoc.attributes['author'] = 'Joe Bloggs'
    >>> asciidoc.execute(infile, outfile, backend='html4')
@@ -29,7 +29,7 @@
 2. Check error handling:
 
    >>> import StringIO
-   >>> asciidoc = AsciiDoc()
+   >>> asciidoc = AsciiDocAPI()
    >>> infile = StringIO.StringIO('---------')
    >>> outfile = StringIO.StringIO()
    >>> asciidoc.execute(infile, outfile)
@@ -45,11 +45,11 @@
 
 """
 
+import sys,os,re
+
 API_VERSION = '0.1.0'
 MIN_ASCIIDOC_VERSION = '8.3.6'  # Minimum acceptable AsciiDoc version.
 
-import sys,os,re
-
 
 def find_in_path(fname, path=None):
     """
@@ -71,14 +71,7 @@ class AsciiDocError(Exception):
 
 class Options(object):
     """
-    List of (key,value) command option tuples.
-
-    The following examples append ('--verbose',None) and
-    ('--conf-file','blog.conf') to the options.values list (you can
-    optionally omit append):
-
-    options.append('--verbose')
-    options.append('--conf-file', 'blog.conf')
+    Stores asciidoc(1) command options.
     """
     def __init__(self, values=[]):
         self.values = values[:]
@@ -140,11 +133,15 @@ def __cmp__(self, other):
                 result = cmp(self.micro, other.micro)
         return result
 
-class AsciiDoc(object):
+class AsciiDocAPI(object):
     """
-    The following options are invalid in API context: help,  version.
+    AsciiDoc API class.
     """
     def __init__(self, asciidoc_py=None):
+        """
+        Locate and import asciidoc.py.
+        Initialize instance attributes.
+        """
         self.options = Options()
         self.attributes = {}
         self.messages = []
@@ -186,6 +183,10 @@ def __init__(self, asciidoc_py=None):
         self.cmd = cmd
 
     def execute(self, infile, outfile=None, backend=None):
+        """
+        Compile infile to outfile using backend format.
+        infile can outfile can be file path strings or file like objects.
+        """
         self.messages = []
         opts = Options(self.options.values)
         if outfile is not None:
@@ -215,6 +216,9 @@ def execute(self, infile, outfile=None, backend=None):
 
 
 if __name__ == "__main__":
+    """
+    Run module doctests.
+    """
     import doctest
     options = doctest.NORMALIZE_WHITESPACE + doctest.ELLIPSIS
     doctest.testmod(optionflags=options)

doc/asciidoc.dict

@@ -1,19 +1,21 @@
-personal_ws-1.1 en 742 
+personal_ws-1.1 en 760 
 Sturmer
-Kl�ber
 Kleber
+Kl�ber
 quis
 auctor
+tuples
 linkcss
 multi
 CommentBlock
 AsciiDoc's
 BOLID
 callouts
+API
 bulleted
 starttags
-ListingBlock
 listingblock
+ListingBlock
 eval
 ListLabel
 asc
@@ -38,6 +40,7 @@ programlisting
 xhtml
 Windtrainer
 des
+cmd
 specialwords
 muellner
 Miklos
@@ -96,8 +99,8 @@ pageunits
 LaTeX
 citetitle
 emphasizedwords
-blocktitle
 BlockTitle
+blocktitle
 DTD
 CVS
 valign
@@ -126,8 +129,8 @@ luptatum
 TitleBlock
 fmt
 subscripted
-middlename
 MiddleName
+middlename
 subdirectories
 footnoteref
 passtext
@@ -148,8 +151,8 @@ entrytbl
 Ghostscript
 verear
 Buenos
-LinuxDoc
 linuxdoc
+LinuxDoc
 PostScript
 hhp
 Vijay
@@ -164,8 +167,9 @@ ListingBlocks
 GPL
 hsides
 upperalpha
-B�lido
+docfile
 Bolido
+B�lido
 footrow
 misspelt
 WINNT
@@ -177,8 +181,8 @@ bloggs
 hoc
 LiteralParagraphs
 primis
-verbatimblock
 VerbatimBlock
+verbatimblock
 corpname
 shiftwidth
 misevaluations
@@ -187,6 +191,7 @@ mattis
 Chai
 headrow
 Efros
+setuptools
 gui
 Blondel
 ile
@@ -220,6 +225,7 @@ SimpleList
 apos
 MSHR
 unescaped
+IRC
 toclevel
 runtime
 CalloutList
@@ -229,6 +235,7 @@ ctags
 sudo
 Helvetica
 SectionClose
+blog
 termtag
 OpenBlock
 joe
@@ -353,6 +360,7 @@ Bouchers
 JavaScript
 newlists
 guimenu
+init
 ListParagraphs
 bodydata
 MEPIS
@@ -373,6 +381,7 @@ mantitle
 RCS
 indentsize
 outfilesuffix
+doctime
 Berglunds
 syntaxes
 manvolnum
@@ -388,8 +397,8 @@ pre
 coid
 params
 mediaobjects
-JavaScripts
 javascripts
+JavaScripts
 sgmlfmt
 subsnormal
 unchunked
@@ -400,6 +409,7 @@ RevisionLine
 refname
 listelement
 PRS
+config
 CONFIG
 sem
 gzip
@@ -422,6 +432,7 @@ fileextension
 filetype
 URIs
 Blackdown
+pyc
 lang
 filesystem
 taoup
@@ -460,14 +471,17 @@ arabic
 fringilla
 retab
 BackendBlocks
-ChangeLog
 changelog
+ChangeLog
 tis
 Ubuntu
 sectids
+AsciiDocAPI
+asciidocapi
 Sommer
 LabeledList
 ZapfDingbats
+Julien
 hyperlinks
 EmailAddress
 Cheatsheet
@@ -480,8 +494,8 @@ crlf
 vel
 Iisaka's
 localtime
-BlockMacro
 blockmacro
+BlockMacro
 Xandros
 groff
 POSIX
@@ -507,7 +521,9 @@ configfile
 Donec
 colpcwidth
 uri
+AsciiDocError
 monospaced
+docdate
 llevar
 utf
 subdirectory
@@ -524,8 +540,8 @@ dbtimestamp
 txt
 BlockId
 passthrough
-Berguvsv�gen
 Berguvsvagen
+Berguvsv�gen
 noincsearch
 TableRow
 inlinemediaobject
@@ -537,6 +553,7 @@ xsltproc
 coids
 resx
 NumberedList
+getvalue
 colstop
 undefine
 tagname
@@ -573,9 +590,9 @@ Redhat
 cb
 tuple
 cd
-asciimathml
-AsciiMathML
 ASCIIMathML
+AsciiMathML
+asciimathml
 arounds
 filename
 mansource
@@ -591,8 +608,8 @@ scaledwidth
 cp
 xsl
 fb
-DocBook
 docbook
+DocBook
 stylesheet
 pagefile
 superscripted
@@ -604,6 +621,7 @@ Klum
 fo
 sgmlformat
 et
+StringIO
 eu
 showcomments
 gq
@@ -612,8 +630,8 @@ fprintf
 colabswidth
 tabsize
 smallnew
-BlockTitles
 blocktitles
+BlockTitles
 localdate
 bodyrow
 hs
@@ -663,8 +681,8 @@ permalink
 td
 py
 AROUT
-literalblock
 LiteralBlock
+literalblock
 sgml
 biggy
 softtabstop
@@ -680,8 +698,8 @@ tt
 blandit
 inline
 Mart�n
-SectionBody
 sectionbody
+SectionBody
 VM
 conformant
 listchars
@@ -726,8 +744,8 @@ nbsp
 qanda
 noout
 massa
-AsciiDoc
 asciidoc
+AsciiDoc
 manmanual
 TableBody
 realpath