diff options
| author | georg.brandl <devnull@localhost> | 2008-03-18 19:34:25 +0000 |
|---|---|---|
| committer | georg.brandl <devnull@localhost> | 2008-03-18 19:34:25 +0000 |
| commit | 740aae36e8251ef299acf657d74ea816a8caa7a6 (patch) | |
| tree | 2478579164830f114edcd713d3f500dc808dcc42 | |
| parent | 8d09e328ae8d30a236aac0f66517cbeac5df2863 (diff) | |
| download | sphinx-740aae36e8251ef299acf657d74ea816a8caa7a6.tar.gz | |
Move converter to its own dir.
28 files changed, 0 insertions, 5026 deletions
diff --git a/converter/__init__.py b/converter/__init__.py deleted file mode 100644 index 46f10322..00000000 --- a/converter/__init__.py +++ /dev/null @@ -1,144 +0,0 @@ -# -*- coding: utf-8 -*- -""" - Documentation converter - high level functions - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -import sys -import os -import glob -import shutil -import codecs -from os import path - -from .tokenizer import Tokenizer -from .latexparser import DocParser -from .restwriter import RestWriter -from .filenamemap import (fn_mapping, copyfiles_mapping, newfiles_mapping, - rename_mapping, dirs_to_make, toctree_mapping, - amendments_mapping) -from .console import red, green - -def convert_file(infile, outfile, doraise=True, splitchap=False, - toctree=None, deflang=None, labelprefix=''): - inf = codecs.open(infile, 'r', 'latin1') - p = DocParser(Tokenizer(inf.read()).tokenize(), infile) - if not splitchap: - outf = codecs.open(outfile, 'w', 'utf-8') - else: - outf = None - r = RestWriter(outf, splitchap, toctree, deflang, labelprefix) - try: - r.write_document(p.parse()) - if splitchap: - for i, chapter in enumerate(r.chapters[1:]): - coutf = codecs.open('%s/%d_%s' % ( - path.dirname(outfile), i+1, path.basename(outfile)), - 'w', 'utf-8') - coutf.write(chapter.getvalue()) - coutf.close() - else: - outf.close() - return 1, r.warnings - except Exception, err: - if doraise: - raise - return 0, str(err) - - -def convert_dir(outdirname, *args): - # make directories - for dirname in dirs_to_make: - try: - os.mkdir(path.join(outdirname, dirname)) - except OSError: - pass - - # copy files (currently only non-tex includes) - for oldfn, newfn in copyfiles_mapping.iteritems(): - newpathfn = path.join(outdirname, newfn) - globfns = glob.glob(oldfn) - if len(globfns) == 1 and not path.isdir(newpathfn): - shutil.copyfile(globfns[0], newpathfn) - else: - for globfn in globfns: - shutil.copyfile(globfn, path.join(newpathfn, - path.basename(globfn))) - - # convert tex files - # "doc" is not converted. It must be rewritten anyway. - for subdir in ('api', 'dist', 'ext', 'inst', 'commontex', - 'lib', 'mac', 'ref', 'tut', 'whatsnew'): - if args and subdir not in args: - continue - if subdir not in fn_mapping: - continue - newsubdir = fn_mapping[subdir]['__newname__'] - deflang = fn_mapping[subdir].get('__defaulthighlightlang__') - labelprefix = fn_mapping[subdir].get('__labelprefix__', '') - for filename in sorted(os.listdir(subdir)): - if not filename.endswith('.tex'): - continue - filename = filename[:-4] # strip extension - newname = fn_mapping[subdir][filename] - if newname is None: - continue - if newname.endswith(':split'): - newname = newname[:-6] - splitchap = True - else: - splitchap = False - if '/' not in newname: - outfilename = path.join(outdirname, newsubdir, newname + '.rst') - else: - outfilename = path.join(outdirname, newname + '.rst') - toctree = toctree_mapping.get(path.join(subdir, filename)) - infilename = path.join(subdir, filename + '.tex') - print green(infilename), - success, state = convert_file(infilename, outfilename, False, - splitchap, toctree, deflang, labelprefix) - if not success: - print red("ERROR:") - print red(" " + state) - else: - if state: - print "warnings:" - for warning in state: - print " " + warning - - # rename files, e.g. splitted ones - for oldfn, newfn in rename_mapping.iteritems(): - try: - if newfn is None: - os.unlink(path.join(outdirname, oldfn)) - else: - os.rename(path.join(outdirname, oldfn), - path.join(outdirname, newfn)) - except OSError, err: - if err.errno == 2: - continue - raise - - # copy new files - srcdirname = path.join(path.dirname(__file__), 'newfiles') - for fn, newfn in newfiles_mapping.iteritems(): - shutil.copyfile(path.join(srcdirname, fn), - path.join(outdirname, newfn)) - - # make amendments - for newfn, (pre, post) in amendments_mapping.iteritems(): - fn = path.join(outdirname, newfn) - try: - ft = open(fn).read() - except Exception, err: - print "Error making amendments to %s: %s" % (newfn, err) - continue - else: - fw = open(fn, 'w') - fw.write(pre) - fw.write(ft) - fw.write(post) - fw.close() diff --git a/converter/console.py b/converter/console.py deleted file mode 100644 index a5e201a7..00000000 --- a/converter/console.py +++ /dev/null @@ -1,101 +0,0 @@ -# -*- coding: utf-8 -*- -""" - Console utils - ~~~~~~~~~~~~~ - - Format colored console output. - - :copyright: 1998-2004 by the Gentoo Foundation. - :copyright: 2006-2007 by Georg Brandl. - :license: GNU GPL. -""" - -esc_seq = "\x1b[" - -codes = {} -codes["reset"] = esc_seq + "39;49;00m" - -codes["bold"] = esc_seq + "01m" -codes["faint"] = esc_seq + "02m" -codes["standout"] = esc_seq + "03m" -codes["underline"] = esc_seq + "04m" -codes["blink"] = esc_seq + "05m" -codes["overline"] = esc_seq + "06m" # Who made this up? Seriously. - -ansi_color_codes = [] -for x in xrange(30, 38): - ansi_color_codes.append("%im" % x) - ansi_color_codes.append("%i;01m" % x) - -rgb_ansi_colors = [ - '0x000000', '0x555555', '0xAA0000', '0xFF5555', - '0x00AA00', '0x55FF55', '0xAA5500', '0xFFFF55', - '0x0000AA', '0x5555FF', '0xAA00AA', '0xFF55FF', - '0x00AAAA', '0x55FFFF', '0xAAAAAA', '0xFFFFFF' -] - -for x in xrange(len(rgb_ansi_colors)): - codes[rgb_ansi_colors[x]] = esc_seq + ansi_color_codes[x] - -del x - -codes["black"] = codes["0x000000"] -codes["darkgray"] = codes["0x555555"] - -codes["red"] = codes["0xFF5555"] -codes["darkred"] = codes["0xAA0000"] - -codes["green"] = codes["0x55FF55"] -codes["darkgreen"] = codes["0x00AA00"] - -codes["yellow"] = codes["0xFFFF55"] -codes["brown"] = codes["0xAA5500"] - -codes["blue"] = codes["0x5555FF"] -codes["darkblue"] = codes["0x0000AA"] - -codes["fuchsia"] = codes["0xFF55FF"] -codes["purple"] = codes["0xAA00AA"] - -codes["teal"] = codes["0x00AAAA"] -codes["turquoise"] = codes["0x55FFFF"] - -codes["white"] = codes["0xFFFFFF"] -codes["lightgray"] = codes["0xAAAAAA"] - -codes["darkteal"] = codes["turquoise"] -codes["darkyellow"] = codes["brown"] -codes["fuscia"] = codes["fuchsia"] -codes["white"] = codes["bold"] - -def nocolor(): - "turn off colorization" - for code in codes: - codes[code] = "" - -def reset_color(): - return codes["reset"] - -def colorize(color_key, text): - return codes[color_key] + text + codes["reset"] - -functions_colors = [ - "bold", "white", "teal", "turquoise", "darkteal", - "fuscia", "fuchsia", "purple", "blue", "darkblue", - "green", "darkgreen", "yellow", "brown", - "darkyellow", "red", "darkred" -] - -def create_color_func(color_key): - """ - Return a function that formats its argument in the given color. - """ - def derived_func(text): - return colorize(color_key, text) - return derived_func - -ns = locals() -for c in functions_colors: - ns[c] = create_color_func(c) - -del c, ns diff --git a/converter/docnodes.py b/converter/docnodes.py deleted file mode 100644 index 85ca2625..00000000 --- a/converter/docnodes.py +++ /dev/null @@ -1,297 +0,0 @@ -# -*- coding: utf-8 -*- -""" - Python documentation LaTeX parser - document nodes - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - - -class DocNode(object): - """ A node in the document tree. """ - def __repr__(self): - return '%s()' % self.__class__.__name__ - - def __str__(self): - raise RuntimeError('cannot stringify docnodes') - - def walk(self): - return [] - - -class CommentNode(DocNode): - """ A comment. """ - def __init__(self, comment): - assert isinstance(comment, basestring) - self.comment = comment - - def __repr__(self): - return 'CommentNode(%r)' % self.comment - - -class RootNode(DocNode): - """ A whole document. """ - def __init__(self, filename, children): - self.filename = filename - self.children = children - self.params = {} - self.labels = {} - - def __repr__(self): - return 'RootNode(%r, %r)' % (self.filename, self.children) - - def walk(self): - return self.children - - def transform(self): - """ Do restructurings not possible during parsing. """ - def do_descenvs(node): - r""" Make \xxxlines an attribute of the parent xxxdesc node. """ - for subnode in node.walk(): - do_descenvs(subnode) - if isinstance(node, DescEnvironmentNode): - for subnode in node.content.walk(): - if isinstance(subnode, DescLineCommandNode): - node.additional.append((subnode.cmdname, subnode.args)) - - do_descenvs(self) - - -class NodeList(DocNode, list): - """ A list of subnodes. """ - def __init__(self, children=None): - list.__init__(self, children or []) - - def __repr__(self): - return 'NL%s' % list.__repr__(self) - - def walk(self): - return self - - def append(self, node): - assert isinstance(node, DocNode) - if type(node) is EmptyNode: - return - elif self and isinstance(node, TextNode) and \ - type(self[-1]) is TextNode: - self[-1].text += node.text - elif type(node) is NodeList: - list.extend(self, node) - elif type(node) is VerbatimNode and self and \ - isinstance(self[-1], ParaSepNode): - # don't allow a ParaSepNode before VerbatimNode - # because this breaks ReST's '::' - self[-1] = node - else: - list.append(self, node) - - def flatten(self): - if len(self) > 1: - return self - elif len(self) == 1: - return self[0] - else: - return EmptyNode() - - -class ParaSepNode(DocNode): - """ A node for paragraph separator. """ - def __repr__(self): - return 'Para' - - -class TextNode(DocNode): - """ A node containing text. """ - def __init__(self, text): - assert isinstance(text, basestring) - self.text = text - - def __repr__(self): - if type(self) is TextNode: - return 'T%r' % self.text - else: - return '%s(%r)' % (self.__class__.__name__, self.text) - - -class EmptyNode(TextNode): - """ An empty node. """ - def __init__(self, *args): - self.text = '' - - -class NbspNode(TextNode): - """ A non-breaking space. """ - def __init__(self, *args): - # this breaks ReST markup (!) - #self.text = u'\N{NO-BREAK SPACE}' - self.text = ' ' - - def __repr__(self): - return 'NBSP' - - -simplecmd_mapping = { - 'ldots': u'...', - 'moreargs': '...', - 'unspecified': '...', - 'ASCII': 'ASCII', - 'UNIX': 'Unix', - 'Unix': 'Unix', - 'POSIX': 'POSIX', - 'LaTeX': 'LaTeX', - 'EOF': 'EOF', - 'Cpp': 'C++', - 'C': 'C', - 'sub': u'--> ', - 'textbackslash': '\\\\', - 'textunderscore': '_', - 'texteuro': u'\N{EURO SIGN}', - 'textasciicircum': u'^', - 'textasciitilde': u'~', - 'textgreater': '>', - 'textless': '<', - 'textbar': '|', - 'backslash': '\\\\', - 'tilde': '~', - 'copyright': u'\N{COPYRIGHT SIGN}', - # \e is mostly inside \code and therefore not escaped. - 'e': '\\', - 'infinity': u'\N{INFINITY}', - 'plusminus': u'\N{PLUS-MINUS SIGN}', - 'leq': u'\N{LESS-THAN OR EQUAL TO}', - 'geq': u'\N{GREATER-THAN OR EQUAL TO}', - 'pi': u'\N{GREEK SMALL LETTER PI}', - 'AA': u'\N{LATIN CAPITAL LETTER A WITH RING ABOVE}', -} - -class SimpleCmdNode(TextNode): - """ A command resulting in simple text. """ - def __init__(self, cmdname, args): - self.text = simplecmd_mapping[cmdname] - - -class BreakNode(DocNode): - """ A line break. """ - def __repr__(self): - return 'BR' - - -class CommandNode(DocNode): - """ A general command. """ - def __init__(self, cmdname, args): - self.cmdname = cmdname - self.args = args - - def __repr__(self): - return '%s(%r, %r)' % (self.__class__.__name__, self.cmdname, self.args) - - def walk(self): - return self.args - - -class DescLineCommandNode(CommandNode): - """ A \\xxxline command. """ - - -class InlineNode(CommandNode): - """ A node with inline markup. """ - def walk(self): - return [] - - -class IndexNode(InlineNode): - """ An index-generating command. """ - def __init__(self, cmdname, args): - self.cmdname = cmdname - # tricky -- this is to make this silent in paragraphs - # while still generating index entries for textonly() - self.args = [] - self.indexargs = args - - -class SectioningNode(CommandNode): - """ A heading node. """ - - -class EnvironmentNode(DocNode): - """ An environment. """ - def __init__(self, envname, args, content): - self.envname = envname - self.args = args - self.content = content - - def __repr__(self): - return 'EnvironmentNode(%r, %r, %r)' % (self.envname, - self.args, self.content) - - def walk(self): - return [self.content] - - -class DescEnvironmentNode(EnvironmentNode): - """ An xxxdesc environment. """ - def __init__(self, envname, args, content): - self.envname = envname - self.args = args - self.additional = [] - self.content = content - - def __repr__(self): - return 'DescEnvironmentNode(%r, %r, %r)' % (self.envname, - self.args, self.content) - - -class TableNode(EnvironmentNode): - def __init__(self, numcols, headings, lines): - self.numcols = numcols - self.headings = headings - self.lines = lines - - def __repr__(self): - return 'TableNode(%r, %r, %r)' % (self.numcols, - self.headings, self.lines) - - def walk(self): - return [] - - -class VerbatimNode(DocNode): - """ A verbatim code block. """ - def __init__(self, content): - self.content = content - - def __repr__(self): - return 'VerbatimNode(%r)' % self.content - - -class ListNode(DocNode): - """ A list. """ - def __init__(self, items): - self.items = items - - def __repr__(self): - return '%s(%r)' % (self.__class__.__name__, self.items) - - def walk(self): - return [item[1] for item in self.items] - - -class ItemizeNode(ListNode): - """ An enumeration with bullets. """ - - -class EnumerateNode(ListNode): - """ An enumeration with numbers. """ - - -class DescriptionNode(ListNode): - """ A description list. """ - - -class DefinitionsNode(ListNode): - """ A definition list. """ - - -class ProductionListNode(ListNode): - """ A grammar production list. """ diff --git a/converter/etc/inst.diff b/converter/etc/inst.diff deleted file mode 100644 index 30f41404..00000000 --- a/converter/etc/inst.diff +++ /dev/null @@ -1,122 +0,0 @@ -Index: inst/inst.tex -=================================================================== ---- inst/inst.tex (Revision 54633) -+++ inst/inst.tex (Arbeitskopie) -@@ -324,32 +324,6 @@ - section~\ref{custom-install} on custom installations. - - --% This rather nasty macro is used to generate the tables that describe --% each installation scheme. It's nasty because it takes two arguments --% for each "slot" in an installation scheme, there will soon be more --% than five of these slots, and TeX has a limit of 10 arguments to a --% macro. Uh-oh. -- --\newcommand{\installscheme}[8] -- {\begin{tableiii}{l|l|l}{textrm} -- {Type of file} -- {Installation Directory} -- {Override option} -- \lineiii{pure module distribution} -- {\filevar{#1}\filenq{#2}} -- {\longprogramopt{install-purelib}} -- \lineiii{non-pure module distribution} -- {\filevar{#3}\filenq{#4}} -- {\longprogramopt{install-platlib}} -- \lineiii{scripts} -- {\filevar{#5}\filenq{#6}} -- {\longprogramopt{install-scripts}} -- \lineiii{data} -- {\filevar{#7}\filenq{#8}} -- {\longprogramopt{install-data}} -- \end{tableiii}} -- -- - \section{Alternate Installation} - \label{alt-install} - -@@ -399,10 +373,23 @@ - The \longprogramopt{home} option defines the installation base - directory. Files are installed to the following directories under the - installation base as follows: --\installscheme{home}{/lib/python} -- {home}{/lib/python} -- {home}{/bin} -- {home}{/share} -+\begin{tableiii}{l|l|l}{textrm} -+ {Type of file} -+ {Installation Directory} -+ {Override option} -+ \lineiii{pure module distribution} -+ {\filevar{home}\filenq{/lib/python}} -+ {\longprogramopt{install-purelib}} -+ \lineiii{non-pure module distribution} -+ {\filevar{home}\filenq{/lib/python}} -+ {\longprogramopt{install-platlib}} -+ \lineiii{scripts} -+ {\filevar{home}\filenq{/bin}} -+ {\longprogramopt{install-scripts}} -+ \lineiii{data} -+ {\filevar{home}\filenq{/share}} -+ {\longprogramopt{install-data}} -+\end{tableiii} - - - \versionchanged[The \longprogramopt{home} option used to be supported -@@ -452,10 +439,23 @@ - etc.) If \longprogramopt{exec-prefix} is not supplied, it defaults to - \longprogramopt{prefix}. Files are installed as follows: - --\installscheme{prefix}{/lib/python2.\filevar{X}/site-packages} -- {exec-prefix}{/lib/python2.\filevar{X}/site-packages} -- {prefix}{/bin} -- {prefix}{/share} -+\begin{tableiii}{l|l|l}{textrm} -+ {Type of file} -+ {Installation Directory} -+ {Override option} -+ \lineiii{pure module distribution} -+ {\filevar{prefix}\filenq{/lib/python2.\filevar{X}/site-packages}} -+ {\longprogramopt{install-purelib}} -+ \lineiii{non-pure module distribution} -+ {\filevar{exec-prefix}\filenq{/lib/python2.\filevar{X}/site-packages}} -+ {\longprogramopt{install-platlib}} -+ \lineiii{scripts} -+ {\filevar{prefix}\filenq{/bin}} -+ {\longprogramopt{install-scripts}} -+ \lineiii{data} -+ {\filevar{prefix}\filenq{/share}} -+ {\longprogramopt{install-data}} -+\end{tableiii} - - There is no requirement that \longprogramopt{prefix} or - \longprogramopt{exec-prefix} actually point to an alternate Python -@@ -502,11 +502,24 @@ - The installation base is defined by the \longprogramopt{prefix} option; - the \longprogramopt{exec-prefix} option is not supported under Windows. - Files are installed as follows: --\installscheme{prefix}{} -- {prefix}{} -- {prefix}{\textbackslash{}Scripts} -- {prefix}{\textbackslash{}Data} - -+\begin{tableiii}{l|l|l}{textrm} -+ {Type of file} -+ {Installation Directory} -+ {Override option} -+ \lineiii{pure module distribution} -+ {\filevar{prefix}\filenq{}} -+ {\longprogramopt{install-purelib}} -+ \lineiii{non-pure module distribution} -+ {\filevar{prefix}\filenq{}} -+ {\longprogramopt{install-platlib}} -+ \lineiii{scripts} -+ {\filevar{prefix}\filenq{\textbackslash{}Scripts}} -+ {\longprogramopt{install-scripts}} -+ \lineiii{data} -+ {\filevar{prefix}\filenq{\textbackslash{}Data}} -+ {\longprogramopt{install-data}} -+\end{tableiii} - - - \section{Custom Installation} diff --git a/converter/filenamemap.py b/converter/filenamemap.py deleted file mode 100644 index 0d743b41..00000000 --- a/converter/filenamemap.py +++ /dev/null @@ -1,636 +0,0 @@ -# -*- coding: utf-8 -*- -""" - Map LaTeX filenames to ReST filenames - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -# '' means: use same name, strip prefix if applicable. -# None means: don't translate at all. - -_mapping = { - 'lib': { - '__newname__' : 'library', - - 'asttable': '', - 'compiler': '', - 'distutils': '', - 'email': '', - 'emailcharsets': 'email.charset', - 'emailencoders': 'email.encoders', - 'emailexc': 'email.errors', - 'emailgenerator': 'email.generator', - 'emailheaders': 'email.header', - 'emailiter': 'email.iterators', - 'emailmessage': 'email.message', - 'emailmimebase': 'email.mime', - 'emailparser': 'email.parser', - 'emailutil': 'email.util', - 'libaifc': '', - 'libanydbm': '', - 'libarray': '', - 'libascii': 'curses.ascii', - 'libast': '', - 'libasynchat': '', - 'libasyncore': '', - 'libatexit': '', - 'libaudioop': '', - 'libbase64': '', - 'libbasehttp': 'basehttpserver', - 'libbastion': '', - 'libbinascii': '', - 'libbinhex': '', - 'libbisect': '', - 'libbltin': '__builtin__', - 'libbsddb': '', - 'libbz2': '', - 'libcalendar': '', - 'libcfgparser': 'configparser', - 'libcgihttp': 'cgihttpserver', - 'libcgi': '', - 'libcgitb': '', - 'libchunk': '', - 'libcmath': '', - 'libcmd': '', - 'libcodecs': '', - 'libcodeop': '', - 'libcode': '', - 'libcollections': '', - 'libcolorsys': '', - 'libcommands': '', - 'libcompileall': '', - 'libcontextlib': '', - 'libcookielib': '', - 'libcookie': '', - 'libcopyreg': 'copy_reg', - 'libcopy': '', - 'libcrypt': '', - 'libcsv': '', - 'libctypes': '', - 'libcursespanel': 'curses.panel', - 'libcurses': '', - 'libdatetime': '', - 'libdbhash': '', - 'libdbm': '', - 'libdecimal': '', - 'libdifflib': '', - 'libdircache': '', - 'libdis': '', - 'libdl': '', - 'libdoctest': '', - 'libdocxmlrpc': 'docxmlrpcserver', - 'libdumbdbm': '', - 'libdummythreading': 'dummy_threading', - 'libdummythread': 'dummy_thread', - 'liberrno': '', - 'libetree': 'xml.etree.elementtree', - 'libfcntl': '', - 'libfilecmp': '', - 'libfileinput': '', - 'libfnmatch': '', - 'libformatter': '', - 'libfpectl': '', - 'libfpformat': '', - 'libftplib': '', - 'libfunctools': '', - 'libfuture': '__future__', - 'libgc': '', - 'libgdbm': '', - 'libgetopt': '', - 'libgetpass': '', - 'libgettext': '', - 'libglob': '', - 'libgrp': '', - 'libgzip': '', - 'libhashlib': '', - 'libheapq': '', - 'libhmac': '', - 'libhotshot': '', - 'libhtmllib': '', - 'libhtmlparser': '', - 'libhttplib': '', - 'libimageop': '', - 'libimaplib': '', - 'libimgfile': '', - 'libimghdr': '', - 'libimp': '', - 'libinspect': '', - 'libitertools': '', - 'libjpeg': '', - 'libkeyword': '', - 'liblinecache': '', - 'liblocale': '', - 'liblogging': '', - 'libmailbox': '', - 'libmailcap': '', - 'libmain': '__main__', - 'libmarshal': '', - 'libmath': '', - 'libmd5': '', - 'libmhlib': '', - 'libmimetools': '', - 'libmimetypes': '', - 'libmimewriter': '', - 'libmimify': '', - 'libmmap': '', - 'libmodulefinder': '', - 'libmsilib': '', - 'libmsvcrt': '', - 'libmultifile': '', - 'libmutex': '', - 'libnetrc': '', - 'libnew': '', - 'libnis': '', - 'libnntplib': '', - 'liboperator': '', - 'liboptparse': '', - 'libos': '', - 'libossaudiodev': '', - 'libparser': '', - 'libpdb': '', - 'libpickle': '', - 'libpickletools': '', - 'libpipes': '', - 'libpkgutil': '', - 'libplatform': '', - 'libpopen2': '', - 'libpoplib': '', - 'libposixpath': 'os.path', - 'libposix': '', - 'libpprint': '', - 'libprofile': '', - 'libpty': '', - 'libpwd': '', - 'libpyclbr': '', - 'libpycompile': 'py_compile', - 'libpydoc': '', - 'libpyexpat': '', - 'libqueue': '', - 'libquopri': '', - 'librandom': '', - 'libreadline': '', - 'librepr': '', - 'libre': '', - 'libresource': '', - 'librexec': '', - 'librfc822': '', - 'librlcompleter': '', - 'librobotparser': '', - 'librunpy': '', - 'libsched': '', - 'libselect': '', - 'libsets': '', - 'libsgmllib': '', - 'libsha': '', - 'libshelve': '', - 'libshlex': '', - 'libshutil': '', - 'libsignal': '', - 'libsimplehttp': 'simplehttpserver', - 'libsimplexmlrpc': 'simplexmlrpcserver', - 'libsite': '', - 'libsmtpd': '', - 'libsmtplib': '', - 'libsndhdr': '', - 'libsocket': '', - 'libsocksvr': 'socketserver', - 'libspwd': '', - 'libsqlite3': '', - 'libstat': '', - 'libstatvfs': '', - 'libstringio': '', - 'libstringprep': '', - 'libstring': '', - 'libstruct': '', - 'libsunaudio': '', - 'libsunau': '', - 'libsubprocess': '', - 'libsymbol': '', - 'libsyslog': '', - 'libsys': '', - 'libtabnanny': '', - 'libtarfile': '', - 'libtelnetlib': '', - 'libtempfile': '', - 'libtermios': '', - 'libtest': '', - 'libtextwrap': '', - 'libthreading': '', - 'libthread': '', - 'libtimeit': '', - 'libtime': '', - 'libtokenize': '', - 'libtoken': '', - 'libtraceback': '', - 'libtrace': '', - 'libtty': '', - 'libturtle': '', - 'libtypes': '', - 'libunicodedata': '', - 'libunittest': '', - 'liburllib2': '', - 'liburllib': '', - 'liburlparse': '', - 'libuserdict': '', - 'libuser': '', - 'libuuid': '', - 'libuu': '', - 'libwarnings': '', - 'libwave': '', - 'libweakref': '', - 'libwebbrowser': '', - 'libwhichdb': '', - 'libwinreg': '_winreg', - 'libwinsound': '', - 'libwsgiref': '', - 'libxdrlib': '', - 'libxmllib': '', - 'libxmlrpclib': '', - 'libzipfile': '', - 'libzipimport': '', - 'libzlib': '', - 'tkinter': '', - 'xmldomminidom': 'xml.dom.minidom', - 'xmldompulldom': 'xml.dom.pulldom', - 'xmldom': 'xml.dom', - 'xmletree': 'xml.etree', - 'xmlsaxhandler': 'xml.sax.handler', - 'xmlsaxreader': 'xml.sax.reader', - 'xmlsax': 'xml.sax', - 'xmlsaxutils': 'xml.sax.utils', - 'libal': '', - 'libcd': '', - 'libfl': '', - 'libfm': '', - 'libgl': '', - 'libposixfile': '', - - # specials - 'libundoc': '', - 'libintro': '', - - 'libconsts': 'constants', - 'libexcs': 'exceptions', - 'libfuncs': 'functions', - 'libobjs': 'objects', - 'libstdtypes': 'stdtypes', - - # mainfiles - 'lib': None, - 'mimelib': None, - - # obsolete - 'libni': None, - 'libcmpcache': None, - 'libcmp': None, - - # chapter overviews - 'fileformats': '', - 'filesys': '', - 'frameworks': '', - 'i18n': '', - 'internet': '', - 'ipc': '', - 'language': '', - 'archiving': '', - 'custominterp': '', - 'datatypes': '', - 'development': '', - 'markup': '', - 'modules': '', - 'netdata': '', - 'numeric': '', - 'persistence': '', - 'windows': '', - 'libsun': '', - 'libmm': '', - 'liballos': '', - 'libcrypto': '', - 'libsomeos': '', - 'libsgi': '', - 'libmisc': '', - 'libpython': '', - 'librestricted': '', - 'libstrings': '', - 'libunix': '', - }, - - 'ref': { - '__newname__': 'reference', - 'ref': None, - 'ref1': 'introduction', - 'ref2': 'lexical_analysis', - 'ref3': 'datamodel', - 'ref4': 'executionmodel', - 'ref5': 'expressions', - 'ref6': 'simple_stmts', - 'ref7': 'compound_stmts', - 'ref8': 'toplevel_components', - }, - - 'tut': { - '__newname__': 'tutorial', - '__labelprefix__': 'tut-', - 'tut': 'tutorial:split', - 'glossary': 'glossary', - }, - - 'api': { - '__newname__': 'c-api', - '__defaulthighlightlang__': 'c', - 'api': None, - - 'abstract': '', - 'concrete': '', - 'exceptions': '', - 'init': '', - 'intro': '', - 'memory': '', - 'newtypes': '', - 'refcounting': '', - 'utilities': '', - 'veryhigh': '', - }, - - 'ext': { - '__newname__': 'extending', - '__defaulthighlightlang__': 'c', - 'ext': None, - - 'building': '', - 'embedding': '', - 'extending': 'extending', - 'newtypes': '', - 'windows': '', - }, - - 'dist': { - '__newname__': 'distutils', - 'dist': 'distutils:split', - 'sysconfig': '', - }, - - 'mac': { - '__newname__': 'maclib', - 'mac': None, - - 'libaepack': 'aepack', - 'libaetools': 'aetools', - 'libaetypes': 'aetypes', - 'libautogil': 'autogil', - 'libcolorpicker': 'colorpicker', - 'libframework': 'framework', - 'libgensuitemodule': 'gensuitemodule', - 'libmacic': 'macic', - 'libmacos': 'macos', - 'libmacostools': 'macostools', - 'libmac': 'mac', - 'libmacui': 'macui', - 'libminiae': 'miniae', - 'libscrap': 'scrap', - 'scripting': '', - 'toolbox': '', - 'undoc': '', - 'using': '', - - }, - - 'inst': { - '__newname__': 'install', - '__defaulthighlightlang__': 'none', - 'inst': 'index', - }, - - 'whatsnew': { - '__newname__': 'whatsnew', - 'whatsnew20': '2.0', - 'whatsnew21': '2.1', - 'whatsnew22': '2.2', - 'whatsnew23': '2.3', - 'whatsnew24': '2.4', - 'whatsnew25': '2.5', - 'whatsnew26': '2.6', - 'whatsnew30': '3.0', - }, - - 'commontex': { - '__newname__': '', - 'boilerplate': None, - 'patchlevel': None, - 'copyright': '', - 'license': '', - 'reportingbugs': 'bugs', - }, -} - -fn_mapping = {} - -for dir, files in _mapping.iteritems(): - newmap = fn_mapping[dir] = {} - for fn in files: - if not fn.startswith('_') and files[fn] == '': - if fn.startswith(dir): - newmap[fn] = fn[len(dir):] - else: - newmap[fn] = fn - else: - newmap[fn] = files[fn] - - -# new directories to create -dirs_to_make = [ - 'c-api', - 'data', - 'distutils', - 'documenting', - 'extending', - 'includes', - 'includes/sqlite3', - 'install', - 'maclib', - 'library', - 'reference', - 'tutorial', - 'whatsnew', - 'tools', -] - -# includefiles for \verbatiminput and \input -includes_mapping = { - '../../Parser/Python.asdl': None, # XXX - '../../Lib/test/exception_hierarchy.txt': None, - 'emailmessage': 'email.message.rst', - 'emailparser': 'email.parser.rst', - 'emailgenerator': 'email.generator.rst', - 'emailmimebase': 'email.mime.rst', - 'emailheaders': 'email.header.rst', - 'emailcharsets': 'email.charset.rst', - 'emailencoders': 'email.encoders.rst', - 'emailexc': 'email.errors.rst', - 'emailutil': 'email.util.rst', - 'emailiter': 'email.iterators.rst', -} - -# new files to copy from converter/newfiles -newfiles_mapping = { - 'conf.py': 'conf.py', - 'TODO': 'TODO', - 'ACKS': 'ACKS', - - 'ref_index.rst': 'reference/index.rst', - 'tutorial_index.rst': 'tutorial/index.rst', - 'modules_index.rst': 'library/index.rst', - 'mac_index.rst': 'maclib/index.rst', - 'ext_index.rst': 'extending/index.rst', - 'api_index.rst': 'c-api/index.rst', - 'dist_index.rst': 'distutils/index.rst', - 'contents.rst': 'contents.rst', - 'about.rst': 'about.rst', - - 'doc.rst': 'documenting/index.rst', - 'doc_intro.rst': 'documenting/intro.rst', - 'doc_style.rst': 'documenting/style.rst', - 'doc_sphinx.rst': 'documenting/sphinx.rst', - 'doc_rest.rst': 'documenting/rest.rst', - 'doc_markup.rst': 'documenting/markup.rst', -} - -# copy files from the old doc tree -copyfiles_mapping = { - 'api/refcounts.dat': 'data', - 'lib/email-*.py': 'includes', - 'lib/minidom-example.py': 'includes', - 'lib/tzinfo-examples.py': 'includes', - 'lib/sqlite3/*.py': 'includes/sqlite3', - 'ext/*.c': 'includes', - 'ext/*.py': 'includes', - 'commontex/typestruct.h': 'includes', -} - -# files to rename -rename_mapping = { - 'tutorial/1_tutorial.rst': None, # delete - 'tutorial/2_tutorial.rst': 'tutorial/appetite.rst', - 'tutorial/3_tutorial.rst': 'tutorial/interpreter.rst', - 'tutorial/4_tutorial.rst': 'tutorial/introduction.rst', - 'tutorial/5_tutorial.rst': 'tutorial/controlflow.rst', - 'tutorial/6_tutorial.rst': 'tutorial/datastructures.rst', - 'tutorial/7_tutorial.rst': 'tutorial/modules.rst', - 'tutorial/8_tutorial.rst': 'tutorial/inputoutput.rst', - 'tutorial/9_tutorial.rst': 'tutorial/errors.rst', - 'tutorial/10_tutorial.rst': 'tutorial/classes.rst', - 'tutorial/11_tutorial.rst': 'tutorial/stdlib.rst', - 'tutorial/12_tutorial.rst': 'tutorial/stdlib2.rst', - 'tutorial/13_tutorial.rst': 'tutorial/whatnow.rst', - 'tutorial/14_tutorial.rst': 'tutorial/interactive.rst', - 'tutorial/15_tutorial.rst': 'tutorial/floatingpoint.rst', - 'tutorial/16_tutorial.rst': None, # delete - - 'distutils/1_distutils.rst': 'distutils/introduction.rst', - 'distutils/2_distutils.rst': 'distutils/setupscript.rst', - 'distutils/3_distutils.rst': 'distutils/configfile.rst', - 'distutils/4_distutils.rst': 'distutils/sourcedist.rst', - 'distutils/5_distutils.rst': 'distutils/builtdist.rst', - 'distutils/6_distutils.rst': 'distutils/packageindex.rst', - 'distutils/7_distutils.rst': 'distutils/uploading.rst', - 'distutils/8_distutils.rst': 'distutils/examples.rst', - 'distutils/9_distutils.rst': 'distutils/extending.rst', - 'distutils/10_distutils.rst': 'distutils/commandref.rst', - 'distutils/11_distutils.rst': 'distutils/apiref.rst', -} - -# toctree entries -toctree_mapping = { - 'mac/scripting': ['gensuitemodule', 'aetools', 'aepack', 'aetypes', 'miniae'], - 'mac/toolbox': ['colorpicker'], - 'mac/undoc': [], - 'lib/libstrings': ['string', 're', 'struct', 'difflib', 'stringio', 'textwrap', - 'codecs', 'unicodedata', 'stringprep', 'fpformat'], - 'lib/datatypes': ['datetime', 'calendar', 'collections', 'heapq', 'bisect', - 'array', 'sets', 'sched', 'mutex', 'queue', 'weakref', - 'userdict', 'types', 'new', 'copy', 'pprint', 'repr'], - 'lib/numeric': ['math', 'cmath', 'decimal', 'random', 'itertools', 'functools', - 'operator'], - 'lib/netdata': ['email', 'mailcap', 'mailbox', 'mhlib', 'mimetools', 'mimetypes', - 'mimewriter', 'mimify', 'multifile', 'rfc822', - 'base64', 'binhex', 'binascii', 'quopri', 'uu'], - 'lib/markup': ['htmlparser', 'sgmllib', 'htmllib', 'pyexpat', 'xml.dom', - 'xml.dom.minidom', 'xml.dom.pulldom', 'xml.sax', 'xml.sax.handler', - 'xml.sax.utils', 'xml.sax.reader', 'xml.etree.elementtree'], - 'lib/fileformats': ['csv', 'configparser', 'robotparser', 'netrc', 'xdrlib'], - 'lib/libcrypto': ['hashlib', 'hmac', 'md5', 'sha'], - 'lib/filesys': ['os.path', 'fileinput', 'stat', 'statvfs', 'filecmp', - 'tempfile', 'glob', 'fnmatch', 'linecache', 'shutil', 'dircache'], - 'lib/archiving': ['zlib', 'gzip', 'bz2', 'zipfile', 'tarfile'], - 'lib/persistence': ['pickle', 'copy_reg', 'shelve', 'marshal', 'anydbm', - 'whichdb', 'dbm', 'gdbm', 'dbhash', 'bsddb', 'dumbdbm', - 'sqlite3'], - 'lib/liballos': ['os', 'time', 'optparse', 'getopt', 'logging', 'getpass', - 'curses', 'curses.ascii', 'curses.panel', 'platform', - 'errno', 'ctypes'], - 'lib/libsomeos': ['select', 'thread', 'threading', 'dummy_thread', 'dummy_threading', - 'mmap', 'readline', 'rlcompleter'], - 'lib/libunix': ['posix', 'pwd', 'spwd', 'grp', 'crypt', 'dl', 'termios', 'tty', - 'pty', 'fcntl', 'pipes', 'posixfile', 'resource', 'nis', - 'syslog', 'commands'], - 'lib/ipc': ['subprocess', 'socket', 'signal', 'popen2', 'asyncore', 'asynchat'], - 'lib/internet': ['webbrowser', 'cgi', 'cgitb', 'wsgiref', 'urllib', 'urllib2', - 'httplib', 'ftplib', 'poplib', 'imaplib', - 'nntplib', 'smtplib', 'smtpd', 'telnetlib', 'uuid', 'urlparse', - 'socketserver', 'basehttpserver', 'simplehttpserver', - 'cgihttpserver', 'cookielib', 'cookie', 'xmlrpclib', - 'simplexmlrpcserver', 'docxmlrpcserver'], - 'lib/libmm': ['audioop', 'imageop', 'aifc', 'sunau', 'wave', 'chunk', - 'colorsys', 'imghdr', 'sndhdr', 'ossaudiodev'], - 'lib/i18n': ['gettext', 'locale'], - 'lib/frameworks': ['cmd', 'shlex'], - 'lib/development': ['pydoc', 'doctest', 'unittest', 'test'], - 'lib/libpython': ['sys', '__builtin__', '__main__', 'warnings', 'contextlib', - 'atexit', 'traceback', '__future__', 'gc', 'inspect', - 'site', 'user', 'fpectl'], - 'lib/custominterp': ['code', 'codeop'], - 'lib/librestricted': ['rexec', 'bastion'], - 'lib/modules': ['imp', 'zipimport', 'pkgutil', 'modulefinder', 'runpy'], - 'lib/language': ['parser', 'symbol', 'token', 'keyword', 'tokenize', - 'tabnanny', 'pyclbr', 'py_compile', 'compileall', 'dis', - 'pickletools', 'distutils'], - 'lib/compiler': ['ast'], - 'lib/libmisc': ['formatter'], - 'lib/libsgi': ['al', 'cd', 'fl', 'fm', 'gl', 'imgfile', 'jpeg'], - 'lib/libsun': ['sunaudio'], - 'lib/windows': ['msilib', 'msvcrt', '_winreg', 'winsound'], - 'lib/tkinter': [], -} - -# map sourcefilename to [pre, post] -amendments_mapping = { - 'license.rst': ['''\ -.. highlightlang:: none - -******************* -History and License -******************* - -''', ''], - - 'bugs.rst': ['''\ -************** -Reporting Bugs -************** - -''', ''], - - 'copyright.rst': ['''\ -********* -Copyright -********* - -''', ''], - - 'install/index.rst': ['''\ -.. _install-index: - -''', ''], -} diff --git a/converter/latexparser.py b/converter/latexparser.py deleted file mode 100644 index bceffd2d..00000000 --- a/converter/latexparser.py +++ /dev/null @@ -1,697 +0,0 @@ -# -*- coding: utf-8 -*- -""" - Python documentation LaTeX file parser - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - For more documentation, look into the ``restwriter.py`` file. - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -from .docnodes import CommentNode, RootNode, NodeList, ParaSepNode, \ - TextNode, EmptyNode, NbspNode, SimpleCmdNode, BreakNode, CommandNode, \ - DescLineCommandNode, InlineNode, IndexNode, SectioningNode, \ - EnvironmentNode, DescEnvironmentNode, TableNode, VerbatimNode, \ - ListNode, ItemizeNode, EnumerateNode, DescriptionNode, \ - DefinitionsNode, ProductionListNode - -from .util import umlaut, empty - - -class ParserError(Exception): - def __init__(self, msg, lineno): - Exception.__init__(self, msg, lineno) - - def __str__(self): - return '%s, line %s' % self.args - - -def generic_command(name, argspec, nodetype=CommandNode): - def handle(self): - args = self.parse_args('\\'+name, argspec) - return nodetype(name, args) - return handle - -def sectioning_command(name): - """ Special handling for sectioning commands: move labels directly following - a sectioning command before it, as required by reST. """ - def handle(self): - args = self.parse_args('\\'+name, 'M') - snode = SectioningNode(name, args) - for l, t, v, r in self.tokens: - if t == 'command' and v == 'label': - largs = self.parse_args('\\label', 'T') - snode.args[0] = NodeList([snode.args[0], CommandNode('label', largs)]) - break - if t == 'text': - if not v.strip(): - # discard whitespace; after a section that's no problem - continue - self.tokens.push((l, t, v, r)) - break - # no label followed - return snode - return handle - -def generic_environment(name, argspec, nodetype=EnvironmentNode): - def handle(self): - args = self.parse_args(name, argspec) - return nodetype(name, args, self.parse_until(self.environment_end)) - return handle - - -class DocParserMeta(type): - def __init__(cls, name, bases, dict): - for nodetype, commands in cls.generic_commands.iteritems(): - for cmdname, argspec in commands.iteritems(): - setattr(cls, 'handle_' + cmdname, - generic_command(cmdname, argspec, nodetype)) - - for cmdname in cls.sectioning_commands: - setattr(cls, 'handle_' + cmdname, sectioning_command(cmdname)) - - for nodetype, envs in cls.generic_envs.iteritems(): - for envname, argspec in envs.iteritems(): - setattr(cls, 'handle_%s_env' % envname, - generic_environment(envname, argspec, nodetype)) - - -class DocParser(object): - """ Parse a Python documentation LaTeX file. """ - __metaclass__ = DocParserMeta - - def __init__(self, tokenstream, filename): - self.tokens = tokenstream - self.filename = filename - - def parse(self): - self.rootnode = RootNode(self.filename, None) - self.rootnode.children = self.parse_until(None) - self.rootnode.transform() - return self.rootnode - - def parse_until(self, condition=None, endatbrace=False): - nodelist = NodeList() - bracelevel = 0 - for l, t, v, r in self.tokens: - if condition and condition(t, v, bracelevel): - return nodelist.flatten() - if t == 'command': - if len(v) == 1 and not v.isalpha(): - nodelist.append(self.handle_special_command(v)) - continue - handler = getattr(self, 'handle_' + v, None) - if not handler: - raise ParserError('no handler for \\%s command' % v, l) - nodelist.append(handler()) - elif t == 'bgroup': - bracelevel += 1 - elif t == 'egroup': - if bracelevel == 0 and endatbrace: - return nodelist.flatten() - bracelevel -= 1 - elif t == 'comment': - nodelist.append(CommentNode(v)) - elif t == 'tilde': - nodelist.append(NbspNode()) - elif t == 'mathmode': - pass # ignore math mode - elif t == 'parasep': - nodelist.append(ParaSepNode()) - else: - # includes 'boptional' and 'eoptional' which don't have a - # special meaning in text - nodelist.append(TextNode(v)) - return nodelist.flatten() - - def parse_args(self, cmdname, argspec): - """ Helper to parse arguments of a command. """ - # argspec: M = mandatory, T = mandatory, check text-only, - # O = optional, Q = optional, check text-only - args = [] - def optional_end(type, value, bracelevel): - return type == 'eoptional' and bracelevel == 0 - - for i, c in enumerate(argspec): - assert c in 'OMTQ' - nextl, nextt, nextv, nextr = self.tokens.pop() - while nextt == 'comment' or (nextt == 'text' and nextv.isspace()): - nextl, nextt, nextv, nextr = self.tokens.pop() - - if c in 'OQ': - if nextt == 'boptional': - arg = self.parse_until(optional_end) - if c == 'Q' and not isinstance(arg, TextNode): - raise ParserError('%s: argument %d must be text only' % - (cmdname, i), nextl) - args.append(arg) - else: - # not given - args.append(EmptyNode()) - self.tokens.push((nextl, nextt, nextv, nextr)) - continue - - if nextt == 'bgroup': - arg = self.parse_until(None, endatbrace=True) - if c == 'T' and not isinstance(arg, TextNode): - raise ParserError('%s: argument %d must be text only' % - (cmdname, i), nextl) - args.append(arg) - else: - if nextt != 'text': - raise ParserError('%s: non-grouped non-text arguments not ' - 'supported' % cmdname, nextl) - args.append(TextNode(nextv[0])) - self.tokens.push((nextl, nextt, nextv[1:], nextr[1:])) - return args - - sectioning_commands = [ - 'chapter', - 'chapter*', - 'section', - 'subsection', - 'subsubsection', - 'paragraph', - ] - - generic_commands = { - CommandNode: { - 'label': 'T', - - 'localmoduletable': '', - 'verbatiminput': 'T', - 'input': 'T', - 'centerline': 'M', - - # Pydoc specific commands - 'versionadded': 'OT', - 'versionchanged': 'OT', - 'deprecated': 'TM', - 'XX' 'X': 'M', # used in dist.tex ;) - - # module-specific - 'declaremodule': 'QTT', - 'platform': 'T', - 'modulesynopsis': 'M', - 'moduleauthor': 'TT', - 'sectionauthor': 'TT', - - # reference lists - 'seelink': 'TMM', - 'seemodule': 'QTM', - 'seepep': 'TMM', - 'seerfc': 'TTM', - 'seetext': 'M', - 'seetitle': 'OMM', - 'seeurl': 'MM', - }, - - DescLineCommandNode: { - # additional items for ...desc - 'funcline': 'TM', - 'funclineni': 'TM', - 'methodline': 'QTM', - 'methodlineni': 'QTM', - 'memberline': 'QT', - 'memberlineni': 'QT', - 'dataline': 'T', - 'datalineni': 'T', - 'cfuncline': 'MTM', - 'cmemberline': 'TTT', - 'csimplemacroline': 'T', - 'ctypeline': 'QT', - 'cvarline': 'TT', - }, - - InlineNode: { - # specials - 'footnote': 'M', - 'frac': 'TT', - 'refmodule': 'QT', - 'citetitle': 'QT', - 'ulink': 'MT', - 'url': 'M', - - # mapped to normal - 'textrm': 'M', - 'b': 'M', - 'email': 'M', # email addresses are recognized by ReST - - # mapped to **strong** - 'textbf': 'M', - 'strong': 'M', - - # mapped to *emphasized* - 'textit': 'M', - 'emph': 'M', - - # mapped to ``code`` - 'bfcode': 'M', - 'code': 'M', - 'samp': 'M', - 'character': 'M', - 'texttt': 'M', - - # mapped to `default role` - 'var': 'M', - - # mapped to [brackets] - 'optional': 'M', - - # mapped to :role:`text` - 'cdata': 'M', - 'cfunction': 'M', # -> :cfunc: - 'class': 'M', - 'command': 'M', - 'constant': 'M', # -> :const: - 'csimplemacro': 'M', # -> :cmacro: - 'ctype': 'M', - 'data': 'M', # NEW - 'dfn': 'M', - 'envvar': 'M', - 'exception': 'M', # -> :exc: - 'file': 'M', - 'filenq': 'M', - 'filevar': 'M', - 'function': 'M', # -> :func: - 'grammartoken': 'M', # -> :token: - 'guilabel': 'M', - 'kbd': 'M', - 'keyword': 'M', - 'mailheader': 'M', - 'makevar': 'M', - 'manpage': 'MM', - 'member': 'M', - 'menuselection': 'M', - 'method': 'M', # -> :meth: - 'mimetype': 'M', - 'module': 'M', # -> :mod: - 'newsgroup': 'M', - 'option': 'M', - 'pep': 'M', - 'program': 'M', - 'programopt': 'M', # -> :option: - 'longprogramopt': 'M', # -> :option: - 'ref': 'T', - 'regexp': 'M', - 'rfc': 'M', - 'token': 'M', - - 'NULL': '', - # these are defined via substitutions - 'shortversion': '', - 'version': '', - 'today': '', - }, - - SimpleCmdNode: { - # these are directly mapped to text - 'AA': '', # A as in Angstrom - 'ASCII': '', - 'C': '', - 'Cpp': '', - 'EOF': '', - 'LaTeX': '', - 'POSIX': '', - 'UNIX': '', - 'Unix': '', - 'backslash': '', - 'copyright': '', - 'e': '', # backslash - 'geq': '', - 'infinity': '', - 'ldots': '', - 'leq': '', - 'moreargs': '', - 'pi': '', - 'plusminus': '', - 'sub': '', # menu separator - 'textbackslash': '', - 'textunderscore': '', - 'texteuro': '', - 'textasciicircum': '', - 'textasciitilde': '', - 'textgreater': '', - 'textless': '', - 'textbar': '', - 'tilde': '', - 'unspecified': '', - }, - - IndexNode: { - 'bifuncindex': 'T', - 'exindex': 'T', - 'kwindex': 'T', - 'obindex': 'T', - 'opindex': 'T', - 'refmodindex': 'T', - 'refexmodindex': 'T', - 'refbimodindex': 'T', - 'refstmodindex': 'T', - 'stindex': 'T', - 'index': 'M', - 'indexii': 'TT', - 'indexiii': 'TTT', - 'indexiv': 'TTTT', - 'ttindex': 'T', - 'withsubitem': 'TM', - }, - - # These can be safely ignored - EmptyNode: { - 'setindexsubitem': 'T', - 'tableofcontents': '', - 'makeindex': '', - 'makemodindex': '', - 'maketitle': '', - 'appendix': '', - 'documentclass': 'OM', - 'usepackage': 'OM', - 'noindent': '', - 'protect': '', - 'ifhtml': '', - 'fi': '', - }, - } - - generic_envs = { - EnvironmentNode: { - # generic LaTeX environments - 'abstract': '', - 'quote': '', - 'quotation': '', - - 'notice': 'Q', - 'seealso': '', - 'seealso*': '', - }, - - DescEnvironmentNode: { - # information units - 'datadesc': 'T', - 'datadescni': 'T', - 'excclassdesc': 'TM', - 'excdesc': 'T', - 'funcdesc': 'TM', - 'funcdescni': 'TM', - 'classdesc': 'TM', - 'classdesc*': 'T', - 'memberdesc': 'QT', - 'memberdescni': 'QT', - 'methoddesc': 'QMM', - 'methoddescni': 'QMM', - 'opcodedesc': 'TT', - - 'cfuncdesc': 'MTM', - 'cmemberdesc': 'TTT', - 'csimplemacrodesc': 'T', - 'ctypedesc': 'QT', - 'cvardesc': 'TT', - }, - } - - # ------------------------- special handlers ----------------------------- - - def handle_special_command(self, cmdname): - if cmdname in '{}%$^#&_ ': - # these are just escapes for special LaTeX commands - return TextNode(cmdname) - elif cmdname in '\'`~"c': - # accents and umlauts - nextl, nextt, nextv, nextr = self.tokens.next() - if nextt == 'bgroup': - _, nextt, _, _ = self.tokens.next() - if nextt != 'egroup': - raise ParserError('wrong argtype for \\%s' % cmdname, nextl) - return TextNode(cmdname) - if nextt != 'text': - # not nice, but {\~} = ~ - self.tokens.push((nextl, nextt, nextv, nextr)) - return TextNode(cmdname) - c = umlaut(cmdname, nextv[0]) - self.tokens.push((nextl, nextt, nextv[1:], nextr[1:])) - return TextNode(c) - elif cmdname == '\\': - return BreakNode() - raise ParserError('no handler for \\%s command' % cmdname, - self.tokens.peek()[0]) - - def handle_begin(self): - envname, = self.parse_args('begin', 'T') - handler = getattr(self, 'handle_%s_env' % envname.text, None) - if not handler: - raise ParserError('no handler for %s environment' % envname.text, - self.tokens.peek()[0]) - return handler() - - # ------------------------- command handlers ----------------------------- - - def mk_metadata_handler(self, name, mdname=None): - if mdname is None: - mdname = name - def handler(self): - data, = self.parse_args('\\'+name, 'M') - self.rootnode.params[mdname] = data - return EmptyNode() - return handler - - handle_title = mk_metadata_handler(None, 'title') - handle_author = mk_metadata_handler(None, 'author') - handle_authoraddress = mk_metadata_handler(None, 'authoraddress') - handle_date = mk_metadata_handler(None, 'date') - handle_release = mk_metadata_handler(None, 'release') - handle_setshortversion = mk_metadata_handler(None, 'setshortversion', - 'shortversion') - handle_setreleaseinfo = mk_metadata_handler(None, 'setreleaseinfo', - 'releaseinfo') - - def handle_note(self): - note = self.parse_args('\\note', 'M')[0] - return EnvironmentNode('notice', [TextNode('note')], note) - - def handle_warning(self): - warning = self.parse_args('\\warning', 'M')[0] - return EnvironmentNode('notice', [TextNode('warning')], warning) - - def handle_ifx(self): - for l, t, v, r in self.tokens: - if t == 'command' and v == 'fi': - break - return EmptyNode() - - def handle_c(self): - return self.handle_special_command('c') - - def handle_mbox(self): - return self.parse_args('\\mbox', 'M')[0] - - def handle_leftline(self): - return self.parse_args('\\leftline', 'M')[0] - - def handle_Large(self): - return self.parse_args('\\Large', 'M')[0] - - def handle_pytype(self): - # \pytype{x} is synonymous to \class{x} now - return self.handle_class() - - def handle_nodename(self): - return self.handle_label() - - def handle_verb(self): - # skip delimiter - l, t, v, r = self.tokens.next() - l, t, v, r = self.tokens.next() - assert t == 'text' - node = InlineNode('code', [TextNode(r)]) - # skip delimiter - l, t, v, r = self.tokens.next() - return node - - def handle_locallinewidth(self): - return EmptyNode() - - def handle_linewidth(self): - return EmptyNode() - - def handle_setlength(self): - self.parse_args('\\setlength', 'MM') - return EmptyNode() - - def handle_stmodindex(self): - arg, = self.parse_args('\\stmodindex', 'T') - return CommandNode('declaremodule', [EmptyNode(), - TextNode(u'standard'), - arg]) - - def handle_indexname(self): - return EmptyNode() - - def handle_renewcommand(self): - self.parse_args('\\renewcommand', 'MM') - return EmptyNode() - - # ------------------------- environment handlers ------------------------- - - def handle_document_env(self): - return self.parse_until(self.environment_end) - - handle_sloppypar_env = handle_document_env - handle_flushleft_env = handle_document_env - handle_math_env = handle_document_env - - def handle_verbatim_env(self): - text = [] - for l, t, v, r in self.tokens: - if t == 'command' and v == 'end' : - tok = self.tokens.peekmany(3) - if tok[0][1] == 'bgroup' and \ - tok[1][1] == 'text' and \ - tok[1][2] == 'verbatim' and \ - tok[2][1] == 'egroup': - self.tokens.popmany(3) - break - text.append(r) - return VerbatimNode(TextNode(''.join(text))) - - # involved math markup must be corrected manually - def handle_displaymath_env(self): - text = ['XXX: translate this math'] - for l, t, v, r in self.tokens: - if t == 'command' and v == 'end' : - tok = self.tokens.peekmany(3) - if tok[0][1] == 'bgroup' and \ - tok[1][1] == 'text' and \ - tok[1][2] == 'displaymath' and \ - tok[2][1] == 'egroup': - self.tokens.popmany(3) - break - text.append(r) - return VerbatimNode(TextNode(''.join(text))) - - # alltt is different from verbatim because it allows markup - def handle_alltt_env(self): - nodelist = NodeList() - for l, t, v, r in self.tokens: - if self.environment_end(t, v): - break - if t == 'command': - if len(v) == 1 and not v.isalpha(): - nodelist.append(self.handle_special_command(v)) - continue - handler = getattr(self, 'handle_' + v, None) - if not handler: - raise ParserError('no handler for \\%s command' % v, l) - nodelist.append(handler()) - elif t == 'comment': - nodelist.append(CommentNode(v)) - else: - # all else is appended raw - nodelist.append(TextNode(r)) - return VerbatimNode(nodelist.flatten()) - - def handle_itemize_env(self, nodetype=ItemizeNode): - items = [] - # a usecase for nonlocal :) - running = [False] - - def item_condition(t, v, bracelevel): - if self.environment_end(t, v): - del running[:] - return True - if t == 'command' and v == 'item': - return True - return False - - # the text until the first \item is discarded - self.parse_until(item_condition) - while running: - itemname, = self.parse_args('\\item', 'O') - itemcontent = self.parse_until(item_condition) - items.append([itemname, itemcontent]) - return nodetype(items) - - def handle_enumerate_env(self): - return self.handle_itemize_env(EnumerateNode) - - def handle_description_env(self): - return self.handle_itemize_env(DescriptionNode) - - def handle_definitions_env(self): - items = [] - running = [False] - - def item_condition(t, v, bracelevel): - if self.environment_end(t, v): - del running[:] - return True - if t == 'command' and v == 'term': - return True - return False - - # the text until the first \item is discarded - self.parse_until(item_condition) - while running: - itemname, = self.parse_args('\\term', 'M') - itemcontent = self.parse_until(item_condition) - items.append([itemname, itemcontent]) - return DefinitionsNode(items) - - def mk_table_handler(self, envname, numcols): - def handle_table(self): - args = self.parse_args('table'+envname, 'TT' + 'M'*numcols) - firstcolformat = args[1].text - headings = args[2:] - lines = [] - for l, t, v, r in self.tokens: - # XXX: everything outside of \linexxx is lost here - if t == 'command': - if v == 'line'+envname: - lines.append(self.parse_args('\\line'+envname, - 'M'*numcols)) - elif v == 'end': - arg = self.parse_args('\\end', 'T') - assert arg[0].text.endswith('table'+envname), arg[0].text - break - for line in lines: - if not empty(line[0]): - line[0] = InlineNode(firstcolformat, [line[0]]) - return TableNode(numcols, headings, lines) - return handle_table - - handle_tableii_env = mk_table_handler(None, 'ii', 2) - handle_longtableii_env = handle_tableii_env - handle_tableiii_env = mk_table_handler(None, 'iii', 3) - handle_longtableiii_env = handle_tableiii_env - handle_tableiv_env = mk_table_handler(None, 'iv', 4) - handle_longtableiv_env = handle_tableiv_env - handle_tablev_env = mk_table_handler(None, 'v', 5) - handle_longtablev_env = handle_tablev_env - - def handle_productionlist_env(self): - env_args = self.parse_args('productionlist', 'Q') - items = [] - for l, t, v, r in self.tokens: - # XXX: everything outside of \production is lost here - if t == 'command': - if v == 'production': - items.append(self.parse_args('\\production', 'TM')) - elif v == 'productioncont': - args = self.parse_args('\\productioncont', 'M') - args.insert(0, EmptyNode()) - items.append(args) - elif v == 'end': - arg = self.parse_args('\\end', 'T') - assert arg[0].text == 'productionlist' - break - node = ProductionListNode(items) - # the argument specifies a production group - node.arg = env_args[0] - return node - - def environment_end(self, t, v, bracelevel=0): - if t == 'command' and v == 'end': - self.parse_args('\\end', 'T') - return True - return False diff --git a/converter/newfiles/ACKS b/converter/newfiles/ACKS deleted file mode 100644 index 1e10a219..00000000 --- a/converter/newfiles/ACKS +++ /dev/null @@ -1,197 +0,0 @@ -Contributors to the Python Documentation ----------------------------------------- - -This file lists people who have contributed in some way to the Python -documentation. It is probably not complete -- if you feel that you or -anyone else should be on this list, please let us know (send email to -docs@python.org), and we'll be glad to correct the problem. - -It is only with the input and contributions of the Python community -that Python has such wonderful documentation -- Thank You! - - -* Aahz -* Michael Abbott -* Steve Alexander -* Jim Ahlstrom -* Fred Allen -* A. Amoroso -* Pehr Anderson -* Oliver Andrich -* Jesús Cea Avión -* Daniel Barclay -* Chris Barker -* Don Bashford -* Anthony Baxter -* Bennett Benson -* Jonathan Black -* Robin Boerdijk -* Michal Bozon -* Aaron Brancotti -* Keith Briggs -* Lee Busby -* Lorenzo M. Catucci -* Mauro Cicognini -* Gilles Civario -* Mike Clarkson -* Steve Clift -* Dave Cole -* Matthew Cowles -* Jeremy Craven -* Andrew Dalke -* Ben Darnell -* L. Peter Deutsch -* Robert Donohue -* Fred L. Drake, Jr. -* Jeff Epler -* Michael Ernst -* Blame Andy Eskilsson -* Carey Evans -* Martijn Faassen -* Carl Feynman -* Hernán Martínez Foffani -* Stefan Franke -* Jim Fulton -* Peter Funk -* Lele Gaifax -* Matthew Gallagher -* Ben Gertzfield -* Nadim Ghaznavi -* Jonathan Giddy -* Shelley Gooch -* Nathaniel Gray -* Grant Griffin -* Thomas Guettler -* Anders Hammarquist -* Mark Hammond -* Harald Hanche-Olsen -* Manus Hand -* Gerhard Häring -* Travis B. Hartwell -* Janko Hauser -* Bernhard Herzog -* Magnus L. Hetland -* Konrad Hinsen -* Stefan Hoffmeister -* Albert Hofkamp -* Gregor Hoffleit -* Steve Holden -* Thomas Holenstein -* Gerrit Holl -* Rob Hooft -* Brian Hooper -* Randall Hopper -* Michael Hudson -* Eric Huss -* Jeremy Hylton -* Roger Irwin -* Jack Jansen -* Philip H. Jensen -* Pedro Diaz Jimenez -* Kent Johnson -* Lucas de Jonge -* Andreas Jung -* Robert Kern -* Jim Kerr -* Jan Kim -* Greg Kochanski -* Guido Kollerie -* Peter A. Koren -* Daniel Kozan -* Andrew M. Kuchling -* Dave Kuhlman -* Erno Kuusela -* Detlef Lannert -* Piers Lauder -* Glyph Lefkowitz -* Marc-André Lemburg -* Ulf A. Lindgren -* Everett Lipman -* Mirko Liss -* Martin von Löwis -* Fredrik Lundh -* Jeff MacDonald -* John Machin -* Andrew MacIntyre -* Vladimir Marangozov -* Vincent Marchetti -* Laura Matson -* Daniel May -* Doug Mennella -* Paolo Milani -* Skip Montanaro -* Paul Moore -* Ross Moore -* Sjoerd Mullender -* Dale Nagata -* Ng Pheng Siong -* Koray Oner -* Tomas Oppelstrup -* Denis S. Otkidach -* Zooko O'Whielacronx -* William Park -* Joonas Paalasmaa -* Harri Pasanen -* Bo Peng -* Tim Peters -* Christopher Petrilli -* Justin D. Pettit -* Chris Phoenix -* François Pinard -* Paul Prescod -* Eric S. Raymond -* Edward K. Ream -* Sean Reifschneider -* Bernhard Reiter -* Armin Rigo -* Wes Rishel -* Jim Roskind -* Guido van Rossum -* Donald Wallace Rouse II -* Nick Russo -* Chris Ryland -* Constantina S. -* Hugh Sasse -* Bob Savage -* Scott Schram -* Neil Schemenauer -* Barry Scott -* Joakim Sernbrant -* Justin Sheehy -* Michael Simcich -* Ionel Simionescu -* Gregory P. Smith -* Roy Smith -* Clay Spence -* Nicholas Spies -* Tage Stabell-Kulo -* Frank Stajano -* Anthony Starks -* Greg Stein -* Peter Stoehr -* Mark Summerfield -* Reuben Sumner -* Kalle Svensson -* Jim Tittsler -* Ville Vainio -* Martijn Vries -* Charles G. Waldman -* Greg Ward -* Barry Warsaw -* Corran Webster -* Glyn Webster -* Bob Weiner -* Eddy Welbourne -* Mats Wichmann -* Gerry Wiener -* Timothy Wild -* Collin Winter -* Blake Winton -* Dan Wolfe -* Steven Work -* Thomas Wouters -* Ka-Ping Yee -* Rory Yorke -* Moshe Zadka -* Milan Zamazal -* Cheng Zhang diff --git a/converter/newfiles/TODO b/converter/newfiles/TODO deleted file mode 100644 index 73b3ab2a..00000000 --- a/converter/newfiles/TODO +++ /dev/null @@ -1,18 +0,0 @@ -To do after conversion -====================== - -* fix all references and links marked with `XXX` -* adjust all literal include paths -* remove all non-literal includes -* fix all duplicate labels and undefined label references -* fix the email package docs: add a toctree -* split very large files and add toctrees -* integrate standalone HOWTOs -* find out which files get "comments disabled" metadata -* double backslashes in production lists -* add synopses for each module -* write "About these documents" -* finish "Documenting Python" -* extend copyright.rst -* fix the "quadruple" index term -* fix :file: and |version| in install
\ No newline at end of file diff --git a/converter/newfiles/about.rst b/converter/newfiles/about.rst deleted file mode 100644 index f828e46a..00000000 --- a/converter/newfiles/about.rst +++ /dev/null @@ -1,18 +0,0 @@ -===================== -About these documents -===================== - -These documents are generated from `reStructuredText -<http://docutils.sf.net/rst.html>`_ sources by *Sphinx*, a document processor -specifically written for the Python documentation. - -In the online version of these documents, you can submit comments and suggest -changes directly on the documentation pages. - -Development of the documentation and its toolchain takes place on the -docs@python.org mailing list. We're always looking for volunteers wanting -to help with the docs, so feel free to send a mail there! - -See :ref:`reporting-bugs` for information how to report bugs in Python itself. - -.. include:: ACKS
\ No newline at end of file diff --git a/converter/newfiles/api_index.rst b/converter/newfiles/api_index.rst deleted file mode 100644 index c6433125..00000000 --- a/converter/newfiles/api_index.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _c-api-index: - -################################## - Python/C API Reference Manual -################################## - -:Release: |version| -:Date: |today| - -This manual documents the API used by C and C++ programmers who want to write -extension modules or embed Python. It is a companion to :ref:`extending-index`, -which describes the general principles of extension writing but does not -document the API functions in detail. - -.. warning:: - - The current version of this document is somewhat incomplete. However, most of - the important functions, types and structures are described. - - -.. toctree:: - :maxdepth: 2 - - intro.rst - veryhigh.rst - refcounting.rst - exceptions.rst - utilities.rst - abstract.rst - concrete.rst - init.rst - memory.rst - newtypes.rst diff --git a/converter/newfiles/conf.py b/converter/newfiles/conf.py deleted file mode 100644 index b54a53e0..00000000 --- a/converter/newfiles/conf.py +++ /dev/null @@ -1,47 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Python documentation build configuration file -# -# The contents of this file are pickled, so don't put values in the namespace -# that aren't pickleable (module imports are okay, they're removed automatically). -# - -# The default replacements for |version| and |release|. -# If 'auto', Sphinx looks for the Include/patchlevel.h file in the current Python -# source tree and replaces the values accordingly. -# -# The short X.Y version. -# version = '2.6' -version = 'auto' -# The full version, including alpha/beta/rc tags. -# release = '2.6a0' -release = 'auto' - -# There are two options for replacing |today|: either, you set today to some -# non-false value, then it is used: -today = '' -# Else, today_fmt is used as the format for a strftime call. -today_fmt = '%B %d, %Y' - -# List of files that shouldn't be included in the build. -unused_files = [ - 'whatsnew/2.0.rst', - 'whatsnew/2.1.rst', - 'whatsnew/2.2.rst', - 'whatsnew/2.3.rst', - 'whatsnew/2.4.rst', - 'whatsnew/2.5.rst', - 'maclib/scrap.rst', - 'library/xmllib.rst', -] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -last_updated_format = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -use_smartypants = True - -# If true, '()' will be appended to :func: etc. cross-reference text. -add_function_parentheses = True diff --git a/converter/newfiles/contents.rst b/converter/newfiles/contents.rst deleted file mode 100644 index aebe1ab9..00000000 --- a/converter/newfiles/contents.rst +++ /dev/null @@ -1,21 +0,0 @@ -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - Python Documentation contents -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -.. toctree:: - - whatsnew/2.6.rst - tutorial/index.rst - reference/index.rst - library/index.rst - maclib/index.rst - extending/index.rst - c-api/index.rst - distutils/index.rst - install/index.rst - documenting/index.rst - - bugs.rst - about.rst - license.rst - copyright.rst diff --git a/converter/newfiles/dist_index.rst b/converter/newfiles/dist_index.rst deleted file mode 100644 index 34eef86d..00000000 --- a/converter/newfiles/dist_index.rst +++ /dev/null @@ -1,28 +0,0 @@ -.. _distutils-index: - -############################### - Distributing Python Modules -############################### - -:Release: |version| -:Date: |today| - -This document describes the Python Distribution Utilities ("Distutils") from -the module developer's point of view, describing how to use the Distutils to -make Python modules and extensions easily available to a wider audience with -very little overhead for build/release/install mechanics. - -.. toctree:: - :maxdepth: 2 - - introduction.rst - setupscript.rst - configfile.rst - sourcedist.rst - builtdist.rst - packageindex.rst - uploading.rst - examples.rst - extending.rst - commandref.rst - apiref.rst diff --git a/converter/newfiles/doc.rst b/converter/newfiles/doc.rst deleted file mode 100644 index 1a3778b0..00000000 --- a/converter/newfiles/doc.rst +++ /dev/null @@ -1,33 +0,0 @@ -.. _documenting-index: - -###################### - Documenting Python -###################### - - -The Python language has a substantial body of documentation, much of it -contributed by various authors. The markup used for the Python documentation is -`reStructuredText`_, developed by the `docutils`_ project, amended by custom -directives and using a toolset named *Sphinx* to postprocess the HTML output. - -This document describes the style guide for our documentation, the custom -reStructuredText markup introduced to support Python documentation and how it -should be used, as well as the Sphinx build system. - -.. _reStructuredText: http://docutils.sf.net/rst.html -.. _docutils: http://docutils.sf.net/ - -If you're interested in contributing to Python's documentation, there's no need -to write reStructuredText if you're not so inclined; plain text contributions -are more than welcome as well. - -.. toctree:: - - intro.rst - style.rst - rest.rst - markup.rst - sphinx.rst - -.. XXX add credits, thanks etc. - diff --git a/converter/newfiles/doc_intro.rst b/converter/newfiles/doc_intro.rst deleted file mode 100644 index e02ad7de..00000000 --- a/converter/newfiles/doc_intro.rst +++ /dev/null @@ -1,29 +0,0 @@ -Introduction -============ - -Python's documentation has long been considered to be good for a free -programming language. There are a number of reasons for this, the most -important being the early commitment of Python's creator, Guido van Rossum, to -providing documentation on the language and its libraries, and the continuing -involvement of the user community in providing assistance for creating and -maintaining documentation. - -The involvement of the community takes many forms, from authoring to bug reports -to just plain complaining when the documentation could be more complete or -easier to use. - -This document is aimed at authors and potential authors of documentation for -Python. More specifically, it is for people contributing to the standard -documentation and developing additional documents using the same tools as the -standard documents. This guide will be less useful for authors using the Python -documentation tools for topics other than Python, and less useful still for -authors not using the tools at all. - -If your interest is in contributing to the Python documentation, but you don't -have the time or inclination to learn reStructuredText and the markup structures -documented here, there's a welcoming place for you among the Python contributors -as well. Any time you feel that you can clarify existing documentation or -provide documentation that's missing, the existing documentation team will -gladly work with you to integrate your text, dealing with the markup for you. -Please don't let the material in this document stand between the documentation -and your desire to help out!
\ No newline at end of file diff --git a/converter/newfiles/doc_markup.rst b/converter/newfiles/doc_markup.rst deleted file mode 100644 index a1658e95..00000000 --- a/converter/newfiles/doc_markup.rst +++ /dev/null @@ -1,742 +0,0 @@ -.. highlightlang:: rest - -Additional Markup Constructs -============================ - -Sphinx adds a lot of new directives and interpreted text roles to standard reST -markup. This section contains the reference material for these facilities. -Documentation for "standard" reST constructs is not included here, though -they are used in the Python documentation. - -XXX: file-wide metadata - -Meta-information markup ------------------------ - -.. describe:: sectionauthor - - Identifies the author of the current section. The argument should include - the author's name such that it can be used for presentation (though it isn't) - and email address. The domain name portion of the address should be lower - case. Example:: - - .. sectionauthor:: Guido van Rossum <guido@python.org> - - Currently, this markup isn't reflected in the output in any way, but it helps - keep track of contributions. - - -Module-specific markup ----------------------- - -The markup described in this section is used to provide information about a -module being documented. Each module should be documented in its own file. -Normally this markup appears after the title heading of that file; a typical -file might start like this:: - - :mod:`parrot` -- Dead parrot access - =================================== - - .. module:: parrot - :platform: Unix, Windows - :synopsis: Analyze and reanimate dead parrots. - .. moduleauthor:: Eric Cleese <eric@python.invalid> - .. moduleauthor:: John Idle <john@python.invalid> - -As you can see, the module-specific markup consists of two directives, the -``module`` directive and the ``moduleauthor`` directive. - -.. describe:: module - - This directive marks the beginning of the description of a module (or package - submodule, in which case the name should be fully qualified, including the - package name). - - The ``platform`` option, if present, is a comma-separated list of the - platforms on which the module is available (if it is available on all - platforms, the option should be omitted). The keys are short identifiers; - examples that are in use include "IRIX", "Mac", "Windows", and "Unix". It is - important to use a key which has already been used when applicable. - - The ``synopsis`` option should consist of one sentence describing the - module's purpose -- it is currently only used in the Global Module Index. - -.. describe:: moduleauthor - - The ``moduleauthor`` directive, which can appear multiple times, names the - authors of the module code, just like ``sectionauthor`` names the author(s) - of a piece of documentation. It too does not result in any output currently. - - -.. note:: - - It is important to make the section title of a module-describing file - meaningful since that value will be inserted in the table-of-contents trees - in overview files. - - -Information units ------------------ - -There are a number of directives used to describe specific features provided by -modules. Each directive requires one or more signatures to provide basic -information about what is being described, and the content should be the -description. The basic version makes entries in the general index; if no index -entry is desired, you can give the directive option flag ``:noindex:``. The -following example shows all of the features of this directive type:: - - .. function:: spam(eggs) - ham(eggs) - :noindex: - - Spam or ham the foo. - -The signatures of object methods or data attributes should always include the -type name (``.. method:: FileInput.input(...)``), even if it is obvious from the -context which type they belong to; this is to enable consistent -cross-references. If you describe methods belonging to an abstract protocol, -such as "context managers", include a (pseudo-)type name too to make the -index entries more informative. - -The directives are: - -.. describe:: cfunction - - Describes a C function. The signature should be given as in C, e.g.:: - - .. cfunction:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) - - This is also used to describe function-like preprocessor macros. The names - of the arguments should be given so they may be used in the description. - - Note that you don't have to backslash-escape asterisks in the signature, - as it is not parsed by the reST inliner. - -.. describe:: cmember - - Describes a C struct member. Example signature:: - - .. cmember:: PyObject* PyTypeObject.tp_bases - - The text of the description should include the range of values allowed, how - the value should be interpreted, and whether the value can be changed. - References to structure members in text should use the ``member`` role. - -.. describe:: cmacro - - Describes a "simple" C macro. Simple macros are macros which are used - for code expansion, but which do not take arguments so cannot be described as - functions. This is not to be used for simple constant definitions. Examples - of its use in the Python documentation include :cmacro:`PyObject_HEAD` and - :cmacro:`Py_BEGIN_ALLOW_THREADS`. - -.. describe:: ctype - - Describes a C type. The signature should just be the type name. - -.. describe:: cvar - - Describes a global C variable. The signature should include the type, such - as:: - - .. cvar:: PyObject* PyClass_Type - -.. describe:: data - - Describes global data in a module, including both variables and values used - as "defined constants." Class and object attributes are not documented - using this environment. - -.. describe:: exception - - Describes an exception class. The signature can, but need not include - parentheses with constructor arguments. - -.. describe:: function - - Describes a module-level function. The signature should include the - parameters, enclosing optional parameters in brackets. Default values can be - given if it enhances clarity. For example:: - - .. function:: Timer.repeat([repeat=3[, number=1000000]]) - - Object methods are not documented using this directive. Bound object methods - placed in the module namespace as part of the public interface of the module - are documented using this, as they are equivalent to normal functions for - most purposes. - - The description should include information about the parameters required and - how they are used (especially whether mutable objects passed as parameters - are modified), side effects, and possible exceptions. A small example may be - provided. - -.. describe:: class - - Describes a class. The signature can include parentheses with parameters - which will be shown as the constructor arguments. - -.. describe:: attribute - - Describes an object data attribute. The description should include - information about the type of the data to be expected and whether it may be - changed directly. - -.. describe:: method - - Describes an object method. The parameters should not include the ``self`` - parameter. The description should include similar information to that - described for ``function``. - -.. describe:: opcode - - Describes a Python bytecode instruction. - - -There is also a generic version of these directives: - -.. describe:: describe - - This directive produces the same formatting as the specific ones explained - above but does not create index entries or cross-referencing targets. It is - used, for example, to describe the directives in this document. Example:: - - .. describe:: opcode - - Describes a Python bytecode instruction. - - -Showing code examples ---------------------- - -Examples of Python source code or interactive sessions are represented using -standard reST literal blocks. They are started by a ``::`` at the end of the -preceding paragraph and delimited by indentation. - -Representing an interactive session requires including the prompts and output -along with the Python code. No special markup is required for interactive -sessions. After the last line of input or output presented, there should not be -an "unused" primary prompt; this is an example of what *not* to do:: - - >>> 1 + 1 - 2 - >>> - -Syntax highlighting is handled in a smart way: - -* There is a "highlighting language" for each source file. Per default, - this is ``'python'`` as the majority of files will have to highlight Python - snippets. - -* Within Python highlighting mode, interactive sessions are recognized - automatically and highlighted appropriately. - -* The highlighting language can be changed using the ``highlightlang`` - directive, used as follows:: - - .. highlightlang:: c - - This language is used until the next ``highlightlang`` directive is - encountered. - -* The valid values for the highlighting language are: - - * ``python`` (the default) - * ``c`` - * ``rest`` - * ``none`` (no highlighting) - -* If highlighting with the current language fails, the block is not highlighted - in any way. - -Longer displays of verbatim text may be included by storing the example text in -an external file containing only plain text. The file may be included using the -standard ``include`` directive with the ``literal`` option flag. For example, -to include the Python source file :file:`example.py`, use:: - - .. include:: example.py - :literal: - - -Inline markup -------------- - -As said before, Sphinx uses interpreted text roles to insert semantic markup in -documents. - -The default role is ``var``, as that was one of the most common macros used in -the old LaTeX docs. That means that you can use ```var``` to refer to a -variable named "var". - -For all other roles, you have to write ``:rolename:`content```. - -The following roles refer to objects in modules and are possibly hyperlinked if -a matching identifier is found: - -.. describe:: mod - - The name of a module; a dotted name may be used. This should also be used for - package names. - -.. describe:: func - - The name of a Python function; dotted names may be used. The role text - should include trailing parentheses to enhance readability. The parentheses - are stripped when searching for identifiers. - -.. describe:: data - - The name of a module-level variable. - -.. describe:: const - - The name of a "defined" constant. This may be a C-language ``#define`` - or a Python variable that is not intended to be changed. - -.. describe:: class - - A class name; a dotted name may be used. - -.. describe:: meth - - The name of a method of an object. The role text should include the type - name, method name and the trailing parentheses. A dotted name may be used. - -.. describe:: attr - - The name of a data attribute of an object. - -.. describe:: exc - - The name of an exception. A dotted name may be used. - -The name enclosed in this markup can include a module name and/or a class name. -For example, ``:func:`filter``` could refer to a function named ``filter`` in -the current module, or the built-in function of that name. In contrast, -``:func:`foo.filter``` clearly refers to the ``filter`` function in the ``foo`` -module. - -A similar heuristic is used to determine whether the name is an attribute of -the currently documented class. - -The following roles create cross-references to C-language constructs if they -are defined in the API documentation: - -.. describe:: cdata - - The name of a C-language variable. - -.. describe:: cfunc - - The name of a C-language function. Should include trailing parentheses. - -.. describe:: cmacro - - The name of a "simple" C macro, as defined above. - -.. describe:: ctype - - The name of a C-language type. - - -The following role does possibly create a cross-reference, but does not refer -to objects: - -.. describe:: token - - The name of a grammar token (used in the reference manual to create links - between production displays). - ---------- - -The following roles don't do anything special except formatting the text -in a different style: - -.. describe:: command - - The name of an OS-level command, such as ``rm``. - -.. describe:: dfn - - Mark the defining instance of a term in the text. (No index entries are - generated.) - -.. describe:: envvar - - An environment variable. Index entries are generated. - -.. describe:: file - - The name of a file or directory. Within the contents, you can use curly - braces to indicate a "variable" part, for example:: - - ... is installed in :file:`/usr/lib/python2.{x}/site-packages` ... - - In the built documentation, the ``x`` will be displayed differently to - indicate that it is to be replaced by the Python minor version. - -.. describe:: guilabel - - Labels presented as part of an interactive user interface should be marked - using ``guilabel``. This includes labels from text-based interfaces such as - those created using :mod:`curses` or other text-based libraries. Any label - used in the interface should be marked with this role, including button - labels, window titles, field names, menu and menu selection names, and even - values in selection lists. - -.. describe:: kbd - - Mark a sequence of keystrokes. What form the key sequence takes may depend - on platform- or application-specific conventions. When there are no relevant - conventions, the names of modifier keys should be spelled out, to improve - accessibility for new users and non-native speakers. For example, an - *xemacs* key sequence may be marked like ``:kbd:`C-x C-f```, but without - reference to a specific application or platform, the same sequence should be - marked as ``:kbd:`Control-x Control-f```. - -.. describe:: keyword - - The name of a keyword in a programming language. - -.. describe:: mailheader - - The name of an RFC 822-style mail header. This markup does not imply that - the header is being used in an email message, but can be used to refer to any - header of the same "style." This is also used for headers defined by the - various MIME specifications. The header name should be entered in the same - way it would normally be found in practice, with the camel-casing conventions - being preferred where there is more than one common usage. For example: - ``:mailheader:`Content-Type```. - -.. describe:: makevar - - The name of a :command:`make` variable. - -.. describe:: manpage - - A reference to a Unix manual page including the section, - e.g. ``:manpage:`ls(1)```. - -.. describe:: menuselection - - Menu selections should be marked using the ``menuselection`` role. This is - used to mark a complete sequence of menu selections, including selecting - submenus and choosing a specific operation, or any subsequence of such a - sequence. The names of individual selections should be separated by - ``-->``. - - For example, to mark the selection "Start > Programs", use this markup:: - - :menuselection:`Start --> Programs` - - When including a selection that includes some trailing indicator, such as the - ellipsis some operating systems use to indicate that the command opens a - dialog, the indicator should be omitted from the selection name. - -.. describe:: mimetype - - The name of a MIME type, or a component of a MIME type (the major or minor - portion, taken alone). - -.. describe:: newsgroup - - The name of a Usenet newsgroup. - -.. describe:: option - - A command-line option to an executable program. The leading hyphen(s) must - be included. - -.. describe:: program - - The name of an executable program. This may differ from the file name for - the executable for some platforms. In particular, the ``.exe`` (or other) - extension should be omitted for Windows programs. - -.. describe:: regexp - - A regular expression. Quotes should not be included. - -.. describe:: var - - A Python or C variable or parameter name. - - -The following roles generate external links: - -.. describe:: pep - - A reference to a Python Enhancement Proposal. This generates appropriate - index entries. The text "PEP *number*\ " is generated; in the HTML output, - this text is a hyperlink to an online copy of the specified PEP. - -.. describe:: rfc - - A reference to an Internet Request for Comments. This generates appropriate - index entries. The text "RFC *number*\ " is generated; in the HTML output, - this text is a hyperlink to an online copy of the specified RFC. - - -Note that there are no special roles for including hyperlinks as you can use -the standard reST markup for that purpose. - - -.. _doc-ref-role: - -Cross-linking markup --------------------- - -To support cross-referencing to arbitrary sections in the documentation, the -standard reST labels are "abused" a bit: Every label must precede a section -title; and every label name must be unique throughout the entire documentation -source. - -You can then reference to these sections using the ``:ref:`label-name``` role. - -Example:: - - .. _my-reference-label: - - Section to cross-reference - -------------------------- - - This is the text of the section. - - It refers to the section itself, see :ref:`my-reference-label`. - -The ``:ref:`` invocation is replaced with the section title. - - -Paragraph-level markup ----------------------- - -These directives create short paragraphs and can be used inside information -units as well as normal text: - -.. describe:: note - - An especially important bit of information about an API that a user should be - aware of when using whatever bit of API the note pertains to. The content of - the directive should be written in complete sentences and include all - appropriate punctuation. - - Example:: - - .. note:: - - This function is not suitable for sending spam e-mails. - -.. describe:: warning - - An important bit of information about an API that a user should be very aware - of when using whatever bit of API the warning pertains to. The content of - the directive should be written in complete sentences and include all - appropriate punctuation. This differs from ``note`` in that it is recommended - over ``note`` for information regarding security. - -.. describe:: versionadded - - This directive documents the version of Python which added the described - feature to the library or C API. When this applies to an entire module, it - should be placed at the top of the module section before any prose. - - The first argument must be given and is the version in question; you can add - a second argument consisting of a *brief* explanation of the change. - - Example:: - - .. versionadded:: 2.5 - The `spam` parameter. - - Note that there must be no blank line between the directive head and the - explanation; this is to make these blocks visually continuous in the markup. - -.. describe:: versionchanged - - Similar to ``versionadded``, but describes when and what changed in the named - feature in some way (new parameters, changed side effects, etc.). - --------------- - -.. describe:: seealso - - Many sections include a list of references to module documentation or - external documents. These lists are created using the ``seealso`` directive. - - The ``seealso`` directive is typically placed in a section just before any - sub-sections. For the HTML output, it is shown boxed off from the main flow - of the text. - - The content of the ``seealso`` directive should be a reST definition list. - Example:: - - .. seealso:: - - Module :mod:`zipfile` - Documentation of the :mod:`zipfile` standard module. - - `GNU tar manual, Basic Tar Format <http://link>`_ - Documentation for tar archive files, including GNU tar extensions. - -.. describe:: rubric - - This directive creates a paragraph heading that is not used to create a - table of contents node. It is currently used for the "Footnotes" caption. - -.. describe:: centered - - This directive creates a centered boldfaced paragraph. Use it as follows:: - - .. centered:: - - Paragraph contents. - - -Table-of-contents markup ------------------------- - -Since reST does not have facilities to interconnect several documents, or split -documents into multiple output files, Sphinx uses a custom directive to add -relations between the single files the documentation is made of, as well as -tables of contents. The ``toctree`` directive is the central element. - -.. describe:: toctree - - This directive inserts a "TOC tree" at the current location, using the - individual TOCs (including "sub-TOC trees") of the files given in the - directive body. A numeric ``maxdepth`` option may be given to indicate the - depth of the tree; by default, all levels are included. - - Consider this example (taken from the library reference index):: - - .. toctree:: - :maxdepth: 2 - - intro.rst - strings.rst - datatypes.rst - numeric.rst - (many more files listed here) - - This accomplishes two things: - - * Tables of contents from all those files are inserted, with a maximum depth - of two, that means one nested heading. ``toctree`` directives in those - files are also taken into account. - * Sphinx knows that the relative order of the files ``intro.rst``, - ``strings.rst`` and so forth, and it knows that they are children of the - shown file, the library index. From this information it generates "next - chapter", "previous chapter" and "parent chapter" links. - - In the end, all files included in the build process must occur in one - ``toctree`` directive; Sphinx will emit a warning if it finds a file that is - not included, because that means that this file will not be reachable through - standard navigation. - - The special file ``contents.rst`` at the root of the source directory is the - "root" of the TOC tree hierarchy; from it the "Contents" page is generated. - - -Index-generating markup ------------------------ - -Sphinx automatically creates index entries from all information units (like -functions, classes or attributes) like discussed before. - -However, there is also an explicit directive available, to make the index more -comprehensive and enable index entries in documents where information is not -mainly contained in information units, such as the language reference. - -The directive is ``index`` and contains one or more index entries. Each entry -consists of a type and a value, separated by a colon. - -For example:: - - .. index:: - single: execution!context - module: __main__ - module: sys - triple: module; search; path - -This directive contains five entries, which will be converted to entries in the -generated index which link to the exact location of the index statement (or, in -case of offline media, the corresponding page number). - -The possible entry types are: - -single - Creates a single index entry. Can be made a subentry by separating the - subentry text with a semicolon (this is also used below to describe what - entries are created). -pair - ``pair: loop; statement`` is a shortcut that creates two index entries, - namely ``loop; statement`` and ``statement; loop``. -triple - Likewise, ``triple: module; search; path`` is a shortcut that creates three - index entries, which are ``module; search path``, ``search; path, module`` and - ``path; module search``. -module, keyword, operator, object, exception, statement, builtin - These all create two index entries. For example, ``module: hashlib`` creates - the entries ``module; hashlib`` and ``hashlib; module``. - - -Grammar production displays ---------------------------- - -Special markup is available for displaying the productions of a formal grammar. -The markup is simple and does not attempt to model all aspects of BNF (or any -derived forms), but provides enough to allow context-free grammars to be -displayed in a way that causes uses of a symbol to be rendered as hyperlinks to -the definition of the symbol. There is this directive: - -.. describe:: productionlist - - This directive is used to enclose a group of productions. Each production is - given on a single line and consists of a name, separated by a colon from the - following definition. If the definition spans multiple lines, each - continuation line must begin with a colon placed at the same column as in the - first line. - - Blank lines are not allowed within ``productionlist`` directive arguments. - - The definition can contain token names which are marked as interpreted text - (e.g. ``sum ::= `integer` "+" `integer```) -- this generates cross-references - to the productions of these tokens. Note that vertical bars used to indicate - alternatives must be escaped with backslashes because otherwise they would - indicate a substitution reference to the reST parser. - - -.. XXX describe optional first parameter - -The following is an example taken from the Python Reference Manual:: - - .. productionlist:: - try_stmt: try1_stmt \| try2_stmt - try1_stmt: "try" ":" :token:`suite` - : ("except" [:token:`expression` ["," :token:`target`]] ":" :token:`suite`)+ - : ["else" ":" :token:`suite`] - : ["finally" ":" :token:`suite`] - try2_stmt: "try" ":" :token:`suite` - : "finally" ":" :token:`suite` - - -Substitutions -------------- - -The documentation system provides three substitutions that are defined by default. -They are set in the build configuration file, see :ref:`doc-build-config`. - -.. describe:: |release| - - Replaced by the Python release the documentation refers to. This is the full - version string including alpha/beta/release candidate tags, e.g. ``2.5.2b3``. - -.. describe:: |version| - - Replaced by the Python version the documentation refers to. This consists - only of the major and minor version parts, e.g. ``2.5``, even for version - 2.5.1. - -.. describe:: |today| - - Replaced by either today's date, or the date set in the build configuration - file. Normally has the format ``April 14, 2007``. diff --git a/converter/newfiles/doc_rest.rst b/converter/newfiles/doc_rest.rst deleted file mode 100644 index 11d111f5..00000000 --- a/converter/newfiles/doc_rest.rst +++ /dev/null @@ -1,232 +0,0 @@ -.. highlightlang:: rest - -reStructuredText Primer -======================= - -This section is a brief introduction to reStructuredText (reST) concepts and -syntax, intended to provide authors with enough information to author -documents productively. -Since reST was designed to be a simple, unobtrusive markup language, this will -not take too long. - -.. seealso:: - - The authoritative `reStructuredText User - Documentation <http://docutils.sourceforge.net/rst.html>`_. - - -Paragraphs ----------- - -The paragraph is the most basic block in a reST document. -Paragraphs are simply chunks of text -separated by one or more blank lines. As in Python, indentation is significant -in reST, so all lines of the same paragraph must be left-aligned -to the same level of indentation. - - -Inline markup -------------- - -The standard reST inline markup is quite simple: use - -* one asterisk: ``*text*`` for emphasis (italics), -* two asterisks: ``**text**`` for strong emphasis (boldface), and -* backquotes: ````text```` for code samples. - -If asterisks or backquotes appear in running text and could be confused with -inline markup delimiters, they have to be escaped with a backslash. - -Be aware of some restrictions of this markup: - -* it may not be nested, -* content may not start or end with whitespace: ``* text*`` is wrong, -* it must be separated from surrounding text by non-word characters. Use a - backslash escaped space to work around that: ``thisis\ *one*\ word``. - -These restrictions may be lifted in future versions of the docutils. - -reST also allows for custom "interpreted text roles"', which signify that the -enclosed text should be interpreted in a specific way. Sphinx uses this to -provide semantic markup and cross-referencing of identifiers, as described in -the appropriate section. The general syntax is ``:rolename:`content```. - - -Lists and Quotes ----------------- - -List markup is natural: just place an asterisk at the start of a paragraph and -indent properly. The same goes for numbered lists; they can also be -autonumbered using a ``#`` sign:: - - * This is a bulleted list. - * It has two items, the second - item uses two lines. - - #. This is a numbered list. - #. It has two items too. - -Nested lists are possible, but be aware that they must be separated from the -parent list items by blank lines:: - - * this is - * a list - - * with a nested list - * and some subitems - - * and here the parent list continues - -Definition lists are created as follows:: - - term (up to a line of text) - Definition of the term, which must be indented - - and can even consist of multiple paragraphs - - next term - Description. - - -Paragraphs are quoted by just indenting them more than the surrounding -paragraphs. - - -Source Code ------------ - -Literal code blocks are introduced by ending a paragraph with the special marker -``::``. The literal block must be indented, to be able to include blank lines:: - - This is a normal text paragraph. The next paragraph is a code sample:: - - It is not processed in any way, except - that the indentation is removed. - - It can span multiple lines. - - This is a normal text paragraph again. - -The handling of the ``::`` marker is smart: - -* If it occurs as a paragraph of its own, that paragraph is completely left - out of the document. -* If it is preceded by whitespace, the marker is removed. -* If it is preceded by non-whitespace, the marker is replaced by a single - colon. - -That way, the second sentence in the above example's first paragraph would be -rendered as "The next paragraph is a code sample:". - - -Hyperlinks ----------- - -External links -^^^^^^^^^^^^^^ - -Use ```Link text <http://target>`_`` for inline web links. If the link text -should be the web address, you don't need special markup at all, the parser -finds links and mail addresses in ordinary text. - -Internal links -^^^^^^^^^^^^^^ - -Internal linking is done via a special reST role, see the section on specific -markup, :ref:`doc-ref-role`. - - -Sections --------- - -Section headers are created by underlining (and optionally overlining) the -section title with a punctuation character, at least as long as the text:: - - ================= - This is a heading - ================= - -Normally, there are no heading levels assigned to certain characters as the -structure is determined from the succession of headings. However, for the -Python documentation, we use this convention: - -* ``#`` with overline, for parts -* ``*`` with overline, for chapters -* ``=``, for sections -* ``-``, for subsections -* ``^``, for subsubsections -* ``"``, for paragraphs - - -Explicit Markup ---------------- - -"Explicit markup" is used in reST for most constructs that need special -handling, such as footnotes, specially-highlighted paragraphs, comments, and -generic directives. - -An explicit markup block begins with a line starting with ``..`` followed by -whitespace and is terminated by the next paragraph at the same level of -indentation. (There needs to be a blank line between explicit markup and normal -paragraphs. This may all sound a bit complicated, but it is intuitive enough -when you write it.) - - -Directives ----------- - -A directive is a generic block of explicit markup. Besides roles, it is one of -the extension mechanisms of reST, and Sphinx makes heavy use of it. - -Basically, a directive consists of a name, arguments, options and content. (Keep -this terminology in mind, it is used in the next chapter describing custom -directives.) Looking at this example, :: - - .. function:: foo(x) - foo(y, z) - :bar: no - - Return a line of text input from the user. - -``function`` is the directive name. It is given two arguments here, the -remainder of the first line and the second line, as well as one option ``bar`` -(as you can see, options are given in the lines immediately following the -arguments and indicated by the colons). - -The directive content follows after a blank line and is indented relative to the -directive start. - - -Footnotes ---------- - -For footnotes, use ``[#]_`` to mark the footnote location, and add the footnote -body at the bottom of the document after a "Footnotes" rubric heading, like so:: - - Lorem ipsum [#]_ dolor sit amet ... [#]_ - - .. rubric:: Footnotes - - .. [#] Text of the first footnote. - .. [#] Text of the second footnote. - - -Comments --------- - -Every explicit markup block which isn't a valid markup construct (like the -footnotes above) is regared as a comment. - - -Source encoding ---------------- - -Since the easiest way to include special characters like em dashes or copyright -signs in reST is to directly write them as Unicode characters, one has to -specify an encoding: - -All Python documentation source files must be in UTF-8 encoding, and the HTML -documents written from them will be in that encoding as well. - - -XXX: Gotchas diff --git a/converter/newfiles/doc_sphinx.rst b/converter/newfiles/doc_sphinx.rst deleted file mode 100644 index 582bdbf7..00000000 --- a/converter/newfiles/doc_sphinx.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. highlightlang:: rest - -The Sphinx build system -======================= - -XXX: intro... - -.. _doc-build-config: - -The build configuration file ----------------------------- - -The documentation root, that is the ``Doc`` subdirectory of the source -distribution, contains a file named ``conf.py``. This file is called the "build -configuration file", and it contains several variables that are read and used -during a build run. - -These variables are: - -version : string - A string that is used as a replacement for the ``|version|`` reST - substitution. It should be the Python version the documentation refers to. - This consists only of the major and minor version parts, e.g. ``2.5``, even - for version 2.5.1. - -release : string - A string that is used as a replacement for the ``|release|`` reST - substitution. It should be the full version string including - alpha/beta/release candidate tags, e.g. ``2.5.2b3``. - -Both ``release`` and ``version`` can be ``'auto'``, which means that they are -determined at runtime from the ``Include/patchlevel.h`` file, if a complete -Python source distribution can be found, or else from the interpreter running -Sphinx. - -today_fmt : string - A ``strftime`` format that is used to format a replacement for the - ``|today|`` reST substitution. - -today : string - A string that can contain a date that should be written to the documentation - output literally. If this is nonzero, it is used instead of - ``strftime(today_fmt)``. - -unused_files : list of strings - A list of reST filenames that are to be disregarded during building. This - could be docs for temporarily disabled modules or documentation that's not - yet ready for public consumption. - -last_updated_format : string - If this is not an empty string, it will be given to ``time.strftime()`` and - written to each generated output file after "last updated on:". - -use_smartypants : bool - If true, use SmartyPants to convert quotes and dashes to the typographically - correct entities. - -add_function_parentheses : bool - If true, ``()`` will be appended to the content of ``:func:``, ``:meth:`` and - ``:cfunc:`` cross-references.
\ No newline at end of file diff --git a/converter/newfiles/doc_style.rst b/converter/newfiles/doc_style.rst deleted file mode 100644 index 64d7c36b..00000000 --- a/converter/newfiles/doc_style.rst +++ /dev/null @@ -1,57 +0,0 @@ -.. highlightlang:: rest - -Style Guide -=========== - -The Python documentation should follow the `Apple Publications Style Guide`_ -wherever possible. This particular style guide was selected mostly because it -seems reasonable and is easy to get online. - -.. _Apple Publications Style Guide: http://developer.apple.com/documentation/UserExperience/Conceptual/APStyleGuide/AppleStyleGuide2003.pdf - -Topics which are not covered in the Apple's style guide will be discussed in -this document if necessary. - -Footnotes are generally discouraged, though they may be used when they are the -best way to present specific information. When a footnote reference is added at -the end of the sentence, it should follow the sentence-ending punctuation. The -reST markup should appear something like this:: - - This sentence has a footnote reference. [#]_ This is the next sentence. - -Footnotes should be gathered at the end of a file, or if the file is very long, -at the end of a section. The docutils will automatically create backlinks to the -footnote reference. - -Footnotes may appear in the middle of sentences where appropriate. - -Many special names are used in the Python documentation, including the names of -operating systems, programming languages, standards bodies, and the like. Most -of these entities are not assigned any special markup, but the preferred -spellings are given here to aid authors in maintaining the consistency of -presentation in the Python documentation. - -Other terms and words deserve special mention as well; these conventions should -be used to ensure consistency throughout the documentation: - -CPU - For "central processing unit." Many style guides say this should be spelled - out on the first use (and if you must use it, do so!). For the Python - documentation, this abbreviation should be avoided since there's no - reasonable way to predict which occurrence will be the first seen by the - reader. It is better to use the word "processor" instead. - -POSIX - The name assigned to a particular group of standards. This is always - uppercase. - -Python - The name of our favorite programming language is always capitalized. - -Unicode - The name of a character set and matching encoding. This is always written - capitalized. - -Unix - The name of the operating system developed at AT&T Bell Labs in the early - 1970s.
\ No newline at end of file diff --git a/converter/newfiles/ext_index.rst b/converter/newfiles/ext_index.rst deleted file mode 100644 index 13332dcc..00000000 --- a/converter/newfiles/ext_index.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _extending-index: - -################################################## - Extending and Embedding the Python Interpreter -################################################## - -:Release: |version| -:Date: |today| - -This document describes how to write modules in C or C++ to extend the Python -interpreter with new modules. Those modules can define new functions but also -new object types and their methods. The document also describes how to embed -the Python interpreter in another application, for use as an extension language. -Finally, it shows how to compile and link extension modules so that they can be -loaded dynamically (at run time) into the interpreter, if the underlying -operating system supports this feature. - -This document assumes basic knowledge about Python. For an informal -introduction to the language, see :ref:`tutorial-index`. :ref:`reference-index` -gives a more formal definition of the language. :ref:`modules-index` documents -the existing object types, functions and modules (both built-in and written in -Python) that give the language its wide application range. - -For a detailed description of the whole Python/C API, see the separate -:ref:`c-api-index`. - -.. toctree:: - :maxdepth: 2 - - extending.rst - newtypes.rst - building.rst - windows.rst - embedding.rst diff --git a/converter/newfiles/mac_index.rst b/converter/newfiles/mac_index.rst deleted file mode 100644 index df7955dd..00000000 --- a/converter/newfiles/mac_index.rst +++ /dev/null @@ -1,34 +0,0 @@ -.. _maclib-index: - -############################## - Macintosh Library Modules -############################## - -:Release: |version| -:Date: |today| - -This library reference manual documents Python's extensions for the Macintosh. -It should be used in conjunction with :ref:`library-index`, which documents the -standard library and built-in types. - -This manual assumes basic knowledge about the Python language. For an informal -introduction to Python, see :ref:`tutorial-index`; :ref:`reference-index` -remains the highest authority on syntactic and semantic questions. Finally, the -manual entitled :ref:`extending-index` describes how to add new extensions to -Python and how to embed it in other applications. - -.. toctree:: - :maxdepth: 2 - - using.rst - mac.rst - macic.rst - macos.rst - macostools.rst - macui.rst - framework.rst - autogil.rst - scripting.rst - toolbox.rst - colorpicker.rst - undoc.rst diff --git a/converter/newfiles/modules_index.rst b/converter/newfiles/modules_index.rst deleted file mode 100644 index d8dd2d0a..00000000 --- a/converter/newfiles/modules_index.rst +++ /dev/null @@ -1,73 +0,0 @@ -.. _library-index: - -############################### - The Python standard library -############################### - -:Release: |version| -:Date: |today| - -While :ref:`reference-index` describes the exact syntax and semantics of the -language, it does not describe the standard library that is distributed with the -language, and which greatly enhances its immediate usability. This library -contains built-in modules (written in C) that provide access to system -functionality such as file I/O that would otherwise be inaccessible to Python -programmers, as well as modules written in Python that provide standardized -solutions for many problems that occur in everyday programming. Some of these -modules are explicitly designed to encourage and enhance the portability of -Python programs. - -This library reference manual documents Python's standard library, as well as -many optional library modules (which may or may not be available, depending on -whether the underlying platform supports them and on the configuration choices -made at compile time). It also documents the standard types of the language and -its built-in functions and exceptions, many of which are not or incompletely -documented in the Reference Manual. - - -.. toctree:: - :maxdepth: 2 - - intro.rst - functions.rst - constants.rst - objects.rst - stdtypes.rst - exceptions.rst - - strings.rst - datatypes.rst - numeric.rst - netdata.rst - markup.rst - fileformats.rst - crypto.rst - filesys.rst - archiving.rst - persistence.rst - allos.rst - someos.rst - unix.rst - ipc.rst - internet.rst - mm.rst - tkinter.rst - i18n.rst - frameworks.rst - development.rst - pdb.rst - profile.rst - hotshot.rst - timeit.rst - trace.rst - python.rst - custominterp.rst - restricted.rst - modules.rst - language.rst - compiler.rst - misc.rst - sgi.rst - sun.rst - windows.rst - undoc.rst diff --git a/converter/newfiles/ref_index.rst b/converter/newfiles/ref_index.rst deleted file mode 100644 index 18bf0537..00000000 --- a/converter/newfiles/ref_index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _reference-index: - -################################# - The Python language reference -################################# - -:Release: |version| -:Date: |today| - -This reference manual describes the syntax and "core semantics" of the -language. It is terse, but attempts to be exact and complete. The semantics of -non-essential built-in object types and of the built-in functions and modules -are described in :ref:`library-index`. For an informal introduction to the -language, see :ref:`tutorial-index`. For C or C++ programmers, two additional -manuals exist: :ref:`extending-index` describes the high-level picture of how to -write a Python extension module, and the :ref:`c-api-index` describes the -interfaces available to C/C++ programmers in detail. - -.. toctree:: - :maxdepth: 2 - - introduction.rst - lexical_analysis.rst - datamodel.rst - executionmodel.rst - expressions.rst - simple_stmts.rst - compound_stmts.rst - toplevel_components.rst - diff --git a/converter/newfiles/tutorial_index.rst b/converter/newfiles/tutorial_index.rst deleted file mode 100644 index 7309b7c7..00000000 --- a/converter/newfiles/tutorial_index.rst +++ /dev/null @@ -1,60 +0,0 @@ -.. _tutorial-index: - -###################### - The Python tutorial -###################### - -:Release: |version| -:Date: |today| - -Python is an easy to learn, powerful programming language. It has efficient -high-level data structures and a simple but effective approach to -object-oriented programming. Python's elegant syntax and dynamic typing, -together with its interpreted nature, make it an ideal language for scripting -and rapid application development in many areas on most platforms. - -The Python interpreter and the extensive standard library are freely available -in source or binary form for all major platforms from the Python Web site, -http://www.python.org/, and may be freely distributed. The same site also -contains distributions of and pointers to many free third party Python modules, -programs and tools, and additional documentation. - -The Python interpreter is easily extended with new functions and data types -implemented in C or C++ (or other languages callable from C). Python is also -suitable as an extension language for customizable applications. - -This tutorial introduces the reader informally to the basic concepts and -features of the Python language and system. It helps to have a Python -interpreter handy for hands-on experience, but all examples are self-contained, -so the tutorial can be read off-line as well. - -For a description of standard objects and modules, see the Python Library -Reference document. The Python Reference Manual gives a more formal definition -of the language. To write extensions in C or C++, read Extending and Embedding -the Python Interpreter and Python/C API Reference. There are also several books -covering Python in depth. - -This tutorial does not attempt to be comprehensive and cover every single -feature, or even every commonly used feature. Instead, it introduces many of -Python's most noteworthy features, and will give you a good idea of the -language's flavor and style. After reading it, you will be able to read and -write Python modules and programs, and you will be ready to learn more about the -various Python library modules described in the Python Library Reference. - -.. toctree:: - - appetite.rst - interpreter.rst - introduction.rst - controlflow.rst - datastructures.rst - modules.rst - inputoutput.rst - errors.rst - classes.rst - stdlib.rst - stdlib2.rst - whatnow.rst - interactive.rst - floatingpoint.rst - glossary.rst diff --git a/converter/restwriter.py b/converter/restwriter.py deleted file mode 100644 index da964c69..00000000 --- a/converter/restwriter.py +++ /dev/null @@ -1,962 +0,0 @@ -# -*- coding: utf-8 -*- -""" - Python documentation ReST writer - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - How the converter works - ======================= - - A LaTeX document is tokenized by a `Tokenizer`. The tokens are processed by - the `DocParser` class which emits a tree of `DocNode`\s. The `RestWriter` - now walks this node tree and generates ReST from that. - - There are some intricacies while writing ReST: - - - Paragraph text must be rewrapped in order to avoid ragged lines. The - `textwrap` module does that nicely, but it must obviously operate on a - whole paragraph at a time. Therefore the contents of the current paragraph - are cached in `self.curpar`. Every time a block level element is - encountered, its node handler calls `self.flush_par()` which writes out a - paragraph. Because this can be detrimental for the markup at several - stages, the `self.noflush` context manager can be used to forbid paragraph - flushing temporarily, which means that no block level nodes can be - processed. - - - There are no inline comments in ReST. Therefore comments are stored in - `self.comments` and written out every time the paragraph is flushed. - - - A similar thing goes for footnotes: `self.footnotes`. - - - Some inline markup cannot contain nested markup. Therefore the function - `textonly()` exists which returns a node similar to its argument, but - stripped of inline markup. - - - Some constructs need to format non-block-level nodes, but without writing - the result to the current paragraph. These use `self.get_node_text()` - which writes to a temporary paragraph and returns the resulting markup. - - - Indentation is important. The `self.indent` context manager helps keeping - track of indentation levels. - - - Some blocks, like lists, need to prevent the first line from being - indented because the indentation space is already filled (e.g. by a - bullet). Therefore the `self.indent` context manager accepts a - `firstline` flag which can be set to ``False``, resulting in the first - line not being indented. - - - There are some restrictions on markup compared to LaTeX: - - - Table cells may not contain blocks. - - - Hard line breaks don't exist. - - - Block level markup inside "alltt" environments doesn't work. - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -# yay! -from __future__ import with_statement - -import re -import StringIO -import textwrap - -WIDTH = 80 -INDENT = 3 - -new_wordsep_re = re.compile( - r'(\s+|' # any whitespace - r'(?<=\s)(?::[a-z-]+:)?`\S+|' # interpreted text start - r'[^\s\w]*\w+[a-zA-Z]-(?=\w+[a-zA-Z])|' # hyphenated words - r'(?<=[\w\!\"\'\&\.\,\?])-{2,}(?=\w))') # em-dash - -import textwrap -# monkey-patch... -textwrap.TextWrapper.wordsep_re = new_wordsep_re -wrapper = textwrap.TextWrapper(width=WIDTH, break_long_words=False) - -from .docnodes import RootNode, TextNode, NodeList, InlineNode, \ - CommentNode, EmptyNode -from .util import fixup_text, empty, text, my_make_id, \ - repair_bad_inline_markup -from .filenamemap import includes_mapping - -class WriterError(Exception): - pass - - -class Indenter(object): - """ Context manager factory for indentation. """ - def __init__(self, writer): - class IndenterManager(object): - def __init__(self, indentlevel, flush, firstline): - self.indentlevel = indentlevel - self.flush = flush - self.firstline = firstline - - def __enter__(self): - writer.indentation += (self.indentlevel * ' ') - writer.indentfirstline = self.firstline - return self - - def __exit__(self, *ignored): - if self.flush: - writer.flush_par() - writer.indentation = writer.indentation[:-self.indentlevel] - - self.manager = IndenterManager - - def __call__(self, indentlevel=INDENT, flush=True, firstline=True): - return self.manager(indentlevel, flush, firstline) - - -class NoFlush(object): - """ Convenience context manager. """ - def __init__(self, writer): - self.writer = writer - - def __enter__(self): - self.writer.no_flushing += 1 - - def __exit__(self, *ignored): - self.writer.no_flushing -= 1 - - -class SectionMeta(object): - def __init__(self): - self.modname = '' - self.platform = '' - self.synopsis = [] - self.modauthors = [] - self.sectauthors = [] - - -class RestWriter(object): - """ Write ReST from a node tree. """ - - def __init__(self, fp, splitchap=False, toctree=None, deflang=None, labelprefix=''): - self.splitchap = splitchap # split output at chapters? - if splitchap: - self.fp = StringIO.StringIO() # dummy one - self.chapters = [self.fp] - else: - self.fp = fp # file pointer - self.toctree = toctree # entries for the TOC tree - self.deflang = deflang # default highlighting language - self.labelprefix = labelprefix # prefix for all label names - - # indentation tools - self.indentation = '' # current indentation string - self.indentfirstline = True # indent the first line of next paragraph? - self.indented = Indenter(self) # convenience context manager - - # paragraph flushing tools - self.flush_cb = None # callback run on next paragraph flush, used - # for properly separating field lists from - # the following paragraph - self.no_flushing = 0 # raise an error on paragraph flush? - self.noflush = NoFlush(self) # convenience context manager - - # collected items to output later - self.curpar = [] # text in current paragraph - self.comments = [] # comments to be output after flushing - self.indexentries = [] # indexentries to be output before flushing - self.footnotes = [] # footnotes to be output at document end - self.warnings = [] # warnings while writing - - # specials - self.sectionlabel = '' # most recent \label command - self.thisclass = '' # most recent classdesc name - self.sectionmeta = None # current section metadata - self.noescape = 0 # don't escape text nodes - self.indexsubitem = '' # current \withsubitem text - - def write_document(self, rootnode): - """ Write a document, represented by a RootNode. """ - assert type(rootnode) is RootNode - - if self.deflang: - self.write_directive('highlightlang', self.deflang) - - self.visit_node(rootnode) - self.write_footnotes() - - def new_chapter(self): - """ Called if self.splitchap is True. Create a new file pointer - and set self.fp to it. """ - new_fp = StringIO.StringIO() - self.chapters.append(new_fp) - self.fp = new_fp - - def write(self, text='', nl=True, first=False): - """ Write a string to the output file. """ - if first: - self.fp.write((self.indentation if self.indentfirstline else '') + text) - self.indentfirstline = True - elif text: # don't write indentation only - self.fp.write(self.indentation + text) - if nl: - self.fp.write('\n') - - def write_footnotes(self): - """ Write the current footnotes, if any. """ - self.flush_par() - if self.footnotes: - self.write('.. rubric:: Footnotes\n') - footnotes = self.footnotes - self.footnotes = [] # first clear since indented() will flush - for footnode in footnotes: - self.write('.. [#] ', nl=False) - with self.indented(3, firstline=False): - self.visit_node(footnode) - - def write_directive(self, name, args='', node=None, spabove=False, spbelow=True): - """ Helper to write a ReST directive. """ - if spabove: - self.write() - self.write('.. %s::%s' % (name, args and ' '+args)) - if spbelow: - self.write() - with self.indented(): - if node is not None: - self.visit_node(node) - - def write_sectionmeta(self): - mod = self.sectionmeta - self.sectionmeta = None - if not mod: - return - if mod.modname: - self.write('.. module:: %s' % mod.modname) - if mod.platform: - self.write(' :platform: %s' % mod.platform) - if mod.synopsis: - self.write(' :synopsis: %s' % mod.synopsis[0]) - for line in mod.synopsis[1:]: - self.write(' %s' % line) - if mod.modauthors: - for author in mod.modauthors: - self.write('.. moduleauthor:: %s' % author) - if mod.sectauthors: - for author in mod.sectauthors: - self.write('.. sectionauthor:: %s' % author) - self.write() - self.write() - - indexentry_mapping = { - 'index': 'single', - 'indexii': 'pair', - 'indexiii': 'triple', - 'indexiv': 'quadruple', - 'stindex': 'statement', - 'ttindex': 'single', - 'obindex': 'object', - 'opindex': 'operator', - 'kwindex': 'keyword', - 'exindex': 'exception', - 'bifuncindex': 'builtin', - 'refmodindex': 'module', - 'refbimodindex': 'module', - 'refexmodindex': 'module', - 'refstmodindex': 'module', - } - - def get_indexentries(self, entries): - """ Return a list of lines for the index entries. """ - def format_entry(cmdname, args, subitem): - textargs = [] - for arg in args: - if isinstance(arg, TextNode): - textarg = text(arg) - else: - textarg = self.get_node_text(self.get_textonly_node(arg, warn=0)) - if ';' in textarg: - raise WriterError("semicolon in index args: " + textarg) - textarg += subitem - textarg = textarg.replace('!', '; ') - textargs.append(textarg) - return '%s: %s' % (self.indexentry_mapping[cmdname], - '; '.join(textarg for textarg in textargs - if not empty(arg))) - - ret = [] - if len(entries) == 1: - ret.append('.. index:: %s' % format_entry(*entries[0])) - else: - ret.append('.. index::') - for entry in entries: - ret.append(' %s' % format_entry(*entry)) - return ret - - def get_par(self, wrap, width=None): - """ Get the contents of the current paragraph. - Returns a list if wrap and not indent, else a string. """ - if not self.curpar: - if wrap: - return [] - else: - return '' - text = ''.join(self.curpar).lstrip() - text = repair_bad_inline_markup(text) - self.curpar = [] - if wrap: - # returns a list! - wrapper.width = width or WIDTH - return wrapper.wrap(text) - else: - return text - - no_warn_textonly = set(( - 'var', 'code', 'textrm', 'emph', 'keyword', 'textit', 'programopt', - 'cfunction', 'texttt', 'email', 'constant', - )) - - def get_textonly_node(self, node, cmd='', warn=1): - """ Return a similar Node or NodeList that only has TextNode subnodes. - - Warning values: - - 0: never warn - - 1: warn for markup losing information - """ - if cmd == 'code': - warn = 0 - def do(subnode): - if isinstance(subnode, TextNode): - return subnode - if isinstance(subnode, NodeList): - return NodeList(do(subsubnode) for subsubnode in subnode) - if isinstance(subnode, CommentNode): - # loses comments, but huh - return EmptyNode() - if isinstance(subnode, InlineNode): - if subnode.cmdname in ('filevar', 'envvar'): - return NodeList([TextNode('{'), do(subnode.args[0]), TextNode('}')]) - if subnode.cmdname == 'optional': - # this is not mapped to ReST markup - return subnode - if len(subnode.args) == 1: - if warn == 1 and subnode.cmdname not in self.no_warn_textonly: - self.warnings.append('%r: Discarding %s markup in %r' % - (cmd, subnode.cmdname, node)) - return do(subnode.args[0]) - elif len(subnode.args) == 0: - # should only happen for IndexNodes which stay in - return subnode - elif len(subnode.args) == 2 and subnode.cmdname == 'refmodule': - if not warn: - return do(subnode.args[1]) - raise WriterError('get_textonly_node() failed for %r' % subnode) - return do(node) - - def get_node_text(self, node, wrap=False, width=None): - """ Write the node to a temporary paragraph and return the result - as a string. """ - with self.noflush: - self._old_curpar = self.curpar - self.curpar = [] - self.visit_node(node) - ret = self.get_par(wrap, width=width) - self.curpar = self._old_curpar - return ret - - def flush_par(self, nocb=False, nocomments=False): - """ Write the current paragraph to the output file. - Prepend index entries, append comments and footnotes. """ - if self.no_flushing: - raise WriterError('called flush_par() while noflush active') - if self.indexentries: - for line in self.get_indexentries(self.indexentries): - self.write(line) - self.write() - self.indexentries = [] - if self.flush_cb and not nocb: - self.flush_cb() - self.flush_cb = None - par = self.get_par(wrap=True) - if par: - for i, line in enumerate(par): - self.write(line, first=(i==0)) - self.write() - if self.comments and not nocomments: - for comment in self.comments: - self.write('.. % ' + comment) - self.write() - self.comments = [] - - def visit_wrapped(self, pre, node, post, noescape=False): - """ Write a node within a paragraph, wrapped with pre and post strings. """ - if noescape: - self.noescape += 1 - self.curpar.append(pre) - with self.noflush: - self.visit_node(node) - self.curpar.append(post) - if noescape: - self.noescape -= 1 - - def visit_node(self, node): - """ "Write" a node (appends to curpar or writes something). """ - visitfunc = getattr(self, 'visit_' + node.__class__.__name__, None) - if not visitfunc: - raise WriterError('no visit function for %s node' % node.__class__) - visitfunc(node) - - # ------------------------- node handlers ----------------------------- - - def visit_RootNode(self, node): - if node.params.get('title'): - title = self.get_node_text(node.params['title']) - hl = len(title) - self.write('*' * (hl+4)) - self.write(' %s ' % title) - self.write('*' * (hl+4)) - self.write() - - if node.params.get('author'): - self.write(':Author: %s%s' % - (self.get_node_text(node.params['author']), - (' <%s>' % self.get_node_text(node.params['authoremail']) - if 'authoremail' in node.params else ''))) - self.write() - - if node.params.get('date'): - self.write(':Date: %s' % self.get_node_text(node.params['date'])) - self.write() - - if node.params.get('release'): - self.write('.. |release| replace:: %s' % - self.get_node_text(node.params['release'])) - self.write() - - self.visit_NodeList(node.children) - - def visit_NodeList(self, nodelist): - for node in nodelist: - self.visit_node(node) - - def visit_CommentNode(self, node): - # no inline comments -> they are all output at the start of a new paragraph - self.comments.append(node.comment.strip()) - - sectchars = { - 'chapter': '*', - 'chapter*': '*', - 'section': '=', - 'subsection': '-', - 'subsubsection': '^', - 'paragraph': '"', - } - - sectdoubleline = [ - 'chapter', - 'chapter*', - ] - - def visit_SectioningNode(self, node): - self.flush_par() - self.sectionlabel = '' - self.thisclass = '' - self.write() - - if self.splitchap and node.cmdname.startswith('chapter'): - self.write_footnotes() - self.new_chapter() - - heading = self.get_node_text(node.args[0]).strip() - if self.sectionlabel: - self.write('.. _%s:\n' % self.sectionlabel) - hl = len(heading) - if node.cmdname in self.sectdoubleline: - self.write(self.sectchars[node.cmdname] * hl) - self.write(heading) - self.write(self.sectchars[node.cmdname] * hl) - self.write() - - def visit_EnvironmentNode(self, node): - self.flush_par() - envname = node.envname - if envname == 'notice': - type = text(node.args[0]) or 'note' - self.write_directive(type, '', node.content) - elif envname in ('seealso', 'seealso*'): - self.write_directive('seealso', '', node.content, spabove=True) - elif envname == 'abstract': - self.write_directive('topic', 'Abstract', node.content, spabove=True) - elif envname == 'quote': - with self.indented(): - self.visit_node(node.content) - self.write() - elif envname == 'quotation': - self.write_directive('epigraph', '', node.content, spabove=True) - else: - raise WriterError('no handler for %s environment' % envname) - - descmap = { - 'funcdesc': ('function', '0(1)'), - 'funcdescni': ('function', '0(1)'), - 'classdesc': ('class', '0(1)'), - 'classdesc*': ('class', '0'), - 'methoddesc': ('method', '0.1(2)'), - 'methoddescni': ('method', '0.1(2)'), - 'excdesc': ('exception', '0'), - 'excclassdesc': ('exception', '0(1)'), - 'datadesc': ('data', '0'), - 'datadescni': ('data', '0'), - 'memberdesc': ('attribute', '0.1'), - 'memberdescni': ('attribute', '0.1'), - 'opcodedesc': ('opcode', '0 (1)'), - - 'cfuncdesc': ('cfunction', '0 1(2)'), - 'cmemberdesc': ('cmember', '1 0.2'), - 'csimplemacrodesc': ('cmacro', '0'), - 'ctypedesc': ('ctype', '1'), - 'cvardesc': ('cvar', '0 1'), - } - - def _write_sig(self, spec, args): - # don't escape "*" in signatures - self.noescape += 1 - for c in spec: - if c.isdigit(): - self.visit_node(self.get_textonly_node(args[int(c)])) - else: - self.curpar.append(c) - self.noescape -= 1 - - def visit_DescEnvironmentNode(self, node): - envname = node.envname - if envname not in self.descmap: - raise WriterError('no handler for %s environment' % envname) - - self.flush_par() - # automatically fill in the class name if not given - if envname[:9] == 'classdesc' or envname[:12] == 'excclassdesc': - self.thisclass = text(node.args[0]) - elif envname[:10] in ('methoddesc', 'memberdesc') and not \ - text(node.args[0]): - if not self.thisclass: - raise WriterError('No current class for %s member' % - text(node.args[1])) - node.args[0] = TextNode(self.thisclass) - directivename, sigspec = self.descmap[envname] - self._write_sig(sigspec, node.args) - signature = self.get_par(wrap=False) - self.write() - self.write('.. %s:: %s' % (directivename, signature)) - if node.additional: - for cmdname, add in node.additional: - entry = self.descmap[cmdname.replace('line', 'desc')] - if envname[:10] in ('methoddesc', 'memberdesc') and not \ - text(add[0]): - if not self.thisclass: - raise WriterError('No current class for %s member' % - text(add[1])) - add[0] = TextNode(self.thisclass) - self._write_sig(entry[1], add) - signature = self.get_par(wrap=False) - self.write(' %s%s' % (' ' * (len(directivename) - 2), - signature)) - if envname.endswith('ni'): - self.write(' :noindex:') - self.write() - with self.indented(): - self.visit_node(node.content) - - - def visit_CommandNode(self, node): - cmdname = node.cmdname - if cmdname == 'label': - labelname = self.labelprefix + text(node.args[0]).lower() - if self.no_flushing: - # in section - self.sectionlabel = labelname - else: - self.flush_par() - self.write('.. _%s:\n' % labelname) - return - - elif cmdname in ('declaremodule', 'modulesynopsis', - 'moduleauthor', 'sectionauthor', 'platform'): - self.flush_par(nocb=True, nocomments=True) - if not self.sectionmeta: - self.sectionmeta = SectionMeta() - if cmdname == 'declaremodule': - self.sectionmeta.modname = text(node.args[2]) - elif cmdname == 'modulesynopsis': - self.sectionmeta.synopsis = self.get_node_text( - self.get_textonly_node(node.args[0], warn=0), wrap=True) - elif cmdname == 'moduleauthor': - email = text(node.args[1]) - self.sectionmeta.modauthors.append( - '%s%s' % (text(node.args[0]), (email and ' <%s>' % email))) - elif cmdname == 'sectionauthor': - email = text(node.args[1]) - self.sectionmeta.sectauthors.append( - '%s%s' % (text(node.args[0]), (email and ' <%s>' % email))) - elif cmdname == 'platform': - self.sectionmeta.platform = text(node.args[0]) - self.flush_cb = lambda: self.write_sectionmeta() - return - - self.flush_par() - if cmdname.startswith('see'): - i = 2 - if cmdname == 'seemodule': - self.write('Module :mod:`%s`' % text(node.args[1])) - elif cmdname == 'seelink': - linktext = self.get_node_text(node.args[1]) - self.write('`%s <%s>`_' % (linktext, text(node.args[0]))) - elif cmdname == 'seepep': - self.write(':pep:`%s` - %s' % (text(node.args[0]), - self.get_node_text(node.args[1]))) - elif cmdname == 'seerfc': - self.write(':rfc:`%s` - %s' % (text(node.args[0]), - text(node.args[1]))) - elif cmdname == 'seetitle': - if empty(node.args[0]): - self.write('%s' % text(node.args[1])) - else: - self.write('`%s <%s>`_' % (text(node.args[1]), - text(node.args[0]))) - elif cmdname == 'seeurl': - i = 1 - self.write('%s' % text(node.args[0])) - elif cmdname == 'seetext': - self.visit_node(node.args[0]) - return - with self.indented(): - self.visit_node(node.args[i]) - elif cmdname in ('versionchanged', 'versionadded'): - self.write('.. %s:: %s' % (cmdname, text(node.args[1]))) - if not empty(node.args[0]): - with self.indented(): - self.visit_node(node.args[0]) - self.curpar.append('.') - else: - self.write() - elif cmdname == 'deprecated': - self.write_directive('deprecated', text(node.args[0]), node.args[1], - spbelow=False) - elif cmdname == 'localmoduletable': - if self.toctree is not None: - self.write_directive('toctree', '', spbelow=True, spabove=True) - with self.indented(): - for entry in self.toctree: - self.write(entry + '.rst') - else: - self.warnings.append('no toctree given, but \\localmoduletable in file') - elif cmdname == 'verbatiminput': - inclname = text(node.args[0]) - newname = includes_mapping.get(inclname, '../includes/' + inclname) - if newname is None: - self.write() - self.write('.. XXX includefile %s' % inclname) - return - self.write() - self.write('.. include:: %s' % newname) - self.write(' :literal:') - self.write() - elif cmdname == 'input': - inclname = text(node.args[0]) - newname = includes_mapping.get(inclname, None) - if newname is None: - self.write('X' 'XX: input{%s} :XX' 'X' % inclname) - return - self.write_directive('include', newname, spabove=True) - elif cmdname == 'centerline': - self.write_directive('centered', self.get_node_text(node.args[0]), - spabove=True, spbelow=True) - elif cmdname == 'XX' 'X': - self.visit_wrapped(r'**\*\*** ', node.args[0], ' **\*\***') - else: - raise WriterError('no handler for %s command' % cmdname) - - def visit_DescLineCommandNode(self, node): - # these have already been written as arguments of the corresponding - # DescEnvironmentNode - pass - - def visit_ParaSepNode(self, node): - self.flush_par() - - def visit_VerbatimNode(self, node): - if self.comments: - # these interfer with the literal block - self.flush_par() - if self.curpar: - last = self.curpar[-1].rstrip(' ') - if last.endswith(':'): - self.curpar[-1] = last + ':' - else: - self.curpar.append(' ::') - else: - self.curpar.append('::') - self.flush_par() - with self.indented(): - if isinstance(node.content, TextNode): - # verbatim - lines = textwrap.dedent(text(node.content).lstrip('\n')).split('\n') - if not lines: - return - else: - # alltt, possibly with inline formats - lines = self.get_node_text(self.get_textonly_node( - node.content, warn=0)).split('\n') + [''] - # discard leading blank links - while not lines[0].strip(): - del lines[0] - for line in lines: - self.write(line) - - note_re = re.compile('^\(\d\)$') - - def visit_TableNode(self, node): - self.flush_par() - lines = node.lines[:] - lines.insert(0, node.headings) - fmted_rows = [] - width = WIDTH - len(self.indentation) - realwidths = [0] * node.numcols - colwidth = (width / node.numcols) + 5 - # don't allow paragraphs in table cells for now - with self.noflush: - for line in lines: - cells = [] - for i, cell in enumerate(line): - par = self.get_node_text(cell, wrap=True, width=colwidth) - if len(par) == 1 and self.note_re.match(par[0].strip()): - # special case: escape "(1)" to avoid enumeration - par[0] = '\\' + par[0] - maxwidth = max(map(len, par)) if par else 0 - realwidths[i] = max(realwidths[i], maxwidth) - cells.append(par) - fmted_rows.append(cells) - - def writesep(char='-'): - out = ['+'] - for width in realwidths: - out.append(char * (width+2)) - out.append('+') - self.write(''.join(out)) - - def writerow(row): - lines = map(None, *row) - for line in lines: - out = ['|'] - for i, cell in enumerate(line): - if cell: - out.append(' ' + cell.ljust(realwidths[i]+1)) - else: - out.append(' ' * (realwidths[i] + 2)) - out.append('|') - self.write(''.join(out)) - - writesep('-') - writerow(fmted_rows[0]) - writesep('=') - for row in fmted_rows[1:]: - writerow(row) - writesep('-') - self.write() - - def visit_ItemizeNode(self, node): - self.flush_par() - for title, content in node.items: - if not empty(title): - # do it like in a description list - self.write(self.get_node_text(title)) - with self.indented(): - self.visit_node(content) - else: - self.curpar.append('* ') - with self.indented(2, firstline=False): - self.visit_node(content) - - def visit_EnumerateNode(self, node): - self.flush_par() - for title, content in node.items: - assert empty(title) - self.curpar.append('#. ') - with self.indented(3, firstline=False): - self.visit_node(content) - - def visit_DescriptionNode(self, node): - self.flush_par() - for title, content in node.items: - self.write(self.get_node_text(title)) - with self.indented(): - self.visit_node(content) - - visit_DefinitionsNode = visit_DescriptionNode - - def visit_ProductionListNode(self, node): - self.flush_par() - arg = text(node.arg) - self.write('.. productionlist::%s' % (' '+arg if arg else '')) - with self.indented(): - for item in node.items: - if not empty(item[0]): - lasttext = text(item[0]) - self.write('%s: %s' % ( - text(item[0]).ljust(len(lasttext)), - self.get_node_text(item[1]))) - self.write() - - def visit_EmptyNode(self, node): - pass - - def visit_TextNode(self, node): - if self.noescape: - self.curpar.append(node.text) - else: - self.curpar.append(fixup_text(node.text)) - - visit_NbspNode = visit_TextNode - visit_SimpleCmdNode = visit_TextNode - - def visit_BreakNode(self, node): - # XXX: linebreaks in ReST? - self.curpar.append(' --- ') - - def visit_IndexNode(self, node): - if node.cmdname == 'withsubitem': - self.indexsubitem = ' ' + text(node.indexargs[0]) - self.visit_node(node.indexargs[1]) - self.indexsubitem = '' - else: - self.indexentries.append((node.cmdname, node.indexargs, - self.indexsubitem)) - - # maps argumentless commands to text - simplecmd_mapping = { - 'NULL': '*NULL*', - 'shortversion': '|version|', - 'version': '|release|', - 'today': '|today|', - } - - # map LaTeX command names to roles: shorter names! - role_mapping = { - 'cfunction': 'cfunc', - 'constant': 'const', - 'csimplemacro': 'cmacro', - 'exception': 'exc', - 'function': 'func', - 'grammartoken': 'token', - 'member': 'attr', - 'method': 'meth', - 'module': 'mod', - 'programopt': 'option', - 'filenq': 'file', - # these mean: no change - 'cdata': '', - 'class': '', - 'command': '', - 'ctype': '', - 'data': '', # NEW - 'dfn': '', - 'envvar': '', - 'file': '', - 'guilabel': '', - 'kbd': '', - 'keyword': '', - 'mailheader': '', - 'makevar': '', - 'menuselection': '', - 'mimetype': '', - 'newsgroup': '', - 'option': '', - 'pep': '', - 'program': '', - 'ref': '', - 'rfc': '', - } - - # do not warn about nested inline markup in these roles - role_no_warn = set(( - 'cdata', 'cfunction', 'class', 'constant', 'csimplemacro', 'ctype', - 'data', 'exception', 'function', 'member', 'method', 'module', - )) - - def visit_InlineNode(self, node): - # XXX: no nested markup -- docutils doesn't support it - cmdname = node.cmdname - if not node.args: - self.curpar.append(self.simplecmd_mapping[cmdname]) - return - content = node.args[0] - if cmdname in ('code', 'bfcode', 'samp', 'texttt', 'regexp'): - self.visit_wrapped('``', self.get_textonly_node(content, 'code', - warn=1), '``', noescape=True) - elif cmdname in ('emph', 'textit', 'var'): - self.visit_wrapped('*', self.get_textonly_node(content, 'emph', - warn=1), '*') - elif cmdname in ('strong', 'textbf'): - self.visit_wrapped('**', self.get_textonly_node(content, 'strong', - warn=1), '**') - elif cmdname in ('b', 'textrm', 'email'): - self.visit_node(content) - elif cmdname == 'token': - # \token appears in productionlists only - self.visit_wrapped('`', self.get_textonly_node(content, 'var', - warn=1), '`') - elif cmdname == 'ref': - self.curpar.append(':ref:`%s%s`' % (self.labelprefix, - text(node.args[0]).lower())) - elif cmdname == 'refmodule': - self.visit_wrapped(':mod:`', node.args[1], '`', noescape=True) - elif cmdname == 'optional': - self.visit_wrapped('[', content, ']') - elif cmdname == 'url': - self.visit_node(content) - elif cmdname == 'ulink': - target = text(node.args[1]) - if target.startswith('..'): - self.visit_wrapped('', content, ' (X' + 'XX reference: %s)' % target) - elif not target.startswith(('http:', 'mailto:')): - #self.warnings.append('Local \\ulink to %s, use \\ref instead' % target) - self.visit_wrapped('', content, ' (X' 'XX reference: %s)' % target) - else: - self.visit_wrapped('`', self.get_textonly_node(content, 'ulink', warn=1), - ' <%s>`_' % target) - elif cmdname == 'citetitle': - target = text(content) - if not target: - self.visit_node(node.args[1]) - elif target.startswith('..'): - self.visit_wrapped('', node.args[1], - ' (X' + 'XX reference: %s)' % target) - else: - self.visit_wrapped('`', self.get_textonly_node(node.args[1], - 'citetitle', warn=1), - ' <%s>`_' % target) - elif cmdname == 'character': - # ``'a'`` is not longer than :character:`a` - self.visit_wrapped("``'", content, "'``", noescape=True) - elif cmdname == 'manpage': - self.curpar.append(':manpage:`') - self.visit_node(self.get_textonly_node(content, warn=0)) - self.visit_wrapped('(', self.get_textonly_node(node.args[1], warn=0), ')') - self.curpar.append('`') - elif cmdname == 'footnote': - self.curpar.append(' [#]_') - self.footnotes.append(content) - elif cmdname == 'frac': - self.visit_wrapped('(', node.args[0], ')/') - self.visit_wrapped('(', node.args[1], ')') - elif cmdname == 'longprogramopt': - self.visit_wrapped(':option:`--', content, '`') - elif cmdname == 'filevar': - self.visit_wrapped(':file:`{', content, '}`') - elif cmdname == '': - self.visit_node(content) - # stray commands from distutils - elif cmdname in ('argument name', 'value', 'attribute', 'option name'): - self.visit_wrapped('*', content, '*') - else: - self.visit_wrapped(':%s:`' % (self.role_mapping[cmdname] or cmdname), - self.get_textonly_node( - content, cmdname, warn=(cmdname not in self.role_no_warn)), '`') diff --git a/converter/scanner.py b/converter/scanner.py deleted file mode 100644 index 53502d2c..00000000 --- a/converter/scanner.py +++ /dev/null @@ -1,97 +0,0 @@ -# -*- coding: utf-8 -*- -""" - scanner - ~~~~~~~ - - This library implements a regex based scanner. - - :copyright: 2006-2007 by Armin Ronacher, Georg Brandl. - :license: BSD license. -""" -import re - - -class EndOfText(RuntimeError): - """ - Raise if end of text is reached and the user - tried to call a match function. - """ - - -class Scanner(object): - """ - Simple scanner - - All method patterns are regular expression strings (not - compiled expressions!) - """ - - def __init__(self, text, flags=0): - """ - :param text: The text which should be scanned - :param flags: default regular expression flags - """ - self.data = text - self.data_length = len(text) - self.start_pos = 0 - self.pos = 0 - self.flags = flags - self.last = None - self.match = None - self._re_cache = {} - - def eos(self): - """`True` if the scanner reached the end of text.""" - return self.pos >= self.data_length - eos = property(eos, eos.__doc__) - - def check(self, pattern): - """ - Apply `pattern` on the current position and return - the match object. (Doesn't touch pos). Use this for - lookahead. - """ - if self.eos: - raise EndOfText() - if pattern not in self._re_cache: - self._re_cache[pattern] = re.compile(pattern, self.flags) - return self._re_cache[pattern].match(self.data, self.pos) - - def test(self, pattern): - """Apply a pattern on the current position and check - if it patches. Doesn't touch pos.""" - return self.check(pattern) is not None - - def scan(self, pattern): - """ - Scan the text for the given pattern and update pos/match - and related fields. The return value is a boolen that - indicates if the pattern matched. The matched value is - stored on the instance as ``match``, the last value is - stored as ``last``. ``start_pos`` is the position of the - pointer before the pattern was matched, ``pos`` is the - end position. - """ - if self.eos: - raise EndOfText() - if pattern not in self._re_cache: - self._re_cache[pattern] = re.compile(pattern, self.flags) - self.last = self.match - m = self._re_cache[pattern].match(self.data, self.pos) - if m is None: - return False - self.start_pos = m.start() - self.pos = m.end() - self.match = m - return True - - def get_char(self): - """Scan exactly one char.""" - self.scan('.') - - def __repr__(self): - return '<%s %d/%d>' % ( - self.__class__.__name__, - self.pos, - self.data_length - ) diff --git a/converter/tokenizer.py b/converter/tokenizer.py deleted file mode 100644 index 61960919..00000000 --- a/converter/tokenizer.py +++ /dev/null @@ -1,124 +0,0 @@ -# -*- coding: utf-8 -*- -""" - Python documentation LaTeX file tokenizer - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - For more documentation, look into the ``restwriter.py`` file. - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -import re - -from .scanner import Scanner - -class Tokenizer(Scanner): - """ Lex a Python doc LaTeX document. """ - - specials = { - '{': 'bgroup', - '}': 'egroup', - '[': 'boptional', - ']': 'eoptional', - '~': 'tilde', - '$': 'mathmode', - } - - @property - def mtext(self): - return self.match.group() - - def tokenize(self): - return TokenStream(self._tokenize()) - - def _tokenize(self): - lineno = 1 - while not self.eos: - if self.scan(r'\\verb([^a-zA-Z])(.*?)(\1)'): - # specialcase \verb here - yield lineno, 'command', 'verb', '\\verb' - yield lineno, 'text', self.match.group(1), self.match.group(1) - yield lineno, 'text', self.match.group(2), self.match.group(2) - yield lineno, 'text', self.match.group(3), self.match.group(3) - elif self.scan(r'\\([a-zA-Z]+\*?)[ \t]*'): - yield lineno, 'command', self.match.group(1), self.mtext - elif self.scan(r'\\.'): - yield lineno, 'command', self.mtext[1], self.mtext - elif self.scan(r'\\\n'): - yield lineno, 'text', self.mtext, self.mtext - lineno += 1 - elif self.scan(r'%(.*)\n[ \t]*'): - yield lineno, 'comment', self.match.group(1), self.mtext - lineno += 1 - elif self.scan(r'[{}\[\]~$]'): - yield lineno, self.specials[self.mtext], self.mtext, self.mtext - elif self.scan(r'(\n[ \t]*){2,}'): - lines = self.mtext.count('\n') - yield lineno, 'parasep', '\n' * lines, self.mtext - lineno += lines - elif self.scan(r'\n[ \t]*'): - yield lineno, 'text', ' ', self.mtext - lineno += 1 - elif self.scan(r'[^\\%}{\[\]~\n]+'): - yield lineno, 'text', self.mtext, self.mtext - else: - raise RuntimeError('unexpected text on line %d: %r' % - (lineno, self.data[self.pos:self.pos+100])) - - -class TokenStream(object): - """ - A token stream works like a normal generator just that - it supports peeking and pushing tokens back to the stream. - """ - - def __init__(self, generator): - self._generator = generator - self._pushed = [] - self.last = (1, 'initial', '') - - def __iter__(self): - return self - - def __nonzero__(self): - """ Are we at the end of the tokenstream? """ - if self._pushed: - return True - try: - self.push(self.next()) - except StopIteration: - return False - return True - - def pop(self): - """ Return the next token from the stream. """ - if self._pushed: - rv = self._pushed.pop() - else: - rv = self._generator.next() - self.last = rv - return rv - - next = pop - - def popmany(self, num=1): - """ Pop a list of tokens. """ - return [self.next() for i in range(num)] - - def peek(self): - """ Pop and push a token, return it. """ - token = self.next() - self.push(token) - return token - - def peekmany(self, num=1): - """ Pop and push a list of tokens. """ - tokens = self.popmany(num) - for tok in tokens: - self.push(tok) - return tokens - - def push(self, item): - """ Push a token back to the stream. """ - self._pushed.append(item) diff --git a/converter/util.py b/converter/util.py deleted file mode 100644 index 7b7cc4bb..00000000 --- a/converter/util.py +++ /dev/null @@ -1,100 +0,0 @@ -# -*- coding: utf-8 -*- -""" - Python documentation conversion utils - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -import re - -from docutils.nodes import make_id - -from .docnodes import TextNode, EmptyNode, NodeList - - -def umlaut(cmd, c): - try: - if cmd == '"': - return {'o': u'ö', - 'a': u'ä', - 'u': u'ü', - 'i': u'ï', - 'O': u'Ö', - 'A': u'Ä', - 'U': u'Ü'}[c] - elif cmd == "'": - return {'a': u'á', - 'e': u'é'}[c] - elif cmd == '~': - return {'n': u'ñ'}[c] - elif cmd == 'c': - return {'c': u'ç'}[c] - elif cmd == '`': - return {'o': u'ò'}[c] - else: - from .latexparser import ParserError - raise ParserError('invalid umlaut \\%s' % cmd, 0) - except KeyError: - from .latexparser import ParserError - raise ParserError('unsupported umlaut \\%s%s' % (cmd, c), 0) - -def fixup_text(text): - return text.replace('``', '"').replace("''", '"').replace('`', "'").\ - replace('|', '\\|').replace('*', '\\*') - -def empty(node): - return (type(node) is EmptyNode) - -def text(node): - """ Return the text for a TextNode or raise an error. """ - if isinstance(node, TextNode): - return node.text - elif isinstance(node, NodeList): - restext = '' - for subnode in node: - restext += text(subnode) - return restext - from .restwriter import WriterError - raise WriterError('text() failed for %r' % node) - -markup_re = re.compile(r'(:[a-zA-Z0-9_-]+:)?`(.*?)`') - -def my_make_id(name): - """ Like make_id(), but strip roles first. """ - return make_id(markup_re.sub(r'\2', name)) - -alphanum = u'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789' -wordchars_s = alphanum + u'_.-' -wordchars_e = alphanum + u'+`(-' -bad_markup_re = re.compile(r'(:[a-zA-Z0-9_-]+:)?(`{1,2})[ ]*(.+?)[ ]*(\2)') -quoted_code_re = re.compile(r'\\`(``.+?``)\'') -paren_re = re.compile(r':(func|meth|cfunc):`(.*?)\(\)`') - -def repair_bad_inline_markup(text): - # remove quoting from `\code{x}' - xtext = quoted_code_re.sub(r'\1', text) - - # special: the literal backslash - xtext = xtext.replace('``\\``', '\x03') - # special: literal backquotes - xtext = xtext.replace('``````', '\x02') - - # remove () from function markup - xtext = paren_re.sub(r':\1:`\2`', xtext) - - ntext = [] - lasti = 0 - l = len(xtext) - for m in bad_markup_re.finditer(xtext): - ntext.append(xtext[lasti:m.start()]) - s, e = m.start(), m.end() - if s != 0 and xtext[s-1:s] in wordchars_s: - ntext.append('\\ ') - ntext.append((m.group(1) or '') + m.group(2) + m.group(3) + m.group(4)) - if e != l and xtext[e:e+1] in wordchars_e: - ntext.append('\\ ') - lasti = m.end() - ntext.append(xtext[lasti:]) - return ''.join(ntext).replace('\x02', '``````').replace('\x03', '``\\``') |