From 7f5fda7bf8cc9f4a5d8093636fb738d021faeb09 Mon Sep 17 00:00:00 2001 From: cperkins1 Date: Tue, 4 Nov 2008 10:29:50 -0700 Subject: initial code brought over from numpy. Now we need to do some simplification of the numpy code. --- setup.py | 3 +- sphinx/ext/autosummary/__init__.py | 328 +++++++++++++++++++ sphinx/ext/autosummary/docscrape.py | 500 +++++++++++++++++++++++++++++ sphinx/ext/autosummary/docscrape_sphinx.py | 133 ++++++++ sphinx/scripts/__init__.py | 0 sphinx/scripts/autosummary_generate.py | 198 ++++++++++++ sphinx/templates/autosummary-module.html | 39 +++ 7 files changed, 1200 insertions(+), 1 deletion(-) create mode 100644 sphinx/ext/autosummary/__init__.py create mode 100644 sphinx/ext/autosummary/docscrape.py create mode 100644 sphinx/ext/autosummary/docscrape_sphinx.py create mode 100644 sphinx/scripts/__init__.py create mode 100755 sphinx/scripts/autosummary_generate.py create mode 100644 sphinx/templates/autosummary-module.html diff --git a/setup.py b/setup.py index abe82198..aa4d2c21 100644 --- a/setup.py +++ b/setup.py @@ -177,7 +177,8 @@ setup( entry_points={ 'console_scripts': [ 'sphinx-build = sphinx:main', - 'sphinx-quickstart = sphinx.quickstart:main' + 'sphinx-quickstart = sphinx.quickstart:main', + 'sphinx-autogen = sphinx.scripts.autosummary_generate:main', ], 'distutils.commands': [ 'build_sphinx = sphinx.setup_command:BuildDoc', diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py new file mode 100644 index 00000000..6b74190c --- /dev/null +++ b/sphinx/ext/autosummary/__init__.py @@ -0,0 +1,328 @@ +""" +=========== +autosummary +=========== + +Sphinx extension that adds an autosummary:: directive, which can be +used to generate function/method/attribute/etc. summary lists, similar +to those output eg. by Epydoc and other API doc generation tools. + +An :autolink: role is also provided. + +autosummary directive +--------------------- + +The autosummary directive has the form:: + + .. autosummary:: + :nosignatures: + :toctree: generated/ + + module.function_1 + module.function_2 + ... + +and it generates an output table (containing signatures, optionally) + + ======================== ============================================= + module.function_1(args) Summary line from the docstring of function_1 + module.function_2(args) Summary line from the docstring + ... + ======================== ============================================= + +If the :toctree: option is specified, files matching the function names +are inserted to the toctree with the given prefix: + + generated/module.function_1 + generated/module.function_2 + ... + +Note: The file names contain the module:: or currentmodule:: prefixes. + +.. seealso:: autosummary_generate.py + + +autolink role +------------- + +The autolink role functions as ``:obj:`` when the name referred can be +resolved to a Python object, and otherwise it becomes simple emphasis. +This can be used as the default role to make links 'smart'. + +""" +import sys, os, posixpath, re + +from docutils.parsers.rst import directives +from docutils.statemachine import ViewList +from docutils import nodes + +import sphinx.addnodes, sphinx.roles, sphinx.builder +from sphinx.util import patfilter + +from docscrape_sphinx import get_doc_object +import inspect + +def setup(app): + app.add_directive('autosummary', autosummary_directive, True, (0, 0, False), + toctree=directives.unchanged, + nosignatures=directives.flag) + app.add_role('autolink', autolink_role) + + app.add_node(autosummary_toc, + html=(autosummary_toc_visit_html, autosummary_toc_depart_noop), + latex=(autosummary_toc_visit_latex, autosummary_toc_depart_noop)) + app.connect('doctree-read', process_autosummary_toc) + +#------------------------------------------------------------------------------ +# autosummary_toc node +#------------------------------------------------------------------------------ + +class autosummary_toc(nodes.comment): + pass + +def process_autosummary_toc(app, doctree): + """ + Insert items described in autosummary:: to the TOC tree, but do + not generate the toctree:: list. + + """ + env = app.builder.env + crawled = {} + def crawl_toc(node, depth=1): + crawled[node] = True + for j, subnode in enumerate(node): + try: + if (isinstance(subnode, autosummary_toc) + and isinstance(subnode[0], sphinx.addnodes.toctree)): + env.note_toctree(env.docname, subnode[0]) + continue + except IndexError: + continue + if not isinstance(subnode, nodes.section): + continue + if subnode not in crawled: + crawl_toc(subnode, depth+1) + crawl_toc(doctree) + +def autosummary_toc_visit_html(self, node): + """Hide autosummary toctree list in HTML output""" + raise nodes.SkipNode + +def autosummary_toc_visit_latex(self, node): + """Show autosummary toctree (= put the referenced pages here) in Latex""" + pass + +def autosummary_toc_depart_noop(self, node): + pass + +#------------------------------------------------------------------------------ +# .. autosummary:: +#------------------------------------------------------------------------------ + +def autosummary_directive(dirname, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + """ + Pretty table containing short signatures and summaries of functions etc. + + autosummary also generates a (hidden) toctree:: node. + + """ + + names = [] + names += [x.strip() for x in content if x.strip()] + + table, warnings, real_names = get_autosummary(names, state, + 'nosignatures' in options) + node = table + + env = state.document.settings.env + suffix = env.config.source_suffix + all_docnames = env.found_docs.copy() + dirname = posixpath.dirname(env.docname) + + if 'toctree' in options: + tree_prefix = options['toctree'].strip() + docnames = [] + for name in names: + name = real_names.get(name, name) + + docname = tree_prefix + name + if docname.endswith(suffix): + docname = docname[:-len(suffix)] + docname = posixpath.normpath(posixpath.join(dirname, docname)) + if docname not in env.found_docs: + warnings.append(state.document.reporter.warning( + 'toctree references unknown document %r' % docname, + line=lineno)) + docnames.append(docname) + + tocnode = sphinx.addnodes.toctree() + tocnode['includefiles'] = docnames + tocnode['maxdepth'] = -1 + tocnode['glob'] = None + + tocnode = autosummary_toc('', '', tocnode) + return warnings + [node] + [tocnode] + else: + return warnings + [node] + +def get_autosummary(names, state, no_signatures=False): + """ + Generate a proper table node for autosummary:: directive. + + Parameters + ---------- + names : list of str + Names of Python objects to be imported and added to the table. + document : document + Docutils document object + + """ + document = state.document + + real_names = {} + warnings = [] + + prefixes = [''] + prefixes.insert(0, document.settings.env.currmodule) + + table = nodes.table('') + group = nodes.tgroup('', cols=2) + table.append(group) + group.append(nodes.colspec('', colwidth=30)) + group.append(nodes.colspec('', colwidth=70)) + body = nodes.tbody('') + group.append(body) + + def append_row(*column_texts): + row = nodes.row('') + for text in column_texts: + node = nodes.paragraph('') + vl = ViewList() + vl.append(text, '') + state.nested_parse(vl, 0, node) + row.append(nodes.entry('', node)) + body.append(row) + + for name in names: + try: + obj, real_name = import_by_name(name, prefixes=prefixes) + except ImportError: + warnings.append(document.reporter.warning( + 'failed to import %s' % name)) + append_row(":obj:`%s`" % name, "") + continue + + real_names[name] = real_name + + doc = get_doc_object(obj) + + if doc['Summary']: + title = " ".join(doc['Summary']) + else: + title = "" + qualifier = 'obj' + if inspect.ismodule(obj): + qualifier = 'mod' + col1 = ":"+qualifier+":`%s <%s>`" % (name, real_name) + if doc['Signature']: + sig = re.sub('^[a-zA-Z_0-9.-]*', '', + doc['Signature'].replace('*', r'\*')) + if '=' in sig: + # abbreviate optional arguments + sig = re.sub(r', ([a-zA-Z0-9_]+)=', r'[, \1=', sig, count=1) + sig = re.sub(r'\(([a-zA-Z0-9_]+)=', r'([\1=', sig, count=1) + sig = re.sub(r'=[^,)]+,', ',', sig) + sig = re.sub(r'=[^,)]+\)$', '])', sig) + # shorten long strings + sig = re.sub(r'(\[.{16,16}[^,)]*?),.*?\]\)', r'\1, ...])', sig) + else: + sig = re.sub(r'(\(.{16,16}[^,)]*?),.*?\)', r'\1, ...)', sig) + col1 += " " + sig + col2 = title + append_row(col1, col2) + + return table, warnings, real_names + +def import_by_name(name, prefixes=[None]): + """ + Import a Python object that has the given name, under one of the prefixes. + + Parameters + ---------- + name : str + Name of a Python object, eg. 'numpy.ndarray.view' + prefixes : list of (str or None), optional + Prefixes to prepend to the name (None implies no prefix). + The first prefixed name that results to successful import is used. + + Returns + ------- + obj + The imported object + name + Name of the imported object (useful if `prefixes` was used) + + """ + for prefix in prefixes: + try: + if prefix: + prefixed_name = '.'.join([prefix, name]) + else: + prefixed_name = name + return _import_by_name(prefixed_name), prefixed_name + except ImportError: + pass + raise ImportError + +def _import_by_name(name): + """Import a Python object given its full name""" + try: + name_parts = name.split('.') + last_j = 0 + modname = None + for j in reversed(range(1, len(name_parts)+1)): + last_j = j + modname = '.'.join(name_parts[:j]) + try: + __import__(modname) + except ImportError: + continue + if modname in sys.modules: + break + + if last_j < len(name_parts): + obj = sys.modules[modname] + for obj_name in name_parts[last_j:]: + obj = getattr(obj, obj_name) + return obj + else: + return sys.modules[modname] + except (ValueError, ImportError, AttributeError, KeyError), e: + raise ImportError(e) + +#------------------------------------------------------------------------------ +# :autolink: (smart default role) +#------------------------------------------------------------------------------ + +def autolink_role(typ, rawtext, etext, lineno, inliner, + options={}, content=[]): + """ + Smart linking role. + + Expands to ":obj:`text`" if `text` is an object that can be imported; + otherwise expands to "*text*". + """ + r = sphinx.roles.xfileref_role('obj', rawtext, etext, lineno, inliner, + options, content) + pnode = r[0][0] + + prefixes = [None] + #prefixes.insert(0, inliner.document.settings.env.currmodule) + try: + obj, name = import_by_name(pnode['reftarget'], prefixes) + except ImportError: + content = pnode[0] + r[0][0] = nodes.emphasis(rawtext, content[0].astext(), + classes=content['classes']) + return r diff --git a/sphinx/ext/autosummary/docscrape.py b/sphinx/ext/autosummary/docscrape.py new file mode 100644 index 00000000..beb4a24e --- /dev/null +++ b/sphinx/ext/autosummary/docscrape.py @@ -0,0 +1,500 @@ +"""Extract reference documentation from the NumPy source tree. + +""" + +import inspect +import textwrap +import re +import pydoc +from StringIO import StringIO +from warnings import warn + +class Reader(object): + """A line-based string reader. + + """ + def __init__(self, data): + """ + Parameters + ---------- + data : str + String with lines separated by '\n'. + + """ + if isinstance(data,list): + self._str = data + else: + self._str = data.split('\n') # store string as list of lines + + self.reset() + + def __getitem__(self, n): + return self._str[n] + + def reset(self): + self._l = 0 # current line nr + + def read(self): + if not self.eof(): + out = self[self._l] + self._l += 1 + return out + else: + return '' + + def seek_next_non_empty_line(self): + for l in self[self._l:]: + if l.strip(): + break + else: + self._l += 1 + + def eof(self): + return self._l >= len(self._str) + + def read_to_condition(self, condition_func): + start = self._l + for line in self[start:]: + if condition_func(line): + return self[start:self._l] + self._l += 1 + if self.eof(): + return self[start:self._l+1] + return [] + + def read_to_next_empty_line(self): + self.seek_next_non_empty_line() + def is_empty(line): + return not line.strip() + return self.read_to_condition(is_empty) + + def read_to_next_unindented_line(self): + def is_unindented(line): + return (line.strip() and (len(line.lstrip()) == len(line))) + return self.read_to_condition(is_unindented) + + def peek(self,n=0): + if self._l + n < len(self._str): + return self[self._l + n] + else: + return '' + + def is_empty(self): + return not ''.join(self._str).strip() + + +class NumpyDocString(object): + def __init__(self,docstring): + docstring = docstring.split('\n') + + # De-indent paragraph + try: + indent = min(len(s) - len(s.lstrip()) for s in docstring + if s.strip()) + except ValueError: + indent = 0 + + for n,line in enumerate(docstring): + docstring[n] = docstring[n][indent:] + + self._doc = Reader(docstring) + self._parsed_data = { + 'Signature': '', + 'Summary': '', + 'Extended Summary': [], + 'Parameters': [], + 'Returns': [], + 'Raises': [], + 'Warns': [], + 'Other Parameters': [], + 'Attributes': [], + 'Methods': [], + 'See Also': [], + 'Notes': [], + 'Warnings': [], + 'References': '', + 'Examples': '', + 'index': {} + } + + self._parse() + + def __getitem__(self,key): + return self._parsed_data[key] + + def __setitem__(self,key,val): + if not self._parsed_data.has_key(key): + warn("Unknown section %s" % key) + else: + self._parsed_data[key] = val + + def _is_at_section(self): + self._doc.seek_next_non_empty_line() + + if self._doc.eof(): + return False + + l1 = self._doc.peek().strip() # e.g. Parameters + + if l1.startswith('.. index::'): + return True + + l2 = self._doc.peek(1).strip() # ---------- or ========== + return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1)) + + def _strip(self,doc): + i = 0 + j = 0 + for i,line in enumerate(doc): + if line.strip(): break + + for j,line in enumerate(doc[::-1]): + if line.strip(): break + + return doc[i:len(doc)-j] + + def _read_to_next_section(self): + section = self._doc.read_to_next_empty_line() + + while not self._is_at_section() and not self._doc.eof(): + if not self._doc.peek(-1).strip(): # previous line was empty + section += [''] + + section += self._doc.read_to_next_empty_line() + + return section + + def _read_sections(self): + while not self._doc.eof(): + data = self._read_to_next_section() + name = data[0].strip() + + if name.startswith('..'): # index section + yield name, data[1:] + elif len(data) < 2: + yield StopIteration + else: + yield name, self._strip(data[2:]) + + def _parse_param_list(self,content): + r = Reader(content) + params = [] + while not r.eof(): + header = r.read().strip() + if ' : ' in header: + arg_name, arg_type = header.split(' : ')[:2] + else: + arg_name, arg_type = header, '' + + desc = r.read_to_next_unindented_line() + for n,line in enumerate(desc): + desc[n] = line.strip() + desc = desc #'\n'.join(desc) + + params.append((arg_name,arg_type,desc)) + + return params + + + _name_rgx = re.compile(r"^\s*(:(?P\w+):`(?P[a-zA-Z0-9_.-]+)`|" + r" (?P[a-zA-Z0-9_.-]+))\s*", re.X) + def _parse_see_also(self, content): + """ + func_name : Descriptive text + continued text + another_func_name : Descriptive text + func_name1, func_name2, :meth:`func_name`, func_name3 + + """ + items = [] + + def parse_item_name(text): + """Match ':role:`name`' or 'name'""" + m = self._name_rgx.match(text) + if m: + g = m.groups() + if g[1] is None: + return g[3], None + else: + return g[2], g[1] + raise ValueError("%s is not a item name" % text) + + def push_item(name, rest): + if not name: + return + name, role = parse_item_name(name) + items.append((name, list(rest), role)) + del rest[:] + + current_func = None + rest = [] + + for line in content: + if not line.strip(): continue + + m = self._name_rgx.match(line) + if m and line[m.end():].strip().startswith(':'): + push_item(current_func, rest) + current_func, line = line[:m.end()], line[m.end():] + rest = [line.split(':', 1)[1].strip()] + if not rest[0]: + rest = [] + elif not line.startswith(' '): + push_item(current_func, rest) + current_func = None + if ',' in line: + for func in line.split(','): + push_item(func, []) + elif line.strip(): + current_func = line + elif current_func is not None: + rest.append(line.strip()) + push_item(current_func, rest) + return items + + def _parse_index(self, section, content): + """ + .. index: default + :refguide: something, else, and more + + """ + def strip_each_in(lst): + return [s.strip() for s in lst] + + out = {} + section = section.split('::') + if len(section) > 1: + out['default'] = strip_each_in(section[1].split(','))[0] + for line in content: + line = line.split(':') + if len(line) > 2: + out[line[1]] = strip_each_in(line[2].split(',')) + return out + + def _parse_summary(self): + """Grab signature (if given) and summary""" + if self._is_at_section(): + return + + summary = self._doc.read_to_next_empty_line() + summary_str = " ".join([s.strip() for s in summary]).strip() + if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str): + self['Signature'] = summary_str + if not self._is_at_section(): + self['Summary'] = self._doc.read_to_next_empty_line() + else: + self['Summary'] = summary + + if not self._is_at_section(): + self['Extended Summary'] = self._read_to_next_section() + + def _parse(self): + self._doc.reset() + self._parse_summary() + + for (section,content) in self._read_sections(): + if not section.startswith('..'): + section = ' '.join([s.capitalize() for s in section.split(' ')]) + if section in ('Parameters', 'Attributes', 'Methods', + 'Returns', 'Raises', 'Warns'): + self[section] = self._parse_param_list(content) + elif section.startswith('.. index::'): + self['index'] = self._parse_index(section, content) + elif section == 'See Also': + self['See Also'] = self._parse_see_also(content) + else: + self[section] = content + + # string conversion routines + + def _str_header(self, name, symbol='-'): + return [name, len(name)*symbol] + + def _str_indent(self, doc, indent=4): + out = [] + for line in doc: + out += [' '*indent + line] + return out + + def _str_signature(self): + if self['Signature']: + return [self['Signature'].replace('*','\*')] + [''] + else: + return [''] + + def _str_summary(self): + if self['Summary']: + return self['Summary'] + [''] + else: + return [] + + def _str_extended_summary(self): + if self['Extended Summary']: + return self['Extended Summary'] + [''] + else: + return [] + + def _str_param_list(self, name): + out = [] + if self[name]: + out += self._str_header(name) + for param,param_type,desc in self[name]: + out += ['%s : %s' % (param, param_type)] + out += self._str_indent(desc) + out += [''] + return out + + def _str_section(self, name): + out = [] + if self[name]: + out += self._str_header(name) + out += self[name] + out += [''] + return out + + def _str_see_also(self, func_role): + if not self['See Also']: return [] + out = [] + out += self._str_header("See Also") + last_had_desc = True + for func, desc, role in self['See Also']: + if role: + link = ':%s:`%s`' % (role, func) + elif func_role: + link = ':%s:`%s`' % (func_role, func) + else: + link = "`%s`_" % func + if desc or last_had_desc: + out += [''] + out += [link] + else: + out[-1] += ", %s" % link + if desc: + out += self._str_indent([' '.join(desc)]) + last_had_desc = True + else: + last_had_desc = False + out += [''] + return out + + def _str_index(self): + idx = self['index'] + out = [] + out += ['.. index:: %s' % idx.get('default','')] + for section, references in idx.iteritems(): + if section == 'default': + continue + out += [' :%s: %s' % (section, ', '.join(references))] + return out + + def __str__(self, func_role=''): + out = [] + out += self._str_signature() + out += self._str_summary() + out += self._str_extended_summary() + for param_list in ('Parameters','Returns','Raises'): + out += self._str_param_list(param_list) + out += self._str_section('Warnings') + out += self._str_see_also(func_role) + for s in ('Notes','References','Examples'): + out += self._str_section(s) + out += self._str_index() + return '\n'.join(out) + + +def indent(str,indent=4): + indent_str = ' '*indent + if str is None: + return indent_str + lines = str.split('\n') + return '\n'.join(indent_str + l for l in lines) + +def header(text, style='-'): + return text + '\n' + style*len(text) + '\n' + + +class FunctionDoc(NumpyDocString): + def __init__(self, func, role='func'): + self._f = func + self._role = role # e.g. "func" or "meth" + try: + NumpyDocString.__init__(self,inspect.getdoc(func) or '') + except ValueError, e: + print '*'*78 + print "ERROR: '%s' while parsing `%s`" % (e, self._f) + print '*'*78 + #print "Docstring follows:" + #print doclines + #print '='*78 + + if not self['Signature']: + func, func_name = self.get_func() + try: + # try to read signature + argspec = inspect.getargspec(func) + argspec = inspect.formatargspec(*argspec) + argspec = argspec.replace('*','\*') + signature = '%s%s' % (func_name, argspec) + except TypeError, e: + signature = '%s()' % func_name + self['Signature'] = signature + + def get_func(self): + func_name = getattr(self._f, '__name__', self.__class__.__name__) + if inspect.isclass(self._f): + func = getattr(self._f, '__call__', self._f.__init__) + else: + func = self._f + return func, func_name + + def __str__(self): + out = '' + + func, func_name = self.get_func() + signature = self['Signature'].replace('*', '\*') + + roles = {'func': 'function', + 'meth': 'method'} + + if self._role: + if not roles.has_key(self._role): + print "Warning: invalid role %s" % self._role + out += '.. %s:: %s\n \n\n' % (roles.get(self._role,''), + func_name) + + out += super(FunctionDoc, self).__str__(func_role=self._role) + return out + + +class ClassDoc(NumpyDocString): + def __init__(self,cls,modulename='',func_doc=FunctionDoc): + if not inspect.isclass(cls): + raise ValueError("Initialise using a class. Got %r" % cls) + self._cls = cls + + if modulename and not modulename.endswith('.'): + modulename += '.' + self._mod = modulename + self._name = cls.__name__ + self._func_doc = func_doc + + NumpyDocString.__init__(self, pydoc.getdoc(cls)) + + @property + def methods(self): + return [name for name,func in inspect.getmembers(self._cls) + if not name.startswith('_') and callable(func)] + + def __str__(self): + out = '' + out += super(ClassDoc, self).__str__() + out += "\n\n" + + #for m in self.methods: + # print "Parsing `%s`" % m + # out += str(self._func_doc(getattr(self._cls,m), 'meth')) + '\n\n' + # out += '.. index::\n single: %s; %s\n\n' % (self._name, m) + + return out + + diff --git a/sphinx/ext/autosummary/docscrape_sphinx.py b/sphinx/ext/autosummary/docscrape_sphinx.py new file mode 100644 index 00000000..d431ecd3 --- /dev/null +++ b/sphinx/ext/autosummary/docscrape_sphinx.py @@ -0,0 +1,133 @@ +import re, inspect, textwrap, pydoc +from docscrape import NumpyDocString, FunctionDoc, ClassDoc + +class SphinxDocString(NumpyDocString): + # string conversion routines + def _str_header(self, name, symbol='`'): + return ['.. rubric:: ' + name, ''] + + def _str_field_list(self, name): + return [':' + name + ':'] + + def _str_indent(self, doc, indent=4): + out = [] + for line in doc: + out += [' '*indent + line] + return out + + def _str_signature(self): + return [''] + if self['Signature']: + return ['``%s``' % self['Signature']] + [''] + else: + return [''] + + def _str_summary(self): + return self['Summary'] + [''] + + def _str_extended_summary(self): + return self['Extended Summary'] + [''] + + def _str_param_list(self, name): + out = [] + if self[name]: + out += self._str_field_list(name) + out += [''] + for param,param_type,desc in self[name]: + out += self._str_indent(['**%s** : %s' % (param.strip(), + param_type)]) + out += [''] + out += self._str_indent(desc,8) + out += [''] + return out + + def _str_section(self, name): + out = [] + if self[name]: + out += self._str_header(name) + out += [''] + content = textwrap.dedent("\n".join(self[name])).split("\n") + out += content + out += [''] + return out + + def _str_see_also(self, func_role): + out = [] + if self['See Also']: + see_also = super(SphinxDocString, self)._str_see_also(func_role) + out = ['.. seealso::', ''] + out += self._str_indent(see_also[2:]) + return out + + def _str_warnings(self): + out = [] + if self['Warnings']: + out = ['.. warning::', ''] + out += self._str_indent(self['Warnings']) + return out + + def _str_index(self): + idx = self['index'] + out = [] + if len(idx) == 0: + return out + + out += ['.. index:: %s' % idx.get('default','')] + for section, references in idx.iteritems(): + if section == 'default': + continue + elif section == 'refguide': + out += [' single: %s' % (', '.join(references))] + else: + out += [' %s: %s' % (section, ','.join(references))] + return out + + def _str_references(self): + out = [] + if self['References']: + out += self._str_header('References') + if isinstance(self['References'], str): + self['References'] = [self['References']] + out.extend(self['References']) + out += [''] + return out + + def __str__(self, indent=0, func_role="obj"): + out = [] + out += self._str_signature() + out += self._str_index() + [''] + out += self._str_summary() + out += self._str_extended_summary() + for param_list in ('Parameters', 'Attributes', 'Methods', + 'Returns','Raises'): + out += self._str_param_list(param_list) + out += self._str_warnings() + out += self._str_see_also(func_role) + out += self._str_section('Notes') + out += self._str_references() + out += self._str_section('Examples') + out = self._str_indent(out,indent) + return '\n'.join(out) + +class SphinxFunctionDoc(SphinxDocString, FunctionDoc): + pass + +class SphinxClassDoc(SphinxDocString, ClassDoc): + pass + +def get_doc_object(obj, what=None): + if what is None: + if inspect.isclass(obj): + what = 'class' + elif inspect.ismodule(obj): + what = 'module' + elif callable(obj): + what = 'function' + else: + what = 'object' + if what == 'class': + return SphinxClassDoc(obj, '', func_doc=SphinxFunctionDoc) + elif what in ('function', 'method'): + return SphinxFunctionDoc(obj, '') + else: + return SphinxDocString(pydoc.getdoc(obj)) diff --git a/sphinx/scripts/__init__.py b/sphinx/scripts/__init__.py new file mode 100644 index 00000000..e69de29b diff --git a/sphinx/scripts/autosummary_generate.py b/sphinx/scripts/autosummary_generate.py new file mode 100755 index 00000000..acab57d3 --- /dev/null +++ b/sphinx/scripts/autosummary_generate.py @@ -0,0 +1,198 @@ +#!/usr/bin/env python +r""" +autosummary_generate.py OPTIONS FILES + +Generate automatic RST source files for items referred to in +autosummary:: directives. + +Each generated RST file contains a single auto*:: directive which +extracts the docstring of the referred item. + +Example Makefile rule:: + + generate: + ./ext/autosummary_generate.py -o source/generated source/*.rst + +""" +import glob, re, inspect, os, optparse +from sphinx.ext.autosummary import import_by_name + +from jinja import Environment, PackageLoader +env = Environment(loader=PackageLoader('numpyext', 'templates')) + +def main(): + p = optparse.OptionParser(__doc__.strip()) + p.add_option("-o", "--output-dir", action="store", type="string", + dest="output_dir", default=None, + help=("Write all output files to the given directory (instead " + "of writing them as specified in the autosummary:: " + "directives)")) + options, args = p.parse_args() + + if len(args) == 0: + p.error("wrong number of arguments") + + # read + names = {} + for name, loc in get_documented(args).items(): + for (filename, sec_title, keyword, toctree) in loc: + if toctree is not None: + path = os.path.join(os.path.dirname(filename), toctree) + names[name] = os.path.abspath(path) + + # write + for name, path in sorted(names.items()): + if options.output_dir is not None: + path = options.output_dir + + if not os.path.isdir(path): + os.makedirs(path) + + try: + obj, name = import_by_name(name) + except ImportError, e: + print "Failed to import '%s': %s" % (name, e) + continue + + fn = os.path.join(path, '%s.rst' % name) + + if os.path.exists(fn): + # skip + continue + + f = open(fn, 'w') + + + try: + + if inspect.ismodule(obj): + tmpl = env.get_template('module.html') + functions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isfunction(getattr(obj, item))] + classes = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and not issubclass(getattr(obj, item), Exception)] + exceptions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and issubclass(getattr(obj, item), Exception)] + rendered = tmpl.render(name=name, + functions=functions, + classes=classes, + exceptions=exceptions, + len_functions=len(functions), + len_classes=len(classes), + len_exceptions=len(exceptions) + + ) + f.write(rendered) + else: + f.write('%s\n%s\n\n' % (name, '='*len(name))) + + if inspect.isclass(obj): + if issubclass(obj, Exception): + f.write(format_modulemember(name, 'autoexception')) + else: + f.write(format_modulemember(name, 'autoclass')) + elif inspect.ismethod(obj) or inspect.ismethoddescriptor(obj): + f.write(format_classmember(name, 'automethod')) + elif callable(obj): + f.write(format_modulemember(name, 'autofunction')) + elif hasattr(obj, '__get__'): + f.write(format_classmember(name, 'autoattribute')) + else: + f.write(format_modulemember(name, 'autofunction')) + finally: + f.close() + +def format_modulemember(name, directive): + parts = name.split('.') + mod, name = '.'.join(parts[:-1]), parts[-1] + return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) + +def format_classmember(name, directive): + parts = name.split('.') + mod, name = '.'.join(parts[:-2]), '.'.join(parts[-2:]) + return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) + +def get_documented(filenames): + """ + Find out what items are documented in source/*.rst + + Returns + ------- + documented : dict of list of (filename, title, keyword, toctree) + Dictionary whose keys are documented names of objects. + The value is a list of locations where the object was documented. + Each location is a tuple of filename, the current section title, + the name of the directive, and the value of the :toctree: argument + (if present) of the directive. + + """ + + title_underline_re = re.compile("^[-=*_^#]{3,}\s*$") + autodoc_re = re.compile(".. auto(function|method|attribute|class|exception|module)::\s*([A-Za-z0-9_.]+)\s*$") + autosummary_re = re.compile(r'^\.\.\s+autosummary::\s*') + module_re = re.compile(r'^\.\.\s+(current)?module::\s*([a-zA-Z0-9_.]+)\s*$') + autosummary_item_re = re.compile(r'^\s+([_a-zA-Z][a-zA-Z0-9_.]*)\s*') + toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') + + documented = {} + + for filename in filenames: + current_title = [] + last_line = None + toctree = None + current_module = None + in_autosummary = False + + f = open(filename, 'r') + for line in f: + try: + if in_autosummary: + m = toctree_arg_re.match(line) + if m: + toctree = m.group(1) + continue + + if line.strip().startswith(':'): + continue # skip options + + m = autosummary_item_re.match(line) + + if m: + name = m.group(1).strip() + if current_module and not name.startswith(current_module + '.'): + name = "%s.%s" % (current_module, name) + documented.setdefault(name, []).append( + (filename, current_title, 'autosummary', toctree)) + continue + if line.strip() == '': + continue + in_autosummary = False + + m = autosummary_re.match(line) + if m: + in_autosummary = True + continue + + m = autodoc_re.search(line) + if m: + name = m.group(2).strip() + if current_module and not name.startswith(current_module + '.'): + name = "%s.%s" % (current_module, name) + if m.group(1) == "module": + current_module = name + documented.setdefault(name, []).append( + (filename, current_title, "auto" + m.group(1), None)) + continue + + m = title_underline_re.match(line) + if m and last_line: + current_title = last_line.strip() + continue + + m = module_re.match(line) + if m: + current_module = m.group(2) + continue + finally: + last_line = line + return documented + +if __name__ == "__main__": + main() diff --git a/sphinx/templates/autosummary-module.html b/sphinx/templates/autosummary-module.html new file mode 100644 index 00000000..34dd8100 --- /dev/null +++ b/sphinx/templates/autosummary-module.html @@ -0,0 +1,39 @@ +:mod:`{{name}}` +=============================================================================================================================================== + + +.. automodule:: {{name}} + +{% if len_functions > 0 %} +Functions +---------- +{% for item in functions %} +.. autofunction:: {{item}} +{% endfor %} +{% endif %} + +{% if len_classes > 0 %} +Classes +-------- +{% for item in classes %} +.. autoclass:: {{item}} + :show-inheritance: + :members: + :inherited-members: + :undoc-members: + +{% endfor %} +{% endif %} + +{% if len_exceptions > 0 %} +Exceptions +------------ +{% for item in exceptions %} +.. autoclass:: {{item}} + :show-inheritance: + :members: + :inherited-members: + :undoc-members: + +{% endfor %} +{% endif %} \ No newline at end of file -- cgit v1.2.1 From 98bd7c4775810b502a1bd47c6a8f1a53f50f7535 Mon Sep 17 00:00:00 2001 From: percious Date: Tue, 4 Nov 2008 10:40:42 -0700 Subject: brought over license file from numpy --- sphinx/ext/autosummary/LICENSE.txt | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 sphinx/ext/autosummary/LICENSE.txt diff --git a/sphinx/ext/autosummary/LICENSE.txt b/sphinx/ext/autosummary/LICENSE.txt new file mode 100644 index 00000000..035a2095 --- /dev/null +++ b/sphinx/ext/autosummary/LICENSE.txt @@ -0,0 +1,32 @@ + The files + - __init__.py + - docscrape.py + - doscrape-sphinx.py + - ../scripts/autosummary_generate.py + + have the following license: + +Copyright (C) 2008 Stefan van der Walt , Pauli Virtanen , Christopher Perkins + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are +met: + + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in + the documentation and/or other materials provided with the + distribution. + +THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, +INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES +(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +POSSIBILITY OF SUCH DAMAGE. -- cgit v1.2.1 From f2b1348908e73a94b063fb2c2fb703ab93b07c1f Mon Sep 17 00:00:00 2001 From: percious Date: Tue, 4 Nov 2008 11:07:58 -0700 Subject: reorganized code to fit within the ext.autosummary module --- setup.py | 2 +- sphinx/ext/autosummary/LICENSE.txt | 3 +- sphinx/ext/autosummary/generate.py | 195 ++++++++++++++++++++++++++ sphinx/ext/autosummary/templates/module.html | 39 ++++++ sphinx/scripts/__init__.py | 0 sphinx/scripts/autosummary_generate.py | 198 --------------------------- sphinx/templates/autosummary-module.html | 39 ------ 7 files changed, 237 insertions(+), 239 deletions(-) create mode 100644 sphinx/ext/autosummary/generate.py create mode 100644 sphinx/ext/autosummary/templates/module.html delete mode 100644 sphinx/scripts/__init__.py delete mode 100755 sphinx/scripts/autosummary_generate.py delete mode 100644 sphinx/templates/autosummary-module.html diff --git a/setup.py b/setup.py index aa4d2c21..13e70690 100644 --- a/setup.py +++ b/setup.py @@ -178,7 +178,7 @@ setup( 'console_scripts': [ 'sphinx-build = sphinx:main', 'sphinx-quickstart = sphinx.quickstart:main', - 'sphinx-autogen = sphinx.scripts.autosummary_generate:main', + 'sphinx-autogen = sphinx.ext.autosummary.generate:main', ], 'distutils.commands': [ 'build_sphinx = sphinx.setup_command:BuildDoc', diff --git a/sphinx/ext/autosummary/LICENSE.txt b/sphinx/ext/autosummary/LICENSE.txt index 035a2095..da27afd4 100644 --- a/sphinx/ext/autosummary/LICENSE.txt +++ b/sphinx/ext/autosummary/LICENSE.txt @@ -2,7 +2,8 @@ - __init__.py - docscrape.py - doscrape-sphinx.py - - ../scripts/autosummary_generate.py + - generate.py + - templates/module.html have the following license: diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py new file mode 100644 index 00000000..ce9e4c2d --- /dev/null +++ b/sphinx/ext/autosummary/generate.py @@ -0,0 +1,195 @@ +""" +autosummary_generate.py OPTIONS FILES + +Generate automatic RST source files for items referred to in +autosummary:: directives. + +Each generated RST file contains a single auto*:: directive which +extracts the docstring of the referred item. + +Example Makefile rule:: + + generate: + sphinx-autogen source/*.rst source/generated + +""" +import glob, re, inspect, os, optparse +from sphinx.ext.autosummary import import_by_name + +from jinja import Environment, PackageLoader +env = Environment(loader=PackageLoader('sphinx.ext.autosummary', 'templates')) + +def main(): + p = optparse.OptionParser(__doc__.strip()) + options, args = p.parse_args() + + if len(args) <2: + p.error("wrong number of arguments") + + print 'generating docs from:', args[:-1] + generate_autosummary_docs(args[:-1], args[-1]) + +def generate_autosummary_docs(source_dir, output_dir): + # read + names = {} + for name, loc in get_documented(source_dir).items(): + for (filename, sec_title, keyword, toctree) in loc: + if toctree is not None: + path = os.path.join(os.path.dirname(filename), toctree) + names[name] = os.path.abspath(path) + + # write + for name, path in sorted(names.items()): + path = output_dir + + if not os.path.isdir(path): + os.makedirs(path) + + try: + obj, name = import_by_name(name) + except ImportError, e: + print "Failed to import '%s': %s" % (name, e) + continue + + fn = os.path.join(path, '%s.rst' % name) + + if os.path.exists(fn): + # skip + continue + + f = open(fn, 'w') + + + try: + + if inspect.ismodule(obj): + tmpl = env.get_template('module.html') + functions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isfunction(getattr(obj, item))] + classes = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and not issubclass(getattr(obj, item), Exception)] + exceptions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and issubclass(getattr(obj, item), Exception)] + rendered = tmpl.render(name=name, + functions=functions, + classes=classes, + exceptions=exceptions, + len_functions=len(functions), + len_classes=len(classes), + len_exceptions=len(exceptions) + + ) + f.write(rendered) + else: + f.write('%s\n%s\n\n' % (name, '='*len(name))) + + if inspect.isclass(obj): + if issubclass(obj, Exception): + f.write(format_modulemember(name, 'autoexception')) + else: + f.write(format_modulemember(name, 'autoclass')) + elif inspect.ismethod(obj) or inspect.ismethoddescriptor(obj): + f.write(format_classmember(name, 'automethod')) + elif callable(obj): + f.write(format_modulemember(name, 'autofunction')) + elif hasattr(obj, '__get__'): + f.write(format_classmember(name, 'autoattribute')) + else: + f.write(format_modulemember(name, 'autofunction')) + finally: + f.close() + +def format_modulemember(name, directive): + parts = name.split('.') + mod, name = '.'.join(parts[:-1]), parts[-1] + return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) + +def format_classmember(name, directive): + parts = name.split('.') + mod, name = '.'.join(parts[:-2]), '.'.join(parts[-2:]) + return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) + +def get_documented(filenames): + """ + Find out what items are documented in source/*.rst + + Returns + ------- + documented : dict of list of (filename, title, keyword, toctree) + Dictionary whose keys are documented names of objects. + The value is a list of locations where the object was documented. + Each location is a tuple of filename, the current section title, + the name of the directive, and the value of the :toctree: argument + (if present) of the directive. + + """ + + title_underline_re = re.compile("^[-=*_^#]{3,}\s*$") + autodoc_re = re.compile(".. auto(function|method|attribute|class|exception|module)::\s*([A-Za-z0-9_.]+)\s*$") + autosummary_re = re.compile(r'^\.\.\s+autosummary::\s*') + module_re = re.compile(r'^\.\.\s+(current)?module::\s*([a-zA-Z0-9_.]+)\s*$') + autosummary_item_re = re.compile(r'^\s+([_a-zA-Z][a-zA-Z0-9_.]*)\s*') + toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') + + documented = {} + + for filename in filenames: + current_title = [] + last_line = None + toctree = None + current_module = None + in_autosummary = False + + f = open(filename, 'r') + for line in f: + try: + if in_autosummary: + m = toctree_arg_re.match(line) + if m: + toctree = m.group(1) + continue + + if line.strip().startswith(':'): + continue # skip options + + m = autosummary_item_re.match(line) + + if m: + name = m.group(1).strip() + if current_module and not name.startswith(current_module + '.'): + name = "%s.%s" % (current_module, name) + documented.setdefault(name, []).append( + (filename, current_title, 'autosummary', toctree)) + continue + if line.strip() == '': + continue + in_autosummary = False + + m = autosummary_re.match(line) + if m: + in_autosummary = True + continue + + m = autodoc_re.search(line) + if m: + name = m.group(2).strip() + if current_module and not name.startswith(current_module + '.'): + name = "%s.%s" % (current_module, name) + if m.group(1) == "module": + current_module = name + documented.setdefault(name, []).append( + (filename, current_title, "auto" + m.group(1), None)) + continue + + m = title_underline_re.match(line) + if m and last_line: + current_title = last_line.strip() + continue + + m = module_re.match(line) + if m: + current_module = m.group(2) + continue + finally: + last_line = line + return documented + +if __name__ == "__main__": + main() diff --git a/sphinx/ext/autosummary/templates/module.html b/sphinx/ext/autosummary/templates/module.html new file mode 100644 index 00000000..34dd8100 --- /dev/null +++ b/sphinx/ext/autosummary/templates/module.html @@ -0,0 +1,39 @@ +:mod:`{{name}}` +=============================================================================================================================================== + + +.. automodule:: {{name}} + +{% if len_functions > 0 %} +Functions +---------- +{% for item in functions %} +.. autofunction:: {{item}} +{% endfor %} +{% endif %} + +{% if len_classes > 0 %} +Classes +-------- +{% for item in classes %} +.. autoclass:: {{item}} + :show-inheritance: + :members: + :inherited-members: + :undoc-members: + +{% endfor %} +{% endif %} + +{% if len_exceptions > 0 %} +Exceptions +------------ +{% for item in exceptions %} +.. autoclass:: {{item}} + :show-inheritance: + :members: + :inherited-members: + :undoc-members: + +{% endfor %} +{% endif %} \ No newline at end of file diff --git a/sphinx/scripts/__init__.py b/sphinx/scripts/__init__.py deleted file mode 100644 index e69de29b..00000000 diff --git a/sphinx/scripts/autosummary_generate.py b/sphinx/scripts/autosummary_generate.py deleted file mode 100755 index acab57d3..00000000 --- a/sphinx/scripts/autosummary_generate.py +++ /dev/null @@ -1,198 +0,0 @@ -#!/usr/bin/env python -r""" -autosummary_generate.py OPTIONS FILES - -Generate automatic RST source files for items referred to in -autosummary:: directives. - -Each generated RST file contains a single auto*:: directive which -extracts the docstring of the referred item. - -Example Makefile rule:: - - generate: - ./ext/autosummary_generate.py -o source/generated source/*.rst - -""" -import glob, re, inspect, os, optparse -from sphinx.ext.autosummary import import_by_name - -from jinja import Environment, PackageLoader -env = Environment(loader=PackageLoader('numpyext', 'templates')) - -def main(): - p = optparse.OptionParser(__doc__.strip()) - p.add_option("-o", "--output-dir", action="store", type="string", - dest="output_dir", default=None, - help=("Write all output files to the given directory (instead " - "of writing them as specified in the autosummary:: " - "directives)")) - options, args = p.parse_args() - - if len(args) == 0: - p.error("wrong number of arguments") - - # read - names = {} - for name, loc in get_documented(args).items(): - for (filename, sec_title, keyword, toctree) in loc: - if toctree is not None: - path = os.path.join(os.path.dirname(filename), toctree) - names[name] = os.path.abspath(path) - - # write - for name, path in sorted(names.items()): - if options.output_dir is not None: - path = options.output_dir - - if not os.path.isdir(path): - os.makedirs(path) - - try: - obj, name = import_by_name(name) - except ImportError, e: - print "Failed to import '%s': %s" % (name, e) - continue - - fn = os.path.join(path, '%s.rst' % name) - - if os.path.exists(fn): - # skip - continue - - f = open(fn, 'w') - - - try: - - if inspect.ismodule(obj): - tmpl = env.get_template('module.html') - functions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isfunction(getattr(obj, item))] - classes = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and not issubclass(getattr(obj, item), Exception)] - exceptions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and issubclass(getattr(obj, item), Exception)] - rendered = tmpl.render(name=name, - functions=functions, - classes=classes, - exceptions=exceptions, - len_functions=len(functions), - len_classes=len(classes), - len_exceptions=len(exceptions) - - ) - f.write(rendered) - else: - f.write('%s\n%s\n\n' % (name, '='*len(name))) - - if inspect.isclass(obj): - if issubclass(obj, Exception): - f.write(format_modulemember(name, 'autoexception')) - else: - f.write(format_modulemember(name, 'autoclass')) - elif inspect.ismethod(obj) or inspect.ismethoddescriptor(obj): - f.write(format_classmember(name, 'automethod')) - elif callable(obj): - f.write(format_modulemember(name, 'autofunction')) - elif hasattr(obj, '__get__'): - f.write(format_classmember(name, 'autoattribute')) - else: - f.write(format_modulemember(name, 'autofunction')) - finally: - f.close() - -def format_modulemember(name, directive): - parts = name.split('.') - mod, name = '.'.join(parts[:-1]), parts[-1] - return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) - -def format_classmember(name, directive): - parts = name.split('.') - mod, name = '.'.join(parts[:-2]), '.'.join(parts[-2:]) - return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) - -def get_documented(filenames): - """ - Find out what items are documented in source/*.rst - - Returns - ------- - documented : dict of list of (filename, title, keyword, toctree) - Dictionary whose keys are documented names of objects. - The value is a list of locations where the object was documented. - Each location is a tuple of filename, the current section title, - the name of the directive, and the value of the :toctree: argument - (if present) of the directive. - - """ - - title_underline_re = re.compile("^[-=*_^#]{3,}\s*$") - autodoc_re = re.compile(".. auto(function|method|attribute|class|exception|module)::\s*([A-Za-z0-9_.]+)\s*$") - autosummary_re = re.compile(r'^\.\.\s+autosummary::\s*') - module_re = re.compile(r'^\.\.\s+(current)?module::\s*([a-zA-Z0-9_.]+)\s*$') - autosummary_item_re = re.compile(r'^\s+([_a-zA-Z][a-zA-Z0-9_.]*)\s*') - toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') - - documented = {} - - for filename in filenames: - current_title = [] - last_line = None - toctree = None - current_module = None - in_autosummary = False - - f = open(filename, 'r') - for line in f: - try: - if in_autosummary: - m = toctree_arg_re.match(line) - if m: - toctree = m.group(1) - continue - - if line.strip().startswith(':'): - continue # skip options - - m = autosummary_item_re.match(line) - - if m: - name = m.group(1).strip() - if current_module and not name.startswith(current_module + '.'): - name = "%s.%s" % (current_module, name) - documented.setdefault(name, []).append( - (filename, current_title, 'autosummary', toctree)) - continue - if line.strip() == '': - continue - in_autosummary = False - - m = autosummary_re.match(line) - if m: - in_autosummary = True - continue - - m = autodoc_re.search(line) - if m: - name = m.group(2).strip() - if current_module and not name.startswith(current_module + '.'): - name = "%s.%s" % (current_module, name) - if m.group(1) == "module": - current_module = name - documented.setdefault(name, []).append( - (filename, current_title, "auto" + m.group(1), None)) - continue - - m = title_underline_re.match(line) - if m and last_line: - current_title = last_line.strip() - continue - - m = module_re.match(line) - if m: - current_module = m.group(2) - continue - finally: - last_line = line - return documented - -if __name__ == "__main__": - main() diff --git a/sphinx/templates/autosummary-module.html b/sphinx/templates/autosummary-module.html deleted file mode 100644 index 34dd8100..00000000 --- a/sphinx/templates/autosummary-module.html +++ /dev/null @@ -1,39 +0,0 @@ -:mod:`{{name}}` -=============================================================================================================================================== - - -.. automodule:: {{name}} - -{% if len_functions > 0 %} -Functions ----------- -{% for item in functions %} -.. autofunction:: {{item}} -{% endfor %} -{% endif %} - -{% if len_classes > 0 %} -Classes --------- -{% for item in classes %} -.. autoclass:: {{item}} - :show-inheritance: - :members: - :inherited-members: - :undoc-members: - -{% endfor %} -{% endif %} - -{% if len_exceptions > 0 %} -Exceptions ------------- -{% for item in exceptions %} -.. autoclass:: {{item}} - :show-inheritance: - :members: - :inherited-members: - :undoc-members: - -{% endfor %} -{% endif %} \ No newline at end of file -- cgit v1.2.1 From bd4d482e749d592f9745f0f2b84133fdb3b3a4ba Mon Sep 17 00:00:00 2001 From: percious Date: Tue, 4 Nov 2008 11:25:03 -0700 Subject: modified sphinx-build script to allow for auto-generation of docs --- sphinx/__init__.py | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/sphinx/__init__.py b/sphinx/__init__.py index d53fdafd..2c96cdd9 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -42,6 +42,7 @@ Options: -b -- builder to use; default is html -N -- do not do colored output -q -- no output on stdout, just warnings on stderr -P -- run Pdb on exception + -g -- create autogenerated files Modi: * without -a and without filenames, write new and changed files. * with -a, write all files. @@ -59,7 +60,7 @@ def main(argv=sys.argv): nocolor() try: - opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:NEqP') + opts, args = getopt.getopt(argv[1:], 'ab:d:c:D:g:NEqP') srcdir = confdir = path.abspath(args[0]) if not path.isdir(srcdir): print >>sys.stderr, 'Error: Cannot find source directory.' @@ -84,6 +85,7 @@ def main(argv=sys.argv): err = 1 if err: return 1 + buildername = all_files = None freshenv = use_pdb = False @@ -91,7 +93,19 @@ def main(argv=sys.argv): confoverrides = {} doctreedir = path.join(outdir, '.doctrees') for opt, val in opts: - if opt == '-b': + + if opt == '-g': + print 'in here' + source_filenames =[srcdir+'/'+f for f in os.listdir(srcdir) if f.endswith('.rst')] + if val is None: + print >>sys.stderr, \ + 'Error: you must provide a destination directory for autodoc generation.' + return 1 + p = path.abspath(val) + from sphinx.ext.autosummary.generate import generate_autosummary_docs + generate_autosummary_docs(source_filenames, p) + + elif opt == '-b': buildername = val elif opt == '-a': if filenames: -- cgit v1.2.1 From d5943afe33490828fd8dfeee969b25e8b49d0314 Mon Sep 17 00:00:00 2001 From: percious Date: Tue, 4 Nov 2008 13:58:17 -0700 Subject: added -g option to sphinx-build and cleaned out numpy code. --- sphinx/__init__.py | 1 - sphinx/ext/autosummary/__init__.py | 22 +- sphinx/ext/autosummary/docscrape.py | 500 ----------------------------- sphinx/ext/autosummary/docscrape_sphinx.py | 133 -------- 4 files changed, 1 insertion(+), 655 deletions(-) delete mode 100644 sphinx/ext/autosummary/docscrape.py delete mode 100644 sphinx/ext/autosummary/docscrape_sphinx.py diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 2c96cdd9..bda0efb0 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -95,7 +95,6 @@ def main(argv=sys.argv): for opt, val in opts: if opt == '-g': - print 'in here' source_filenames =[srcdir+'/'+f for f in os.listdir(srcdir) if f.endswith('.rst')] if val is None: print >>sys.stderr, \ diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 6b74190c..be11309e 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -59,7 +59,6 @@ from docutils import nodes import sphinx.addnodes, sphinx.roles, sphinx.builder from sphinx.util import patfilter -from docscrape_sphinx import get_doc_object import inspect def setup(app): @@ -215,30 +214,11 @@ def get_autosummary(names, state, no_signatures=False): real_names[name] = real_name - doc = get_doc_object(obj) - - if doc['Summary']: - title = " ".join(doc['Summary']) - else: - title = "" qualifier = 'obj' if inspect.ismodule(obj): qualifier = 'mod' col1 = ":"+qualifier+":`%s <%s>`" % (name, real_name) - if doc['Signature']: - sig = re.sub('^[a-zA-Z_0-9.-]*', '', - doc['Signature'].replace('*', r'\*')) - if '=' in sig: - # abbreviate optional arguments - sig = re.sub(r', ([a-zA-Z0-9_]+)=', r'[, \1=', sig, count=1) - sig = re.sub(r'\(([a-zA-Z0-9_]+)=', r'([\1=', sig, count=1) - sig = re.sub(r'=[^,)]+,', ',', sig) - sig = re.sub(r'=[^,)]+\)$', '])', sig) - # shorten long strings - sig = re.sub(r'(\[.{16,16}[^,)]*?),.*?\]\)', r'\1, ...])', sig) - else: - sig = re.sub(r'(\(.{16,16}[^,)]*?),.*?\)', r'\1, ...)', sig) - col1 += " " + sig + col2 = title append_row(col1, col2) diff --git a/sphinx/ext/autosummary/docscrape.py b/sphinx/ext/autosummary/docscrape.py deleted file mode 100644 index beb4a24e..00000000 --- a/sphinx/ext/autosummary/docscrape.py +++ /dev/null @@ -1,500 +0,0 @@ -"""Extract reference documentation from the NumPy source tree. - -""" - -import inspect -import textwrap -import re -import pydoc -from StringIO import StringIO -from warnings import warn - -class Reader(object): - """A line-based string reader. - - """ - def __init__(self, data): - """ - Parameters - ---------- - data : str - String with lines separated by '\n'. - - """ - if isinstance(data,list): - self._str = data - else: - self._str = data.split('\n') # store string as list of lines - - self.reset() - - def __getitem__(self, n): - return self._str[n] - - def reset(self): - self._l = 0 # current line nr - - def read(self): - if not self.eof(): - out = self[self._l] - self._l += 1 - return out - else: - return '' - - def seek_next_non_empty_line(self): - for l in self[self._l:]: - if l.strip(): - break - else: - self._l += 1 - - def eof(self): - return self._l >= len(self._str) - - def read_to_condition(self, condition_func): - start = self._l - for line in self[start:]: - if condition_func(line): - return self[start:self._l] - self._l += 1 - if self.eof(): - return self[start:self._l+1] - return [] - - def read_to_next_empty_line(self): - self.seek_next_non_empty_line() - def is_empty(line): - return not line.strip() - return self.read_to_condition(is_empty) - - def read_to_next_unindented_line(self): - def is_unindented(line): - return (line.strip() and (len(line.lstrip()) == len(line))) - return self.read_to_condition(is_unindented) - - def peek(self,n=0): - if self._l + n < len(self._str): - return self[self._l + n] - else: - return '' - - def is_empty(self): - return not ''.join(self._str).strip() - - -class NumpyDocString(object): - def __init__(self,docstring): - docstring = docstring.split('\n') - - # De-indent paragraph - try: - indent = min(len(s) - len(s.lstrip()) for s in docstring - if s.strip()) - except ValueError: - indent = 0 - - for n,line in enumerate(docstring): - docstring[n] = docstring[n][indent:] - - self._doc = Reader(docstring) - self._parsed_data = { - 'Signature': '', - 'Summary': '', - 'Extended Summary': [], - 'Parameters': [], - 'Returns': [], - 'Raises': [], - 'Warns': [], - 'Other Parameters': [], - 'Attributes': [], - 'Methods': [], - 'See Also': [], - 'Notes': [], - 'Warnings': [], - 'References': '', - 'Examples': '', - 'index': {} - } - - self._parse() - - def __getitem__(self,key): - return self._parsed_data[key] - - def __setitem__(self,key,val): - if not self._parsed_data.has_key(key): - warn("Unknown section %s" % key) - else: - self._parsed_data[key] = val - - def _is_at_section(self): - self._doc.seek_next_non_empty_line() - - if self._doc.eof(): - return False - - l1 = self._doc.peek().strip() # e.g. Parameters - - if l1.startswith('.. index::'): - return True - - l2 = self._doc.peek(1).strip() # ---------- or ========== - return l2.startswith('-'*len(l1)) or l2.startswith('='*len(l1)) - - def _strip(self,doc): - i = 0 - j = 0 - for i,line in enumerate(doc): - if line.strip(): break - - for j,line in enumerate(doc[::-1]): - if line.strip(): break - - return doc[i:len(doc)-j] - - def _read_to_next_section(self): - section = self._doc.read_to_next_empty_line() - - while not self._is_at_section() and not self._doc.eof(): - if not self._doc.peek(-1).strip(): # previous line was empty - section += [''] - - section += self._doc.read_to_next_empty_line() - - return section - - def _read_sections(self): - while not self._doc.eof(): - data = self._read_to_next_section() - name = data[0].strip() - - if name.startswith('..'): # index section - yield name, data[1:] - elif len(data) < 2: - yield StopIteration - else: - yield name, self._strip(data[2:]) - - def _parse_param_list(self,content): - r = Reader(content) - params = [] - while not r.eof(): - header = r.read().strip() - if ' : ' in header: - arg_name, arg_type = header.split(' : ')[:2] - else: - arg_name, arg_type = header, '' - - desc = r.read_to_next_unindented_line() - for n,line in enumerate(desc): - desc[n] = line.strip() - desc = desc #'\n'.join(desc) - - params.append((arg_name,arg_type,desc)) - - return params - - - _name_rgx = re.compile(r"^\s*(:(?P\w+):`(?P[a-zA-Z0-9_.-]+)`|" - r" (?P[a-zA-Z0-9_.-]+))\s*", re.X) - def _parse_see_also(self, content): - """ - func_name : Descriptive text - continued text - another_func_name : Descriptive text - func_name1, func_name2, :meth:`func_name`, func_name3 - - """ - items = [] - - def parse_item_name(text): - """Match ':role:`name`' or 'name'""" - m = self._name_rgx.match(text) - if m: - g = m.groups() - if g[1] is None: - return g[3], None - else: - return g[2], g[1] - raise ValueError("%s is not a item name" % text) - - def push_item(name, rest): - if not name: - return - name, role = parse_item_name(name) - items.append((name, list(rest), role)) - del rest[:] - - current_func = None - rest = [] - - for line in content: - if not line.strip(): continue - - m = self._name_rgx.match(line) - if m and line[m.end():].strip().startswith(':'): - push_item(current_func, rest) - current_func, line = line[:m.end()], line[m.end():] - rest = [line.split(':', 1)[1].strip()] - if not rest[0]: - rest = [] - elif not line.startswith(' '): - push_item(current_func, rest) - current_func = None - if ',' in line: - for func in line.split(','): - push_item(func, []) - elif line.strip(): - current_func = line - elif current_func is not None: - rest.append(line.strip()) - push_item(current_func, rest) - return items - - def _parse_index(self, section, content): - """ - .. index: default - :refguide: something, else, and more - - """ - def strip_each_in(lst): - return [s.strip() for s in lst] - - out = {} - section = section.split('::') - if len(section) > 1: - out['default'] = strip_each_in(section[1].split(','))[0] - for line in content: - line = line.split(':') - if len(line) > 2: - out[line[1]] = strip_each_in(line[2].split(',')) - return out - - def _parse_summary(self): - """Grab signature (if given) and summary""" - if self._is_at_section(): - return - - summary = self._doc.read_to_next_empty_line() - summary_str = " ".join([s.strip() for s in summary]).strip() - if re.compile('^([\w., ]+=)?\s*[\w\.]+\(.*\)$').match(summary_str): - self['Signature'] = summary_str - if not self._is_at_section(): - self['Summary'] = self._doc.read_to_next_empty_line() - else: - self['Summary'] = summary - - if not self._is_at_section(): - self['Extended Summary'] = self._read_to_next_section() - - def _parse(self): - self._doc.reset() - self._parse_summary() - - for (section,content) in self._read_sections(): - if not section.startswith('..'): - section = ' '.join([s.capitalize() for s in section.split(' ')]) - if section in ('Parameters', 'Attributes', 'Methods', - 'Returns', 'Raises', 'Warns'): - self[section] = self._parse_param_list(content) - elif section.startswith('.. index::'): - self['index'] = self._parse_index(section, content) - elif section == 'See Also': - self['See Also'] = self._parse_see_also(content) - else: - self[section] = content - - # string conversion routines - - def _str_header(self, name, symbol='-'): - return [name, len(name)*symbol] - - def _str_indent(self, doc, indent=4): - out = [] - for line in doc: - out += [' '*indent + line] - return out - - def _str_signature(self): - if self['Signature']: - return [self['Signature'].replace('*','\*')] + [''] - else: - return [''] - - def _str_summary(self): - if self['Summary']: - return self['Summary'] + [''] - else: - return [] - - def _str_extended_summary(self): - if self['Extended Summary']: - return self['Extended Summary'] + [''] - else: - return [] - - def _str_param_list(self, name): - out = [] - if self[name]: - out += self._str_header(name) - for param,param_type,desc in self[name]: - out += ['%s : %s' % (param, param_type)] - out += self._str_indent(desc) - out += [''] - return out - - def _str_section(self, name): - out = [] - if self[name]: - out += self._str_header(name) - out += self[name] - out += [''] - return out - - def _str_see_also(self, func_role): - if not self['See Also']: return [] - out = [] - out += self._str_header("See Also") - last_had_desc = True - for func, desc, role in self['See Also']: - if role: - link = ':%s:`%s`' % (role, func) - elif func_role: - link = ':%s:`%s`' % (func_role, func) - else: - link = "`%s`_" % func - if desc or last_had_desc: - out += [''] - out += [link] - else: - out[-1] += ", %s" % link - if desc: - out += self._str_indent([' '.join(desc)]) - last_had_desc = True - else: - last_had_desc = False - out += [''] - return out - - def _str_index(self): - idx = self['index'] - out = [] - out += ['.. index:: %s' % idx.get('default','')] - for section, references in idx.iteritems(): - if section == 'default': - continue - out += [' :%s: %s' % (section, ', '.join(references))] - return out - - def __str__(self, func_role=''): - out = [] - out += self._str_signature() - out += self._str_summary() - out += self._str_extended_summary() - for param_list in ('Parameters','Returns','Raises'): - out += self._str_param_list(param_list) - out += self._str_section('Warnings') - out += self._str_see_also(func_role) - for s in ('Notes','References','Examples'): - out += self._str_section(s) - out += self._str_index() - return '\n'.join(out) - - -def indent(str,indent=4): - indent_str = ' '*indent - if str is None: - return indent_str - lines = str.split('\n') - return '\n'.join(indent_str + l for l in lines) - -def header(text, style='-'): - return text + '\n' + style*len(text) + '\n' - - -class FunctionDoc(NumpyDocString): - def __init__(self, func, role='func'): - self._f = func - self._role = role # e.g. "func" or "meth" - try: - NumpyDocString.__init__(self,inspect.getdoc(func) or '') - except ValueError, e: - print '*'*78 - print "ERROR: '%s' while parsing `%s`" % (e, self._f) - print '*'*78 - #print "Docstring follows:" - #print doclines - #print '='*78 - - if not self['Signature']: - func, func_name = self.get_func() - try: - # try to read signature - argspec = inspect.getargspec(func) - argspec = inspect.formatargspec(*argspec) - argspec = argspec.replace('*','\*') - signature = '%s%s' % (func_name, argspec) - except TypeError, e: - signature = '%s()' % func_name - self['Signature'] = signature - - def get_func(self): - func_name = getattr(self._f, '__name__', self.__class__.__name__) - if inspect.isclass(self._f): - func = getattr(self._f, '__call__', self._f.__init__) - else: - func = self._f - return func, func_name - - def __str__(self): - out = '' - - func, func_name = self.get_func() - signature = self['Signature'].replace('*', '\*') - - roles = {'func': 'function', - 'meth': 'method'} - - if self._role: - if not roles.has_key(self._role): - print "Warning: invalid role %s" % self._role - out += '.. %s:: %s\n \n\n' % (roles.get(self._role,''), - func_name) - - out += super(FunctionDoc, self).__str__(func_role=self._role) - return out - - -class ClassDoc(NumpyDocString): - def __init__(self,cls,modulename='',func_doc=FunctionDoc): - if not inspect.isclass(cls): - raise ValueError("Initialise using a class. Got %r" % cls) - self._cls = cls - - if modulename and not modulename.endswith('.'): - modulename += '.' - self._mod = modulename - self._name = cls.__name__ - self._func_doc = func_doc - - NumpyDocString.__init__(self, pydoc.getdoc(cls)) - - @property - def methods(self): - return [name for name,func in inspect.getmembers(self._cls) - if not name.startswith('_') and callable(func)] - - def __str__(self): - out = '' - out += super(ClassDoc, self).__str__() - out += "\n\n" - - #for m in self.methods: - # print "Parsing `%s`" % m - # out += str(self._func_doc(getattr(self._cls,m), 'meth')) + '\n\n' - # out += '.. index::\n single: %s; %s\n\n' % (self._name, m) - - return out - - diff --git a/sphinx/ext/autosummary/docscrape_sphinx.py b/sphinx/ext/autosummary/docscrape_sphinx.py deleted file mode 100644 index d431ecd3..00000000 --- a/sphinx/ext/autosummary/docscrape_sphinx.py +++ /dev/null @@ -1,133 +0,0 @@ -import re, inspect, textwrap, pydoc -from docscrape import NumpyDocString, FunctionDoc, ClassDoc - -class SphinxDocString(NumpyDocString): - # string conversion routines - def _str_header(self, name, symbol='`'): - return ['.. rubric:: ' + name, ''] - - def _str_field_list(self, name): - return [':' + name + ':'] - - def _str_indent(self, doc, indent=4): - out = [] - for line in doc: - out += [' '*indent + line] - return out - - def _str_signature(self): - return [''] - if self['Signature']: - return ['``%s``' % self['Signature']] + [''] - else: - return [''] - - def _str_summary(self): - return self['Summary'] + [''] - - def _str_extended_summary(self): - return self['Extended Summary'] + [''] - - def _str_param_list(self, name): - out = [] - if self[name]: - out += self._str_field_list(name) - out += [''] - for param,param_type,desc in self[name]: - out += self._str_indent(['**%s** : %s' % (param.strip(), - param_type)]) - out += [''] - out += self._str_indent(desc,8) - out += [''] - return out - - def _str_section(self, name): - out = [] - if self[name]: - out += self._str_header(name) - out += [''] - content = textwrap.dedent("\n".join(self[name])).split("\n") - out += content - out += [''] - return out - - def _str_see_also(self, func_role): - out = [] - if self['See Also']: - see_also = super(SphinxDocString, self)._str_see_also(func_role) - out = ['.. seealso::', ''] - out += self._str_indent(see_also[2:]) - return out - - def _str_warnings(self): - out = [] - if self['Warnings']: - out = ['.. warning::', ''] - out += self._str_indent(self['Warnings']) - return out - - def _str_index(self): - idx = self['index'] - out = [] - if len(idx) == 0: - return out - - out += ['.. index:: %s' % idx.get('default','')] - for section, references in idx.iteritems(): - if section == 'default': - continue - elif section == 'refguide': - out += [' single: %s' % (', '.join(references))] - else: - out += [' %s: %s' % (section, ','.join(references))] - return out - - def _str_references(self): - out = [] - if self['References']: - out += self._str_header('References') - if isinstance(self['References'], str): - self['References'] = [self['References']] - out.extend(self['References']) - out += [''] - return out - - def __str__(self, indent=0, func_role="obj"): - out = [] - out += self._str_signature() - out += self._str_index() + [''] - out += self._str_summary() - out += self._str_extended_summary() - for param_list in ('Parameters', 'Attributes', 'Methods', - 'Returns','Raises'): - out += self._str_param_list(param_list) - out += self._str_warnings() - out += self._str_see_also(func_role) - out += self._str_section('Notes') - out += self._str_references() - out += self._str_section('Examples') - out = self._str_indent(out,indent) - return '\n'.join(out) - -class SphinxFunctionDoc(SphinxDocString, FunctionDoc): - pass - -class SphinxClassDoc(SphinxDocString, ClassDoc): - pass - -def get_doc_object(obj, what=None): - if what is None: - if inspect.isclass(obj): - what = 'class' - elif inspect.ismodule(obj): - what = 'module' - elif callable(obj): - what = 'function' - else: - what = 'object' - if what == 'class': - return SphinxClassDoc(obj, '', func_doc=SphinxFunctionDoc) - elif what in ('function', 'method'): - return SphinxFunctionDoc(obj, '') - else: - return SphinxDocString(pydoc.getdoc(obj)) -- cgit v1.2.1 From 5f4c4a17c9691abff90d8f1cbf028a9a67967621 Mon Sep 17 00:00:00 2001 From: percious Date: Tue, 4 Nov 2008 13:59:02 -0700 Subject: modified license file to reflect removal of numpy-specific code. --- sphinx/ext/autosummary/LICENSE.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/sphinx/ext/autosummary/LICENSE.txt b/sphinx/ext/autosummary/LICENSE.txt index da27afd4..aa1bf333 100644 --- a/sphinx/ext/autosummary/LICENSE.txt +++ b/sphinx/ext/autosummary/LICENSE.txt @@ -1,7 +1,5 @@ The files - __init__.py - - docscrape.py - - doscrape-sphinx.py - generate.py - templates/module.html -- cgit v1.2.1 From b3d241f948b0f0022dd2eb23600ae60555a5ab16 Mon Sep 17 00:00:00 2001 From: percious Date: Tue, 4 Nov 2008 15:01:46 -0700 Subject: fixed bug in autosummary. --- sphinx/ext/autosummary/__init__.py | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index be11309e..f26c4676 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -214,11 +214,9 @@ def get_autosummary(names, state, no_signatures=False): real_names[name] = real_name + title = "" qualifier = 'obj' - if inspect.ismodule(obj): - qualifier = 'mod' col1 = ":"+qualifier+":`%s <%s>`" % (name, real_name) - col2 = title append_row(col1, col2) -- cgit v1.2.1 From 11b7c42eac7391e60cfe6d523a988c5410b431fd Mon Sep 17 00:00:00 2001 From: Sebastian Wiesner Date: Thu, 20 Nov 2008 20:05:45 +0100 Subject: Switched templating to jinja2 --- babel.cfg | 6 +-- setup.py | 4 +- sphinx/_jinja2.py | 90 ++++++++++++++++++++++++++++++++++++++++++ sphinx/builder.py | 2 +- sphinx/templates/layout.html | 6 +-- sphinx/templates/modindex.html | 2 +- 6 files changed, 99 insertions(+), 11 deletions(-) create mode 100644 sphinx/_jinja2.py diff --git a/babel.cfg b/babel.cfg index 5f5188b1..e53a462d 100644 --- a/babel.cfg +++ b/babel.cfg @@ -1,6 +1,4 @@ -[extractors] -jinja = sphinx._jinja.babel_extract [python: **.py] -[jinja: **/templates/**.html] -[jinja: **/templates/**.xml] +[jinja2: **/templates/**.html] +[jinja2: **/templates/**.xml] [javascript: **.js] diff --git a/setup.py b/setup.py index abe82198..ba80ea23 100644 --- a/setup.py +++ b/setup.py @@ -1,4 +1,4 @@ -# -*- coding: utf-8 -*- +0;115;0c# -*- coding: utf-8 -*- import ez_setup ez_setup.use_setuptools() @@ -36,7 +36,7 @@ are already present, work fine and can be seen "in action" in the Python docs: and inclusion of appropriately formatted docstrings. ''' -requires = ['Pygments>=0.8', 'Jinja>=1.1', 'docutils>=0.4'] +requires = ['Pygments>=0.8', 'Jinja2>=2.0', 'docutils>=0.4'] if sys.version_info < (2, 4): print 'ERROR: Sphinx requires at least Python 2.4 to run.' diff --git a/sphinx/_jinja2.py b/sphinx/_jinja2.py new file mode 100644 index 00000000..a6f23e28 --- /dev/null +++ b/sphinx/_jinja2.py @@ -0,0 +1,90 @@ +# -*- coding: utf-8 -*- + +""" + sphinx._jinja2 + ============== + + Glue code for jinja2. + + :author: Sebastian Wiesner + :contact: basti.wiesner@gmx.net + :copyright: 2008 by Sebastian Wiesner + :license: MIT +""" + +import codecs +from os import path + +import jinja2 + +from sphinx.util import mtimes_of_files +from sphinx.application import TemplateBridge + + +class SphinxLoader(jinja2.BaseLoader): + """ + A jinja2 reimplementation of `sphinx._jinja.SphinxFileSystemLoader`. + """ + + def __init__(self, basepath, extpaths, encoding='utf-8'): + """ + Creates a new loader for sphinx. + + ``extpaths`` is a list of directories, which provide additional + templates to sphinx. + + ``encoding`` is used to decode the templates into unicode strings. + Defaults to utf-8. + + If ``basepath`` is set, this path is used to load sphinx core + templates. If False, these templates are loaded from the sphinx + package. + """ + self.core_loader = jinja2.FileSystemLoader(basepath) + self.all_loaders = jinja2.ChoiceLoader( + [jinja2.FileSystemLoader(extpath) for extpath in extpaths] + + [self.core_loader]) + + def get_source(self, environment, template): + # exclamation mark forces loading from core + if template.startswith('!'): + return self.core_loader.get_source(environment, template[1:]) + # check if the template is probably an absolute path + fs_path = template.replace('/', path.sep) + if path.isabs(fs_path): + if not path.exists(fs_path): + raise jinja2.TemplateNotFound(template) + f = codecs.open(fs_path, 'r', self.encoding) + try: + mtime = path.getmtime(path) + return (f.read(), fs_path, + lambda: mtime == path.getmtime(path)) + finally: + f.close() + # finally try to load from custom templates + return self.all_loaders.get_source(environment, template) + + +class BuiltinTemplates(TemplateBridge): + """ + Interfaces the rendering environment of jinja2 for use in sphinx. + """ + + def init(self, builder): + base_templates_path = path.join(path.dirname(__file__), 'templates') + ext_templates_path = [path.join(builder.confdir, dir) + for dir in builder.config.templates_path] + self.templates_path = [base_templates_path] + ext_templates_path + loader = SphinxLoader(base_templates_path, ext_templates_path) + use_i18n = builder.translator is not None + extensions = use_i18n and ['jinja2.ext.i18n'] or [] + self.environment = jinja2.Environment(loader=loader, + extensions=extensions) + if use_i18n: + self.environment.install_gettext_translations(builder.translator) + + def render(self, template, context): + return self.environment.get_template(template).render(context) + + def newest_template_mtime(self): + return max(mtimes_of_files(self.templates_path, '.html')) diff --git a/sphinx/builder.py b/sphinx/builder.py index 159fe803..24c42d2b 100644 --- a/sphinx/builder.py +++ b/sphinx/builder.py @@ -98,7 +98,7 @@ class Builder(object): self.templates = self.app.import_object( self.config.template_bridge, 'template_bridge setting')() else: - from sphinx._jinja import BuiltinTemplates + from sphinx._jinja2 import BuiltinTemplates self.templates = BuiltinTemplates() self.templates.init(self) diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index 5ad4f8dd..e6374b6d 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -4,7 +4,7 @@ {%- endblock %} {%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} {%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} -{%- macro relbar %} +{%- macro relbar() %}

{{ _('Navigation') }}

    @@ -24,7 +24,7 @@
{%- endmacro %} -{%- macro sidebar %} +{%- macro sidebar() %} {%- if builder != 'htmlhelp' %}
@@ -64,7 +64,7 @@ {%- endif %} {%- if customsidebar %} - {{ rendertemplate(customsidebar) }} + {% include customsidebar %} {%- endif %} {%- block sidebarsearch %} {%- if pagename != "search" %} diff --git a/sphinx/templates/modindex.html b/sphinx/templates/modindex.html index d6b505da..a2d2bb9a 100644 --- a/sphinx/templates/modindex.html +++ b/sphinx/templates/modindex.html @@ -52,7 +52,7 @@ {% if fname %}{% endif -%} {{ modname|e }} {%- if fname %}{% endif %} - {%- if pform[0] %} ({{ pform|join(', ') }}){% endif -%} + {%- if pform and pform[0] %} ({{ pform|join(', ') }}){% endif -%} {% if dep %}{{ _('Deprecated')}}:{% endif %} {{ synops|e }} {%- endif -%} -- cgit v1.2.1 From 71355f44f63d6fba8767d08d6d3ba0c15267006d Mon Sep 17 00:00:00 2001 From: Sebastian Wiesner Date: Thu, 20 Nov 2008 20:06:36 +0100 Subject: Fixed encoding issue in pngmath hashing --- sphinx/ext/pngmath.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/pngmath.py b/sphinx/ext/pngmath.py index 77d08eef..aa0d0c2e 100644 --- a/sphinx/ext/pngmath.py +++ b/sphinx/ext/pngmath.py @@ -75,7 +75,7 @@ def render_math(self, math): """ use_preview = self.builder.config.pngmath_use_preview - shasum = "%s.png" % sha(math).hexdigest() + shasum = "%s.png" % sha(math.encode('utf-8')).hexdigest() relfn = posixpath.join(self.builder.imgpath, 'math', shasum) outfn = path.join(self.builder.outdir, '_images', 'math', shasum) if path.isfile(outfn): -- cgit v1.2.1 From 72e0a250c7d891171e2c648ee585e6ec8b453aa7 Mon Sep 17 00:00:00 2001 From: Sebastian Wiesner Date: Thu, 20 Nov 2008 20:12:41 +0100 Subject: Fixed syntax error in setup.py --- setup.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setup.py b/setup.py index ba80ea23..c3fbcf2d 100644 --- a/setup.py +++ b/setup.py @@ -1,4 +1,4 @@ -0;115;0c# -*- coding: utf-8 -*- +# -*- coding: utf-8 -*- import ez_setup ez_setup.use_setuptools() -- cgit v1.2.1 From 35b9921582ff30eb1b7c343cfcf45cc41208a045 Mon Sep 17 00:00:00 2001 From: Vsevolod Solovyov Date: Mon, 24 Nov 2008 16:55:06 +0200 Subject: Fixes #32. sphinx-quickstart adapted for windows --- sphinx/quickstart.py | 130 +++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 125 insertions(+), 5 deletions(-) diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 03024535..998d93fb 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -318,6 +318,109 @@ linkcheck: \t "or in %(rbuilddir)s/linkcheck/output.txt." ''' +BATCHFILE = '''\ +@ECHO OFF + +REM Command file for Sphinx documentation + +set SPHINXBUILD=sphinx-build +set ALLSPHINXOPTS=-d %(rbuilddir)s/doctrees %%SPHINXOPTS%% %(rsrcdir)s +if NOT "%%PAPER%%" == "" ( +\tset ALLSPHINXOPTS=-D latex_paper_size=%%PAPER%% %%ALLSPHINXOPTS%% +) + +if "%%1" == "" goto help + +if "%%1" == "help" ( +\t:help +\techo.Please use `make-docs ^` where ^ is one of +\techo. html to make standalone HTML files +\techo. pickle to make pickle files +\techo. json to make JSON files +\techo. htmlhelp to make HTML files and a HTML help project +\techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter +\techo. changes to make an overview over all changed/added/deprecated items +\techo. linkcheck to check all external links for integrity +\tgoto end +) + +if "%%1" == "clean" ( +\tfor /d %%%%i in (%(rbuilddir)s\*) do rmdir /q /s %%%%i +\tdel /q /s %(rbuilddir)s\* +\tgoto end +) + +if "%%1" == "html" ( +\tcall :mkdir %(rbuilddir)s\html %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b html %%ALLSPHINXOPTS%% %(rbuilddir)s/html +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/html. +\tgoto end +) + +if "%%1" == "web" goto pickle + +if "%%1" == "pickle" ( +\t:pickle +\tcall :mkdir %(rbuilddir)s\pickle %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b pickle %%ALLSPHINXOPTS%% %(rbuilddir)s/pickle +\techo. +\techo.Build finished; now you can process the pickle files. +\tgoto end +) + +if "%%1" == "json" ( +\tcall :mkdir %(rbuilddir)s\json %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b json %%ALLSPHINXOPTS%% %(rbuilddir)s/json +\techo. +\techo.Build finished; now you can process the JSON files. +\tgoto end +) + +if "%%1" == "htmlhelp" ( +\tcall :mkdir %(rbuilddir)s\htmlhelp %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b htmlhelp %%ALLSPHINXOPTS%% %(rbuilddir)s/htmlhelp +\techo. +\techo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %(rbuilddir)s/htmlhelp. +\tgoto end +) + +if "%%1" == "latex" ( +\tcall :mkdir %(rbuilddir)s\latex %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b latex %%ALLSPHINXOPTS%% %(rbuilddir)s/latex +\techo. +\techo.Build finished; the LaTeX files are in %(rbuilddir)s/latex. +\tgoto end +) + +if "%%1" == "changes" ( +\tcall :mkdir %(rbuilddir)s\changes %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b changes %%ALLSPHINXOPTS%% %(rbuilddir)s/changes +\techo. +\techo.The overview file is in %(rbuilddir)s/changes. +\tgoto end +) + +if "%%1" == "linkcheck" ( +\tcall :mkdir %(rbuilddir)s\linkcheck %(rbuilddir)s\doctrees +\t%%SPHINXBUILD%% -b linkcheck %%ALLSPHINXOPTS%% %(rbuilddir)s/linkcheck +\techo. +\techo.Link check complete; look for any errors in the above output ^ +or in %(rbuilddir)s/linkcheck/output.txt. +\tgoto end +) + +goto end + +:mkdir %%1 %%2 +\tIF NOT EXIST %%1 mkdir %%1 +\tIF NOT EXIST %%2 mkdir %%2 +\texit /b + +:end +''' + def mkdir_p(dir): if path.isdir(dir): @@ -410,12 +513,18 @@ Either, you use a directory ".build" within the root path, or you separate "source" and "build" directories within the root path.''' do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n', boolean) - print ''' + if os.name == 'nt': + print ''' +Inside the root directory, two more directories will be created; "_templates" +for custom HTML templates and "_static" for custom stylesheets and other +static files. You can enter another prefix (such as ".") to replace the underscore.''' + do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok) + else: + print ''' Inside the root directory, two more directories will be created; ".templates" for custom HTML templates and ".static" for custom stylesheets and other -static files. Since the leading dot may be inconvenient for Windows users, -you can enter another prefix (such as "_") to replace the dot.''' - do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok) +static files. You can enter another prefix (such as "_") to replace the dot.''' + do_prompt(d, 'dot', 'Name prefix for templates and static dir', '.', ok) print ''' The project name will occur in several places in the built documentation.''' @@ -454,6 +563,8 @@ only have to run e.g. `make html' instead of invoking sphinx-build directly.''' do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', os.name == 'posix' and 'y' or 'n', boolean) + do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)', + os.name == 'nt' and 'y' or 'n', boolean) d['project_fn'] = make_filename(d['project']) d['now'] = time.asctime() @@ -505,12 +616,21 @@ directly.''' f.write((MAKEFILE % d).encode('utf-8')) f.close() + create_batch = d['batchfile'].upper() in ('Y', 'YES') + if create_batch: + d['rsrcdir'] = separate and 'source' or '.' + d['rbuilddir'] = separate and 'build' or d['dot'] + 'build' + f = open(path.join(d['path'], 'make.bat'), 'w') + f.write((BATCHFILE % d).encode('utf-8')) + f.close() + + print print bold('Finished: An initial directory structure has been created.') print ''' You should now populate your master file %s and create other documentation source files. Use the sphinx-build script to build the docs, like so: -''' % masterfile + (create_makefile and ''' +''' % masterfile + ((create_makefile or create_batch) and ''' make ''' or ''' sphinx-build -b %s %s -- cgit v1.2.1 From 61f7e12faeca94a847aa32084bc4f1933d32c89a Mon Sep 17 00:00:00 2001 From: Sebastian Wiesner Date: Thu, 27 Nov 2008 00:31:43 +0100 Subject: Fixed markup escaping issue --- sphinx/templates/layout.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index eb691455..f2314f41 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -89,7 +89,7 @@ {{ metatags }} {%- if builder != 'htmlhelp' %} - {%- set titlesuffix = " — " + docstitle|e %} + {%- set titlesuffix = " — "|safe + docstitle|e %} {%- endif %} {{ title|striptags }}{{ titlesuffix }} {%- if builder == 'web' %} -- cgit v1.2.1 From 10c994f344a0ecee8b43e94d0190b95d8d1d4aea Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 29 Nov 2008 19:56:58 +0100 Subject: Move builders and writers into new packages. --- sphinx/__init__.py | 3 + sphinx/_jinja.py | 3 +- sphinx/application.py | 24 +- sphinx/builder.py | 1274 +----------------------------------------- sphinx/builders/__init__.py | 328 +++++++++++ sphinx/builders/changes.py | 137 +++++ sphinx/builders/html.py | 607 ++++++++++++++++++++ sphinx/builders/htmlhelp.py | 245 ++++++++ sphinx/builders/latex.py | 185 ++++++ sphinx/builders/linkcheck.py | 130 +++++ sphinx/builders/text.py | 68 +++ sphinx/ext/intersphinx.py | 2 +- sphinx/htmlhelp.py | 220 -------- sphinx/htmlwriter.py | 457 --------------- sphinx/latexwriter.py | 1185 --------------------------------------- sphinx/linkcheck.py | 130 ----- sphinx/textwriter.py | 679 ---------------------- sphinx/writers/__init__.py | 10 + sphinx/writers/html.py | 457 +++++++++++++++ sphinx/writers/latex.py | 1185 +++++++++++++++++++++++++++++++++++++++ sphinx/writers/text.py | 679 ++++++++++++++++++++++ tests/test_build.py | 2 +- tests/test_markup.py | 4 +- 23 files changed, 4070 insertions(+), 3944 deletions(-) create mode 100644 sphinx/builders/__init__.py create mode 100644 sphinx/builders/changes.py create mode 100644 sphinx/builders/html.py create mode 100644 sphinx/builders/htmlhelp.py create mode 100644 sphinx/builders/latex.py create mode 100644 sphinx/builders/linkcheck.py create mode 100644 sphinx/builders/text.py delete mode 100644 sphinx/htmlhelp.py delete mode 100644 sphinx/htmlwriter.py delete mode 100644 sphinx/latexwriter.py delete mode 100644 sphinx/linkcheck.py delete mode 100644 sphinx/textwriter.py create mode 100644 sphinx/writers/__init__.py create mode 100644 sphinx/writers/html.py create mode 100644 sphinx/writers/latex.py create mode 100644 sphinx/writers/text.py diff --git a/sphinx/__init__.py b/sphinx/__init__.py index aa4398e0..2df41707 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -10,11 +10,14 @@ """ import sys +from os import path __revision__ = '$Revision$' __version__ = '0.5' __released__ = '0.5' +package_dir = path.abspath(path.dirname(__file__)) + def main(argv=sys.argv): if sys.version_info[:3] < (2, 4, 0): diff --git a/sphinx/_jinja.py b/sphinx/_jinja.py index d6e98b21..654e0c52 100644 --- a/sphinx/_jinja.py +++ b/sphinx/_jinja.py @@ -12,6 +12,7 @@ import codecs from os import path +from sphinx import package_dir from sphinx.util import mtimes_of_files from sphinx.application import TemplateBridge @@ -88,7 +89,7 @@ class TranslatorEnvironment(Environment): class BuiltinTemplates(TemplateBridge): def init(self, builder): self.templates = {} - base_templates_path = path.join(path.dirname(__file__), 'templates') + base_templates_path = path.join(package_dir, 'templates') ext_templates_path = [path.join(builder.confdir, dir) for dir in builder.config.templates_path] self.templates_path = [base_templates_path] + ext_templates_path diff --git a/sphinx/application.py b/sphinx/application.py index 888d7567..6c644bbe 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -22,7 +22,7 @@ from docutils.parsers.rst import directives, roles import sphinx from sphinx.roles import xfileref_role, innernodetypes from sphinx.config import Config -from sphinx.builder import builtin_builders, StandaloneHTMLBuilder +from sphinx.builders import BUILTIN_BUILDERS from sphinx.directives import desc_directive, target_directive, additional_xref_types from sphinx.environment import SphinxStandaloneReader from sphinx.util.console import bold @@ -77,7 +77,7 @@ class Sphinx(object): confoverrides, status, warning=sys.stderr, freshenv=False): self.next_listener_id = 0 self._listeners = {} - self.builderclasses = builtin_builders.copy() + self.builderclasses = BUILTIN_BUILDERS.copy() self.builder = None self.srcdir = srcdir @@ -125,6 +125,11 @@ class Sphinx(object): buildername))) builderclass = self.builderclasses[buildername] + if isinstance(builderclass, tuple): + # builtin builder + mod, cls = builderclass + builderclass = getattr( + __import__('sphinx.builders.' + mod, None, None, [cls]), cls) self.builder = builderclass(self, freshenv=freshenv) self.emit('builder-inited') @@ -220,8 +225,12 @@ class Sphinx(object): if not hasattr(builder, 'name'): raise ExtensionError('Builder class %s has no "name" attribute' % builder) if builder.name in self.builderclasses: - raise ExtensionError('Builder %r already exists (in module %s)' % ( - builder.name, self.builderclasses[builder.name].__module__)) + if isinstance(self.builderclasses[builder.name], tuple): + raise ExtensionError('Builder %r is a builtin builder' % + builder.name) + else: + raise ExtensionError('Builder %r already exists (in module %s)' % ( + builder.name, self.builderclasses[builder.name].__module__)) self.builderclasses[builder.name] = builder def add_config_value(self, name, default, rebuild_env): @@ -243,11 +252,11 @@ class Sphinx(object): raise ExtensionError('Value for key %r must be a (visit, depart) ' 'function tuple' % key) if key == 'html': - from sphinx.htmlwriter import HTMLTranslator as translator + from sphinx.writers.html import HTMLTranslator as translator elif key == 'latex': - from sphinx.latexwriter import LaTeXTranslator as translator + from sphinx.writers.latex import LaTeXTranslator as translator elif key == 'text': - from sphinx.textwriter import TextTranslator as translator + from sphinx.writers.text import TextTranslator as translator else: # ignore invalid keys for compatibility continue @@ -284,6 +293,7 @@ class Sphinx(object): SphinxStandaloneReader.transforms.append(transform) def add_javascript(self, filename): + from sphinx.builders.html import StandaloneHTMLBuilder StandaloneHTMLBuilder.script_files.append( posixpath.join('_static', filename)) diff --git a/sphinx/builder.py b/sphinx/builder.py index 159fe803..2a19b751 100644 --- a/sphinx/builder.py +++ b/sphinx/builder.py @@ -3,1268 +3,20 @@ sphinx.builder ~~~~~~~~~~~~~~ - Builder classes for different output formats. + .. warning:: - :copyright: 2007-2008 by Georg Brandl, Sebastian Wiesner, Horst Gutmann. + This module is only kept for API compatibility; new code should + import these classes directly from the sphinx.builders package. + + :copyright: 2008 by Georg Brandl. :license: BSD. """ -import os -import time -import codecs -import shutil -import gettext -import cPickle as pickle -from os import path -from cgi import escape - -from docutils import nodes -from docutils.io import StringOutput, FileOutput, DocTreeInput -from docutils.core import publish_parts -from docutils.utils import new_document -from docutils.frontend import OptionParser -from docutils.readers.doctree import Reader as DoctreeReader - -from sphinx import addnodes, locale, __version__ -from sphinx.util import ensuredir, relative_uri, SEP, os_path, texescape, ustrftime -from sphinx.htmlhelp import build_hhx -from sphinx.htmlwriter import HTMLWriter, HTMLTranslator, SmartyPantsHTMLTranslator -from sphinx.textwriter import TextWriter -from sphinx.latexwriter import LaTeXWriter -from sphinx.environment import BuildEnvironment, NoUri -from sphinx.highlighting import PygmentsBridge -from sphinx.util.console import bold, purple, darkgreen -from sphinx.search import js_index - -try: - import json -except ImportError: - try: - import simplejson as json - except ImportError: - json = None - -# side effect: registers roles and directives -from sphinx import roles -from sphinx import directives - -ENV_PICKLE_FILENAME = 'environment.pickle' -LAST_BUILD_FILENAME = 'last_build' -INVENTORY_FILENAME = 'objects.inv' - - -class Builder(object): - """ - Builds target formats from the reST sources. - """ - - # builder's name, for the -b command line options - name = '' - - def __init__(self, app, env=None, freshenv=False): - self.srcdir = app.srcdir - self.confdir = app.confdir - self.outdir = app.outdir - self.doctreedir = app.doctreedir - if not path.isdir(self.doctreedir): - os.makedirs(self.doctreedir) - - self.app = app - self.warn = app.warn - self.info = app.info - self.config = app.config - - self.load_i18n() - - # images that need to be copied over (source -> dest) - self.images = {} - - # if None, this is set in load_env() - self.env = env - self.freshenv = freshenv - - self.init() - self.load_env() - - # helper methods - - def init(self): - """Load necessary templates and perform initialization.""" - raise NotImplementedError - - def init_templates(self): - # Call this from init() if you need templates. - if self.config.template_bridge: - self.templates = self.app.import_object( - self.config.template_bridge, 'template_bridge setting')() - else: - from sphinx._jinja import BuiltinTemplates - self.templates = BuiltinTemplates() - self.templates.init(self) - - def get_target_uri(self, docname, typ=None): - """ - Return the target URI for a document name (typ can be used to qualify - the link characteristic for individual builders). - """ - raise NotImplementedError - - def get_relative_uri(self, from_, to, typ=None): - """ - Return a relative URI between two source filenames. May raise environment.NoUri - if there's no way to return a sensible URI. - """ - return relative_uri(self.get_target_uri(from_), - self.get_target_uri(to, typ)) - - def get_outdated_docs(self): - """ - Return an iterable of output files that are outdated, or a string describing - what an update build will build. - """ - raise NotImplementedError - - def status_iterator(self, iterable, summary, colorfunc=darkgreen): - l = -1 - for item in iterable: - if l == -1: - self.info(bold(summary), nonl=1) - l = 0 - self.info(colorfunc(item) + ' ', nonl=1) - yield item - if l == 0: - self.info() - - supported_image_types = [] - - def post_process_images(self, doctree): - """ - Pick the best candidate for all image URIs. - """ - for node in doctree.traverse(nodes.image): - if '?' in node['candidates']: - # don't rewrite nonlocal image URIs - continue - if '*' not in node['candidates']: - for imgtype in self.supported_image_types: - candidate = node['candidates'].get(imgtype, None) - if candidate: - break - else: - self.warn('%s:%s: no matching candidate for image URI %r' % - (node.source, getattr(node, 'lineno', ''), node['uri'])) - continue - node['uri'] = candidate - else: - candidate = node['uri'] - if candidate not in self.env.images: - # non-existing URI; let it alone - continue - self.images[candidate] = self.env.images[candidate][1] - - # build methods - - def load_i18n(self): - """ - Load translated strings from the configured localedirs if - enabled in the configuration. - """ - self.translator = None - if self.config.language is not None: - self.info(bold('loading translations [%s]... ' % self.config.language), - nonl=True) - locale_dirs = [path.join(path.dirname(__file__), 'locale')] + \ - [path.join(self.srcdir, x) for x in self.config.locale_dirs] - for dir_ in locale_dirs: - try: - trans = gettext.translation('sphinx', localedir=dir_, - languages=[self.config.language]) - if self.translator is None: - self.translator = trans - else: - self.translator._catalog.update(trans.catalog) - except Exception: - # Language couldn't be found in the specified path - pass - if self.translator is not None: - self.info('done') - else: - self.info('locale not available') - if self.translator is None: - self.translator = gettext.NullTranslations() - self.translator.install(unicode=True) - locale.init() # translate common labels - - def load_env(self): - """Set up the build environment.""" - if self.env: - return - if not self.freshenv: - try: - self.info(bold('loading pickled environment... '), nonl=True) - self.env = BuildEnvironment.frompickle(self.config, - path.join(self.doctreedir, ENV_PICKLE_FILENAME)) - self.info('done') - except Exception, err: - if type(err) is IOError and err.errno == 2: - self.info('not found') - else: - self.info('failed: %s' % err) - self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) - self.env.find_files(self.config) - else: - self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) - self.env.find_files(self.config) - self.env.set_warnfunc(self.warn) - - def build_all(self): - """Build all source files.""" - self.build(None, summary='all source files', method='all') - - def build_specific(self, filenames): - """Only rebuild as much as needed for changes in the source_filenames.""" - # bring the filenames to the canonical format, that is, - # relative to the source directory and without source_suffix. - dirlen = len(self.srcdir) + 1 - to_write = [] - suffix = self.config.source_suffix - for filename in filenames: - filename = path.abspath(filename)[dirlen:] - if filename.endswith(suffix): - filename = filename[:-len(suffix)] - filename = filename.replace(os.path.sep, SEP) - to_write.append(filename) - self.build(to_write, method='specific', - summary='%d source files given on command ' - 'line' % len(to_write)) - - def build_update(self): - """Only rebuild files changed or added since last build.""" - to_build = self.get_outdated_docs() - if isinstance(to_build, str): - self.build(['__all__'], to_build) - else: - to_build = list(to_build) - self.build(to_build, - summary='targets for %d source files that are ' - 'out of date' % len(to_build)) - - def build(self, docnames, summary=None, method='update'): - if summary: - self.info(bold('building [%s]: ' % self.name), nonl=1) - self.info(summary) - - updated_docnames = [] - # while reading, collect all warnings from docutils - warnings = [] - self.env.set_warnfunc(warnings.append) - self.info(bold('updating environment: '), nonl=1) - iterator = self.env.update(self.config, self.srcdir, self.doctreedir, self.app) - # the first item in the iterator is a summary message - self.info(iterator.next()) - for docname in self.status_iterator(iterator, 'reading sources... ', purple): - updated_docnames.append(docname) - # nothing further to do, the environment has already done the reading - for warning in warnings: - if warning.strip(): - self.warn(warning) - self.env.set_warnfunc(self.warn) - - if updated_docnames: - # save the environment - self.info(bold('pickling environment... '), nonl=True) - self.env.topickle(path.join(self.doctreedir, ENV_PICKLE_FILENAME)) - self.info('done') - - # global actions - self.info(bold('checking consistency... '), nonl=True) - self.env.check_consistency() - self.info('done') - else: - if method == 'update' and not docnames: - self.info(bold('no targets are out of date.')) - return - - # another indirection to support methods which don't build files - # individually - self.write(docnames, updated_docnames, method) - - # finish (write static files etc.) - self.finish() - if self.app._warncount: - self.info(bold('build succeeded, %s warning%s.' % - (self.app._warncount, - self.app._warncount != 1 and 's' or ''))) - else: - self.info(bold('build succeeded.')) - - def write(self, build_docnames, updated_docnames, method='update'): - if build_docnames is None or build_docnames == ['__all__']: - # build_all - build_docnames = self.env.found_docs - if method == 'update': - # build updated ones as well - docnames = set(build_docnames) | set(updated_docnames) - else: - docnames = set(build_docnames) - - # add all toctree-containing files that may have changed - for docname in list(docnames): - for tocdocname in self.env.files_to_rebuild.get(docname, []): - docnames.add(tocdocname) - docnames.add(self.config.master_doc) - - self.info(bold('preparing documents... '), nonl=True) - self.prepare_writing(docnames) - self.info('done') - - # write target files - warnings = [] - self.env.set_warnfunc(warnings.append) - for docname in self.status_iterator(sorted(docnames), - 'writing output... ', darkgreen): - doctree = self.env.get_and_resolve_doctree(docname, self) - self.write_doc(docname, doctree) - for warning in warnings: - if warning.strip(): - self.warn(warning) - self.env.set_warnfunc(self.warn) - - def prepare_writing(self, docnames): - raise NotImplementedError - - def write_doc(self, docname, doctree): - raise NotImplementedError - - def finish(self): - raise NotImplementedError - - -class StandaloneHTMLBuilder(Builder): - """ - Builds standalone HTML docs. - """ - name = 'html' - copysource = True - out_suffix = '.html' - indexer_format = js_index - supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', - 'image/jpeg'] - searchindex_filename = 'searchindex.js' - add_header_links = True - add_definition_links = True - - # This is a class attribute because it is mutated by Sphinx.add_javascript. - script_files = ['_static/jquery.js', '_static/doctools.js'] - - def init(self): - """Load templates.""" - self.init_templates() - self.init_translator_class() - if self.config.html_file_suffix: - self.out_suffix = self.config.html_file_suffix - - if self.config.language is not None: - jsfile = path.join(path.dirname(__file__), 'locale', self.config.language, - 'LC_MESSAGES', 'sphinx.js') - if path.isfile(jsfile): - self.script_files.append('_static/translations.js') - - def init_translator_class(self): - if self.config.html_translator_class: - self.translator_class = self.app.import_object( - self.config.html_translator_class, 'html_translator_class setting') - elif self.config.html_use_smartypants: - self.translator_class = SmartyPantsHTMLTranslator - else: - self.translator_class = HTMLTranslator - - def render_partial(self, node): - """Utility: Render a lone doctree node.""" - doc = new_document('') - doc.append(node) - return publish_parts( - doc, - source_class=DocTreeInput, - reader=DoctreeReader(), - writer=HTMLWriter(self), - settings_overrides={'output_encoding': 'unicode'} - ) - - def prepare_writing(self, docnames): - from sphinx.search import IndexBuilder - - self.indexer = IndexBuilder(self.env) - self.load_indexer(docnames) - self.docwriter = HTMLWriter(self) - self.docsettings = OptionParser( - defaults=self.env.settings, - components=(self.docwriter,)).get_default_values() - - # format the "last updated on" string, only once is enough since it - # typically doesn't include the time of day - lufmt = self.config.html_last_updated_fmt - if lufmt is not None: - self.last_updated = ustrftime(lufmt or _('%b %d, %Y')) - else: - self.last_updated = None - - logo = self.config.html_logo and \ - path.basename(self.config.html_logo) or '' - - favicon = self.config.html_favicon and \ - path.basename(self.config.html_favicon) or '' - if favicon and os.path.splitext(favicon)[1] != '.ico': - self.warn('html_favicon is not an .ico file') - - if not isinstance(self.config.html_use_opensearch, basestring): - self.warn('html_use_opensearch config value must now be a string') - - self.relations = self.env.collect_relations() - - rellinks = [] - if self.config.html_use_index: - rellinks.append(('genindex', _('General Index'), 'I', _('index'))) - if self.config.html_use_modindex and self.env.modules: - rellinks.append(('modindex', _('Global Module Index'), 'M', _('modules'))) - - self.globalcontext = dict( - project = self.config.project, - release = self.config.release, - version = self.config.version, - last_updated = self.last_updated, - copyright = self.config.copyright, - master_doc = self.config.master_doc, - style = self.config.html_style, - use_opensearch = self.config.html_use_opensearch, - docstitle = self.config.html_title, - shorttitle = self.config.html_short_title, - show_sphinx = self.config.html_show_sphinx, - file_suffix = self.out_suffix, - script_files = self.script_files, - sphinx_version = __version__, - rellinks = rellinks, - builder = self.name, - parents = [], - logo = logo, - favicon = favicon, - ) - self.globalcontext.update(self.config.html_context) - - def get_doc_context(self, docname, body, metatags): - """Collect items for the template context of a page.""" - # find out relations - prev = next = None - parents = [] - rellinks = self.globalcontext['rellinks'][:] - related = self.relations.get(docname) - titles = self.env.titles - if related and related[2]: - try: - next = {'link': self.get_relative_uri(docname, related[2]), - 'title': self.render_partial(titles[related[2]])['title']} - rellinks.append((related[2], next['title'], 'N', _('next'))) - except KeyError: - next = None - if related and related[1]: - try: - prev = {'link': self.get_relative_uri(docname, related[1]), - 'title': self.render_partial(titles[related[1]])['title']} - rellinks.append((related[1], prev['title'], 'P', _('previous'))) - except KeyError: - # the relation is (somehow) not in the TOC tree, handle that gracefully - prev = None - while related and related[0]: - try: - parents.append( - {'link': self.get_relative_uri(docname, related[0]), - 'title': self.render_partial(titles[related[0]])['title']}) - except KeyError: - pass - related = self.relations.get(related[0]) - if parents: - parents.pop() # remove link to the master file; we have a generic - # "back to index" link already - parents.reverse() - - # title rendered as HTML - title = titles.get(docname) - title = title and self.render_partial(title)['title'] or '' - # the name for the copied source - sourcename = self.config.html_copy_source and docname + '.txt' or '' - - # metadata for the document - meta = self.env.metadata.get(docname) - - return dict( - parents = parents, - prev = prev, - next = next, - title = title, - meta = meta, - body = body, - metatags = metatags, - rellinks = rellinks, - sourcename = sourcename, - toc = self.render_partial(self.env.get_toc_for(docname))['fragment'], - # only display a TOC if there's more than one item to show - display_toc = (self.env.toc_num_entries[docname] > 1), - ) - - def write_doc(self, docname, doctree): - self.post_process_images(doctree) - destination = StringOutput(encoding='utf-8') - doctree.settings = self.docsettings - - self.imgpath = relative_uri(self.get_target_uri(docname), '_images') - self.docwriter.write(doctree, destination) - self.docwriter.assemble_parts() - body = self.docwriter.parts['fragment'] - metatags = self.docwriter.clean_meta - - ctx = self.get_doc_context(docname, body, metatags) - self.index_page(docname, doctree, ctx.get('title', '')) - self.handle_page(docname, ctx, event_arg=doctree) - - def finish(self): - self.info(bold('writing additional files...'), nonl=1) - - # the global general index - - if self.config.html_use_index: - # the total count of lines for each index letter, used to distribute - # the entries into two columns - genindex = self.env.create_index(self) - indexcounts = [] - for _, entries in genindex: - indexcounts.append(sum(1 + len(subitems) - for _, (_, subitems) in entries)) - - genindexcontext = dict( - genindexentries = genindex, - genindexcounts = indexcounts, - split_index = self.config.html_split_index, - ) - self.info(' genindex', nonl=1) - - if self.config.html_split_index: - self.handle_page('genindex', genindexcontext, 'genindex-split.html') - self.handle_page('genindex-all', genindexcontext, 'genindex.html') - for (key, entries), count in zip(genindex, indexcounts): - ctx = {'key': key, 'entries': entries, 'count': count, - 'genindexentries': genindex} - self.handle_page('genindex-' + key, ctx, 'genindex-single.html') - else: - self.handle_page('genindex', genindexcontext, 'genindex.html') - - # the global module index - - if self.config.html_use_modindex and self.env.modules: - # the sorted list of all modules, for the global module index - modules = sorted(((mn, (self.get_relative_uri('modindex', fn) + - '#module-' + mn, sy, pl, dep)) - for (mn, (fn, sy, pl, dep)) in - self.env.modules.iteritems()), - key=lambda x: x[0].lower()) - # collect all platforms - platforms = set() - # sort out collapsable modules - modindexentries = [] - letters = [] - pmn = '' - num_toplevels = 0 - num_collapsables = 0 - cg = 0 # collapse group - fl = '' # first letter - for mn, (fn, sy, pl, dep) in modules: - pl = pl and pl.split(', ') or [] - platforms.update(pl) - if fl != mn[0].lower() and mn[0] != '_': - # heading - modindexentries.append(['', False, 0, False, - mn[0].upper(), '', [], False]) - letters.append(mn[0].upper()) - tn = mn.split('.')[0] - if tn != mn: - # submodule - if pmn == tn: - # first submodule - make parent collapsable - modindexentries[-1][1] = True - num_collapsables += 1 - elif not pmn.startswith(tn): - # submodule without parent in list, add dummy entry - cg += 1 - modindexentries.append([tn, True, cg, False, '', '', [], False]) - else: - num_toplevels += 1 - cg += 1 - modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, dep]) - pmn = mn - fl = mn[0].lower() - platforms = sorted(platforms) - - # apply heuristics when to collapse modindex at page load: - # only collapse if number of toplevel modules is larger than - # number of submodules - collapse = len(modules) - num_toplevels < num_toplevels - - modindexcontext = dict( - modindexentries = modindexentries, - platforms = platforms, - letters = letters, - collapse_modindex = collapse, - ) - self.info(' modindex', nonl=1) - self.handle_page('modindex', modindexcontext, 'modindex.html') - - # the search page - if self.name != 'htmlhelp': - self.info(' search', nonl=1) - self.handle_page('search', {}, 'search.html') - - # additional pages from conf.py - for pagename, template in self.config.html_additional_pages.items(): - self.info(' '+pagename, nonl=1) - self.handle_page(pagename, {}, template) - - if self.config.html_use_opensearch and self.name != 'htmlhelp': - self.info(' opensearch', nonl=1) - fn = path.join(self.outdir, '_static', 'opensearch.xml') - self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn) - - self.info() - - # copy image files - if self.images: - self.info(bold('copying images...'), nonl=True) - ensuredir(path.join(self.outdir, '_images')) - for src, dest in self.images.iteritems(): - self.info(' '+src, nonl=1) - shutil.copyfile(path.join(self.srcdir, src), - path.join(self.outdir, '_images', dest)) - self.info() - - # copy static files - self.info(bold('copying static files... '), nonl=True) - ensuredir(path.join(self.outdir, '_static')) - # first, create pygments style file - f = open(path.join(self.outdir, '_static', 'pygments.css'), 'w') - f.write(PygmentsBridge('html', self.config.pygments_style).get_stylesheet()) - f.close() - # then, copy translations JavaScript file - if self.config.language is not None: - jsfile = path.join(path.dirname(__file__), 'locale', self.config.language, - 'LC_MESSAGES', 'sphinx.js') - if path.isfile(jsfile): - shutil.copyfile(jsfile, path.join(self.outdir, '_static', - 'translations.js')) - # then, copy over all user-supplied static files - staticdirnames = [path.join(path.dirname(__file__), 'static')] + \ - [path.join(self.confdir, spath) - for spath in self.config.html_static_path] - for staticdirname in staticdirnames: - for filename in os.listdir(staticdirname): - if filename.startswith('.'): - continue - fullname = path.join(staticdirname, filename) - targetname = path.join(self.outdir, '_static', filename) - if path.isfile(fullname): - shutil.copyfile(fullname, targetname) - elif path.isdir(fullname): - if filename in self.config.exclude_dirnames: - continue - if path.exists(targetname): - shutil.rmtree(targetname) - shutil.copytree(fullname, targetname) - # last, copy logo file (handled differently) - if self.config.html_logo: - logobase = path.basename(self.config.html_logo) - shutil.copyfile(path.join(self.confdir, self.config.html_logo), - path.join(self.outdir, '_static', logobase)) - self.info('done') - - # dump the search index - self.handle_finish() - - def get_outdated_docs(self): - if self.templates: - template_mtime = self.templates.newest_template_mtime() - else: - template_mtime = 0 - for docname in self.env.found_docs: - if docname not in self.env.all_docs: - yield docname - continue - targetname = self.env.doc2path(docname, self.outdir, self.out_suffix) - try: - targetmtime = path.getmtime(targetname) - except Exception: - targetmtime = 0 - try: - srcmtime = max(path.getmtime(self.env.doc2path(docname)), - template_mtime) - if srcmtime > targetmtime: - yield docname - except EnvironmentError: - # source doesn't exist anymore - pass - - def load_indexer(self, docnames): - keep = set(self.env.all_docs) - set(docnames) - try: - f = open(path.join(self.outdir, self.searchindex_filename), 'rb') - try: - self.indexer.load(f, self.indexer_format) - finally: - f.close() - except (IOError, OSError, ValueError): - if keep: - self.warn("search index couldn't be loaded, but not all documents " - "will be built: the index will be incomplete.") - # delete all entries for files that will be rebuilt - self.indexer.prune(keep) - - def index_page(self, pagename, doctree, title): - # only index pages with title - if self.indexer is not None and title: - self.indexer.feed(pagename, title, doctree) - - # --------- these are overwritten by the serialization builder - - def get_target_uri(self, docname, typ=None): - return docname + self.out_suffix - - def handle_page(self, pagename, addctx, templatename='page.html', - outfilename=None, event_arg=None): - ctx = self.globalcontext.copy() - # current_page_name is backwards compatibility - ctx['pagename'] = ctx['current_page_name'] = pagename - - def pathto(otheruri, resource=False, - baseuri=self.get_target_uri(pagename)): - if not resource: - otheruri = self.get_target_uri(otheruri) - return relative_uri(baseuri, otheruri) - ctx['pathto'] = pathto - ctx['hasdoc'] = lambda name: name in self.env.all_docs - ctx['customsidebar'] = self.config.html_sidebars.get(pagename) - ctx.update(addctx) - - self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) - - output = self.templates.render(templatename, ctx) - if not outfilename: - outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) - ensuredir(path.dirname(outfilename)) # normally different from self.outdir - try: - f = codecs.open(outfilename, 'w', 'utf-8') - try: - f.write(output) - finally: - f.close() - except (IOError, OSError), err: - self.warn("Error writing file %s: %s" % (outfilename, err)) - if self.copysource and ctx.get('sourcename'): - # copy the source file for the "show source" link - source_name = path.join(self.outdir, '_sources', os_path(ctx['sourcename'])) - ensuredir(path.dirname(source_name)) - shutil.copyfile(self.env.doc2path(pagename), source_name) - - def handle_finish(self): - self.info(bold('dumping search index... '), nonl=True) - self.indexer.prune(self.env.all_docs) - f = open(path.join(self.outdir, self.searchindex_filename), 'wb') - try: - self.indexer.dump(f, self.indexer_format) - finally: - f.close() - self.info('done') - - self.info(bold('dumping object inventory... '), nonl=True) - f = open(path.join(self.outdir, INVENTORY_FILENAME), 'w') - try: - f.write('# Sphinx inventory version 1\n') - f.write('# Project: %s\n' % self.config.project.encode('utf-8')) - f.write('# Version: %s\n' % self.config.version) - for modname, info in self.env.modules.iteritems(): - f.write('%s mod %s\n' % (modname, self.get_target_uri(info[0]))) - for refname, (docname, desctype) in self.env.descrefs.iteritems(): - f.write('%s %s %s\n' % (refname, desctype, self.get_target_uri(docname))) - finally: - f.close() - self.info('done') - - -class SerializingHTMLBuilder(StandaloneHTMLBuilder): - """ - An abstract builder that serializes the HTML generated. - """ - #: the serializing implementation to use. Set this to a module that - #: implements a `dump`, `load`, `dumps` and `loads` functions - #: (pickle, simplejson etc.) - implementation = None - - #: the filename for the global context file - globalcontext_filename = None - - supported_image_types = ('image/svg+xml', 'image/png', 'image/gif', - 'image/jpeg') - - def init(self): - self.init_translator_class() - self.templates = None # no template bridge necessary - - def get_target_uri(self, docname, typ=None): - if docname == 'index': - return '' - if docname.endswith(SEP + 'index'): - return docname[:-5] # up to sep - return docname + SEP - - def handle_page(self, pagename, ctx, templatename='page.html', - outfilename=None, event_arg=None): - ctx['current_page_name'] = pagename - sidebarfile = self.config.html_sidebars.get(pagename) - if sidebarfile: - ctx['customsidebar'] = sidebarfile - - if not outfilename: - outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) - - self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) - - ensuredir(path.dirname(outfilename)) - f = open(outfilename, 'wb') - try: - self.implementation.dump(ctx, f, 2) - finally: - f.close() - - # if there is a source file, copy the source file for the - # "show source" link - if ctx.get('sourcename'): - source_name = path.join(self.outdir, '_sources', - os_path(ctx['sourcename'])) - ensuredir(path.dirname(source_name)) - shutil.copyfile(self.env.doc2path(pagename), source_name) - - def handle_finish(self): - # dump the global context - outfilename = path.join(self.outdir, self.globalcontext_filename) - f = open(outfilename, 'wb') - try: - self.implementation.dump(self.globalcontext, f, 2) - finally: - f.close() - - # super here to dump the search index - StandaloneHTMLBuilder.handle_finish(self) - - # copy the environment file from the doctree dir to the output dir - # as needed by the web app - shutil.copyfile(path.join(self.doctreedir, ENV_PICKLE_FILENAME), - path.join(self.outdir, ENV_PICKLE_FILENAME)) - - # touch 'last build' file, used by the web application to determine - # when to reload its environment and clear the cache - open(path.join(self.outdir, LAST_BUILD_FILENAME), 'w').close() - - -class PickleHTMLBuilder(SerializingHTMLBuilder): - """ - A Builder that dumps the generated HTML into pickle files. - """ - implementation = pickle - indexer_format = pickle - name = 'pickle' - out_suffix = '.fpickle' - globalcontext_filename = 'globalcontext.pickle' - searchindex_filename = 'searchindex.pickle' - - -class JSONHTMLBuilder(SerializingHTMLBuilder): - """ - A builder that dumps the generated HTML into JSON files. - """ - implementation = json - indexer_format = json - name = 'json' - out_suffix = '.fjson' - globalcontext_filename = 'globalcontext.json' - searchindex_filename = 'searchindex.json' - - def init(self): - if json is None: - from sphinx.application import SphinxError - raise SphinxError('The module simplejson (or json in Python >= 2.6) ' - 'is not available. The JSONHTMLBuilder builder ' - 'will not work.') - SerializingHTMLBuilder.init(self) - - -class HTMLHelpBuilder(StandaloneHTMLBuilder): - """ - Builder that also outputs Windows HTML help project, contents and index files. - Adapted from the original Doc/tools/prechm.py. - """ - name = 'htmlhelp' - - # don't copy the reST source - copysource = False - supported_image_types = ['image/png', 'image/gif', 'image/jpeg'] - - # don't add links - add_header_links = False - add_definition_links = False - - def init(self): - StandaloneHTMLBuilder.init(self) - # the output files for HTML help must be .html only - self.out_suffix = '.html' - - def handle_finish(self): - build_hhx(self, self.outdir, self.config.htmlhelp_basename) - - -class LaTeXBuilder(Builder): - """ - Builds LaTeX output to create PDF. - """ - name = 'latex' - supported_image_types = ['application/pdf', 'image/png', 'image/gif', - 'image/jpeg'] - - def init(self): - self.docnames = [] - self.document_data = [] - texescape.init() - - def get_outdated_docs(self): - return 'all documents' # for now - - def get_target_uri(self, docname, typ=None): - if typ == 'token': - # token references are always inside production lists and must be - # replaced by \token{} in LaTeX - return '@token' - if docname not in self.docnames: - raise NoUri - else: - return '' - - def init_document_data(self): - preliminary_document_data = map(list, self.config.latex_documents) - if not preliminary_document_data: - self.warn('No "latex_documents" config value found; no documents ' - 'will be written.') - return - # assign subdirs to titles - self.titles = [] - for entry in preliminary_document_data: - docname = entry[0] - if docname not in self.env.all_docs: - self.warn('"latex_documents" config value references unknown ' - 'document %s' % docname) - continue - self.document_data.append(entry) - if docname.endswith(SEP+'index'): - docname = docname[:-5] - self.titles.append((docname, entry[2])) - - def write(self, *ignored): - # first, assemble the "appendix" docs that are in every PDF - appendices = [] - for fname in self.config.latex_appendices: - appendices.append(self.env.get_doctree(fname)) - - docwriter = LaTeXWriter(self) - docsettings = OptionParser( - defaults=self.env.settings, - components=(docwriter,)).get_default_values() - - self.init_document_data() - - for entry in self.document_data: - docname, targetname, title, author, docclass = entry[:5] - toctree_only = False - if len(entry) > 5: - toctree_only = entry[5] - destination = FileOutput( - destination_path=path.join(self.outdir, targetname), - encoding='utf-8') - self.info("processing " + targetname + "... ", nonl=1) - doctree = self.assemble_doctree(docname, toctree_only, - appendices=(docclass == 'manual') and appendices or []) - self.post_process_images(doctree) - self.info("writing... ", nonl=1) - doctree.settings = docsettings - doctree.settings.author = author - doctree.settings.title = title - doctree.settings.docname = docname - doctree.settings.docclass = docclass - docwriter.write(doctree, destination) - self.info("done") - - def assemble_doctree(self, indexfile, toctree_only, appendices): - self.docnames = set([indexfile] + appendices) - self.info(darkgreen(indexfile) + " ", nonl=1) - def process_tree(docname, tree): - tree = tree.deepcopy() - for toctreenode in tree.traverse(addnodes.toctree): - newnodes = [] - includefiles = map(str, toctreenode['includefiles']) - for includefile in includefiles: - try: - self.info(darkgreen(includefile) + " ", nonl=1) - subtree = process_tree(includefile, - self.env.get_doctree(includefile)) - self.docnames.add(includefile) - except Exception: - self.warn('%s: toctree contains ref to nonexisting file %r' % - (docname, includefile)) - else: - sof = addnodes.start_of_file() - sof.children = subtree.children - newnodes.append(sof) - toctreenode.parent.replace(toctreenode, newnodes) - return tree - tree = self.env.get_doctree(indexfile) - if toctree_only: - # extract toctree nodes from the tree and put them in a fresh document - new_tree = new_document('') - new_sect = nodes.section() - new_sect += nodes.title(u'', u'') - new_tree += new_sect - for node in tree.traverse(addnodes.toctree): - new_sect += node - tree = new_tree - largetree = process_tree(indexfile, tree) - largetree.extend(appendices) - self.info() - self.info("resolving references...") - self.env.resolve_references(largetree, indexfile, self) - # resolve :ref:s to distant tex files -- we can't add a cross-reference, - # but append the document name - for pendingnode in largetree.traverse(addnodes.pending_xref): - docname = pendingnode['refdocname'] - sectname = pendingnode['refsectname'] - newnodes = [nodes.emphasis(sectname, sectname)] - for subdir, title in self.titles: - if docname.startswith(subdir): - newnodes.append(nodes.Text(_(' (in '), _(' (in '))) - newnodes.append(nodes.emphasis(title, title)) - newnodes.append(nodes.Text(')', ')')) - break - else: - pass - pendingnode.replace_self(newnodes) - return largetree - - def finish(self): - # copy image files - if self.images: - self.info(bold('copying images...'), nonl=1) - for src, dest in self.images.iteritems(): - self.info(' '+src, nonl=1) - shutil.copyfile(path.join(self.srcdir, src), - path.join(self.outdir, dest)) - self.info() - - # the logo is handled differently - if self.config.latex_logo: - logobase = path.basename(self.config.latex_logo) - shutil.copyfile(path.join(self.confdir, self.config.latex_logo), - path.join(self.outdir, logobase)) - - self.info(bold('copying TeX support files... '), nonl=True) - staticdirname = path.join(path.dirname(__file__), 'texinputs') - for filename in os.listdir(staticdirname): - if not filename.startswith('.'): - shutil.copyfile(path.join(staticdirname, filename), - path.join(self.outdir, filename)) - self.info('done') - - -class ChangesBuilder(Builder): - """ - Write a summary with all versionadded/changed directives. - """ - name = 'changes' - - def init(self): - self.init_templates() - - def get_outdated_docs(self): - return self.outdir - - typemap = { - 'versionadded': 'added', - 'versionchanged': 'changed', - 'deprecated': 'deprecated', - } - - def write(self, *ignored): - version = self.config.version - libchanges = {} - apichanges = [] - otherchanges = {} - if version not in self.env.versionchanges: - self.info(bold('no changes in this version.')) - return - self.info(bold('writing summary file...')) - for type, docname, lineno, module, descname, content in \ - self.env.versionchanges[version]: - ttext = self.typemap[type] - context = content.replace('\n', ' ') - if descname and docname.startswith('c-api'): - if not descname: - continue - if context: - entry = '%s: %s: %s' % (descname, ttext, context) - else: - entry = '%s: %s.' % (descname, ttext) - apichanges.append((entry, docname, lineno)) - elif descname or module: - if not module: - module = _('Builtins') - if not descname: - descname = _('Module level') - if context: - entry = '%s: %s: %s' % (descname, ttext, context) - else: - entry = '%s: %s.' % (descname, ttext) - libchanges.setdefault(module, []).append((entry, docname, lineno)) - else: - if not context: - continue - entry = '%s: %s' % (ttext.capitalize(), context) - title = self.env.titles[docname].astext() - otherchanges.setdefault((docname, title), []).append( - (entry, docname, lineno)) - - ctx = { - 'project': self.config.project, - 'version': version, - 'docstitle': self.config.html_title, - 'shorttitle': self.config.html_short_title, - 'libchanges': sorted(libchanges.iteritems()), - 'apichanges': sorted(apichanges), - 'otherchanges': sorted(otherchanges.iteritems()), - 'show_sphinx': self.config.html_show_sphinx, - } - f = open(path.join(self.outdir, 'index.html'), 'w') - try: - f.write(self.templates.render('changes/frameset.html', ctx)) - finally: - f.close() - f = open(path.join(self.outdir, 'changes.html'), 'w') - try: - f.write(self.templates.render('changes/versionchanges.html', ctx)) - finally: - f.close() - - hltext = ['.. versionadded:: %s' % version, - '.. versionchanged:: %s' % version, - '.. deprecated:: %s' % version] - - def hl(no, line): - line = ' ' % no + escape(line) - for x in hltext: - if x in line: - line = '%s' % line - break - return line - - self.info(bold('copying source files...')) - for docname in self.env.all_docs: - f = open(self.env.doc2path(docname)) - lines = f.readlines() - targetfn = path.join(self.outdir, 'rst', os_path(docname)) + '.html' - ensuredir(path.dirname(targetfn)) - f = codecs.open(targetfn, 'w', 'utf8') - try: - text = ''.join(hl(i+1, line) for (i, line) in enumerate(lines)) - ctx = {'filename': self.env.doc2path(docname, None), 'text': text} - f.write(self.templates.render('changes/rstsource.html', ctx)) - finally: - f.close() - shutil.copyfile(path.join(path.dirname(__file__), 'static', 'default.css'), - path.join(self.outdir, 'default.css')) - - def hl(self, text, version): - text = escape(text) - for directive in ['versionchanged', 'versionadded', 'deprecated']: - text = text.replace('.. %s:: %s' % (directive, version), - '.. %s:: %s' % (directive, version)) - return text - - def finish(self): - pass - - -class TextBuilder(Builder): - name = 'text' - out_suffix = '.txt' - - def init(self): - pass - - def get_outdated_docs(self): - for docname in self.env.found_docs: - if docname not in self.env.all_docs: - yield docname - continue - targetname = self.env.doc2path(docname, self.outdir, self.out_suffix) - try: - targetmtime = path.getmtime(targetname) - except Exception: - targetmtime = 0 - try: - srcmtime = path.getmtime(self.env.doc2path(docname)) - if srcmtime > targetmtime: - yield docname - except EnvironmentError: - # source doesn't exist anymore - pass - - def get_target_uri(self, docname, typ=None): - return '' - - def prepare_writing(self, docnames): - self.writer = TextWriter(self) - - def write_doc(self, docname, doctree): - destination = StringOutput(encoding='utf-8') - self.writer.write(doctree, destination) - outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix) - ensuredir(path.dirname(outfilename)) # normally different from self.outdir - try: - f = codecs.open(outfilename, 'w', 'utf-8') - try: - f.write(self.writer.output) - finally: - f.close() - except (IOError, OSError), err: - self.warn("Error writing file %s: %s" % (outfilename, err)) - - def finish(self): - pass - - -# compatibility alias -WebHTMLBuilder = PickleHTMLBuilder - - -from sphinx.linkcheck import CheckExternalLinksBuilder - -builtin_builders = { - 'html': StandaloneHTMLBuilder, - 'pickle': PickleHTMLBuilder, - 'json': JSONHTMLBuilder, - 'web': PickleHTMLBuilder, - 'htmlhelp': HTMLHelpBuilder, - 'latex': LaTeXBuilder, - 'text': TextBuilder, - 'changes': ChangesBuilder, - 'linkcheck': CheckExternalLinksBuilder, -} +from sphinx.builders import Builder +from sphinx.builders.text import TextBuilder +from sphinx.builders.html import StandaloneHTMLBuilder, WebHTMLBuilder, \ + PickleHTMLBuilder, JSONHTMLBuilder +from sphinx.builders.latex import LaTeXBuilder +from sphinx.builders.changes import ChangesBuilder +from sphinx.builders.htmlhelp import HTMLHelpBuilder +from sphinx.builders.linkcheck import CheckExternalLinksBuilder diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py new file mode 100644 index 00000000..09d37de2 --- /dev/null +++ b/sphinx/builders/__init__.py @@ -0,0 +1,328 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders + ~~~~~~~~~~~~~~~ + + Builder superclass for all builders. + + :copyright: 2007-2008 by Georg Brandl, Sebastian Wiesner, Horst Gutmann. + :license: BSD. +""" + +import os +import gettext +from os import path + +from docutils import nodes + +from sphinx import package_dir, locale +from sphinx.util import SEP, relative_uri +from sphinx.environment import BuildEnvironment +from sphinx.util.console import bold, purple, darkgreen + +# side effect: registers roles and directives +from sphinx import roles +from sphinx import directives + + +ENV_PICKLE_FILENAME = 'environment.pickle' + + +class Builder(object): + """ + Builds target formats from the reST sources. + """ + + # builder's name, for the -b command line options + name = '' + + def __init__(self, app, env=None, freshenv=False): + self.srcdir = app.srcdir + self.confdir = app.confdir + self.outdir = app.outdir + self.doctreedir = app.doctreedir + if not path.isdir(self.doctreedir): + os.makedirs(self.doctreedir) + + self.app = app + self.warn = app.warn + self.info = app.info + self.config = app.config + + self.load_i18n() + + # images that need to be copied over (source -> dest) + self.images = {} + + # if None, this is set in load_env() + self.env = env + self.freshenv = freshenv + + self.init() + self.load_env() + + # helper methods + + def init(self): + """Load necessary templates and perform initialization.""" + raise NotImplementedError + + def init_templates(self): + # Call this from init() if you need templates. + if self.config.template_bridge: + self.templates = self.app.import_object( + self.config.template_bridge, 'template_bridge setting')() + else: + from sphinx._jinja import BuiltinTemplates + self.templates = BuiltinTemplates() + self.templates.init(self) + + def get_target_uri(self, docname, typ=None): + """ + Return the target URI for a document name (typ can be used to qualify + the link characteristic for individual builders). + """ + raise NotImplementedError + + def get_relative_uri(self, from_, to, typ=None): + """ + Return a relative URI between two source filenames. May raise environment.NoUri + if there's no way to return a sensible URI. + """ + return relative_uri(self.get_target_uri(from_), + self.get_target_uri(to, typ)) + + def get_outdated_docs(self): + """ + Return an iterable of output files that are outdated, or a string describing + what an update build will build. + """ + raise NotImplementedError + + def status_iterator(self, iterable, summary, colorfunc=darkgreen): + l = -1 + for item in iterable: + if l == -1: + self.info(bold(summary), nonl=1) + l = 0 + self.info(colorfunc(item) + ' ', nonl=1) + yield item + if l == 0: + self.info() + + supported_image_types = [] + + def post_process_images(self, doctree): + """ + Pick the best candidate for all image URIs. + """ + for node in doctree.traverse(nodes.image): + if '?' in node['candidates']: + # don't rewrite nonlocal image URIs + continue + if '*' not in node['candidates']: + for imgtype in self.supported_image_types: + candidate = node['candidates'].get(imgtype, None) + if candidate: + break + else: + self.warn('%s:%s: no matching candidate for image URI %r' % + (node.source, getattr(node, 'lineno', ''), node['uri'])) + continue + node['uri'] = candidate + else: + candidate = node['uri'] + if candidate not in self.env.images: + # non-existing URI; let it alone + continue + self.images[candidate] = self.env.images[candidate][1] + + # build methods + + def load_i18n(self): + """ + Load translated strings from the configured localedirs if + enabled in the configuration. + """ + self.translator = None + if self.config.language is not None: + self.info(bold('loading translations [%s]... ' % self.config.language), + nonl=True) + locale_dirs = [path.join(package_dir, 'locale')] + \ + [path.join(self.srcdir, x) for x in self.config.locale_dirs] + for dir_ in locale_dirs: + try: + trans = gettext.translation('sphinx', localedir=dir_, + languages=[self.config.language]) + if self.translator is None: + self.translator = trans + else: + self.translator._catalog.update(trans.catalog) + except Exception: + # Language couldn't be found in the specified path + pass + if self.translator is not None: + self.info('done') + else: + self.info('locale not available') + if self.translator is None: + self.translator = gettext.NullTranslations() + self.translator.install(unicode=True) + locale.init() # translate common labels + + def load_env(self): + """Set up the build environment.""" + if self.env: + return + if not self.freshenv: + try: + self.info(bold('loading pickled environment... '), nonl=True) + self.env = BuildEnvironment.frompickle(self.config, + path.join(self.doctreedir, ENV_PICKLE_FILENAME)) + self.info('done') + except Exception, err: + if type(err) is IOError and err.errno == 2: + self.info('not found') + else: + self.info('failed: %s' % err) + self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) + self.env.find_files(self.config) + else: + self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) + self.env.find_files(self.config) + self.env.set_warnfunc(self.warn) + + def build_all(self): + """Build all source files.""" + self.build(None, summary='all source files', method='all') + + def build_specific(self, filenames): + """Only rebuild as much as needed for changes in the source_filenames.""" + # bring the filenames to the canonical format, that is, + # relative to the source directory and without source_suffix. + dirlen = len(self.srcdir) + 1 + to_write = [] + suffix = self.config.source_suffix + for filename in filenames: + filename = path.abspath(filename)[dirlen:] + if filename.endswith(suffix): + filename = filename[:-len(suffix)] + filename = filename.replace(os.path.sep, SEP) + to_write.append(filename) + self.build(to_write, method='specific', + summary='%d source files given on command ' + 'line' % len(to_write)) + + def build_update(self): + """Only rebuild files changed or added since last build.""" + to_build = self.get_outdated_docs() + if isinstance(to_build, str): + self.build(['__all__'], to_build) + else: + to_build = list(to_build) + self.build(to_build, + summary='targets for %d source files that are ' + 'out of date' % len(to_build)) + + def build(self, docnames, summary=None, method='update'): + if summary: + self.info(bold('building [%s]: ' % self.name), nonl=1) + self.info(summary) + + updated_docnames = [] + # while reading, collect all warnings from docutils + warnings = [] + self.env.set_warnfunc(warnings.append) + self.info(bold('updating environment: '), nonl=1) + iterator = self.env.update(self.config, self.srcdir, self.doctreedir, self.app) + # the first item in the iterator is a summary message + self.info(iterator.next()) + for docname in self.status_iterator(iterator, 'reading sources... ', purple): + updated_docnames.append(docname) + # nothing further to do, the environment has already done the reading + for warning in warnings: + if warning.strip(): + self.warn(warning) + self.env.set_warnfunc(self.warn) + + if updated_docnames: + # save the environment + self.info(bold('pickling environment... '), nonl=True) + self.env.topickle(path.join(self.doctreedir, ENV_PICKLE_FILENAME)) + self.info('done') + + # global actions + self.info(bold('checking consistency... '), nonl=True) + self.env.check_consistency() + self.info('done') + else: + if method == 'update' and not docnames: + self.info(bold('no targets are out of date.')) + return + + # another indirection to support methods which don't build files + # individually + self.write(docnames, updated_docnames, method) + + # finish (write static files etc.) + self.finish() + if self.app._warncount: + self.info(bold('build succeeded, %s warning%s.' % + (self.app._warncount, + self.app._warncount != 1 and 's' or ''))) + else: + self.info(bold('build succeeded.')) + + def write(self, build_docnames, updated_docnames, method='update'): + if build_docnames is None or build_docnames == ['__all__']: + # build_all + build_docnames = self.env.found_docs + if method == 'update': + # build updated ones as well + docnames = set(build_docnames) | set(updated_docnames) + else: + docnames = set(build_docnames) + + # add all toctree-containing files that may have changed + for docname in list(docnames): + for tocdocname in self.env.files_to_rebuild.get(docname, []): + docnames.add(tocdocname) + docnames.add(self.config.master_doc) + + self.info(bold('preparing documents... '), nonl=True) + self.prepare_writing(docnames) + self.info('done') + + # write target files + warnings = [] + self.env.set_warnfunc(warnings.append) + for docname in self.status_iterator(sorted(docnames), + 'writing output... ', darkgreen): + doctree = self.env.get_and_resolve_doctree(docname, self) + self.write_doc(docname, doctree) + for warning in warnings: + if warning.strip(): + self.warn(warning) + self.env.set_warnfunc(self.warn) + + def prepare_writing(self, docnames): + raise NotImplementedError + + def write_doc(self, docname, doctree): + raise NotImplementedError + + def finish(self): + raise NotImplementedError + + +BUILTIN_BUILDERS = { + 'html': ('html', 'StandaloneHTMLBuilder'), + 'pickle': ('html', 'PickleHTMLBuilder'), + 'json': ('html', 'JSONHTMLBuilder'), + 'web': ('html', 'PickleHTMLBuilder'), + 'htmlhelp': ('htmlhelp', 'HTMLHelpBuilder'), + 'latex': ('latex', 'LaTeXBuilder'), + 'text': ('text', 'TextBuilder'), + 'changes': ('changes', 'ChangesBuilder'), + 'linkcheck': ('linkcheck', 'CheckExternalLinksBuilder'), +} diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py new file mode 100644 index 00000000..28805738 --- /dev/null +++ b/sphinx/builders/changes.py @@ -0,0 +1,137 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.changes + ~~~~~~~~~~~~~~~~~~~~~~~ + + Changelog builder. + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" + +import codecs +import shutil +from os import path +from cgi import escape + +from sphinx import package_dir +from sphinx.util import ensuredir, os_path +from sphinx.builders import Builder +from sphinx.util.console import bold + + +class ChangesBuilder(Builder): + """ + Write a summary with all versionadded/changed directives. + """ + name = 'changes' + + def init(self): + self.init_templates() + + def get_outdated_docs(self): + return self.outdir + + typemap = { + 'versionadded': 'added', + 'versionchanged': 'changed', + 'deprecated': 'deprecated', + } + + def write(self, *ignored): + version = self.config.version + libchanges = {} + apichanges = [] + otherchanges = {} + if version not in self.env.versionchanges: + self.info(bold('no changes in this version.')) + return + self.info(bold('writing summary file...')) + for type, docname, lineno, module, descname, content in \ + self.env.versionchanges[version]: + ttext = self.typemap[type] + context = content.replace('\n', ' ') + if descname and docname.startswith('c-api'): + if not descname: + continue + if context: + entry = '%s: %s: %s' % (descname, ttext, context) + else: + entry = '%s: %s.' % (descname, ttext) + apichanges.append((entry, docname, lineno)) + elif descname or module: + if not module: + module = _('Builtins') + if not descname: + descname = _('Module level') + if context: + entry = '%s: %s: %s' % (descname, ttext, context) + else: + entry = '%s: %s.' % (descname, ttext) + libchanges.setdefault(module, []).append((entry, docname, lineno)) + else: + if not context: + continue + entry = '%s: %s' % (ttext.capitalize(), context) + title = self.env.titles[docname].astext() + otherchanges.setdefault((docname, title), []).append( + (entry, docname, lineno)) + + ctx = { + 'project': self.config.project, + 'version': version, + 'docstitle': self.config.html_title, + 'shorttitle': self.config.html_short_title, + 'libchanges': sorted(libchanges.iteritems()), + 'apichanges': sorted(apichanges), + 'otherchanges': sorted(otherchanges.iteritems()), + 'show_sphinx': self.config.html_show_sphinx, + } + f = open(path.join(self.outdir, 'index.html'), 'w') + try: + f.write(self.templates.render('changes/frameset.html', ctx)) + finally: + f.close() + f = open(path.join(self.outdir, 'changes.html'), 'w') + try: + f.write(self.templates.render('changes/versionchanges.html', ctx)) + finally: + f.close() + + hltext = ['.. versionadded:: %s' % version, + '.. versionchanged:: %s' % version, + '.. deprecated:: %s' % version] + + def hl(no, line): + line = ' ' % no + escape(line) + for x in hltext: + if x in line: + line = '%s' % line + break + return line + + self.info(bold('copying source files...')) + for docname in self.env.all_docs: + f = open(self.env.doc2path(docname)) + lines = f.readlines() + targetfn = path.join(self.outdir, 'rst', os_path(docname)) + '.html' + ensuredir(path.dirname(targetfn)) + f = codecs.open(targetfn, 'w', 'utf8') + try: + text = ''.join(hl(i+1, line) for (i, line) in enumerate(lines)) + ctx = {'filename': self.env.doc2path(docname, None), 'text': text} + f.write(self.templates.render('changes/rstsource.html', ctx)) + finally: + f.close() + shutil.copyfile(path.join(package_dir, 'static', 'default.css'), + path.join(self.outdir, 'default.css')) + + def hl(self, text, version): + text = escape(text) + for directive in ['versionchanged', 'versionadded', 'deprecated']: + text = text.replace('.. %s:: %s' % (directive, version), + '.. %s:: %s' % (directive, version)) + return text + + def finish(self): + pass diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py new file mode 100644 index 00000000..adf58be1 --- /dev/null +++ b/sphinx/builders/html.py @@ -0,0 +1,607 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.html + ~~~~~~~~~~~~~~~~~~~~ + + Several HTML builders. + + :copyright: 2007-2008 by Georg Brandl, Armin Ronacher. + :license: BSD. +""" + +import os +import codecs +import shutil +import cPickle as pickle +from os import path + +from docutils.io import DocTreeInput, StringOutput +from docutils.core import publish_parts +from docutils.utils import new_document +from docutils.frontend import OptionParser +from docutils.readers.doctree import Reader as DoctreeReader + +from sphinx import package_dir, __version__ +from sphinx.util import SEP, os_path, relative_uri, ensuredir, ustrftime +from sphinx.search import js_index +from sphinx.builders import Builder, ENV_PICKLE_FILENAME +from sphinx.highlighting import PygmentsBridge +from sphinx.util.console import bold +from sphinx.writers.html import HTMLWriter, HTMLTranslator, SmartyPantsHTMLTranslator + +try: + import json +except ImportError: + try: + import simplejson as json + except ImportError: + json = None + + +INVENTORY_FILENAME = 'objects.inv' +LAST_BUILD_FILENAME = 'last_build' + + +class StandaloneHTMLBuilder(Builder): + """ + Builds standalone HTML docs. + """ + name = 'html' + copysource = True + out_suffix = '.html' + indexer_format = js_index + supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', + 'image/jpeg'] + searchindex_filename = 'searchindex.js' + add_header_links = True + add_definition_links = True + + # This is a class attribute because it is mutated by Sphinx.add_javascript. + script_files = ['_static/jquery.js', '_static/doctools.js'] + + def init(self): + """Load templates.""" + self.init_templates() + self.init_translator_class() + if self.config.html_file_suffix: + self.out_suffix = self.config.html_file_suffix + + if self.config.language is not None: + jsfile = path.join(package_dir, 'locale', self.config.language, + 'LC_MESSAGES', 'sphinx.js') + if path.isfile(jsfile): + self.script_files.append('_static/translations.js') + + def init_translator_class(self): + if self.config.html_translator_class: + self.translator_class = self.app.import_object( + self.config.html_translator_class, 'html_translator_class setting') + elif self.config.html_use_smartypants: + self.translator_class = SmartyPantsHTMLTranslator + else: + self.translator_class = HTMLTranslator + + def render_partial(self, node): + """Utility: Render a lone doctree node.""" + doc = new_document('') + doc.append(node) + return publish_parts( + doc, + source_class=DocTreeInput, + reader=DoctreeReader(), + writer=HTMLWriter(self), + settings_overrides={'output_encoding': 'unicode'} + ) + + def prepare_writing(self, docnames): + from sphinx.search import IndexBuilder + + self.indexer = IndexBuilder(self.env) + self.load_indexer(docnames) + self.docwriter = HTMLWriter(self) + self.docsettings = OptionParser( + defaults=self.env.settings, + components=(self.docwriter,)).get_default_values() + + # format the "last updated on" string, only once is enough since it + # typically doesn't include the time of day + lufmt = self.config.html_last_updated_fmt + if lufmt is not None: + self.last_updated = ustrftime(lufmt or _('%b %d, %Y')) + else: + self.last_updated = None + + logo = self.config.html_logo and \ + path.basename(self.config.html_logo) or '' + + favicon = self.config.html_favicon and \ + path.basename(self.config.html_favicon) or '' + if favicon and os.path.splitext(favicon)[1] != '.ico': + self.warn('html_favicon is not an .ico file') + + if not isinstance(self.config.html_use_opensearch, basestring): + self.warn('html_use_opensearch config value must now be a string') + + self.relations = self.env.collect_relations() + + rellinks = [] + if self.config.html_use_index: + rellinks.append(('genindex', _('General Index'), 'I', _('index'))) + if self.config.html_use_modindex and self.env.modules: + rellinks.append(('modindex', _('Global Module Index'), 'M', _('modules'))) + + self.globalcontext = dict( + project = self.config.project, + release = self.config.release, + version = self.config.version, + last_updated = self.last_updated, + copyright = self.config.copyright, + master_doc = self.config.master_doc, + style = self.config.html_style, + use_opensearch = self.config.html_use_opensearch, + docstitle = self.config.html_title, + shorttitle = self.config.html_short_title, + show_sphinx = self.config.html_show_sphinx, + file_suffix = self.out_suffix, + script_files = self.script_files, + sphinx_version = __version__, + rellinks = rellinks, + builder = self.name, + parents = [], + logo = logo, + favicon = favicon, + ) + self.globalcontext.update(self.config.html_context) + + def get_doc_context(self, docname, body, metatags): + """Collect items for the template context of a page.""" + # find out relations + prev = next = None + parents = [] + rellinks = self.globalcontext['rellinks'][:] + related = self.relations.get(docname) + titles = self.env.titles + if related and related[2]: + try: + next = {'link': self.get_relative_uri(docname, related[2]), + 'title': self.render_partial(titles[related[2]])['title']} + rellinks.append((related[2], next['title'], 'N', _('next'))) + except KeyError: + next = None + if related and related[1]: + try: + prev = {'link': self.get_relative_uri(docname, related[1]), + 'title': self.render_partial(titles[related[1]])['title']} + rellinks.append((related[1], prev['title'], 'P', _('previous'))) + except KeyError: + # the relation is (somehow) not in the TOC tree, handle that gracefully + prev = None + while related and related[0]: + try: + parents.append( + {'link': self.get_relative_uri(docname, related[0]), + 'title': self.render_partial(titles[related[0]])['title']}) + except KeyError: + pass + related = self.relations.get(related[0]) + if parents: + parents.pop() # remove link to the master file; we have a generic + # "back to index" link already + parents.reverse() + + # title rendered as HTML + title = titles.get(docname) + title = title and self.render_partial(title)['title'] or '' + # the name for the copied source + sourcename = self.config.html_copy_source and docname + '.txt' or '' + + # metadata for the document + meta = self.env.metadata.get(docname) + + return dict( + parents = parents, + prev = prev, + next = next, + title = title, + meta = meta, + body = body, + metatags = metatags, + rellinks = rellinks, + sourcename = sourcename, + toc = self.render_partial(self.env.get_toc_for(docname))['fragment'], + # only display a TOC if there's more than one item to show + display_toc = (self.env.toc_num_entries[docname] > 1), + ) + + def write_doc(self, docname, doctree): + self.post_process_images(doctree) + destination = StringOutput(encoding='utf-8') + doctree.settings = self.docsettings + + self.imgpath = relative_uri(self.get_target_uri(docname), '_images') + self.docwriter.write(doctree, destination) + self.docwriter.assemble_parts() + body = self.docwriter.parts['fragment'] + metatags = self.docwriter.clean_meta + + ctx = self.get_doc_context(docname, body, metatags) + self.index_page(docname, doctree, ctx.get('title', '')) + self.handle_page(docname, ctx, event_arg=doctree) + + def finish(self): + self.info(bold('writing additional files...'), nonl=1) + + # the global general index + + if self.config.html_use_index: + # the total count of lines for each index letter, used to distribute + # the entries into two columns + genindex = self.env.create_index(self) + indexcounts = [] + for _, entries in genindex: + indexcounts.append(sum(1 + len(subitems) + for _, (_, subitems) in entries)) + + genindexcontext = dict( + genindexentries = genindex, + genindexcounts = indexcounts, + split_index = self.config.html_split_index, + ) + self.info(' genindex', nonl=1) + + if self.config.html_split_index: + self.handle_page('genindex', genindexcontext, 'genindex-split.html') + self.handle_page('genindex-all', genindexcontext, 'genindex.html') + for (key, entries), count in zip(genindex, indexcounts): + ctx = {'key': key, 'entries': entries, 'count': count, + 'genindexentries': genindex} + self.handle_page('genindex-' + key, ctx, 'genindex-single.html') + else: + self.handle_page('genindex', genindexcontext, 'genindex.html') + + # the global module index + + if self.config.html_use_modindex and self.env.modules: + # the sorted list of all modules, for the global module index + modules = sorted(((mn, (self.get_relative_uri('modindex', fn) + + '#module-' + mn, sy, pl, dep)) + for (mn, (fn, sy, pl, dep)) in + self.env.modules.iteritems()), + key=lambda x: x[0].lower()) + # collect all platforms + platforms = set() + # sort out collapsable modules + modindexentries = [] + letters = [] + pmn = '' + num_toplevels = 0 + num_collapsables = 0 + cg = 0 # collapse group + fl = '' # first letter + for mn, (fn, sy, pl, dep) in modules: + pl = pl and pl.split(', ') or [] + platforms.update(pl) + if fl != mn[0].lower() and mn[0] != '_': + # heading + modindexentries.append(['', False, 0, False, + mn[0].upper(), '', [], False]) + letters.append(mn[0].upper()) + tn = mn.split('.')[0] + if tn != mn: + # submodule + if pmn == tn: + # first submodule - make parent collapsable + modindexentries[-1][1] = True + num_collapsables += 1 + elif not pmn.startswith(tn): + # submodule without parent in list, add dummy entry + cg += 1 + modindexentries.append([tn, True, cg, False, '', '', [], False]) + else: + num_toplevels += 1 + cg += 1 + modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, dep]) + pmn = mn + fl = mn[0].lower() + platforms = sorted(platforms) + + # apply heuristics when to collapse modindex at page load: + # only collapse if number of toplevel modules is larger than + # number of submodules + collapse = len(modules) - num_toplevels < num_toplevels + + modindexcontext = dict( + modindexentries = modindexentries, + platforms = platforms, + letters = letters, + collapse_modindex = collapse, + ) + self.info(' modindex', nonl=1) + self.handle_page('modindex', modindexcontext, 'modindex.html') + + # the search page + if self.name != 'htmlhelp': + self.info(' search', nonl=1) + self.handle_page('search', {}, 'search.html') + + # additional pages from conf.py + for pagename, template in self.config.html_additional_pages.items(): + self.info(' '+pagename, nonl=1) + self.handle_page(pagename, {}, template) + + if self.config.html_use_opensearch and self.name != 'htmlhelp': + self.info(' opensearch', nonl=1) + fn = path.join(self.outdir, '_static', 'opensearch.xml') + self.handle_page('opensearch', {}, 'opensearch.xml', outfilename=fn) + + self.info() + + # copy image files + if self.images: + self.info(bold('copying images...'), nonl=True) + ensuredir(path.join(self.outdir, '_images')) + for src, dest in self.images.iteritems(): + self.info(' '+src, nonl=1) + shutil.copyfile(path.join(self.srcdir, src), + path.join(self.outdir, '_images', dest)) + self.info() + + # copy static files + self.info(bold('copying static files... '), nonl=True) + ensuredir(path.join(self.outdir, '_static')) + # first, create pygments style file + f = open(path.join(self.outdir, '_static', 'pygments.css'), 'w') + f.write(PygmentsBridge('html', self.config.pygments_style).get_stylesheet()) + f.close() + # then, copy translations JavaScript file + if self.config.language is not None: + jsfile = path.join(package_dir, 'locale', self.config.language, + 'LC_MESSAGES', 'sphinx.js') + if path.isfile(jsfile): + shutil.copyfile(jsfile, path.join(self.outdir, '_static', + 'translations.js')) + # then, copy over all user-supplied static files + staticdirnames = [path.join(package_dir, 'static')] + \ + [path.join(self.confdir, spath) + for spath in self.config.html_static_path] + for staticdirname in staticdirnames: + for filename in os.listdir(staticdirname): + if filename.startswith('.'): + continue + fullname = path.join(staticdirname, filename) + targetname = path.join(self.outdir, '_static', filename) + if path.isfile(fullname): + shutil.copyfile(fullname, targetname) + elif path.isdir(fullname): + if filename in self.config.exclude_dirnames: + continue + if path.exists(targetname): + shutil.rmtree(targetname) + shutil.copytree(fullname, targetname) + # last, copy logo file (handled differently) + if self.config.html_logo: + logobase = path.basename(self.config.html_logo) + shutil.copyfile(path.join(self.confdir, self.config.html_logo), + path.join(self.outdir, '_static', logobase)) + self.info('done') + + # dump the search index + self.handle_finish() + + def get_outdated_docs(self): + if self.templates: + template_mtime = self.templates.newest_template_mtime() + else: + template_mtime = 0 + for docname in self.env.found_docs: + if docname not in self.env.all_docs: + yield docname + continue + targetname = self.env.doc2path(docname, self.outdir, self.out_suffix) + try: + targetmtime = path.getmtime(targetname) + except Exception: + targetmtime = 0 + try: + srcmtime = max(path.getmtime(self.env.doc2path(docname)), + template_mtime) + if srcmtime > targetmtime: + yield docname + except EnvironmentError: + # source doesn't exist anymore + pass + + def load_indexer(self, docnames): + keep = set(self.env.all_docs) - set(docnames) + try: + f = open(path.join(self.outdir, self.searchindex_filename), 'rb') + try: + self.indexer.load(f, self.indexer_format) + finally: + f.close() + except (IOError, OSError, ValueError): + if keep: + self.warn("search index couldn't be loaded, but not all documents " + "will be built: the index will be incomplete.") + # delete all entries for files that will be rebuilt + self.indexer.prune(keep) + + def index_page(self, pagename, doctree, title): + # only index pages with title + if self.indexer is not None and title: + self.indexer.feed(pagename, title, doctree) + + # --------- these are overwritten by the serialization builder + + def get_target_uri(self, docname, typ=None): + return docname + self.out_suffix + + def handle_page(self, pagename, addctx, templatename='page.html', + outfilename=None, event_arg=None): + ctx = self.globalcontext.copy() + # current_page_name is backwards compatibility + ctx['pagename'] = ctx['current_page_name'] = pagename + + def pathto(otheruri, resource=False, + baseuri=self.get_target_uri(pagename)): + if not resource: + otheruri = self.get_target_uri(otheruri) + return relative_uri(baseuri, otheruri) + ctx['pathto'] = pathto + ctx['hasdoc'] = lambda name: name in self.env.all_docs + ctx['customsidebar'] = self.config.html_sidebars.get(pagename) + ctx.update(addctx) + + self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) + + output = self.templates.render(templatename, ctx) + if not outfilename: + outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) + ensuredir(path.dirname(outfilename)) # normally different from self.outdir + try: + f = codecs.open(outfilename, 'w', 'utf-8') + try: + f.write(output) + finally: + f.close() + except (IOError, OSError), err: + self.warn("Error writing file %s: %s" % (outfilename, err)) + if self.copysource and ctx.get('sourcename'): + # copy the source file for the "show source" link + source_name = path.join(self.outdir, '_sources', os_path(ctx['sourcename'])) + ensuredir(path.dirname(source_name)) + shutil.copyfile(self.env.doc2path(pagename), source_name) + + def handle_finish(self): + self.info(bold('dumping search index... '), nonl=True) + self.indexer.prune(self.env.all_docs) + f = open(path.join(self.outdir, self.searchindex_filename), 'wb') + try: + self.indexer.dump(f, self.indexer_format) + finally: + f.close() + self.info('done') + + self.info(bold('dumping object inventory... '), nonl=True) + f = open(path.join(self.outdir, INVENTORY_FILENAME), 'w') + try: + f.write('# Sphinx inventory version 1\n') + f.write('# Project: %s\n' % self.config.project.encode('utf-8')) + f.write('# Version: %s\n' % self.config.version) + for modname, info in self.env.modules.iteritems(): + f.write('%s mod %s\n' % (modname, self.get_target_uri(info[0]))) + for refname, (docname, desctype) in self.env.descrefs.iteritems(): + f.write('%s %s %s\n' % (refname, desctype, self.get_target_uri(docname))) + finally: + f.close() + self.info('done') + + +class SerializingHTMLBuilder(StandaloneHTMLBuilder): + """ + An abstract builder that serializes the HTML generated. + """ + #: the serializing implementation to use. Set this to a module that + #: implements a `dump`, `load`, `dumps` and `loads` functions + #: (pickle, simplejson etc.) + implementation = None + + #: the filename for the global context file + globalcontext_filename = None + + supported_image_types = ('image/svg+xml', 'image/png', 'image/gif', + 'image/jpeg') + + def init(self): + self.init_translator_class() + self.templates = None # no template bridge necessary + + def get_target_uri(self, docname, typ=None): + if docname == 'index': + return '' + if docname.endswith(SEP + 'index'): + return docname[:-5] # up to sep + return docname + SEP + + def handle_page(self, pagename, ctx, templatename='page.html', + outfilename=None, event_arg=None): + ctx['current_page_name'] = pagename + sidebarfile = self.config.html_sidebars.get(pagename) + if sidebarfile: + ctx['customsidebar'] = sidebarfile + + if not outfilename: + outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) + + self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) + + ensuredir(path.dirname(outfilename)) + f = open(outfilename, 'wb') + try: + self.implementation.dump(ctx, f, 2) + finally: + f.close() + + # if there is a source file, copy the source file for the + # "show source" link + if ctx.get('sourcename'): + source_name = path.join(self.outdir, '_sources', + os_path(ctx['sourcename'])) + ensuredir(path.dirname(source_name)) + shutil.copyfile(self.env.doc2path(pagename), source_name) + + def handle_finish(self): + # dump the global context + outfilename = path.join(self.outdir, self.globalcontext_filename) + f = open(outfilename, 'wb') + try: + self.implementation.dump(self.globalcontext, f, 2) + finally: + f.close() + + # super here to dump the search index + StandaloneHTMLBuilder.handle_finish(self) + + # copy the environment file from the doctree dir to the output dir + # as needed by the web app + shutil.copyfile(path.join(self.doctreedir, ENV_PICKLE_FILENAME), + path.join(self.outdir, ENV_PICKLE_FILENAME)) + + # touch 'last build' file, used by the web application to determine + # when to reload its environment and clear the cache + open(path.join(self.outdir, LAST_BUILD_FILENAME), 'w').close() + + +class PickleHTMLBuilder(SerializingHTMLBuilder): + """ + A Builder that dumps the generated HTML into pickle files. + """ + implementation = pickle + indexer_format = pickle + name = 'pickle' + out_suffix = '.fpickle' + globalcontext_filename = 'globalcontext.pickle' + searchindex_filename = 'searchindex.pickle' + +# compatibility alias +WebHTMLBuilder = PickleHTMLBuilder + + +class JSONHTMLBuilder(SerializingHTMLBuilder): + """ + A builder that dumps the generated HTML into JSON files. + """ + implementation = json + indexer_format = json + name = 'json' + out_suffix = '.fjson' + globalcontext_filename = 'globalcontext.json' + searchindex_filename = 'searchindex.json' + + def init(self): + if json is None: + from sphinx.application import SphinxError + raise SphinxError('The module simplejson (or json in Python >= 2.6) ' + 'is not available. The JSONHTMLBuilder builder ' + 'will not work.') + SerializingHTMLBuilder.init(self) diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py new file mode 100644 index 00000000..23900f36 --- /dev/null +++ b/sphinx/builders/htmlhelp.py @@ -0,0 +1,245 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.htmlhelp + ~~~~~~~~~~~~~~~~~~~~~~~~ + + Build HTML help support files. + Parts adapted from Python's Doc/tools/prechm.py. + + :copyright: 2007-2008 by Georg Brandl. + :license: BSD. +""" + +import os +import cgi +from os import path + +from docutils import nodes + +from sphinx import addnodes +from sphinx.builders.html import StandaloneHTMLBuilder + + +# Project file (*.hhp) template. 'outname' is the file basename (like +# the pythlp in pythlp.hhp); 'version' is the doc version number (like +# the 2.2 in Python 2.2). +# The magical numbers in the long line under [WINDOWS] set most of the +# user-visible features (visible buttons, tabs, etc). +# About 0x10384e: This defines the buttons in the help viewer. The +# following defns are taken from htmlhelp.h. Not all possibilities +# actually work, and not all those that work are available from the Help +# Workshop GUI. In particular, the Zoom/Font button works and is not +# available from the GUI. The ones we're using are marked with 'x': +# +# 0x000002 Hide/Show x +# 0x000004 Back x +# 0x000008 Forward x +# 0x000010 Stop +# 0x000020 Refresh +# 0x000040 Home x +# 0x000080 Forward +# 0x000100 Back +# 0x000200 Notes +# 0x000400 Contents +# 0x000800 Locate x +# 0x001000 Options x +# 0x002000 Print x +# 0x004000 Index +# 0x008000 Search +# 0x010000 History +# 0x020000 Favorites +# 0x040000 Jump 1 +# 0x080000 Jump 2 +# 0x100000 Zoom/Font x +# 0x200000 TOC Next +# 0x400000 TOC Prev + +project_template = '''\ +[OPTIONS] +Binary TOC=Yes +Binary Index=No +Compiled file=%(outname)s.chm +Contents file=%(outname)s.hhc +Default Window=%(outname)s +Default topic=index.html +Display compile progress=No +Full text search stop list file=%(outname)s.stp +Full-text search=Yes +Index file=%(outname)s.hhk +Language=0x409 +Title=%(title)s + +[WINDOWS] +%(outname)s="%(title)s","%(outname)s.hhc","%(outname)s.hhk",\ +"index.html","index.html",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0 + +[FILES] +''' + +contents_header = '''\ + + + + + + + + + + +
    +''' + +contents_footer = '''\ +
+''' + +object_sitemap = '''\ + + + + +''' + +# List of words the full text search facility shouldn't index. This +# becomes file outname.stp. Note that this list must be pretty small! +# Different versions of the MS docs claim the file has a maximum size of +# 256 or 512 bytes (including \r\n at the end of each line). +# Note that "and", "or", "not" and "near" are operators in the search +# language, so no point indexing them even if we wanted to. +stopwords = """ +a and are as at +be but by +for +if in into is it +near no not +of on or +such +that the their then there these they this to +was will with +""".split() + + +class HTMLHelpBuilder(StandaloneHTMLBuilder): + """ + Builder that also outputs Windows HTML help project, contents and index files. + Adapted from the original Doc/tools/prechm.py. + """ + name = 'htmlhelp' + + # don't copy the reST source + copysource = False + supported_image_types = ['image/png', 'image/gif', 'image/jpeg'] + + # don't add links + add_header_links = False + add_definition_links = False + + def init(self): + StandaloneHTMLBuilder.init(self) + # the output files for HTML help must be .html only + self.out_suffix = '.html' + + def handle_finish(self): + self.build_hhx(self, self.outdir, self.config.htmlhelp_basename) + + def build_hhx(self, outdir, outname): + self.info('dumping stopword list...') + f = open(path.join(outdir, outname+'.stp'), 'w') + try: + for word in sorted(stopwords): + print >>f, word + finally: + f.close() + + self.info('writing project file...') + f = open(path.join(outdir, outname+'.hhp'), 'w') + try: + f.write(project_template % {'outname': outname, + 'title': self.config.html_title, + 'version': self.config.version, + 'project': self.config.project}) + if not outdir.endswith(os.sep): + outdir += os.sep + olen = len(outdir) + for root, dirs, files in os.walk(outdir): + staticdir = (root == path.join(outdir, '_static')) + for fn in files: + if (staticdir and not fn.endswith('.js')) or fn.endswith('.html'): + print >>f, path.join(root, fn)[olen:].replace(os.sep, '\\') + finally: + f.close() + + self.info('writing TOC file...') + f = open(path.join(outdir, outname+'.hhc'), 'w') + try: + f.write(contents_header) + # special books + f.write('
  • ' + object_sitemap % (self.config.html_short_title, + 'index.html')) + if self.config.html_use_modindex: + f.write('
  • ' + object_sitemap % (_('Global Module Index'), + 'modindex.html')) + # the TOC + tocdoc = self.env.get_and_resolve_doctree(self.config.master_doc, self, + prune_toctrees=False) + def write_toc(node, ullevel=0): + if isinstance(node, nodes.list_item): + f.write('
  • ') + for subnode in node: + write_toc(subnode, ullevel) + elif isinstance(node, nodes.reference): + link = node['refuri'] + title = cgi.escape(node.astext()).replace('"','"') + item = object_sitemap % (title, link) + f.write(item.encode('ascii', 'xmlcharrefreplace')) + elif isinstance(node, nodes.bullet_list): + if ullevel != 0: + f.write('
      \n') + for subnode in node: + write_toc(subnode, ullevel+1) + if ullevel != 0: + f.write('
    \n') + elif isinstance(node, addnodes.compact_paragraph): + for subnode in node: + write_toc(subnode, ullevel) + istoctree = lambda node: isinstance(node, addnodes.compact_paragraph) and \ + node.has_key('toctree') + for node in tocdoc.traverse(istoctree): + write_toc(node) + f.write(contents_footer) + finally: + f.close() + + self.info('writing index file...') + index = self.env.create_index(self) + f = open(path.join(outdir, outname+'.hhk'), 'w') + try: + f.write('
      \n') + def write_index(title, refs, subitems): + def write_param(name, value): + item = ' \n' % (name, value) + f.write(item.encode('ascii', 'xmlcharrefreplace')) + title = cgi.escape(title) + f.write('
    • \n') + write_param('Keyword', title) + if len(refs) == 0: + write_param('See Also', title) + elif len(refs) == 1: + write_param('Local', refs[0]) + else: + for i, ref in enumerate(refs): + write_param('Name', '[%d] %s' % (i, ref)) # XXX: better title? + write_param('Local', ref) + f.write('\n') + if subitems: + f.write('
        ') + for subitem in subitems: + write_index(subitem[0], subitem[1], []) + f.write('
      ') + for (key, group) in index: + for title, (refs, subitems) in group: + write_index(title, refs, subitems) + f.write('
    \n') + finally: + f.close() diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py new file mode 100644 index 00000000..916430db --- /dev/null +++ b/sphinx/builders/latex.py @@ -0,0 +1,185 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.latex + ~~~~~~~~~~~~~~~~~~~~~ + + LaTeX builder. + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" + +import os +import shutil +from os import path + +from docutils import nodes +from docutils.io import FileOutput +from docutils.utils import new_document +from docutils.frontend import OptionParser + +from sphinx import package_dir, addnodes +from sphinx.util import SEP, texescape +from sphinx.builders import Builder +from sphinx.environment import NoUri +from sphinx.util.console import bold, darkgreen +from sphinx.writers.latex import LaTeXWriter + + +class LaTeXBuilder(Builder): + """ + Builds LaTeX output to create PDF. + """ + name = 'latex' + supported_image_types = ['application/pdf', 'image/png', 'image/gif', + 'image/jpeg'] + + def init(self): + self.docnames = [] + self.document_data = [] + texescape.init() + + def get_outdated_docs(self): + return 'all documents' # for now + + def get_target_uri(self, docname, typ=None): + if typ == 'token': + # token references are always inside production lists and must be + # replaced by \token{} in LaTeX + return '@token' + if docname not in self.docnames: + raise NoUri + else: + return '' + + def init_document_data(self): + preliminary_document_data = map(list, self.config.latex_documents) + if not preliminary_document_data: + self.warn('No "latex_documents" config value found; no documents ' + 'will be written.') + return + # assign subdirs to titles + self.titles = [] + for entry in preliminary_document_data: + docname = entry[0] + if docname not in self.env.all_docs: + self.warn('"latex_documents" config value references unknown ' + 'document %s' % docname) + continue + self.document_data.append(entry) + if docname.endswith(SEP+'index'): + docname = docname[:-5] + self.titles.append((docname, entry[2])) + + def write(self, *ignored): + # first, assemble the "appendix" docs that are in every PDF + appendices = [] + for fname in self.config.latex_appendices: + appendices.append(self.env.get_doctree(fname)) + + docwriter = LaTeXWriter(self) + docsettings = OptionParser( + defaults=self.env.settings, + components=(docwriter,)).get_default_values() + + self.init_document_data() + + for entry in self.document_data: + docname, targetname, title, author, docclass = entry[:5] + toctree_only = False + if len(entry) > 5: + toctree_only = entry[5] + destination = FileOutput( + destination_path=path.join(self.outdir, targetname), + encoding='utf-8') + self.info("processing " + targetname + "... ", nonl=1) + doctree = self.assemble_doctree(docname, toctree_only, + appendices=(docclass == 'manual') and appendices or []) + self.post_process_images(doctree) + self.info("writing... ", nonl=1) + doctree.settings = docsettings + doctree.settings.author = author + doctree.settings.title = title + doctree.settings.docname = docname + doctree.settings.docclass = docclass + docwriter.write(doctree, destination) + self.info("done") + + def assemble_doctree(self, indexfile, toctree_only, appendices): + self.docnames = set([indexfile] + appendices) + self.info(darkgreen(indexfile) + " ", nonl=1) + def process_tree(docname, tree): + tree = tree.deepcopy() + for toctreenode in tree.traverse(addnodes.toctree): + newnodes = [] + includefiles = map(str, toctreenode['includefiles']) + for includefile in includefiles: + try: + self.info(darkgreen(includefile) + " ", nonl=1) + subtree = process_tree(includefile, + self.env.get_doctree(includefile)) + self.docnames.add(includefile) + except Exception: + self.warn('%s: toctree contains ref to nonexisting file %r' % + (docname, includefile)) + else: + sof = addnodes.start_of_file() + sof.children = subtree.children + newnodes.append(sof) + toctreenode.parent.replace(toctreenode, newnodes) + return tree + tree = self.env.get_doctree(indexfile) + if toctree_only: + # extract toctree nodes from the tree and put them in a fresh document + new_tree = new_document('') + new_sect = nodes.section() + new_sect += nodes.title(u'', u'') + new_tree += new_sect + for node in tree.traverse(addnodes.toctree): + new_sect += node + tree = new_tree + largetree = process_tree(indexfile, tree) + largetree.extend(appendices) + self.info() + self.info("resolving references...") + self.env.resolve_references(largetree, indexfile, self) + # resolve :ref:s to distant tex files -- we can't add a cross-reference, + # but append the document name + for pendingnode in largetree.traverse(addnodes.pending_xref): + docname = pendingnode['refdocname'] + sectname = pendingnode['refsectname'] + newnodes = [nodes.emphasis(sectname, sectname)] + for subdir, title in self.titles: + if docname.startswith(subdir): + newnodes.append(nodes.Text(_(' (in '), _(' (in '))) + newnodes.append(nodes.emphasis(title, title)) + newnodes.append(nodes.Text(')', ')')) + break + else: + pass + pendingnode.replace_self(newnodes) + return largetree + + def finish(self): + # copy image files + if self.images: + self.info(bold('copying images...'), nonl=1) + for src, dest in self.images.iteritems(): + self.info(' '+src, nonl=1) + shutil.copyfile(path.join(self.srcdir, src), + path.join(self.outdir, dest)) + self.info() + + # the logo is handled differently + if self.config.latex_logo: + logobase = path.basename(self.config.latex_logo) + shutil.copyfile(path.join(self.confdir, self.config.latex_logo), + path.join(self.outdir, logobase)) + + self.info(bold('copying TeX support files... '), nonl=True) + staticdirname = path.join(package_dir, 'texinputs') + for filename in os.listdir(staticdirname): + if not filename.startswith('.'): + shutil.copyfile(path.join(staticdirname, filename), + path.join(self.outdir, filename)) + self.info('done') diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py new file mode 100644 index 00000000..9dbfc913 --- /dev/null +++ b/sphinx/builders/linkcheck.py @@ -0,0 +1,130 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.linkcheck + ~~~~~~~~~~~~~~~~~~~~~~~~~ + + The CheckExternalLinksBuilder class. + + :copyright: 2008 by Georg Brandl, Thomas Lamb. + :license: BSD. +""" + +import socket +from os import path +from urllib2 import build_opener, HTTPError + +from docutils import nodes + +from sphinx.builders import Builder +from sphinx.util.console import purple, red, darkgreen + +# create an opener that will simulate a browser user-agent +opener = build_opener() +opener.addheaders = [('User-agent', 'Mozilla/5.0')] + + +class CheckExternalLinksBuilder(Builder): + """ + Checks for broken external links. + """ + name = 'linkcheck' + + def init(self): + self.good = set() + self.broken = {} + self.redirected = {} + # set a timeout for non-responding servers + socket.setdefaulttimeout(5.0) + # create output file + open(path.join(self.outdir, 'output.txt'), 'w').close() + + def get_target_uri(self, docname, typ=None): + return '' + + def get_outdated_docs(self): + return self.env.found_docs + + def prepare_writing(self, docnames): + return + + def write_doc(self, docname, doctree): + self.info() + for node in doctree.traverse(nodes.reference): + try: + self.check(node, docname) + except KeyError: + continue + + def check(self, node, docname): + uri = node['refuri'] + + if '#' in uri: + uri = uri.split('#')[0] + + if uri in self.good: + return + + lineno = None + while lineno is None and node: + node = node.parent + lineno = node.line + + if uri[0:5] == 'http:' or uri[0:6] == 'https:': + self.info(uri, nonl=1) + + if uri in self.broken: + (r, s) = self.broken[uri] + elif uri in self.redirected: + (r, s) = self.redirected[uri] + else: + (r, s) = self.resolve(uri) + + if r == 0: + self.info(' - ' + darkgreen('working')) + self.good.add(uri) + elif r == 2: + self.info(' - ' + red('broken: ') + s) + self.write_entry('broken', docname, lineno, uri + ': ' + s) + self.broken[uri] = (r, s) + if self.app.quiet: + self.warn('%s:%s: broken link: %s' % (docname, lineno, uri)) + else: + self.info(' - ' + purple('redirected') + ' to ' + s) + self.write_entry('redirected', docname, lineno, uri + ' to ' + s) + self.redirected[uri] = (r, s) + elif len(uri) == 0 or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:': + return + else: + self.warn(uri + ' - ' + red('malformed!')) + self.write_entry('malformed', docname, lineno, uri) + if self.app.quiet: + self.warn('%s:%s: malformed link: %s' % (docname, lineno, uri)) + self.app.statuscode = 1 + + if self.broken: + self.app.statuscode = 1 + + def write_entry(self, what, docname, line, uri): + output = open(path.join(self.outdir, 'output.txt'), 'a') + output.write("%s:%s: [%s] %s\n" % (self.env.doc2path(docname, None), + line, what, uri)) + output.close() + + def resolve(self, uri): + try: + f = opener.open(uri) + f.close() + except HTTPError, err: + #if err.code == 403 and uri.startswith('http://en.wikipedia.org/'): + # # Wikipedia blocks requests from urllib User-Agent + # return (0, 0) + return (2, str(err)) + except Exception, err: + return (2, str(err)) + if f.url.rstrip('/') == uri.rstrip('/'): + return (0, 0) + else: + return (1, f.url) + + def finish(self): + return diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py new file mode 100644 index 00000000..c6f232e8 --- /dev/null +++ b/sphinx/builders/text.py @@ -0,0 +1,68 @@ +# -*- coding: utf-8 -*- +""" + sphinx.builders.text + ~~~~~~~~~~~~~~~~~~~~ + + Plain-text Sphinx builder. + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" + +import codecs +from os import path + +from docutils.io import StringOutput + +from sphinx.util import ensuredir, os_path +from sphinx.builders import Builder +from sphinx.writers.text import TextWriter + + +class TextBuilder(Builder): + name = 'text' + out_suffix = '.txt' + + def init(self): + pass + + def get_outdated_docs(self): + for docname in self.env.found_docs: + if docname not in self.env.all_docs: + yield docname + continue + targetname = self.env.doc2path(docname, self.outdir, self.out_suffix) + try: + targetmtime = path.getmtime(targetname) + except Exception: + targetmtime = 0 + try: + srcmtime = path.getmtime(self.env.doc2path(docname)) + if srcmtime > targetmtime: + yield docname + except EnvironmentError: + # source doesn't exist anymore + pass + + def get_target_uri(self, docname, typ=None): + return '' + + def prepare_writing(self, docnames): + self.writer = TextWriter(self) + + def write_doc(self, docname, doctree): + destination = StringOutput(encoding='utf-8') + self.writer.write(doctree, destination) + outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix) + ensuredir(path.dirname(outfilename)) # normally different from self.outdir + try: + f = codecs.open(outfilename, 'w', 'utf-8') + try: + f.write(self.writer.output) + finally: + f.close() + except (IOError, OSError), err: + self.warn("Error writing file %s: %s" % (outfilename, err)) + + def finish(self): + pass diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py index 0c034e0d..5d9607c9 100644 --- a/sphinx/ext/intersphinx.py +++ b/sphinx/ext/intersphinx.py @@ -31,7 +31,7 @@ from os import path from docutils import nodes -from sphinx.builder import INVENTORY_FILENAME +from sphinx.builders import INVENTORY_FILENAME def fetch_inventory(app, uri, inv): diff --git a/sphinx/htmlhelp.py b/sphinx/htmlhelp.py deleted file mode 100644 index 4cc68bc9..00000000 --- a/sphinx/htmlhelp.py +++ /dev/null @@ -1,220 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.htmlhelp - ~~~~~~~~~~~~~~~ - - Build HTML help support files. - Adapted from the original Doc/tools/prechm.py. - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -import os -import cgi -from os import path - -from docutils import nodes - -from sphinx import addnodes - -# Project file (*.hhp) template. 'outname' is the file basename (like -# the pythlp in pythlp.hhp); 'version' is the doc version number (like -# the 2.2 in Python 2.2). -# The magical numbers in the long line under [WINDOWS] set most of the -# user-visible features (visible buttons, tabs, etc). -# About 0x10384e: This defines the buttons in the help viewer. The -# following defns are taken from htmlhelp.h. Not all possibilities -# actually work, and not all those that work are available from the Help -# Workshop GUI. In particular, the Zoom/Font button works and is not -# available from the GUI. The ones we're using are marked with 'x': -# -# 0x000002 Hide/Show x -# 0x000004 Back x -# 0x000008 Forward x -# 0x000010 Stop -# 0x000020 Refresh -# 0x000040 Home x -# 0x000080 Forward -# 0x000100 Back -# 0x000200 Notes -# 0x000400 Contents -# 0x000800 Locate x -# 0x001000 Options x -# 0x002000 Print x -# 0x004000 Index -# 0x008000 Search -# 0x010000 History -# 0x020000 Favorites -# 0x040000 Jump 1 -# 0x080000 Jump 2 -# 0x100000 Zoom/Font x -# 0x200000 TOC Next -# 0x400000 TOC Prev - -project_template = '''\ -[OPTIONS] -Binary TOC=Yes -Binary Index=No -Compiled file=%(outname)s.chm -Contents file=%(outname)s.hhc -Default Window=%(outname)s -Default topic=index.html -Display compile progress=No -Full text search stop list file=%(outname)s.stp -Full-text search=Yes -Index file=%(outname)s.hhk -Language=0x409 -Title=%(title)s - -[WINDOWS] -%(outname)s="%(title)s","%(outname)s.hhc","%(outname)s.hhk",\ -"index.html","index.html",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0 - -[FILES] -''' - -contents_header = '''\ - - - - - - - - - - -
      -''' - -contents_footer = '''\ -
    -''' - -object_sitemap = '''\ - - - - -''' - -# List of words the full text search facility shouldn't index. This -# becomes file outname.stp. Note that this list must be pretty small! -# Different versions of the MS docs claim the file has a maximum size of -# 256 or 512 bytes (including \r\n at the end of each line). -# Note that "and", "or", "not" and "near" are operators in the search -# language, so no point indexing them even if we wanted to. -stopwords = """ -a and are as at -be but by -for -if in into is it -near no not -of on or -such -that the their then there these they this to -was will with -""".split() - - -def build_hhx(builder, outdir, outname): - builder.info('dumping stopword list...') - f = open(path.join(outdir, outname+'.stp'), 'w') - try: - for word in sorted(stopwords): - print >>f, word - finally: - f.close() - - builder.info('writing project file...') - f = open(path.join(outdir, outname+'.hhp'), 'w') - try: - f.write(project_template % {'outname': outname, - 'title': builder.config.html_title, - 'version': builder.config.version, - 'project': builder.config.project}) - if not outdir.endswith(os.sep): - outdir += os.sep - olen = len(outdir) - for root, dirs, files in os.walk(outdir): - staticdir = (root == path.join(outdir, '_static')) - for fn in files: - if (staticdir and not fn.endswith('.js')) or fn.endswith('.html'): - print >>f, path.join(root, fn)[olen:].replace(os.sep, '\\') - finally: - f.close() - - builder.info('writing TOC file...') - f = open(path.join(outdir, outname+'.hhc'), 'w') - try: - f.write(contents_header) - # special books - f.write('
  • ' + object_sitemap % (builder.config.html_short_title, - 'index.html')) - if builder.config.html_use_modindex: - f.write('
  • ' + object_sitemap % (_('Global Module Index'), - 'modindex.html')) - # the TOC - tocdoc = builder.env.get_and_resolve_doctree(builder.config.master_doc, builder, - prune_toctrees=False) - def write_toc(node, ullevel=0): - if isinstance(node, nodes.list_item): - f.write('
  • ') - for subnode in node: - write_toc(subnode, ullevel) - elif isinstance(node, nodes.reference): - link = node['refuri'] - title = cgi.escape(node.astext()).replace('"','"') - item = object_sitemap % (title, link) - f.write(item.encode('ascii', 'xmlcharrefreplace')) - elif isinstance(node, nodes.bullet_list): - if ullevel != 0: - f.write('
      \n') - for subnode in node: - write_toc(subnode, ullevel+1) - if ullevel != 0: - f.write('
    \n') - elif isinstance(node, addnodes.compact_paragraph): - for subnode in node: - write_toc(subnode, ullevel) - istoctree = lambda node: isinstance(node, addnodes.compact_paragraph) and \ - node.has_key('toctree') - for node in tocdoc.traverse(istoctree): - write_toc(node) - f.write(contents_footer) - finally: - f.close() - - builder.info('writing index file...') - index = builder.env.create_index(builder) - f = open(path.join(outdir, outname+'.hhk'), 'w') - try: - f.write('
      \n') - def write_index(title, refs, subitems): - def write_param(name, value): - item = ' \n' % (name, value) - f.write(item.encode('ascii', 'xmlcharrefreplace')) - title = cgi.escape(title) - f.write('
    • \n') - write_param('Keyword', title) - if len(refs) == 0: - write_param('See Also', title) - elif len(refs) == 1: - write_param('Local', refs[0]) - else: - for i, ref in enumerate(refs): - write_param('Name', '[%d] %s' % (i, ref)) # XXX: better title? - write_param('Local', ref) - f.write('\n') - if subitems: - f.write('
        ') - for subitem in subitems: - write_index(subitem[0], subitem[1], []) - f.write('
      ') - for (key, group) in index: - for title, (refs, subitems) in group: - write_index(title, refs, subitems) - f.write('
    \n') - finally: - f.close() diff --git a/sphinx/htmlwriter.py b/sphinx/htmlwriter.py deleted file mode 100644 index 0505fd08..00000000 --- a/sphinx/htmlwriter.py +++ /dev/null @@ -1,457 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.htmlwriter - ~~~~~~~~~~~~~~~~~ - - docutils writers handling Sphinx' custom nodes. - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -import sys -import posixpath -import os - -from docutils import nodes -from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator - -from sphinx.locale import admonitionlabels, versionlabels -from sphinx.highlighting import PygmentsBridge -from sphinx.util.smartypants import sphinx_smarty_pants - -try: - import Image # check for the Python Imaging Library -except ImportError: - Image = None - -class HTMLWriter(Writer): - def __init__(self, builder): - Writer.__init__(self) - self.builder = builder - - def translate(self): - # sadly, this is mostly copied from parent class - self.visitor = visitor = self.builder.translator_class(self.builder, - self.document) - self.document.walkabout(visitor) - self.output = visitor.astext() - for attr in ('head_prefix', 'stylesheet', 'head', 'body_prefix', - 'body_pre_docinfo', 'docinfo', 'body', 'fragment', - 'body_suffix', 'meta', 'title', 'subtitle', 'header', - 'footer', 'html_prolog', 'html_head', 'html_title', - 'html_subtitle', 'html_body', ): - setattr(self, attr, getattr(visitor, attr, None)) - self.clean_meta = ''.join(visitor.meta[2:]) - - -class HTMLTranslator(BaseTranslator): - """ - Our custom HTML translator. - """ - - def __init__(self, builder, *args, **kwds): - BaseTranslator.__init__(self, *args, **kwds) - self.highlighter = PygmentsBridge('html', builder.config.pygments_style) - self.no_smarty = 0 - self.builder = builder - self.highlightlang = builder.config.highlight_language - self.highlightlinenothreshold = sys.maxint - self.protect_literal_text = 0 - - def visit_desc(self, node): - self.body.append(self.starttag(node, 'dl', CLASS=node['desctype'])) - def depart_desc(self, node): - self.body.append('\n\n') - - def visit_desc_signature(self, node): - # the id is set automatically - self.body.append(self.starttag(node, 'dt')) - # anchor for per-desc interactive data - if node.parent['desctype'] != 'describe' and node['ids'] and node['first']: - self.body.append('' % node['ids'][0]) - if node.parent['desctype'] in ('class', 'exception'): - self.body.append('%s ' % node.parent['desctype']) - def depart_desc_signature(self, node): - if node['ids'] and self.builder.add_definition_links: - self.body.append(u'\u00B6' % - _('Permalink to this definition')) - self.body.append('\n') - - def visit_desc_addname(self, node): - self.body.append(self.starttag(node, 'tt', '', CLASS='descclassname')) - def depart_desc_addname(self, node): - self.body.append('') - - def visit_desc_type(self, node): - pass - def depart_desc_type(self, node): - pass - - def visit_desc_name(self, node): - self.body.append(self.starttag(node, 'tt', '', CLASS='descname')) - def depart_desc_name(self, node): - self.body.append('') - - def visit_desc_parameterlist(self, node): - self.body.append('(') - self.first_param = 1 - def depart_desc_parameterlist(self, node): - self.body.append(')') - - def visit_desc_parameter(self, node): - if not self.first_param: - self.body.append(', ') - else: - self.first_param = 0 - if not node.hasattr('noemph'): - self.body.append('') - def depart_desc_parameter(self, node): - if not node.hasattr('noemph'): - self.body.append('') - - def visit_desc_optional(self, node): - self.body.append('[') - def depart_desc_optional(self, node): - self.body.append(']') - - def visit_desc_annotation(self, node): - self.body.append(self.starttag(node, 'em', CLASS='property')) - def depart_desc_annotation(self, node): - self.body.append('') - - def visit_desc_content(self, node): - self.body.append(self.starttag(node, 'dd', '')) - def depart_desc_content(self, node): - self.body.append('') - - def visit_refcount(self, node): - self.body.append(self.starttag(node, 'em', '', CLASS='refcount')) - def depart_refcount(self, node): - self.body.append('') - - def visit_versionmodified(self, node): - self.body.append(self.starttag(node, 'p')) - text = versionlabels[node['type']] % node['version'] - if len(node): - text += ': ' - else: - text += '.' - self.body.append('%s' % text) - def depart_versionmodified(self, node): - self.body.append('

    \n') - - # overwritten - def visit_reference(self, node): - BaseTranslator.visit_reference(self, node) - if node.hasattr('reftitle'): - # ugly hack to add a title attribute - starttag = self.body[-1] - if not starttag.startswith(' tag - self.section_level += 1 - self.body.append(self.starttag(node, 'div', CLASS='section')) - - def visit_title(self, node): - # don't move the id attribute inside the tag - BaseTranslator.visit_title(self, node, move_ids=0) - - # overwritten - def visit_literal_block(self, node): - if node.rawsource != node.astext(): - # most probably a parsed-literal block -- don't highlight - return BaseTranslator.visit_literal_block(self, node) - lang = self.highlightlang - linenos = node.rawsource.count('\n') >= self.highlightlinenothreshold - 1 - if node.has_key('language'): - # code-block directives - lang = node['language'] - if node.has_key('linenos'): - linenos = node['linenos'] - highlighted = self.highlighter.highlight_block(node.rawsource, lang, linenos) - starttag = self.starttag(node, 'div', suffix='', CLASS='highlight-%s' % lang) - self.body.append(starttag + highlighted + '
    • \n') - raise nodes.SkipNode - - def visit_doctest_block(self, node): - self.visit_literal_block(node) - - # overwritten - def visit_literal(self, node): - if len(node.children) == 1 and \ - node.children[0] in ('None', 'True', 'False'): - node['classes'].append('xref') - self.body.append(self.starttag(node, 'tt', '', CLASS='docutils literal')) - self.protect_literal_text += 1 - def depart_literal(self, node): - self.protect_literal_text -= 1 - self.body.append('') - - def visit_productionlist(self, node): - self.body.append(self.starttag(node, 'pre')) - names = [] - for production in node: - names.append(production['tokenname']) - maxlen = max(len(name) for name in names) - for production in node: - if production['tokenname']: - lastname = production['tokenname'].ljust(maxlen) - self.body.append(self.starttag(production, 'strong', '')) - self.body.append(lastname + ' ::= ') - else: - self.body.append('%s ' % (' '*len(lastname))) - production.walkabout(self) - self.body.append('\n') - self.body.append('\n') - raise nodes.SkipNode - def depart_productionlist(self, node): - pass - - def visit_production(self, node): - pass - def depart_production(self, node): - pass - - def visit_centered(self, node): - self.body.append(self.starttag(node, 'p', CLASS="centered") + '') - def depart_centered(self, node): - self.body.append('

    ') - - def visit_compact_paragraph(self, node): - pass - def depart_compact_paragraph(self, node): - pass - - def visit_highlightlang(self, node): - self.highlightlang = node['lang'] - self.highlightlinenothreshold = node['linenothreshold'] - def depart_highlightlang(self, node): - pass - - # overwritten - def visit_image(self, node): - olduri = node['uri'] - # rewrite the URI if the environment knows about it - if olduri in self.builder.images: - node['uri'] = posixpath.join(self.builder.imgpath, - self.builder.images[olduri]) - - if node.has_key('scale'): - if Image and not (node.has_key('width') - and node.has_key('height')): - try: - im = Image.open(os.path.join(self.builder.srcdir, - olduri)) - except (IOError, # Source image can't be found or opened - UnicodeError): # PIL doesn't like Unicode paths. - print olduri - pass - else: - if not node.has_key('width'): - node['width'] = str(im.size[0]) - if not node.has_key('height'): - node['height'] = str(im.size[1]) - del im - BaseTranslator.visit_image(self, node) - - def visit_toctree(self, node): - # this only happens when formatting a toc from env.tocs -- in this - # case we don't want to include the subtree - raise nodes.SkipNode - - def visit_index(self, node): - raise nodes.SkipNode - - def visit_tabular_col_spec(self, node): - raise nodes.SkipNode - - def visit_glossary(self, node): - pass - def depart_glossary(self, node): - pass - - def visit_acks(self, node): - pass - def depart_acks(self, node): - pass - - def visit_module(self, node): - pass - def depart_module(self, node): - pass - - def bulk_text_processor(self, text): - return text - - # overwritten - def visit_Text(self, node): - text = node.astext() - encoded = self.encode(text) - if self.protect_literal_text: - # moved here from base class's visit_literal to support - # more formatting in literal nodes - for token in self.words_and_spaces.findall(encoded): - if token.strip(): - # protect literal text from line wrapping - self.body.append('%s' % token) - elif token in ' \n': - # allow breaks at whitespace - self.body.append(token) - else: - # protect runs of multiple spaces; the last one can wrap - self.body.append(' ' * (len(token)-1) + ' ') - else: - if self.in_mailto and self.settings.cloak_email_addresses: - encoded = self.cloak_email(encoded) - else: - encoded = self.bulk_text_processor(encoded) - self.body.append(encoded) - - # these are all for docutils 0.5 compatibility - - def visit_note(self, node): - self.visit_admonition(node, 'note') - def depart_note(self, node): - self.depart_admonition(node) - - def visit_warning(self, node): - self.visit_admonition(node, 'warning') - def depart_warning(self, node): - self.depart_admonition(node) - - def visit_attention(self, node): - self.visit_admonition(node, 'attention') - - def depart_attention(self, node): - self.depart_admonition() - - def visit_caution(self, node): - self.visit_admonition(node, 'caution') - def depart_caution(self, node): - self.depart_admonition() - - def visit_danger(self, node): - self.visit_admonition(node, 'danger') - def depart_danger(self, node): - self.depart_admonition() - - def visit_error(self, node): - self.visit_admonition(node, 'error') - def depart_error(self, node): - self.depart_admonition() - - def visit_hint(self, node): - self.visit_admonition(node, 'hint') - def depart_hint(self, node): - self.depart_admonition() - - def visit_important(self, node): - self.visit_admonition(node, 'important') - def depart_important(self, node): - self.depart_admonition() - - def visit_tip(self, node): - self.visit_admonition(node, 'tip') - def depart_tip(self, node): - self.depart_admonition() - - # these are only handled specially in the SmartyPantsHTMLTranslator - def visit_literal_emphasis(self, node): - return self.visit_emphasis(node) - def depart_literal_emphasis(self, node): - return self.depart_emphasis(node) - - def depart_title(self, node): - close_tag = self.context[-1] - if self.builder.add_header_links and \ - (close_tag.startswith('\u00B6    ' % - _('Permalink to this headline')) - BaseTranslator.depart_title(self, node) - - def unknown_visit(self, node): - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) - - -class SmartyPantsHTMLTranslator(HTMLTranslator): - """ - Handle ordinary text via smartypants, converting quotes and dashes - to the correct entities. - """ - - def __init__(self, *args, **kwds): - self.no_smarty = 0 - HTMLTranslator.__init__(self, *args, **kwds) - - def visit_literal(self, node): - self.no_smarty += 1 - try: - # this raises SkipNode - HTMLTranslator.visit_literal(self, node) - finally: - self.no_smarty -= 1 - - def visit_literal_emphasis(self, node): - self.no_smarty += 1 - self.visit_emphasis(node) - - def depart_literal_emphasis(self, node): - self.depart_emphasis(node) - self.no_smarty -= 1 - - def visit_desc_signature(self, node): - self.no_smarty += 1 - HTMLTranslator.visit_desc_signature(self, node) - - def depart_desc_signature(self, node): - self.no_smarty -= 1 - HTMLTranslator.depart_desc_signature(self, node) - - def visit_productionlist(self, node): - self.no_smarty += 1 - try: - HTMLTranslator.visit_productionlist(self, node) - finally: - self.no_smarty -= 1 - - def visit_option(self, node): - self.no_smarty += 1 - HTMLTranslator.visit_option(self, node) - def depart_option(self, node): - self.no_smarty -= 1 - HTMLTranslator.depart_option(self, node) - - def bulk_text_processor(self, text): - if self.no_smarty <= 0: - return sphinx_smarty_pants(text) - return text diff --git a/sphinx/latexwriter.py b/sphinx/latexwriter.py deleted file mode 100644 index 94cb23db..00000000 --- a/sphinx/latexwriter.py +++ /dev/null @@ -1,1185 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.latexwriter - ~~~~~~~~~~~~~~~~~~ - - Custom docutils writer for LaTeX. - - Much of this code is adapted from Dave Kuhlman's "docpy" writer from his - docutils sandbox. - - :copyright: 2007-2008 by Georg Brandl, Dave Kuhlman. - :license: BSD. -""" - -import re -import sys -from os import path - -from docutils import nodes, writers -from docutils.writers.latex2e import Babel - -from sphinx import addnodes -from sphinx import highlighting -from sphinx.locale import admonitionlabels, versionlabels -from sphinx.util import ustrftime -from sphinx.util.texescape import tex_escape_map -from sphinx.util.smartypants import educateQuotesLatex - -HEADER = r'''%% Generated by Sphinx. -\documentclass[%(papersize)s,%(pointsize)s%(classoptions)s]{%(docclass)s} -%(inputenc)s -%(fontenc)s -%(babel)s -%(fontpkg)s -%(fncychap)s -\usepackage{sphinx} -%(preamble)s - -\title{%(title)s} -\date{%(date)s} -\release{%(release)s} -\author{%(author)s} -\newcommand{\sphinxlogo}{%(logo)s} -\renewcommand{\releasename}{%(releasename)s} -%(makeindex)s -%(makemodindex)s -''' - -BEGIN_DOC = r''' -\begin{document} -%(shorthandoff)s -%(maketitle)s -%(tableofcontents)s -''' - -FOOTER = r''' -%(footer)s -\renewcommand{\indexname}{%(modindexname)s} -%(printmodindex)s -\renewcommand{\indexname}{%(indexname)s} -%(printindex)s -\end{document} -''' - - -class LaTeXWriter(writers.Writer): - - supported = ('sphinxlatex',) - - settings_spec = ('LaTeX writer options', '', ( - ('Document name', ['--docname'], {'default': ''}), - ('Document class', ['--docclass'], {'default': 'manual'}), - ('Author', ['--author'], {'default': ''}), - )) - settings_defaults = {} - - output = None - - def __init__(self, builder): - writers.Writer.__init__(self) - self.builder = builder - - def translate(self): - visitor = LaTeXTranslator(self.document, self.builder) - self.document.walkabout(visitor) - self.output = visitor.astext() - - -# Helper classes - -class ExtBabel(Babel): - def get_shorthandoff(self): - shortlang = self.language.split('_')[0] - if shortlang in ('de', 'sl', 'pt', 'es', 'nl', 'pl'): - return '\\shorthandoff{"}' - return '' - - _ISO639_TO_BABEL = Babel._ISO639_TO_BABEL.copy() - _ISO639_TO_BABEL['sl'] = 'slovene' - - -class Table(object): - def __init__(self): - self.col = 0 - self.colcount = 0 - self.colspec = None - self.had_head = False - self.has_verbatim = False - self.caption = None - - -class Desc(object): - def __init__(self, node): - self.env = LaTeXTranslator.desc_map.get(node['desctype'], 'describe') - self.type = self.cls = self.name = self.params = self.annotation = '' - self.count = 0 - - -class LaTeXTranslator(nodes.NodeVisitor): - sectionnames = ["part", "chapter", "section", "subsection", - "subsubsection", "paragraph", "subparagraph"] - - ignore_missing_images = False - - default_elements = { - 'docclass': 'manual', - 'papersize': 'letterpaper', - 'pointsize': '10pt', - 'classoptions': '', - 'inputenc': '\\usepackage[utf8]{inputenc}', - 'fontenc': '\\usepackage[T1]{fontenc}', - 'babel': '\\usepackage{babel}', - 'fontpkg': '\\usepackage{times}', - 'fncychap': '\\usepackage[Bjarne]{fncychap}', - 'preamble': '', - 'title': '', - 'date': '', - 'release': '', - 'author': '', - 'logo': '', - 'releasename': 'Release', - 'makeindex': '\\makeindex', - 'makemodindex': '\\makemodindex', - 'shorthandoff': '', - 'maketitle': '\\maketitle', - 'tableofcontents': '\\tableofcontents', - 'footer': '', - 'printmodindex': '\\printmodindex', - 'printindex': '\\printindex', - } - - def __init__(self, document, builder): - nodes.NodeVisitor.__init__(self, document) - self.builder = builder - self.body = [] - - # sort out some elements - papersize = builder.config.latex_paper_size + 'paper' - if papersize == 'paper': # e.g. command line "-D latex_paper_size=" - papersize = 'letterpaper' - - self.elements = self.default_elements.copy() - self.elements.update({ - 'docclass': document.settings.docclass, - 'papersize': papersize, - 'pointsize': builder.config.latex_font_size, - # if empty, the title is set to the first section title - 'title': document.settings.title, - 'date': ustrftime(builder.config.today_fmt or _('%B %d, %Y')), - 'release': builder.config.release, - 'author': document.settings.author, - 'releasename': _('Release'), - 'preamble': builder.config.latex_preamble, - 'modindexname': _('Module Index'), - 'indexname': _('Index'), - }) - if builder.config.latex_logo: - self.elements['logo'] = '\\includegraphics{%s}\\par' % \ - path.basename(builder.config.latex_logo) - if builder.config.language: - babel = ExtBabel(builder.config.language) - lang = babel.get_language() - if lang: - self.elements['classoptions'] += ',' + babel.get_language() - else: - self.builder.warn('no Babel option known for language %r' % - builder.config.language) - self.elements['shorthandoff'] = babel.get_shorthandoff() - self.elements['fncychap'] = '\\usepackage[Sonny]{fncychap}' - else: - self.elements['classoptions'] += ',english' - if not builder.config.latex_use_modindex: - self.elements['makemodindex'] = '' - self.elements['printmodindex'] = '' - # allow the user to override them all - self.elements.update(builder.config.latex_elements) - - self.highlighter = highlighting.PygmentsBridge( - 'latex', builder.config.pygments_style) - self.context = [] - self.descstack = [] - self.bibitems = [] - self.table = None - self.next_table_colspec = None - self.highlightlang = builder.config.highlight_language - self.highlightlinenothreshold = sys.maxint - self.written_ids = set() - self.footnotestack = [] - if self.elements['docclass'] == 'manual': - if builder.config.latex_use_parts: - self.top_sectionlevel = 0 - else: - self.top_sectionlevel = 1 - else: - self.top_sectionlevel = 2 - self.next_section_target = None - # flags - self.verbatim = None - self.in_title = 0 - self.in_production_list = 0 - self.first_document = 1 - self.this_is_the_title = 1 - self.literal_whitespace = 0 - self.no_contractions = 0 - - def astext(self): - return (HEADER % self.elements + self.highlighter.get_stylesheet() + - u''.join(self.body) + FOOTER % self.elements) - - def visit_document(self, node): - self.footnotestack.append(self.collect_footnotes(node)) - if self.first_document == 1: - # the first document is all the regular content ... - self.body.append(BEGIN_DOC % self.elements) - self.first_document = 0 - elif self.first_document == 0: - # ... and all others are the appendices - self.body.append('\n\\appendix\n') - self.first_document = -1 - # "- 1" because the level is increased before the title is visited - self.sectionlevel = self.top_sectionlevel - 1 - def depart_document(self, node): - if self.bibitems: - widest_label = "" - for bi in self.bibitems: - if len(widest_label) < len(bi[0]): - widest_label = bi[0] - self.body.append('\n\\begin{thebibliography}{%s}\n' % widest_label) - for bi in self.bibitems: - # cite_key: underscores must not be escaped - cite_key = bi[0].replace(r"\_", "_") - self.body.append('\\bibitem[%s]{%s}{%s}\n' % (bi[0], cite_key, bi[1])) - self.body.append('\\end{thebibliography}\n') - self.bibitems = [] - - def visit_start_of_file(self, node): - # This marks the begin of a new file; therefore the current module and - # class must be reset - self.body.append('\n\\resetcurrentobjects\n') - # and also, new footnotes - self.footnotestack.append(self.collect_footnotes(node)) - - def collect_footnotes(self, node): - fnotes = {} - def footnotes_under(n): - if isinstance(n, nodes.footnote): - yield n - else: - for c in n.children: - if isinstance(c, addnodes.start_of_file): - continue - for k in footnotes_under(c): - yield k - for fn in footnotes_under(node): - num = fn.children[0].astext().strip() - fnotes[num] = fn - fn.parent.remove(fn) - return fnotes - - def depart_start_of_file(self, node): - self.footnotestack.pop() - - def visit_highlightlang(self, node): - self.highlightlang = node['lang'] - self.highlightlinenothreshold = node['linenothreshold'] - raise nodes.SkipNode - - def visit_section(self, node): - if not self.this_is_the_title: - self.sectionlevel += 1 - self.body.append('\n\n') - if self.next_section_target: - self.body.append(r'\hypertarget{%s}{}' % self.next_section_target) - self.next_section_target = None - #if node.get('ids'): - # for id in node['ids']: - # if id not in self.written_ids: - # self.body.append(r'\hypertarget{%s}{}' % id) - # self.written_ids.add(id) - def depart_section(self, node): - self.sectionlevel = max(self.sectionlevel - 1, self.top_sectionlevel - 1) - - def visit_problematic(self, node): - self.body.append(r'{\color{red}\bfseries{}') - def depart_problematic(self, node): - self.body.append('}') - - def visit_topic(self, node): - self.body.append('\\setbox0\\vbox{\n' - '\\begin{minipage}{0.95\\textwidth}\n') - def depart_topic(self, node): - self.body.append('\\end{minipage}}\n' - '\\begin{center}\\setlength{\\fboxsep}{5pt}' - '\\shadowbox{\\box0}\\end{center}\n') - visit_sidebar = visit_topic - depart_sidebar = depart_topic - - def visit_glossary(self, node): - pass - def depart_glossary(self, node): - pass - - def visit_productionlist(self, node): - self.body.append('\n\n\\begin{productionlist}\n') - self.in_production_list = 1 - def depart_productionlist(self, node): - self.body.append('\\end{productionlist}\n\n') - self.in_production_list = 0 - - def visit_production(self, node): - if node['tokenname']: - self.body.append('\\production{%s}{' % self.encode(node['tokenname'])) - else: - self.body.append('\\productioncont{') - def depart_production(self, node): - self.body.append('}\n') - - def visit_transition(self, node): - self.body.append('\n\n\\bigskip\\hrule{}\\bigskip\n\n') - def depart_transition(self, node): - pass - - def visit_title(self, node): - parent = node.parent - if isinstance(parent, addnodes.seealso): - # the environment already handles this - raise nodes.SkipNode - elif self.this_is_the_title: - if len(node.children) != 1 and not isinstance(node.children[0], nodes.Text): - self.builder.warn('document title is not a single Text node') - if not self.elements['title']: - # text needs to be escaped since it is inserted into - # the output literally - self.elements['title'] = node.astext().translate(tex_escape_map) - self.this_is_the_title = 0 - raise nodes.SkipNode - elif isinstance(parent, nodes.section): - try: - self.body.append(r'\%s{' % self.sectionnames[self.sectionlevel]) - except IndexError: - from sphinx.application import SphinxError - raise SphinxError('too many nesting section levels for LaTeX, ' - 'at heading: %s' % node.astext()) - self.context.append('}\n') - elif isinstance(parent, (nodes.topic, nodes.sidebar)): - self.body.append(r'\textbf{') - self.context.append('}\n\n\medskip\n\n') - elif isinstance(parent, nodes.Admonition): - self.body.append('{') - self.context.append('}\n') - elif isinstance(parent, nodes.table): - self.table.caption = self.encode(node.astext()) - raise nodes.SkipNode - else: - self.builder.warn('encountered title node not in section, topic, ' - 'table, admonition or sidebar') - self.body.append('\\textbf{') - self.context.append('}\n') - self.in_title = 1 - def depart_title(self, node): - self.in_title = 0 - self.body.append(self.context.pop()) - - def visit_subtitle(self, node): - if isinstance(node.parent, nodes.sidebar): - self.body.append('~\\\\\n\\textbf{') - self.context.append('}\n\\smallskip\n') - else: - self.context.append('') - def depart_subtitle(self, node): - self.body.append(self.context.pop()) - - desc_map = { - 'function' : 'funcdesc', - 'class': 'classdesc', - 'method': 'methoddesc', - 'staticmethod': 'staticmethoddesc', - 'exception': 'excdesc', - 'data': 'datadesc', - 'attribute': 'memberdesc', - 'opcode': 'opcodedesc', - - 'cfunction': 'cfuncdesc', - 'cmember': 'cmemberdesc', - 'cmacro': 'csimplemacrodesc', - 'ctype': 'ctypedesc', - 'cvar': 'cvardesc', - - 'describe': 'describe', - # and all others are 'describe' too - } - - def visit_desc(self, node): - self.descstack.append(Desc(node)) - def depart_desc(self, node): - d = self.descstack.pop() - self.body.append("\\end{%s}\n" % d.env) - - def visit_desc_signature(self, node): - d = self.descstack[-1] - # reset these for every signature - d.type = d.cls = d.name = d.params = '' - def depart_desc_signature(self, node): - d = self.descstack[-1] - d.cls = d.cls.rstrip('.') - if node.parent['desctype'] != 'describe' and node['ids']: - hyper = '\\hypertarget{%s}{}' % node['ids'][0] - else: - hyper = '' - if d.count == 0: - t1 = "\n\n%s\\begin{%s}" % (hyper, d.env) - else: - t1 = "\n%s\\%sline" % (hyper, d.env[:-4]) - d.count += 1 - if d.env in ('funcdesc', 'classdesc', 'excclassdesc'): - t2 = "{%s}{%s}" % (d.name, d.params) - elif d.env in ('datadesc', 'excdesc', 'csimplemacrodesc'): - t2 = "{%s}" % (d.name) - elif d.env in ('methoddesc', 'staticmethoddesc'): - if d.cls: - t2 = "[%s]{%s}{%s}" % (d.cls, d.name, d.params) - else: - t2 = "{%s}{%s}" % (d.name, d.params) - elif d.env == 'memberdesc': - if d.cls: - t2 = "[%s]{%s}" % (d.cls, d.name) - else: - t2 = "{%s}" % d.name - elif d.env == 'cfuncdesc': - if d.cls: - # C++ class names - d.name = '%s::%s' % (d.cls, d.name) - t2 = "{%s}{%s}{%s}" % (d.type, d.name, d.params) - elif d.env == 'cmemberdesc': - try: - type, container = d.type.rsplit(' ', 1) - container = container.rstrip('.') - except ValueError: - container = '' - type = d.type - t2 = "{%s}{%s}{%s}" % (container, type, d.name) - elif d.env == 'cvardesc': - t2 = "{%s}{%s}" % (d.type, d.name) - elif d.env == 'ctypedesc': - t2 = "{%s}" % (d.name) - elif d.env == 'opcodedesc': - t2 = "{%s}{%s}" % (d.name, d.params) - elif d.env == 'describe': - t2 = "{%s}" % d.name - self.body.append(t1 + t2) - - def visit_desc_type(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].type = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_desc_name(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].name = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_desc_addname(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].cls = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_desc_parameterlist(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].params = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_desc_annotation(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].annotation = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_refcount(self, node): - self.body.append("\\emph{") - def depart_refcount(self, node): - self.body.append("}\\\\") - - def visit_desc_content(self, node): - if node.children and not isinstance(node.children[0], nodes.paragraph): - # avoid empty desc environment which causes a formatting bug - self.body.append('~') - def depart_desc_content(self, node): - pass - - def visit_seealso(self, node): - self.body.append("\n\n\\strong{%s:}\n\n" % admonitionlabels['seealso']) - def depart_seealso(self, node): - self.body.append("\n\n") - - def visit_rubric(self, node): - if len(node.children) == 1 and node.children[0].astext() == 'Footnotes': - raise nodes.SkipNode - self.body.append('\\paragraph{') - self.context.append('}\n') - def depart_rubric(self, node): - self.body.append(self.context.pop()) - - def visit_footnote(self, node): - pass - def depart_footnote(self, node): - pass - - def visit_label(self, node): - if isinstance(node.parent, nodes.citation): - self.bibitems[-1][0] = node.astext() - raise nodes.SkipNode - - def visit_tabular_col_spec(self, node): - self.next_table_colspec = node['spec'] - raise nodes.SkipNode - - def visit_table(self, node): - if self.table: - raise NotImplementedError('Nested tables are not supported.') - self.table = Table() - self.tablebody = [] - # Redirect body output until table is finished. - self._body = self.body - self.body = self.tablebody - def depart_table(self, node): - self.body = self._body - if self.table.caption is not None: - self.body.append('\n\\begin{threeparttable}\n' - '\\caption{%s}\n' % self.table.caption) - if self.table.has_verbatim: - self.body.append('\n\\begin{tabular}') - else: - self.body.append('\n\\begin{tabulary}{\\textwidth}') - if self.table.colspec: - self.body.append(self.table.colspec) - else: - if self.table.has_verbatim: - colwidth = 0.95 / self.table.colcount - colspec = ('p{%.3f\\textwidth}|' % colwidth) * self.table.colcount - self.body.append('{|' + colspec + '}\n') - else: - self.body.append('{|' + ('L|' * self.table.colcount) + '}\n') - self.body.extend(self.tablebody) - if self.table.has_verbatim: - self.body.append('\\end{tabular}\n\n') - else: - self.body.append('\\end{tabulary}\n\n') - if self.table.caption is not None: - self.body.append('\\end{threeparttable}\n\n') - self.table = None - self.tablebody = None - - def visit_colspec(self, node): - self.table.colcount += 1 - def depart_colspec(self, node): - pass - - def visit_tgroup(self, node): - pass - def depart_tgroup(self, node): - pass - - def visit_thead(self, node): - if self.next_table_colspec: - self.table.colspec = '{%s}\n' % self.next_table_colspec - self.next_table_colspec = None - self.body.append('\\hline\n') - self.table.had_head = True - def depart_thead(self, node): - self.body.append('\\hline\n') - - def visit_tbody(self, node): - if not self.table.had_head: - self.visit_thead(node) - def depart_tbody(self, node): - self.body.append('\\hline\n') - - def visit_row(self, node): - self.table.col = 0 - def depart_row(self, node): - self.body.append('\\\\\n') - - def visit_entry(self, node): - if node.has_key('morerows') or node.has_key('morecols'): - raise NotImplementedError('Column or row spanning cells are ' - 'not implemented.') - if self.table.col > 0: - self.body.append(' & ') - self.table.col += 1 - if isinstance(node.parent.parent, nodes.thead): - self.body.append('\\textbf{') - self.context.append('}') - else: - self.context.append('') - def depart_entry(self, node): - self.body.append(self.context.pop()) # header - - def visit_acks(self, node): - # this is a list in the source, but should be rendered as a - # comma-separated list here - self.body.append('\n\n') - self.body.append(', '.join(n.astext() for n in node.children[0].children) + '.') - self.body.append('\n\n') - raise nodes.SkipNode - - def visit_bullet_list(self, node): - self.body.append('\\begin{itemize}\n' ) - def depart_bullet_list(self, node): - self.body.append('\\end{itemize}\n' ) - - def visit_enumerated_list(self, node): - self.body.append('\\begin{enumerate}\n' ) - def depart_enumerated_list(self, node): - self.body.append('\\end{enumerate}\n' ) - - def visit_list_item(self, node): - # Append "{}" in case the next character is "[", which would break - # LaTeX's list environment (no numbering and the "[" is not printed). - self.body.append(r'\item {} ') - def depart_list_item(self, node): - self.body.append('\n') - - def visit_definition_list(self, node): - self.body.append('\\begin{description}\n') - def depart_definition_list(self, node): - self.body.append('\\end{description}\n') - - def visit_definition_list_item(self, node): - pass - def depart_definition_list_item(self, node): - pass - - def visit_term(self, node): - ctx = ']' - if node.has_key('ids') and node['ids']: - ctx += '\\hypertarget{%s}{}' % node['ids'][0] - self.body.append('\\item[') - self.context.append(ctx) - def depart_term(self, node): - self.body.append(self.context.pop()) - - def visit_classifier(self, node): - self.body.append('{[}') - def depart_classifier(self, node): - self.body.append('{]}') - - def visit_definition(self, node): - pass - def depart_definition(self, node): - self.body.append('\n') - - def visit_field_list(self, node): - self.body.append('\\begin{quote}\\begin{description}\n') - def depart_field_list(self, node): - self.body.append('\\end{description}\\end{quote}\n') - - def visit_field(self, node): - pass - def depart_field(self, node): - pass - - visit_field_name = visit_term - depart_field_name = depart_term - - visit_field_body = visit_definition - depart_field_body = depart_definition - - def visit_paragraph(self, node): - self.body.append('\n') - def depart_paragraph(self, node): - self.body.append('\n') - - def visit_centered(self, node): - self.body.append('\n\\begin{centering}') - def depart_centered(self, node): - self.body.append('\n\\end{centering}') - - def visit_module(self, node): - modname = node['modname'] - self.body.append('\n\\declaremodule[%s]{}{%s}' % (modname.replace('_', ''), - self.encode(modname))) - self.body.append('\n\\modulesynopsis{%s}' % self.encode(node['synopsis'])) - if node.has_key('platform'): - self.body.append('\\platform{%s}' % self.encode(node['platform'])) - def depart_module(self, node): - pass - - def latex_image_length(self, width_str): - match = re.match('(\d*\.?\d*)\s*(\S*)', width_str) - if not match: - # fallback - return width_str - res = width_str - amount, unit = match.groups()[:2] - if not unit or unit == "px": - # pixels: let LaTeX alone - return None - elif unit == "%": - res = "%.3f\\linewidth" % (float(amount) / 100.0) - return res - - def visit_image(self, node): - attrs = node.attributes - pre = [] # in reverse order - post = [] - include_graphics_options = [] - inline = isinstance(node.parent, nodes.TextElement) - if attrs.has_key('scale'): - # Could also be done with ``scale`` option to - # ``\includegraphics``; doing it this way for consistency. - pre.append('\\scalebox{%f}{' % (attrs['scale'] / 100.0,)) - post.append('}') - if attrs.has_key('width'): - w = self.latex_image_length(attrs['width']) - if w: - include_graphics_options.append('width=%s' % w) - if attrs.has_key('height'): - h = self.latex_image_length(attrs['height']) - include_graphics_options.append('height=%s' % h) - if attrs.has_key('align'): - align_prepost = { - # By default latex aligns the top of an image. - (1, 'top'): ('', ''), - (1, 'middle'): ('\\raisebox{-0.5\\height}{', '}'), - (1, 'bottom'): ('\\raisebox{-\\height}{', '}'), - (0, 'center'): ('{\\hfill', '\\hfill}'), - # These 2 don't exactly do the right thing. The image should - # be floated alongside the paragraph. See - # http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG - (0, 'left'): ('{', '\\hfill}'), - (0, 'right'): ('{\\hfill', '}'),} - try: - pre.append(align_prepost[inline, attrs['align']][0]) - post.append(align_prepost[inline, attrs['align']][1]) - except KeyError: - pass # XXX complain here? - if not inline: - pre.append('\n') - post.append('\n') - pre.reverse() - if node['uri'] in self.builder.images: - uri = self.builder.images[node['uri']] - else: - # missing image! - if self.ignore_missing_images: - return - uri = node['uri'] - if uri.find('://') != -1: - # ignore remote images - return - self.body.extend(pre) - options = '' - if include_graphics_options: - options = '[%s]' % ','.join(include_graphics_options) - self.body.append('\\includegraphics%s{%s}' % (options, uri)) - self.body.extend(post) - def depart_image(self, node): - pass - - def visit_figure(self, node): - if (not node.attributes.has_key('align') or - node.attributes['align'] == 'center'): - # centering does not add vertical space like center. - align = '\n\\centering' - align_end = '' - else: - # TODO non vertical space for other alignments. - align = '\\begin{flush%s}' % node.attributes['align'] - align_end = '\\end{flush%s}' % node.attributes['align'] - self.body.append('\\begin{figure}[htbp]%s\n' % align) - self.context.append('%s\\end{figure}\n' % align_end) - def depart_figure(self, node): - self.body.append(self.context.pop()) - - def visit_caption(self, node): - self.body.append('\\caption{') - def depart_caption(self, node): - self.body.append('}') - - def visit_legend(self, node): - self.body.append('{\\small ') - def depart_legend(self, node): - self.body.append('}') - - def visit_admonition(self, node): - self.body.append('\n\\begin{notice}{note}') - def depart_admonition(self, node): - self.body.append('\\end{notice}\n') - - def _make_visit_admonition(name): - def visit_admonition(self, node): - self.body.append('\n\\begin{notice}{%s}{%s:}' % - (name, admonitionlabels[name])) - return visit_admonition - def _depart_named_admonition(self, node): - self.body.append('\\end{notice}\n') - - visit_attention = _make_visit_admonition('attention') - depart_attention = _depart_named_admonition - visit_caution = _make_visit_admonition('caution') - depart_caution = _depart_named_admonition - visit_danger = _make_visit_admonition('danger') - depart_danger = _depart_named_admonition - visit_error = _make_visit_admonition('error') - depart_error = _depart_named_admonition - visit_hint = _make_visit_admonition('hint') - depart_hint = _depart_named_admonition - visit_important = _make_visit_admonition('important') - depart_important = _depart_named_admonition - visit_note = _make_visit_admonition('note') - depart_note = _depart_named_admonition - visit_tip = _make_visit_admonition('tip') - depart_tip = _depart_named_admonition - visit_warning = _make_visit_admonition('warning') - depart_warning = _depart_named_admonition - - def visit_versionmodified(self, node): - intro = versionlabels[node['type']] % node['version'] - if node.children: - intro += ': ' - else: - intro += '.' - self.body.append(intro) - def depart_versionmodified(self, node): - pass - - def visit_target(self, node): - def add_target(id): - # indexing uses standard LaTeX index markup, so the targets - # will be generated differently - if not id.startswith('index-'): - self.body.append(r'\hypertarget{%s}{}' % id) - - if node.has_key('refid') and node['refid'] not in self.written_ids: - parindex = node.parent.index(node) - try: - next = node.parent[parindex+1] - if isinstance(next, nodes.section): - self.next_section_target = node['refid'] - return - except IndexError: - pass - add_target(node['refid']) - self.written_ids.add(node['refid']) - def depart_target(self, node): - pass - - def visit_attribution(self, node): - self.body.append('\n\\begin{flushright}\n') - self.body.append('---') - def depart_attribution(self, node): - self.body.append('\n\\end{flushright}\n') - - def visit_index(self, node, scre=re.compile(r';\s*')): - entries = node['entries'] - for type, string, tid, _ in entries: - if type == 'single': - self.body.append(r'\index{%s}' % scre.sub('!', self.encode(string))) - elif type == 'pair': - parts = tuple(self.encode(x.strip()) for x in string.split(';', 1)) - self.body.append(r'\indexii{%s}{%s}' % parts) - elif type == 'triple': - parts = tuple(self.encode(x.strip()) for x in string.split(';', 2)) - self.body.append(r'\indexiii{%s}{%s}{%s}' % parts) - else: - self.builder.warn('unknown index entry type %s found' % type) - raise nodes.SkipNode - - def visit_raw(self, node): - if 'latex' in node.get('format', '').split(): - self.body.append(node.astext()) - raise nodes.SkipNode - - def visit_reference(self, node): - uri = node.get('refuri', '') - if self.in_title or not uri: - self.context.append('') - elif uri.startswith('mailto:') or uri.startswith('http:') or \ - uri.startswith('https:') or uri.startswith('ftp:'): - self.body.append('\\href{%s}{' % self.encode(uri)) - self.context.append('}') - elif uri.startswith('#'): - self.body.append('\\hyperlink{%s}{' % uri[1:]) - self.context.append('}') - elif uri.startswith('@token'): - if self.in_production_list: - self.body.append('\\token{') - else: - self.body.append('\\grammartoken{') - self.context.append('}') - else: - self.builder.warn('unusable reference target found: %s' % uri) - self.context.append('') - def depart_reference(self, node): - self.body.append(self.context.pop()) - - def visit_pending_xref(self, node): - pass - def depart_pending_xref(self, node): - pass - - def visit_emphasis(self, node): - self.body.append(r'\emph{') - def depart_emphasis(self, node): - self.body.append('}') - - def visit_literal_emphasis(self, node): - self.body.append(r'\emph{\texttt{') - self.no_contractions += 1 - def depart_literal_emphasis(self, node): - self.body.append('}}') - self.no_contractions -= 1 - - def visit_strong(self, node): - self.body.append(r'\textbf{') - def depart_strong(self, node): - self.body.append('}') - - def visit_title_reference(self, node): - self.body.append(r'\emph{') - def depart_title_reference(self, node): - self.body.append('}') - - def visit_citation(self, node): - # TODO maybe use cite bibitems - self.bibitems.append(['', '']) - self.context.append(len(self.body)) - def depart_citation(self, node): - size = self.context.pop() - text = ''.join(self.body[size:]) - del self.body[size:] - self.bibitems[-1][1] = text - - def visit_citation_reference(self, node): - citeid = node.astext() - self.body.append('\\cite{%s}' % citeid) - raise nodes.SkipNode - - def visit_literal(self, node): - content = self.encode(node.astext().strip()) - if self.in_title: - self.body.append(r'\texttt{%s}' % content) - elif node.has_key('role') and node['role'] == 'samp': - self.body.append(r'\samp{%s}' % content) - else: - self.body.append(r'\code{%s}' % content) - raise nodes.SkipNode - - def visit_footnote_reference(self, node): - num = node.astext().strip() - try: - fn = self.footnotestack[-1][num] - except (KeyError, IndexError): - raise nodes.SkipNode - self.body.append('\\footnote{') - fn.walkabout(self) - raise nodes.SkipChildren - def depart_footnote_reference(self, node): - self.body.append('}') - - def visit_literal_block(self, node): - self.verbatim = '' - def depart_literal_block(self, node): - code = self.verbatim.rstrip('\n') - lang = self.highlightlang - linenos = code.count('\n') >= self.highlightlinenothreshold - 1 - if node.has_key('language'): - # code-block directives - lang = node['language'] - if node.has_key('linenos'): - linenos = node['linenos'] - hlcode = self.highlighter.highlight_block(code, lang, linenos) - # workaround for Unicode issue - hlcode = hlcode.replace(u'€', u'@texteuro[]') - # must use original Verbatim environment and "tabular" environment - if self.table: - hlcode = hlcode.replace('\\begin{Verbatim}', - '\\begin{OriginalVerbatim}') - self.table.has_verbatim = True - # get consistent trailer - hlcode = hlcode.rstrip()[:-14] # strip \end{Verbatim} - hlcode = hlcode.rstrip() + '\n' - self.body.append('\n' + hlcode + '\\end{%sVerbatim}\n' % - (self.table and 'Original' or '')) - self.verbatim = None - visit_doctest_block = visit_literal_block - depart_doctest_block = depart_literal_block - - def visit_line_block(self, node): - """line-block: - * whitespace (including linebreaks) is significant - * inline markup is supported. - * serif typeface - """ - self.body.append('{\\raggedright{}') - self.literal_whitespace = 1 - def depart_line_block(self, node): - self.literal_whitespace = 0 - # remove the last \\ - del self.body[-1] - self.body.append('}\n') - - def visit_line(self, node): - self._line_start = len(self.body) - def depart_line(self, node): - if self._line_start == len(self.body): - # no output in this line -- add a nonbreaking space, else the - # \\ command will give an error - self.body.append('~') - if self.table is not None: - self.body.append('\\newline\n') - else: - self.body.append('\\\\\n') - - def visit_block_quote(self, node): - # If the block quote contains a single object and that object - # is a list, then generate a list not a block quote. - # This lets us indent lists. - done = 0 - if len(node.children) == 1: - child = node.children[0] - if isinstance(child, nodes.bullet_list) or \ - isinstance(child, nodes.enumerated_list): - done = 1 - if not done: - self.body.append('\\begin{quote}\n') - def depart_block_quote(self, node): - done = 0 - if len(node.children) == 1: - child = node.children[0] - if isinstance(child, nodes.bullet_list) or \ - isinstance(child, nodes.enumerated_list): - done = 1 - if not done: - self.body.append('\\end{quote}\n') - - # option node handling copied from docutils' latex writer - - def visit_option(self, node): - if self.context[-1]: - # this is not the first option - self.body.append(', ') - def depart_option(self, node): - # flag that the first option is done. - self.context[-1] += 1 - - def visit_option_argument(self, node): - """The delimiter betweeen an option and its argument.""" - self.body.append(node.get('delimiter', ' ')) - def depart_option_argument(self, node): - pass - - def visit_option_group(self, node): - self.body.append('\\item [') - # flag for first option - self.context.append(0) - def depart_option_group(self, node): - self.context.pop() # the flag - self.body.append('] ') - - def visit_option_list(self, node): - self.body.append('\\begin{optionlist}{3cm}\n') - def depart_option_list(self, node): - self.body.append('\\end{optionlist}\n') - - def visit_option_list_item(self, node): - pass - def depart_option_list_item(self, node): - pass - - def visit_option_string(self, node): - ostring = node.astext() - self.body.append(self.encode(ostring.replace('--', u'-{-}'))) - raise nodes.SkipNode - - def visit_description(self, node): - self.body.append( ' ' ) - def depart_description(self, node): - pass - - def visit_superscript(self, node): - self.body.append('$^{\\text{') - def depart_superscript(self, node): - self.body.append('}}$') - - def visit_subscript(self, node): - self.body.append('$_{\\text{') - def depart_subscript(self, node): - self.body.append('}}$') - - def visit_substitution_definition(self, node): - raise nodes.SkipNode - - def visit_substitution_reference(self, node): - raise nodes.SkipNode - - def visit_generated(self, node): - pass - def depart_generated(self, node): - pass - - def visit_compound(self, node): - pass - def depart_compound(self, node): - pass - - def visit_container(self, node): - pass - def depart_container(self, node): - pass - - def visit_decoration(self, node): - pass - def depart_decoration(self, node): - pass - - # text handling - - def encode(self, text): - text = unicode(text).translate(tex_escape_map) - if self.literal_whitespace: - # Insert a blank before the newline, to avoid - # ! LaTeX Error: There's no line here to end. - text = text.replace(u'\n', u'~\\\\\n').replace(u' ', u'~') - if self.no_contractions: - text = text.replace('--', u'-{-}') - return text - - def visit_Text(self, node): - if self.verbatim is not None: - self.verbatim += node.astext() - else: - text = self.encode(node.astext()) - self.body.append(educateQuotesLatex(text)) - def depart_Text(self, node): - pass - - def visit_comment(self, node): - raise nodes.SkipNode - - def visit_meta(self, node): - # only valid for HTML - raise nodes.SkipNode - - def visit_system_message(self, node): - pass - def depart_system_message(self, node): - self.body.append('\n') - - def unknown_visit(self, node): - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/linkcheck.py b/sphinx/linkcheck.py deleted file mode 100644 index 37aeb7a7..00000000 --- a/sphinx/linkcheck.py +++ /dev/null @@ -1,130 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.linkcheck - ~~~~~~~~~~~~~~~~ - - The CheckExternalLinksBuilder class. - - :copyright: 2008 by Georg Brandl, Thomas Lamb. - :license: BSD. -""" - -import socket -from os import path -from urllib2 import build_opener, HTTPError - -from docutils import nodes - -from sphinx.builder import Builder -from sphinx.util.console import purple, red, darkgreen - -# create an opener that will simulate a browser user-agent -opener = build_opener() -opener.addheaders = [('User-agent', 'Mozilla/5.0')] - - -class CheckExternalLinksBuilder(Builder): - """ - Checks for broken external links. - """ - name = 'linkcheck' - - def init(self): - self.good = set() - self.broken = {} - self.redirected = {} - # set a timeout for non-responding servers - socket.setdefaulttimeout(5.0) - # create output file - open(path.join(self.outdir, 'output.txt'), 'w').close() - - def get_target_uri(self, docname, typ=None): - return '' - - def get_outdated_docs(self): - return self.env.found_docs - - def prepare_writing(self, docnames): - return - - def write_doc(self, docname, doctree): - self.info() - for node in doctree.traverse(nodes.reference): - try: - self.check(node, docname) - except KeyError: - continue - - def check(self, node, docname): - uri = node['refuri'] - - if '#' in uri: - uri = uri.split('#')[0] - - if uri in self.good: - return - - lineno = None - while lineno is None and node: - node = node.parent - lineno = node.line - - if uri[0:5] == 'http:' or uri[0:6] == 'https:': - self.info(uri, nonl=1) - - if uri in self.broken: - (r, s) = self.broken[uri] - elif uri in self.redirected: - (r, s) = self.redirected[uri] - else: - (r, s) = self.resolve(uri) - - if r == 0: - self.info(' - ' + darkgreen('working')) - self.good.add(uri) - elif r == 2: - self.info(' - ' + red('broken: ') + s) - self.write_entry('broken', docname, lineno, uri + ': ' + s) - self.broken[uri] = (r, s) - if self.app.quiet: - self.warn('%s:%s: broken link: %s' % (docname, lineno, uri)) - else: - self.info(' - ' + purple('redirected') + ' to ' + s) - self.write_entry('redirected', docname, lineno, uri + ' to ' + s) - self.redirected[uri] = (r, s) - elif len(uri) == 0 or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:': - return - else: - self.warn(uri + ' - ' + red('malformed!')) - self.write_entry('malformed', docname, lineno, uri) - if self.app.quiet: - self.warn('%s:%s: malformed link: %s' % (docname, lineno, uri)) - self.app.statuscode = 1 - - if self.broken: - self.app.statuscode = 1 - - def write_entry(self, what, docname, line, uri): - output = open(path.join(self.outdir, 'output.txt'), 'a') - output.write("%s:%s: [%s] %s\n" % (self.env.doc2path(docname, None), - line, what, uri)) - output.close() - - def resolve(self, uri): - try: - f = opener.open(uri) - f.close() - except HTTPError, err: - #if err.code == 403 and uri.startswith('http://en.wikipedia.org/'): - # # Wikipedia blocks requests from urllib User-Agent - # return (0, 0) - return (2, str(err)) - except Exception, err: - return (2, str(err)) - if f.url.rstrip('/') == uri.rstrip('/'): - return (0, 0) - else: - return (1, f.url) - - def finish(self): - return diff --git a/sphinx/textwriter.py b/sphinx/textwriter.py deleted file mode 100644 index 4aa18039..00000000 --- a/sphinx/textwriter.py +++ /dev/null @@ -1,679 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.textwriter - ~~~~~~~~~~~~~~~~~ - - Custom docutils writer for plain text. - - :copyright: 2008 by Georg Brandl. - :license: BSD. -""" - -import re -import textwrap - -from docutils import nodes, writers - -from sphinx import addnodes -from sphinx.locale import admonitionlabels, versionlabels - - -class TextWriter(writers.Writer): - supported = ('text',) - settings_spec = ('No options here.', '', ()) - settings_defaults = {} - - output = None - - def __init__(self, builder): - writers.Writer.__init__(self) - self.builder = builder - - def translate(self): - visitor = TextTranslator(self.document, self.builder) - self.document.walkabout(visitor) - self.output = visitor.body - -# monkey-patch... -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 -textwrap.TextWrapper.wordsep_re = new_wordsep_re - -MAXWIDTH = 70 -STDINDENT = 3 - - -class TextTranslator(nodes.NodeVisitor): - sectionchars = '*=-~"+' - - def __init__(self, document, builder): - nodes.NodeVisitor.__init__(self, document) - - self.states = [[]] - self.stateindent = [0] - self.sectionlevel = 0 - self.table = None - - def add_text(self, text): - self.states[-1].append((-1, text)) - def new_state(self, indent=STDINDENT): - self.states.append([]) - self.stateindent.append(indent) - def end_state(self, wrap=True, end=[''], first=None): - content = self.states.pop() - maxindent = sum(self.stateindent) - indent = self.stateindent.pop() - result = [] - toformat = [] - def do_format(): - if not toformat: - return - if wrap: - res = textwrap.wrap(''.join(toformat), width=MAXWIDTH-maxindent) - else: - res = ''.join(toformat).splitlines() - if end: - res += end - result.append((indent, res)) - for itemindent, item in content: - if itemindent == -1: - toformat.append(item) - else: - do_format() - result.append((indent + itemindent, item)) - toformat = [] - do_format() - if first is not None and result: - itemindent, item = result[0] - if item: - result.insert(0, (itemindent - indent, [first + item[0]])) - result[1] = (itemindent, item[1:]) - self.states[-1].extend(result) - - def visit_document(self, node): - self.new_state(0) - def depart_document(self, node): - self.end_state() - self.body = '\n'.join(line and (' '*indent + line) - for indent, lines in self.states[0] - for line in lines) - # XXX header/footer? - - def visit_highlightlang(self, node): - raise nodes.SkipNode - - def visit_section(self, node): - self._title_char = self.sectionchars[self.sectionlevel] - self.sectionlevel += 1 - def depart_section(self, node): - self.sectionlevel -= 1 - - def visit_topic(self, node): - self.new_state(0) - def depart_topic(self, node): - self.end_state() - - visit_sidebar = visit_topic - depart_sidebar = depart_topic - - def visit_rubric(self, node): - self.new_state(0) - self.add_text('-[ ') - def depart_rubric(self, node): - self.add_text(' ]-') - self.end_state() - - def visit_compound(self, node): - pass - def depart_compound(self, node): - pass - - def visit_glossary(self, node): - pass - def depart_glossary(self, node): - pass - - def visit_title(self, node): - if isinstance(node.parent, nodes.Admonition): - self.add_text(node.astext()+': ') - raise nodes.SkipNode - self.new_state(0) - def depart_title(self, node): - if isinstance(node.parent, nodes.section): - char = self._title_char - else: - char = '^' - text = ''.join(x[1] for x in self.states.pop() if x[0] == -1) - self.stateindent.pop() - self.states[-1].append((0, ['', text, '%s' % (char * len(text)), ''])) - - def visit_subtitle(self, node): - pass - def depart_subtitle(self, node): - pass - - def visit_attribution(self, node): - self.add_text('-- ') - def depart_attribution(self, node): - pass - - def visit_module(self, node): - if node.has_key('platform'): - self.new_state(0) - self.add_text(_('Platform: %s') % node['platform']) - self.end_state() - raise nodes.SkipNode - - def visit_desc(self, node): - pass - def depart_desc(self, node): - pass - - def visit_desc_signature(self, node): - self.new_state(0) - if node.parent['desctype'] in ('class', 'exception'): - self.add_text('%s ' % node.parent['desctype']) - def depart_desc_signature(self, node): - # XXX: wrap signatures in a way that makes sense - self.end_state(wrap=False, end=None) - - def visit_desc_name(self, node): - pass - def depart_desc_name(self, node): - pass - - def visit_desc_addname(self, node): - pass - def depart_desc_addname(self, node): - pass - - def visit_desc_type(self, node): - pass - def depart_desc_type(self, node): - pass - - def visit_desc_parameterlist(self, node): - self.add_text('(') - self.first_param = 1 - def depart_desc_parameterlist(self, node): - self.add_text(')') - - def visit_desc_parameter(self, node): - if not self.first_param: - self.add_text(', ') - else: - self.first_param = 0 - self.add_text(node.astext()) - raise nodes.SkipNode - - def visit_desc_optional(self, node): - self.add_text('[') - def depart_desc_optional(self, node): - self.add_text(']') - - def visit_desc_annotation(self, node): - pass - def depart_desc_annotation(self, node): - pass - - def visit_refcount(self, node): - pass - def depart_refcount(self, node): - pass - - def visit_desc_content(self, node): - self.new_state() - self.add_text('\n') - def depart_desc_content(self, node): - self.end_state() - - def visit_figure(self, node): - self.new_state() - def depart_figure(self, node): - self.end_state() - - def visit_caption(self, node): - pass - def depart_caption(self, node): - pass - - def visit_productionlist(self, node): - self.new_state() - names = [] - for production in node: - names.append(production['tokenname']) - maxlen = max(len(name) for name in names) - for production in node: - if production['tokenname']: - self.add_text(production['tokenname'].ljust(maxlen) + ' ::=') - lastname = production['tokenname'] - else: - self.add_text('%s ' % (' '*len(lastname))) - self.add_text(production.astext() + '\n') - self.end_state(wrap=False) - raise nodes.SkipNode - - def visit_seealso(self, node): - self.new_state() - def depart_seealso(self, node): - self.end_state(first='') - - def visit_footnote(self, node): - self._footnote = node.children[0].astext().strip() - self.new_state(len(self._footnote) + 3) - def depart_footnote(self, node): - self.end_state(first='[%s] ' % self._footnote) - - def visit_citation(self, node): - if len(node) and isinstance(node[0], nodes.label): - self._citlabel = node[0].astext() - else: - self._citlabel = '' - self.new_state(len(self._citlabel) + 3) - def depart_citation(self, node): - self.end_state(first='[%s] ' % self._citlabel) - - def visit_label(self, node): - raise nodes.SkipNode - - # XXX: option list could use some better styling - - def visit_option_list(self, node): - pass - def depart_option_list(self, node): - pass - - def visit_option_list_item(self, node): - self.new_state(0) - def depart_option_list_item(self, node): - self.end_state() - - def visit_option_group(self, node): - self._firstoption = True - def depart_option_group(self, node): - self.add_text(' ') - - def visit_option(self, node): - if self._firstoption: - self._firstoption = False - else: - self.add_text(', ') - def depart_option(self, node): - pass - - def visit_option_string(self, node): - pass - def depart_option_string(self, node): - pass - - def visit_option_argument(self, node): - self.add_text(node['delimiter']) - def depart_option_argument(self, node): - pass - - def visit_description(self, node): - pass - def depart_description(self, node): - pass - - def visit_tabular_col_spec(self, node): - raise nodes.SkipNode - - def visit_colspec(self, node): - self.table[0].append(node['colwidth']) - raise nodes.SkipNode - - def visit_tgroup(self, node): - pass - def depart_tgroup(self, node): - pass - - def visit_thead(self, node): - pass - def depart_thead(self, node): - pass - - def visit_tbody(self, node): - self.table.append('sep') - def depart_tbody(self, node): - pass - - def visit_row(self, node): - self.table.append([]) - def depart_row(self, node): - pass - - def visit_entry(self, node): - if node.has_key('morerows') or node.has_key('morecols'): - raise NotImplementedError('Column or row spanning cells are ' - 'not implemented.') - self.new_state(0) - def depart_entry(self, node): - text = '\n'.join('\n'.join(x[1]) for x in self.states.pop()) - self.stateindent.pop() - self.table[-1].append(text) - - def visit_table(self, node): - if self.table: - raise NotImplementedError('Nested tables are not supported.') - self.new_state(0) - self.table = [[]] - def depart_table(self, node): - lines = self.table[1:] - fmted_rows = [] - colwidths = self.table[0] - realwidths = colwidths[:] - separator = 0 - # don't allow paragraphs in table cells for now - for line in lines: - if line == 'sep': - separator = len(fmted_rows) - else: - cells = [] - for i, cell in enumerate(line): - par = textwrap.wrap(cell, width=colwidths[i]) - if par: - maxwidth = max(map(len, par)) - else: - maxwidth = 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.add_text(''.join(out) + '\n') - - 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.add_text(''.join(out) + '\n') - - for i, row in enumerate(fmted_rows): - if separator and i == separator: - writesep('=') - else: - writesep('-') - writerow(row) - writesep('-') - self.table = None - self.end_state(wrap=False) - - def visit_acks(self, node): - self.new_state(0) - self.add_text(', '.join(n.astext() for n in node.children[0].children) + '.') - self.end_state() - raise nodes.SkipNode - - def visit_image(self, node): - self.add_text(_('[image]')) - raise nodes.SkipNode - - def visit_transition(self, node): - indent = sum(self.stateindent) - self.new_state(0) - self.add_text('=' * (MAXWIDTH - indent)) - self.end_state() - raise nodes.SkipNode - - def visit_bullet_list(self, node): - self._list_counter = -1 - def depart_bullet_list(self, node): - pass - - def visit_enumerated_list(self, node): - self._list_counter = 0 - def depart_enumerated_list(self, node): - pass - - def visit_definition_list(self, node): - self._list_counter = -2 - def depart_definition_list(self, node): - pass - - def visit_list_item(self, node): - if self._list_counter == -1: - # bullet list - self.new_state(2) - elif self._list_counter == -2: - # definition list - pass - else: - # enumerated list - self._list_counter += 1 - self.new_state(len(str(self._list_counter)) + 2) - def depart_list_item(self, node): - if self._list_counter == -1: - self.end_state(first='* ', end=None) - elif self._list_counter == -2: - pass - else: - self.end_state(first='%s. ' % self._list_counter, end=None) - - def visit_definition_list_item(self, node): - self._li_has_classifier = len(node) >= 2 and \ - isinstance(node[1], nodes.classifier) - def depart_definition_list_item(self, node): - pass - - def visit_term(self, node): - self.new_state(0) - def depart_term(self, node): - if not self._li_has_classifier: - self.end_state(end=None) - - def visit_classifier(self, node): - self.add_text(' : ') - def depart_classifier(self, node): - self.end_state(end=None) - - def visit_definition(self, node): - self.new_state() - def depart_definition(self, node): - self.end_state() - - def visit_field_list(self, node): - pass - def depart_field_list(self, node): - pass - - def visit_field(self, node): - pass - def depart_field(self, node): - pass - - def visit_field_name(self, node): - self.new_state(0) - def depart_field_name(self, node): - self.add_text(':') - self.end_state(end=None) - - def visit_field_body(self, node): - self.new_state() - def depart_field_body(self, node): - self.end_state() - - def visit_centered(self, node): - pass - def depart_centered(self, node): - pass - - def visit_admonition(self, node): - self.new_state(0) - def depart_admonition(self, node): - self.end_state() - - def _visit_admonition(self, node): - self.new_state(2) - def _make_depart_admonition(name): - def depart_admonition(self, node): - self.end_state(first=admonitionlabels[name] + ': ') - return depart_admonition - - visit_attention = _visit_admonition - depart_attention = _make_depart_admonition('attention') - visit_caution = _visit_admonition - depart_caution = _make_depart_admonition('caution') - visit_danger = _visit_admonition - depart_danger = _make_depart_admonition('danger') - visit_error = _visit_admonition - depart_error = _make_depart_admonition('error') - visit_hint = _visit_admonition - depart_hint = _make_depart_admonition('hint') - visit_important = _visit_admonition - depart_important = _make_depart_admonition('important') - visit_note = _visit_admonition - depart_note = _make_depart_admonition('note') - visit_tip = _visit_admonition - depart_tip = _make_depart_admonition('tip') - visit_warning = _visit_admonition - depart_warning = _make_depart_admonition('warning') - - def visit_versionmodified(self, node): - self.new_state(0) - if node.children: - self.add_text(versionlabels[node['type']] % node['version'] + ': ') - else: - self.add_text(versionlabels[node['type']] % node['version'] + '.') - def depart_versionmodified(self, node): - self.end_state() - - def visit_literal_block(self, node): - self.new_state() - def depart_literal_block(self, node): - self.end_state(wrap=False) - - def visit_doctest_block(self, node): - self.new_state(0) - def depart_doctest_block(self, node): - self.end_state(wrap=False) - - def visit_line_block(self, node): - self.new_state(0) - def depart_line_block(self, node): - self.end_state(wrap=False) - - def visit_line(self, node): - pass - def depart_line(self, node): - pass - - def visit_block_quote(self, node): - self.new_state() - def depart_block_quote(self, node): - self.end_state() - - def visit_compact_paragraph(self, node): - pass - def depart_compact_paragraph(self, node): - pass - - def visit_paragraph(self, node): - if not isinstance(node.parent, nodes.Admonition) or \ - isinstance(node.parent, addnodes.seealso): - self.new_state(0) - def depart_paragraph(self, node): - if not isinstance(node.parent, nodes.Admonition) or \ - isinstance(node.parent, addnodes.seealso): - self.end_state() - - def visit_target(self, node): - raise nodes.SkipNode - - def visit_index(self, node): - raise nodes.SkipNode - - def visit_substitution_definition(self, node): - raise nodes.SkipNode - - def visit_pending_xref(self, node): - pass - def depart_pending_xref(self, node): - pass - - def visit_reference(self, node): - pass - def depart_reference(self, node): - pass - - def visit_emphasis(self, node): - self.add_text('*') - def depart_emphasis(self, node): - self.add_text('*') - - def visit_literal_emphasis(self, node): - self.add_text('*') - def depart_literal_emphasis(self, node): - self.add_text('*') - - def visit_strong(self, node): - self.add_text('**') - def depart_strong(self, node): - self.add_text('**') - - def visit_title_reference(self, node): - self.add_text('*') - def depart_title_reference(self, node): - self.add_text('*') - - def visit_literal(self, node): - self.add_text('``') - def depart_literal(self, node): - self.add_text('``') - - def visit_subscript(self, node): - self.add_text('_') - def depart_subscript(self, node): - pass - - def visit_superscript(self, node): - self.add_text('^') - def depart_superscript(self, node): - pass - - def visit_footnote_reference(self, node): - self.add_text('[%s]' % node.astext()) - raise nodes.SkipNode - - def visit_citation_reference(self, node): - self.add_text('[%s]' % node.astext()) - raise nodes.SkipNode - - def visit_Text(self, node): - self.add_text(node.astext()) - def depart_Text(self, node): - pass - - def visit_problematic(self, node): - self.add_text('>>') - def depart_problematic(self, node): - self.add_text('<<') - - def visit_system_message(self, node): - self.new_state(0) - self.add_text('' % node.astext()) - self.end_state() - raise nodes.SkipNode - - def visit_comment(self, node): - raise nodes.SkipNode - - def visit_meta(self, node): - # only valid for HTML - raise nodes.SkipNode - - def unknown_visit(self, node): - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/writers/__init__.py b/sphinx/writers/__init__.py new file mode 100644 index 00000000..902f04d3 --- /dev/null +++ b/sphinx/writers/__init__.py @@ -0,0 +1,10 @@ +# -*- coding: utf-8 -*- +""" + sphinx.writers + ~~~~~~~~~~~~~~ + + Custom docutils writers. + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py new file mode 100644 index 00000000..b82d7ccc --- /dev/null +++ b/sphinx/writers/html.py @@ -0,0 +1,457 @@ +# -*- coding: utf-8 -*- +""" + sphinx.writers.html + ~~~~~~~~~~~~~~~~~~~ + + docutils writers handling Sphinx' custom nodes. + + :copyright: 2007-2008 by Georg Brandl. + :license: BSD. +""" + +import sys +import posixpath +import os + +from docutils import nodes +from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator + +from sphinx.locale import admonitionlabels, versionlabels +from sphinx.highlighting import PygmentsBridge +from sphinx.util.smartypants import sphinx_smarty_pants + +try: + import Image # check for the Python Imaging Library +except ImportError: + Image = None + +class HTMLWriter(Writer): + def __init__(self, builder): + Writer.__init__(self) + self.builder = builder + + def translate(self): + # sadly, this is mostly copied from parent class + self.visitor = visitor = self.builder.translator_class(self.builder, + self.document) + self.document.walkabout(visitor) + self.output = visitor.astext() + for attr in ('head_prefix', 'stylesheet', 'head', 'body_prefix', + 'body_pre_docinfo', 'docinfo', 'body', 'fragment', + 'body_suffix', 'meta', 'title', 'subtitle', 'header', + 'footer', 'html_prolog', 'html_head', 'html_title', + 'html_subtitle', 'html_body', ): + setattr(self, attr, getattr(visitor, attr, None)) + self.clean_meta = ''.join(visitor.meta[2:]) + + +class HTMLTranslator(BaseTranslator): + """ + Our custom HTML translator. + """ + + def __init__(self, builder, *args, **kwds): + BaseTranslator.__init__(self, *args, **kwds) + self.highlighter = PygmentsBridge('html', builder.config.pygments_style) + self.no_smarty = 0 + self.builder = builder + self.highlightlang = builder.config.highlight_language + self.highlightlinenothreshold = sys.maxint + self.protect_literal_text = 0 + + def visit_desc(self, node): + self.body.append(self.starttag(node, 'dl', CLASS=node['desctype'])) + def depart_desc(self, node): + self.body.append('\n\n') + + def visit_desc_signature(self, node): + # the id is set automatically + self.body.append(self.starttag(node, 'dt')) + # anchor for per-desc interactive data + if node.parent['desctype'] != 'describe' and node['ids'] and node['first']: + self.body.append('' % node['ids'][0]) + if node.parent['desctype'] in ('class', 'exception'): + self.body.append('%s ' % node.parent['desctype']) + def depart_desc_signature(self, node): + if node['ids'] and self.builder.add_definition_links: + self.body.append(u'\u00B6' % + _('Permalink to this definition')) + self.body.append('\n') + + def visit_desc_addname(self, node): + self.body.append(self.starttag(node, 'tt', '', CLASS='descclassname')) + def depart_desc_addname(self, node): + self.body.append('') + + def visit_desc_type(self, node): + pass + def depart_desc_type(self, node): + pass + + def visit_desc_name(self, node): + self.body.append(self.starttag(node, 'tt', '', CLASS='descname')) + def depart_desc_name(self, node): + self.body.append('') + + def visit_desc_parameterlist(self, node): + self.body.append('(') + self.first_param = 1 + def depart_desc_parameterlist(self, node): + self.body.append(')') + + def visit_desc_parameter(self, node): + if not self.first_param: + self.body.append(', ') + else: + self.first_param = 0 + if not node.hasattr('noemph'): + self.body.append('') + def depart_desc_parameter(self, node): + if not node.hasattr('noemph'): + self.body.append('') + + def visit_desc_optional(self, node): + self.body.append('[') + def depart_desc_optional(self, node): + self.body.append(']') + + def visit_desc_annotation(self, node): + self.body.append(self.starttag(node, 'em', CLASS='property')) + def depart_desc_annotation(self, node): + self.body.append('') + + def visit_desc_content(self, node): + self.body.append(self.starttag(node, 'dd', '')) + def depart_desc_content(self, node): + self.body.append('') + + def visit_refcount(self, node): + self.body.append(self.starttag(node, 'em', '', CLASS='refcount')) + def depart_refcount(self, node): + self.body.append('') + + def visit_versionmodified(self, node): + self.body.append(self.starttag(node, 'p')) + text = versionlabels[node['type']] % node['version'] + if len(node): + text += ': ' + else: + text += '.' + self.body.append('%s' % text) + def depart_versionmodified(self, node): + self.body.append('

    \n') + + # overwritten + def visit_reference(self, node): + BaseTranslator.visit_reference(self, node) + if node.hasattr('reftitle'): + # ugly hack to add a title attribute + starttag = self.body[-1] + if not starttag.startswith(' tag + self.section_level += 1 + self.body.append(self.starttag(node, 'div', CLASS='section')) + + def visit_title(self, node): + # don't move the id attribute inside the tag + BaseTranslator.visit_title(self, node, move_ids=0) + + # overwritten + def visit_literal_block(self, node): + if node.rawsource != node.astext(): + # most probably a parsed-literal block -- don't highlight + return BaseTranslator.visit_literal_block(self, node) + lang = self.highlightlang + linenos = node.rawsource.count('\n') >= self.highlightlinenothreshold - 1 + if node.has_key('language'): + # code-block directives + lang = node['language'] + if node.has_key('linenos'): + linenos = node['linenos'] + highlighted = self.highlighter.highlight_block(node.rawsource, lang, linenos) + starttag = self.starttag(node, 'div', suffix='', CLASS='highlight-%s' % lang) + self.body.append(starttag + highlighted + '
    \n') + raise nodes.SkipNode + + def visit_doctest_block(self, node): + self.visit_literal_block(node) + + # overwritten + def visit_literal(self, node): + if len(node.children) == 1 and \ + node.children[0] in ('None', 'True', 'False'): + node['classes'].append('xref') + self.body.append(self.starttag(node, 'tt', '', CLASS='docutils literal')) + self.protect_literal_text += 1 + def depart_literal(self, node): + self.protect_literal_text -= 1 + self.body.append('') + + def visit_productionlist(self, node): + self.body.append(self.starttag(node, 'pre')) + names = [] + for production in node: + names.append(production['tokenname']) + maxlen = max(len(name) for name in names) + for production in node: + if production['tokenname']: + lastname = production['tokenname'].ljust(maxlen) + self.body.append(self.starttag(production, 'strong', '')) + self.body.append(lastname + ' ::= ') + else: + self.body.append('%s ' % (' '*len(lastname))) + production.walkabout(self) + self.body.append('\n') + self.body.append('\n') + raise nodes.SkipNode + def depart_productionlist(self, node): + pass + + def visit_production(self, node): + pass + def depart_production(self, node): + pass + + def visit_centered(self, node): + self.body.append(self.starttag(node, 'p', CLASS="centered") + '') + def depart_centered(self, node): + self.body.append('

    ') + + def visit_compact_paragraph(self, node): + pass + def depart_compact_paragraph(self, node): + pass + + def visit_highlightlang(self, node): + self.highlightlang = node['lang'] + self.highlightlinenothreshold = node['linenothreshold'] + def depart_highlightlang(self, node): + pass + + # overwritten + def visit_image(self, node): + olduri = node['uri'] + # rewrite the URI if the environment knows about it + if olduri in self.builder.images: + node['uri'] = posixpath.join(self.builder.imgpath, + self.builder.images[olduri]) + + if node.has_key('scale'): + if Image and not (node.has_key('width') + and node.has_key('height')): + try: + im = Image.open(os.path.join(self.builder.srcdir, + olduri)) + except (IOError, # Source image can't be found or opened + UnicodeError): # PIL doesn't like Unicode paths. + print olduri + pass + else: + if not node.has_key('width'): + node['width'] = str(im.size[0]) + if not node.has_key('height'): + node['height'] = str(im.size[1]) + del im + BaseTranslator.visit_image(self, node) + + def visit_toctree(self, node): + # this only happens when formatting a toc from env.tocs -- in this + # case we don't want to include the subtree + raise nodes.SkipNode + + def visit_index(self, node): + raise nodes.SkipNode + + def visit_tabular_col_spec(self, node): + raise nodes.SkipNode + + def visit_glossary(self, node): + pass + def depart_glossary(self, node): + pass + + def visit_acks(self, node): + pass + def depart_acks(self, node): + pass + + def visit_module(self, node): + pass + def depart_module(self, node): + pass + + def bulk_text_processor(self, text): + return text + + # overwritten + def visit_Text(self, node): + text = node.astext() + encoded = self.encode(text) + if self.protect_literal_text: + # moved here from base class's visit_literal to support + # more formatting in literal nodes + for token in self.words_and_spaces.findall(encoded): + if token.strip(): + # protect literal text from line wrapping + self.body.append('%s' % token) + elif token in ' \n': + # allow breaks at whitespace + self.body.append(token) + else: + # protect runs of multiple spaces; the last one can wrap + self.body.append(' ' * (len(token)-1) + ' ') + else: + if self.in_mailto and self.settings.cloak_email_addresses: + encoded = self.cloak_email(encoded) + else: + encoded = self.bulk_text_processor(encoded) + self.body.append(encoded) + + # these are all for docutils 0.5 compatibility + + def visit_note(self, node): + self.visit_admonition(node, 'note') + def depart_note(self, node): + self.depart_admonition(node) + + def visit_warning(self, node): + self.visit_admonition(node, 'warning') + def depart_warning(self, node): + self.depart_admonition(node) + + def visit_attention(self, node): + self.visit_admonition(node, 'attention') + + def depart_attention(self, node): + self.depart_admonition() + + def visit_caution(self, node): + self.visit_admonition(node, 'caution') + def depart_caution(self, node): + self.depart_admonition() + + def visit_danger(self, node): + self.visit_admonition(node, 'danger') + def depart_danger(self, node): + self.depart_admonition() + + def visit_error(self, node): + self.visit_admonition(node, 'error') + def depart_error(self, node): + self.depart_admonition() + + def visit_hint(self, node): + self.visit_admonition(node, 'hint') + def depart_hint(self, node): + self.depart_admonition() + + def visit_important(self, node): + self.visit_admonition(node, 'important') + def depart_important(self, node): + self.depart_admonition() + + def visit_tip(self, node): + self.visit_admonition(node, 'tip') + def depart_tip(self, node): + self.depart_admonition() + + # these are only handled specially in the SmartyPantsHTMLTranslator + def visit_literal_emphasis(self, node): + return self.visit_emphasis(node) + def depart_literal_emphasis(self, node): + return self.depart_emphasis(node) + + def depart_title(self, node): + close_tag = self.context[-1] + if self.builder.add_header_links and \ + (close_tag.startswith('\u00B6    ' % + _('Permalink to this headline')) + BaseTranslator.depart_title(self, node) + + def unknown_visit(self, node): + raise NotImplementedError('Unknown node: ' + node.__class__.__name__) + + +class SmartyPantsHTMLTranslator(HTMLTranslator): + """ + Handle ordinary text via smartypants, converting quotes and dashes + to the correct entities. + """ + + def __init__(self, *args, **kwds): + self.no_smarty = 0 + HTMLTranslator.__init__(self, *args, **kwds) + + def visit_literal(self, node): + self.no_smarty += 1 + try: + # this raises SkipNode + HTMLTranslator.visit_literal(self, node) + finally: + self.no_smarty -= 1 + + def visit_literal_emphasis(self, node): + self.no_smarty += 1 + self.visit_emphasis(node) + + def depart_literal_emphasis(self, node): + self.depart_emphasis(node) + self.no_smarty -= 1 + + def visit_desc_signature(self, node): + self.no_smarty += 1 + HTMLTranslator.visit_desc_signature(self, node) + + def depart_desc_signature(self, node): + self.no_smarty -= 1 + HTMLTranslator.depart_desc_signature(self, node) + + def visit_productionlist(self, node): + self.no_smarty += 1 + try: + HTMLTranslator.visit_productionlist(self, node) + finally: + self.no_smarty -= 1 + + def visit_option(self, node): + self.no_smarty += 1 + HTMLTranslator.visit_option(self, node) + def depart_option(self, node): + self.no_smarty -= 1 + HTMLTranslator.depart_option(self, node) + + def bulk_text_processor(self, text): + if self.no_smarty <= 0: + return sphinx_smarty_pants(text) + return text diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py new file mode 100644 index 00000000..bfa9c120 --- /dev/null +++ b/sphinx/writers/latex.py @@ -0,0 +1,1185 @@ +# -*- coding: utf-8 -*- +""" + sphinx.writers.latex + ~~~~~~~~~~~~~~~~~~~~ + + Custom docutils writer for LaTeX. + + Much of this code is adapted from Dave Kuhlman's "docpy" writer from his + docutils sandbox. + + :copyright: 2007-2008 by Georg Brandl, Dave Kuhlman. + :license: BSD. +""" + +import re +import sys +from os import path + +from docutils import nodes, writers +from docutils.writers.latex2e import Babel + +from sphinx import addnodes +from sphinx import highlighting +from sphinx.locale import admonitionlabels, versionlabels +from sphinx.util import ustrftime +from sphinx.util.texescape import tex_escape_map +from sphinx.util.smartypants import educateQuotesLatex + +HEADER = r'''%% Generated by Sphinx. +\documentclass[%(papersize)s,%(pointsize)s%(classoptions)s]{%(docclass)s} +%(inputenc)s +%(fontenc)s +%(babel)s +%(fontpkg)s +%(fncychap)s +\usepackage{sphinx} +%(preamble)s + +\title{%(title)s} +\date{%(date)s} +\release{%(release)s} +\author{%(author)s} +\newcommand{\sphinxlogo}{%(logo)s} +\renewcommand{\releasename}{%(releasename)s} +%(makeindex)s +%(makemodindex)s +''' + +BEGIN_DOC = r''' +\begin{document} +%(shorthandoff)s +%(maketitle)s +%(tableofcontents)s +''' + +FOOTER = r''' +%(footer)s +\renewcommand{\indexname}{%(modindexname)s} +%(printmodindex)s +\renewcommand{\indexname}{%(indexname)s} +%(printindex)s +\end{document} +''' + + +class LaTeXWriter(writers.Writer): + + supported = ('sphinxlatex',) + + settings_spec = ('LaTeX writer options', '', ( + ('Document name', ['--docname'], {'default': ''}), + ('Document class', ['--docclass'], {'default': 'manual'}), + ('Author', ['--author'], {'default': ''}), + )) + settings_defaults = {} + + output = None + + def __init__(self, builder): + writers.Writer.__init__(self) + self.builder = builder + + def translate(self): + visitor = LaTeXTranslator(self.document, self.builder) + self.document.walkabout(visitor) + self.output = visitor.astext() + + +# Helper classes + +class ExtBabel(Babel): + def get_shorthandoff(self): + shortlang = self.language.split('_')[0] + if shortlang in ('de', 'sl', 'pt', 'es', 'nl', 'pl'): + return '\\shorthandoff{"}' + return '' + + _ISO639_TO_BABEL = Babel._ISO639_TO_BABEL.copy() + _ISO639_TO_BABEL['sl'] = 'slovene' + + +class Table(object): + def __init__(self): + self.col = 0 + self.colcount = 0 + self.colspec = None + self.had_head = False + self.has_verbatim = False + self.caption = None + + +class Desc(object): + def __init__(self, node): + self.env = LaTeXTranslator.desc_map.get(node['desctype'], 'describe') + self.type = self.cls = self.name = self.params = self.annotation = '' + self.count = 0 + + +class LaTeXTranslator(nodes.NodeVisitor): + sectionnames = ["part", "chapter", "section", "subsection", + "subsubsection", "paragraph", "subparagraph"] + + ignore_missing_images = False + + default_elements = { + 'docclass': 'manual', + 'papersize': 'letterpaper', + 'pointsize': '10pt', + 'classoptions': '', + 'inputenc': '\\usepackage[utf8]{inputenc}', + 'fontenc': '\\usepackage[T1]{fontenc}', + 'babel': '\\usepackage{babel}', + 'fontpkg': '\\usepackage{times}', + 'fncychap': '\\usepackage[Bjarne]{fncychap}', + 'preamble': '', + 'title': '', + 'date': '', + 'release': '', + 'author': '', + 'logo': '', + 'releasename': 'Release', + 'makeindex': '\\makeindex', + 'makemodindex': '\\makemodindex', + 'shorthandoff': '', + 'maketitle': '\\maketitle', + 'tableofcontents': '\\tableofcontents', + 'footer': '', + 'printmodindex': '\\printmodindex', + 'printindex': '\\printindex', + } + + def __init__(self, document, builder): + nodes.NodeVisitor.__init__(self, document) + self.builder = builder + self.body = [] + + # sort out some elements + papersize = builder.config.latex_paper_size + 'paper' + if papersize == 'paper': # e.g. command line "-D latex_paper_size=" + papersize = 'letterpaper' + + self.elements = self.default_elements.copy() + self.elements.update({ + 'docclass': document.settings.docclass, + 'papersize': papersize, + 'pointsize': builder.config.latex_font_size, + # if empty, the title is set to the first section title + 'title': document.settings.title, + 'date': ustrftime(builder.config.today_fmt or _('%B %d, %Y')), + 'release': builder.config.release, + 'author': document.settings.author, + 'releasename': _('Release'), + 'preamble': builder.config.latex_preamble, + 'modindexname': _('Module Index'), + 'indexname': _('Index'), + }) + if builder.config.latex_logo: + self.elements['logo'] = '\\includegraphics{%s}\\par' % \ + path.basename(builder.config.latex_logo) + if builder.config.language: + babel = ExtBabel(builder.config.language) + lang = babel.get_language() + if lang: + self.elements['classoptions'] += ',' + babel.get_language() + else: + self.builder.warn('no Babel option known for language %r' % + builder.config.language) + self.elements['shorthandoff'] = babel.get_shorthandoff() + self.elements['fncychap'] = '\\usepackage[Sonny]{fncychap}' + else: + self.elements['classoptions'] += ',english' + if not builder.config.latex_use_modindex: + self.elements['makemodindex'] = '' + self.elements['printmodindex'] = '' + # allow the user to override them all + self.elements.update(builder.config.latex_elements) + + self.highlighter = highlighting.PygmentsBridge( + 'latex', builder.config.pygments_style) + self.context = [] + self.descstack = [] + self.bibitems = [] + self.table = None + self.next_table_colspec = None + self.highlightlang = builder.config.highlight_language + self.highlightlinenothreshold = sys.maxint + self.written_ids = set() + self.footnotestack = [] + if self.elements['docclass'] == 'manual': + if builder.config.latex_use_parts: + self.top_sectionlevel = 0 + else: + self.top_sectionlevel = 1 + else: + self.top_sectionlevel = 2 + self.next_section_target = None + # flags + self.verbatim = None + self.in_title = 0 + self.in_production_list = 0 + self.first_document = 1 + self.this_is_the_title = 1 + self.literal_whitespace = 0 + self.no_contractions = 0 + + def astext(self): + return (HEADER % self.elements + self.highlighter.get_stylesheet() + + u''.join(self.body) + FOOTER % self.elements) + + def visit_document(self, node): + self.footnotestack.append(self.collect_footnotes(node)) + if self.first_document == 1: + # the first document is all the regular content ... + self.body.append(BEGIN_DOC % self.elements) + self.first_document = 0 + elif self.first_document == 0: + # ... and all others are the appendices + self.body.append('\n\\appendix\n') + self.first_document = -1 + # "- 1" because the level is increased before the title is visited + self.sectionlevel = self.top_sectionlevel - 1 + def depart_document(self, node): + if self.bibitems: + widest_label = "" + for bi in self.bibitems: + if len(widest_label) < len(bi[0]): + widest_label = bi[0] + self.body.append('\n\\begin{thebibliography}{%s}\n' % widest_label) + for bi in self.bibitems: + # cite_key: underscores must not be escaped + cite_key = bi[0].replace(r"\_", "_") + self.body.append('\\bibitem[%s]{%s}{%s}\n' % (bi[0], cite_key, bi[1])) + self.body.append('\\end{thebibliography}\n') + self.bibitems = [] + + def visit_start_of_file(self, node): + # This marks the begin of a new file; therefore the current module and + # class must be reset + self.body.append('\n\\resetcurrentobjects\n') + # and also, new footnotes + self.footnotestack.append(self.collect_footnotes(node)) + + def collect_footnotes(self, node): + fnotes = {} + def footnotes_under(n): + if isinstance(n, nodes.footnote): + yield n + else: + for c in n.children: + if isinstance(c, addnodes.start_of_file): + continue + for k in footnotes_under(c): + yield k + for fn in footnotes_under(node): + num = fn.children[0].astext().strip() + fnotes[num] = fn + fn.parent.remove(fn) + return fnotes + + def depart_start_of_file(self, node): + self.footnotestack.pop() + + def visit_highlightlang(self, node): + self.highlightlang = node['lang'] + self.highlightlinenothreshold = node['linenothreshold'] + raise nodes.SkipNode + + def visit_section(self, node): + if not self.this_is_the_title: + self.sectionlevel += 1 + self.body.append('\n\n') + if self.next_section_target: + self.body.append(r'\hypertarget{%s}{}' % self.next_section_target) + self.next_section_target = None + #if node.get('ids'): + # for id in node['ids']: + # if id not in self.written_ids: + # self.body.append(r'\hypertarget{%s}{}' % id) + # self.written_ids.add(id) + def depart_section(self, node): + self.sectionlevel = max(self.sectionlevel - 1, self.top_sectionlevel - 1) + + def visit_problematic(self, node): + self.body.append(r'{\color{red}\bfseries{}') + def depart_problematic(self, node): + self.body.append('}') + + def visit_topic(self, node): + self.body.append('\\setbox0\\vbox{\n' + '\\begin{minipage}{0.95\\textwidth}\n') + def depart_topic(self, node): + self.body.append('\\end{minipage}}\n' + '\\begin{center}\\setlength{\\fboxsep}{5pt}' + '\\shadowbox{\\box0}\\end{center}\n') + visit_sidebar = visit_topic + depart_sidebar = depart_topic + + def visit_glossary(self, node): + pass + def depart_glossary(self, node): + pass + + def visit_productionlist(self, node): + self.body.append('\n\n\\begin{productionlist}\n') + self.in_production_list = 1 + def depart_productionlist(self, node): + self.body.append('\\end{productionlist}\n\n') + self.in_production_list = 0 + + def visit_production(self, node): + if node['tokenname']: + self.body.append('\\production{%s}{' % self.encode(node['tokenname'])) + else: + self.body.append('\\productioncont{') + def depart_production(self, node): + self.body.append('}\n') + + def visit_transition(self, node): + self.body.append('\n\n\\bigskip\\hrule{}\\bigskip\n\n') + def depart_transition(self, node): + pass + + def visit_title(self, node): + parent = node.parent + if isinstance(parent, addnodes.seealso): + # the environment already handles this + raise nodes.SkipNode + elif self.this_is_the_title: + if len(node.children) != 1 and not isinstance(node.children[0], nodes.Text): + self.builder.warn('document title is not a single Text node') + if not self.elements['title']: + # text needs to be escaped since it is inserted into + # the output literally + self.elements['title'] = node.astext().translate(tex_escape_map) + self.this_is_the_title = 0 + raise nodes.SkipNode + elif isinstance(parent, nodes.section): + try: + self.body.append(r'\%s{' % self.sectionnames[self.sectionlevel]) + except IndexError: + from sphinx.application import SphinxError + raise SphinxError('too many nesting section levels for LaTeX, ' + 'at heading: %s' % node.astext()) + self.context.append('}\n') + elif isinstance(parent, (nodes.topic, nodes.sidebar)): + self.body.append(r'\textbf{') + self.context.append('}\n\n\medskip\n\n') + elif isinstance(parent, nodes.Admonition): + self.body.append('{') + self.context.append('}\n') + elif isinstance(parent, nodes.table): + self.table.caption = self.encode(node.astext()) + raise nodes.SkipNode + else: + self.builder.warn('encountered title node not in section, topic, ' + 'table, admonition or sidebar') + self.body.append('\\textbf{') + self.context.append('}\n') + self.in_title = 1 + def depart_title(self, node): + self.in_title = 0 + self.body.append(self.context.pop()) + + def visit_subtitle(self, node): + if isinstance(node.parent, nodes.sidebar): + self.body.append('~\\\\\n\\textbf{') + self.context.append('}\n\\smallskip\n') + else: + self.context.append('') + def depart_subtitle(self, node): + self.body.append(self.context.pop()) + + desc_map = { + 'function' : 'funcdesc', + 'class': 'classdesc', + 'method': 'methoddesc', + 'staticmethod': 'staticmethoddesc', + 'exception': 'excdesc', + 'data': 'datadesc', + 'attribute': 'memberdesc', + 'opcode': 'opcodedesc', + + 'cfunction': 'cfuncdesc', + 'cmember': 'cmemberdesc', + 'cmacro': 'csimplemacrodesc', + 'ctype': 'ctypedesc', + 'cvar': 'cvardesc', + + 'describe': 'describe', + # and all others are 'describe' too + } + + def visit_desc(self, node): + self.descstack.append(Desc(node)) + def depart_desc(self, node): + d = self.descstack.pop() + self.body.append("\\end{%s}\n" % d.env) + + def visit_desc_signature(self, node): + d = self.descstack[-1] + # reset these for every signature + d.type = d.cls = d.name = d.params = '' + def depart_desc_signature(self, node): + d = self.descstack[-1] + d.cls = d.cls.rstrip('.') + if node.parent['desctype'] != 'describe' and node['ids']: + hyper = '\\hypertarget{%s}{}' % node['ids'][0] + else: + hyper = '' + if d.count == 0: + t1 = "\n\n%s\\begin{%s}" % (hyper, d.env) + else: + t1 = "\n%s\\%sline" % (hyper, d.env[:-4]) + d.count += 1 + if d.env in ('funcdesc', 'classdesc', 'excclassdesc'): + t2 = "{%s}{%s}" % (d.name, d.params) + elif d.env in ('datadesc', 'excdesc', 'csimplemacrodesc'): + t2 = "{%s}" % (d.name) + elif d.env in ('methoddesc', 'staticmethoddesc'): + if d.cls: + t2 = "[%s]{%s}{%s}" % (d.cls, d.name, d.params) + else: + t2 = "{%s}{%s}" % (d.name, d.params) + elif d.env == 'memberdesc': + if d.cls: + t2 = "[%s]{%s}" % (d.cls, d.name) + else: + t2 = "{%s}" % d.name + elif d.env == 'cfuncdesc': + if d.cls: + # C++ class names + d.name = '%s::%s' % (d.cls, d.name) + t2 = "{%s}{%s}{%s}" % (d.type, d.name, d.params) + elif d.env == 'cmemberdesc': + try: + type, container = d.type.rsplit(' ', 1) + container = container.rstrip('.') + except ValueError: + container = '' + type = d.type + t2 = "{%s}{%s}{%s}" % (container, type, d.name) + elif d.env == 'cvardesc': + t2 = "{%s}{%s}" % (d.type, d.name) + elif d.env == 'ctypedesc': + t2 = "{%s}" % (d.name) + elif d.env == 'opcodedesc': + t2 = "{%s}{%s}" % (d.name, d.params) + elif d.env == 'describe': + t2 = "{%s}" % d.name + self.body.append(t1 + t2) + + def visit_desc_type(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].type = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_desc_name(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].name = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_desc_addname(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].cls = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_desc_parameterlist(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].params = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_desc_annotation(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].annotation = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_refcount(self, node): + self.body.append("\\emph{") + def depart_refcount(self, node): + self.body.append("}\\\\") + + def visit_desc_content(self, node): + if node.children and not isinstance(node.children[0], nodes.paragraph): + # avoid empty desc environment which causes a formatting bug + self.body.append('~') + def depart_desc_content(self, node): + pass + + def visit_seealso(self, node): + self.body.append("\n\n\\strong{%s:}\n\n" % admonitionlabels['seealso']) + def depart_seealso(self, node): + self.body.append("\n\n") + + def visit_rubric(self, node): + if len(node.children) == 1 and node.children[0].astext() == 'Footnotes': + raise nodes.SkipNode + self.body.append('\\paragraph{') + self.context.append('}\n') + def depart_rubric(self, node): + self.body.append(self.context.pop()) + + def visit_footnote(self, node): + pass + def depart_footnote(self, node): + pass + + def visit_label(self, node): + if isinstance(node.parent, nodes.citation): + self.bibitems[-1][0] = node.astext() + raise nodes.SkipNode + + def visit_tabular_col_spec(self, node): + self.next_table_colspec = node['spec'] + raise nodes.SkipNode + + def visit_table(self, node): + if self.table: + raise NotImplementedError('Nested tables are not supported.') + self.table = Table() + self.tablebody = [] + # Redirect body output until table is finished. + self._body = self.body + self.body = self.tablebody + def depart_table(self, node): + self.body = self._body + if self.table.caption is not None: + self.body.append('\n\\begin{threeparttable}\n' + '\\caption{%s}\n' % self.table.caption) + if self.table.has_verbatim: + self.body.append('\n\\begin{tabular}') + else: + self.body.append('\n\\begin{tabulary}{\\textwidth}') + if self.table.colspec: + self.body.append(self.table.colspec) + else: + if self.table.has_verbatim: + colwidth = 0.95 / self.table.colcount + colspec = ('p{%.3f\\textwidth}|' % colwidth) * self.table.colcount + self.body.append('{|' + colspec + '}\n') + else: + self.body.append('{|' + ('L|' * self.table.colcount) + '}\n') + self.body.extend(self.tablebody) + if self.table.has_verbatim: + self.body.append('\\end{tabular}\n\n') + else: + self.body.append('\\end{tabulary}\n\n') + if self.table.caption is not None: + self.body.append('\\end{threeparttable}\n\n') + self.table = None + self.tablebody = None + + def visit_colspec(self, node): + self.table.colcount += 1 + def depart_colspec(self, node): + pass + + def visit_tgroup(self, node): + pass + def depart_tgroup(self, node): + pass + + def visit_thead(self, node): + if self.next_table_colspec: + self.table.colspec = '{%s}\n' % self.next_table_colspec + self.next_table_colspec = None + self.body.append('\\hline\n') + self.table.had_head = True + def depart_thead(self, node): + self.body.append('\\hline\n') + + def visit_tbody(self, node): + if not self.table.had_head: + self.visit_thead(node) + def depart_tbody(self, node): + self.body.append('\\hline\n') + + def visit_row(self, node): + self.table.col = 0 + def depart_row(self, node): + self.body.append('\\\\\n') + + def visit_entry(self, node): + if node.has_key('morerows') or node.has_key('morecols'): + raise NotImplementedError('Column or row spanning cells are ' + 'not implemented.') + if self.table.col > 0: + self.body.append(' & ') + self.table.col += 1 + if isinstance(node.parent.parent, nodes.thead): + self.body.append('\\textbf{') + self.context.append('}') + else: + self.context.append('') + def depart_entry(self, node): + self.body.append(self.context.pop()) # header + + def visit_acks(self, node): + # this is a list in the source, but should be rendered as a + # comma-separated list here + self.body.append('\n\n') + self.body.append(', '.join(n.astext() for n in node.children[0].children) + '.') + self.body.append('\n\n') + raise nodes.SkipNode + + def visit_bullet_list(self, node): + self.body.append('\\begin{itemize}\n' ) + def depart_bullet_list(self, node): + self.body.append('\\end{itemize}\n' ) + + def visit_enumerated_list(self, node): + self.body.append('\\begin{enumerate}\n' ) + def depart_enumerated_list(self, node): + self.body.append('\\end{enumerate}\n' ) + + def visit_list_item(self, node): + # Append "{}" in case the next character is "[", which would break + # LaTeX's list environment (no numbering and the "[" is not printed). + self.body.append(r'\item {} ') + def depart_list_item(self, node): + self.body.append('\n') + + def visit_definition_list(self, node): + self.body.append('\\begin{description}\n') + def depart_definition_list(self, node): + self.body.append('\\end{description}\n') + + def visit_definition_list_item(self, node): + pass + def depart_definition_list_item(self, node): + pass + + def visit_term(self, node): + ctx = ']' + if node.has_key('ids') and node['ids']: + ctx += '\\hypertarget{%s}{}' % node['ids'][0] + self.body.append('\\item[') + self.context.append(ctx) + def depart_term(self, node): + self.body.append(self.context.pop()) + + def visit_classifier(self, node): + self.body.append('{[}') + def depart_classifier(self, node): + self.body.append('{]}') + + def visit_definition(self, node): + pass + def depart_definition(self, node): + self.body.append('\n') + + def visit_field_list(self, node): + self.body.append('\\begin{quote}\\begin{description}\n') + def depart_field_list(self, node): + self.body.append('\\end{description}\\end{quote}\n') + + def visit_field(self, node): + pass + def depart_field(self, node): + pass + + visit_field_name = visit_term + depart_field_name = depart_term + + visit_field_body = visit_definition + depart_field_body = depart_definition + + def visit_paragraph(self, node): + self.body.append('\n') + def depart_paragraph(self, node): + self.body.append('\n') + + def visit_centered(self, node): + self.body.append('\n\\begin{centering}') + def depart_centered(self, node): + self.body.append('\n\\end{centering}') + + def visit_module(self, node): + modname = node['modname'] + self.body.append('\n\\declaremodule[%s]{}{%s}' % (modname.replace('_', ''), + self.encode(modname))) + self.body.append('\n\\modulesynopsis{%s}' % self.encode(node['synopsis'])) + if node.has_key('platform'): + self.body.append('\\platform{%s}' % self.encode(node['platform'])) + def depart_module(self, node): + pass + + def latex_image_length(self, width_str): + match = re.match('(\d*\.?\d*)\s*(\S*)', width_str) + if not match: + # fallback + return width_str + res = width_str + amount, unit = match.groups()[:2] + if not unit or unit == "px": + # pixels: let LaTeX alone + return None + elif unit == "%": + res = "%.3f\\linewidth" % (float(amount) / 100.0) + return res + + def visit_image(self, node): + attrs = node.attributes + pre = [] # in reverse order + post = [] + include_graphics_options = [] + inline = isinstance(node.parent, nodes.TextElement) + if attrs.has_key('scale'): + # Could also be done with ``scale`` option to + # ``\includegraphics``; doing it this way for consistency. + pre.append('\\scalebox{%f}{' % (attrs['scale'] / 100.0,)) + post.append('}') + if attrs.has_key('width'): + w = self.latex_image_length(attrs['width']) + if w: + include_graphics_options.append('width=%s' % w) + if attrs.has_key('height'): + h = self.latex_image_length(attrs['height']) + include_graphics_options.append('height=%s' % h) + if attrs.has_key('align'): + align_prepost = { + # By default latex aligns the top of an image. + (1, 'top'): ('', ''), + (1, 'middle'): ('\\raisebox{-0.5\\height}{', '}'), + (1, 'bottom'): ('\\raisebox{-\\height}{', '}'), + (0, 'center'): ('{\\hfill', '\\hfill}'), + # These 2 don't exactly do the right thing. The image should + # be floated alongside the paragraph. See + # http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG + (0, 'left'): ('{', '\\hfill}'), + (0, 'right'): ('{\\hfill', '}'),} + try: + pre.append(align_prepost[inline, attrs['align']][0]) + post.append(align_prepost[inline, attrs['align']][1]) + except KeyError: + pass # XXX complain here? + if not inline: + pre.append('\n') + post.append('\n') + pre.reverse() + if node['uri'] in self.builder.images: + uri = self.builder.images[node['uri']] + else: + # missing image! + if self.ignore_missing_images: + return + uri = node['uri'] + if uri.find('://') != -1: + # ignore remote images + return + self.body.extend(pre) + options = '' + if include_graphics_options: + options = '[%s]' % ','.join(include_graphics_options) + self.body.append('\\includegraphics%s{%s}' % (options, uri)) + self.body.extend(post) + def depart_image(self, node): + pass + + def visit_figure(self, node): + if (not node.attributes.has_key('align') or + node.attributes['align'] == 'center'): + # centering does not add vertical space like center. + align = '\n\\centering' + align_end = '' + else: + # TODO non vertical space for other alignments. + align = '\\begin{flush%s}' % node.attributes['align'] + align_end = '\\end{flush%s}' % node.attributes['align'] + self.body.append('\\begin{figure}[htbp]%s\n' % align) + self.context.append('%s\\end{figure}\n' % align_end) + def depart_figure(self, node): + self.body.append(self.context.pop()) + + def visit_caption(self, node): + self.body.append('\\caption{') + def depart_caption(self, node): + self.body.append('}') + + def visit_legend(self, node): + self.body.append('{\\small ') + def depart_legend(self, node): + self.body.append('}') + + def visit_admonition(self, node): + self.body.append('\n\\begin{notice}{note}') + def depart_admonition(self, node): + self.body.append('\\end{notice}\n') + + def _make_visit_admonition(name): + def visit_admonition(self, node): + self.body.append('\n\\begin{notice}{%s}{%s:}' % + (name, admonitionlabels[name])) + return visit_admonition + def _depart_named_admonition(self, node): + self.body.append('\\end{notice}\n') + + visit_attention = _make_visit_admonition('attention') + depart_attention = _depart_named_admonition + visit_caution = _make_visit_admonition('caution') + depart_caution = _depart_named_admonition + visit_danger = _make_visit_admonition('danger') + depart_danger = _depart_named_admonition + visit_error = _make_visit_admonition('error') + depart_error = _depart_named_admonition + visit_hint = _make_visit_admonition('hint') + depart_hint = _depart_named_admonition + visit_important = _make_visit_admonition('important') + depart_important = _depart_named_admonition + visit_note = _make_visit_admonition('note') + depart_note = _depart_named_admonition + visit_tip = _make_visit_admonition('tip') + depart_tip = _depart_named_admonition + visit_warning = _make_visit_admonition('warning') + depart_warning = _depart_named_admonition + + def visit_versionmodified(self, node): + intro = versionlabels[node['type']] % node['version'] + if node.children: + intro += ': ' + else: + intro += '.' + self.body.append(intro) + def depart_versionmodified(self, node): + pass + + def visit_target(self, node): + def add_target(id): + # indexing uses standard LaTeX index markup, so the targets + # will be generated differently + if not id.startswith('index-'): + self.body.append(r'\hypertarget{%s}{}' % id) + + if node.has_key('refid') and node['refid'] not in self.written_ids: + parindex = node.parent.index(node) + try: + next = node.parent[parindex+1] + if isinstance(next, nodes.section): + self.next_section_target = node['refid'] + return + except IndexError: + pass + add_target(node['refid']) + self.written_ids.add(node['refid']) + def depart_target(self, node): + pass + + def visit_attribution(self, node): + self.body.append('\n\\begin{flushright}\n') + self.body.append('---') + def depart_attribution(self, node): + self.body.append('\n\\end{flushright}\n') + + def visit_index(self, node, scre=re.compile(r';\s*')): + entries = node['entries'] + for type, string, tid, _ in entries: + if type == 'single': + self.body.append(r'\index{%s}' % scre.sub('!', self.encode(string))) + elif type == 'pair': + parts = tuple(self.encode(x.strip()) for x in string.split(';', 1)) + self.body.append(r'\indexii{%s}{%s}' % parts) + elif type == 'triple': + parts = tuple(self.encode(x.strip()) for x in string.split(';', 2)) + self.body.append(r'\indexiii{%s}{%s}{%s}' % parts) + else: + self.builder.warn('unknown index entry type %s found' % type) + raise nodes.SkipNode + + def visit_raw(self, node): + if 'latex' in node.get('format', '').split(): + self.body.append(node.astext()) + raise nodes.SkipNode + + def visit_reference(self, node): + uri = node.get('refuri', '') + if self.in_title or not uri: + self.context.append('') + elif uri.startswith('mailto:') or uri.startswith('http:') or \ + uri.startswith('https:') or uri.startswith('ftp:'): + self.body.append('\\href{%s}{' % self.encode(uri)) + self.context.append('}') + elif uri.startswith('#'): + self.body.append('\\hyperlink{%s}{' % uri[1:]) + self.context.append('}') + elif uri.startswith('@token'): + if self.in_production_list: + self.body.append('\\token{') + else: + self.body.append('\\grammartoken{') + self.context.append('}') + else: + self.builder.warn('unusable reference target found: %s' % uri) + self.context.append('') + def depart_reference(self, node): + self.body.append(self.context.pop()) + + def visit_pending_xref(self, node): + pass + def depart_pending_xref(self, node): + pass + + def visit_emphasis(self, node): + self.body.append(r'\emph{') + def depart_emphasis(self, node): + self.body.append('}') + + def visit_literal_emphasis(self, node): + self.body.append(r'\emph{\texttt{') + self.no_contractions += 1 + def depart_literal_emphasis(self, node): + self.body.append('}}') + self.no_contractions -= 1 + + def visit_strong(self, node): + self.body.append(r'\textbf{') + def depart_strong(self, node): + self.body.append('}') + + def visit_title_reference(self, node): + self.body.append(r'\emph{') + def depart_title_reference(self, node): + self.body.append('}') + + def visit_citation(self, node): + # TODO maybe use cite bibitems + self.bibitems.append(['', '']) + self.context.append(len(self.body)) + def depart_citation(self, node): + size = self.context.pop() + text = ''.join(self.body[size:]) + del self.body[size:] + self.bibitems[-1][1] = text + + def visit_citation_reference(self, node): + citeid = node.astext() + self.body.append('\\cite{%s}' % citeid) + raise nodes.SkipNode + + def visit_literal(self, node): + content = self.encode(node.astext().strip()) + if self.in_title: + self.body.append(r'\texttt{%s}' % content) + elif node.has_key('role') and node['role'] == 'samp': + self.body.append(r'\samp{%s}' % content) + else: + self.body.append(r'\code{%s}' % content) + raise nodes.SkipNode + + def visit_footnote_reference(self, node): + num = node.astext().strip() + try: + fn = self.footnotestack[-1][num] + except (KeyError, IndexError): + raise nodes.SkipNode + self.body.append('\\footnote{') + fn.walkabout(self) + raise nodes.SkipChildren + def depart_footnote_reference(self, node): + self.body.append('}') + + def visit_literal_block(self, node): + self.verbatim = '' + def depart_literal_block(self, node): + code = self.verbatim.rstrip('\n') + lang = self.highlightlang + linenos = code.count('\n') >= self.highlightlinenothreshold - 1 + if node.has_key('language'): + # code-block directives + lang = node['language'] + if node.has_key('linenos'): + linenos = node['linenos'] + hlcode = self.highlighter.highlight_block(code, lang, linenos) + # workaround for Unicode issue + hlcode = hlcode.replace(u'€', u'@texteuro[]') + # must use original Verbatim environment and "tabular" environment + if self.table: + hlcode = hlcode.replace('\\begin{Verbatim}', + '\\begin{OriginalVerbatim}') + self.table.has_verbatim = True + # get consistent trailer + hlcode = hlcode.rstrip()[:-14] # strip \end{Verbatim} + hlcode = hlcode.rstrip() + '\n' + self.body.append('\n' + hlcode + '\\end{%sVerbatim}\n' % + (self.table and 'Original' or '')) + self.verbatim = None + visit_doctest_block = visit_literal_block + depart_doctest_block = depart_literal_block + + def visit_line_block(self, node): + """line-block: + * whitespace (including linebreaks) is significant + * inline markup is supported. + * serif typeface + """ + self.body.append('{\\raggedright{}') + self.literal_whitespace = 1 + def depart_line_block(self, node): + self.literal_whitespace = 0 + # remove the last \\ + del self.body[-1] + self.body.append('}\n') + + def visit_line(self, node): + self._line_start = len(self.body) + def depart_line(self, node): + if self._line_start == len(self.body): + # no output in this line -- add a nonbreaking space, else the + # \\ command will give an error + self.body.append('~') + if self.table is not None: + self.body.append('\\newline\n') + else: + self.body.append('\\\\\n') + + def visit_block_quote(self, node): + # If the block quote contains a single object and that object + # is a list, then generate a list not a block quote. + # This lets us indent lists. + done = 0 + if len(node.children) == 1: + child = node.children[0] + if isinstance(child, nodes.bullet_list) or \ + isinstance(child, nodes.enumerated_list): + done = 1 + if not done: + self.body.append('\\begin{quote}\n') + def depart_block_quote(self, node): + done = 0 + if len(node.children) == 1: + child = node.children[0] + if isinstance(child, nodes.bullet_list) or \ + isinstance(child, nodes.enumerated_list): + done = 1 + if not done: + self.body.append('\\end{quote}\n') + + # option node handling copied from docutils' latex writer + + def visit_option(self, node): + if self.context[-1]: + # this is not the first option + self.body.append(', ') + def depart_option(self, node): + # flag that the first option is done. + self.context[-1] += 1 + + def visit_option_argument(self, node): + """The delimiter betweeen an option and its argument.""" + self.body.append(node.get('delimiter', ' ')) + def depart_option_argument(self, node): + pass + + def visit_option_group(self, node): + self.body.append('\\item [') + # flag for first option + self.context.append(0) + def depart_option_group(self, node): + self.context.pop() # the flag + self.body.append('] ') + + def visit_option_list(self, node): + self.body.append('\\begin{optionlist}{3cm}\n') + def depart_option_list(self, node): + self.body.append('\\end{optionlist}\n') + + def visit_option_list_item(self, node): + pass + def depart_option_list_item(self, node): + pass + + def visit_option_string(self, node): + ostring = node.astext() + self.body.append(self.encode(ostring.replace('--', u'-{-}'))) + raise nodes.SkipNode + + def visit_description(self, node): + self.body.append( ' ' ) + def depart_description(self, node): + pass + + def visit_superscript(self, node): + self.body.append('$^{\\text{') + def depart_superscript(self, node): + self.body.append('}}$') + + def visit_subscript(self, node): + self.body.append('$_{\\text{') + def depart_subscript(self, node): + self.body.append('}}$') + + def visit_substitution_definition(self, node): + raise nodes.SkipNode + + def visit_substitution_reference(self, node): + raise nodes.SkipNode + + def visit_generated(self, node): + pass + def depart_generated(self, node): + pass + + def visit_compound(self, node): + pass + def depart_compound(self, node): + pass + + def visit_container(self, node): + pass + def depart_container(self, node): + pass + + def visit_decoration(self, node): + pass + def depart_decoration(self, node): + pass + + # text handling + + def encode(self, text): + text = unicode(text).translate(tex_escape_map) + if self.literal_whitespace: + # Insert a blank before the newline, to avoid + # ! LaTeX Error: There's no line here to end. + text = text.replace(u'\n', u'~\\\\\n').replace(u' ', u'~') + if self.no_contractions: + text = text.replace('--', u'-{-}') + return text + + def visit_Text(self, node): + if self.verbatim is not None: + self.verbatim += node.astext() + else: + text = self.encode(node.astext()) + self.body.append(educateQuotesLatex(text)) + def depart_Text(self, node): + pass + + def visit_comment(self, node): + raise nodes.SkipNode + + def visit_meta(self, node): + # only valid for HTML + raise nodes.SkipNode + + def visit_system_message(self, node): + pass + def depart_system_message(self, node): + self.body.append('\n') + + def unknown_visit(self, node): + raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py new file mode 100644 index 00000000..74c637ca --- /dev/null +++ b/sphinx/writers/text.py @@ -0,0 +1,679 @@ +# -*- coding: utf-8 -*- +""" + sphinx.writers.text + ~~~~~~~~~~~~~~~~~~~ + + Custom docutils writer for plain text. + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" + +import re +import textwrap + +from docutils import nodes, writers + +from sphinx import addnodes +from sphinx.locale import admonitionlabels, versionlabels + + +class TextWriter(writers.Writer): + supported = ('text',) + settings_spec = ('No options here.', '', ()) + settings_defaults = {} + + output = None + + def __init__(self, builder): + writers.Writer.__init__(self) + self.builder = builder + + def translate(self): + visitor = TextTranslator(self.document, self.builder) + self.document.walkabout(visitor) + self.output = visitor.body + +# monkey-patch... +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 +textwrap.TextWrapper.wordsep_re = new_wordsep_re + +MAXWIDTH = 70 +STDINDENT = 3 + + +class TextTranslator(nodes.NodeVisitor): + sectionchars = '*=-~"+' + + def __init__(self, document, builder): + nodes.NodeVisitor.__init__(self, document) + + self.states = [[]] + self.stateindent = [0] + self.sectionlevel = 0 + self.table = None + + def add_text(self, text): + self.states[-1].append((-1, text)) + def new_state(self, indent=STDINDENT): + self.states.append([]) + self.stateindent.append(indent) + def end_state(self, wrap=True, end=[''], first=None): + content = self.states.pop() + maxindent = sum(self.stateindent) + indent = self.stateindent.pop() + result = [] + toformat = [] + def do_format(): + if not toformat: + return + if wrap: + res = textwrap.wrap(''.join(toformat), width=MAXWIDTH-maxindent) + else: + res = ''.join(toformat).splitlines() + if end: + res += end + result.append((indent, res)) + for itemindent, item in content: + if itemindent == -1: + toformat.append(item) + else: + do_format() + result.append((indent + itemindent, item)) + toformat = [] + do_format() + if first is not None and result: + itemindent, item = result[0] + if item: + result.insert(0, (itemindent - indent, [first + item[0]])) + result[1] = (itemindent, item[1:]) + self.states[-1].extend(result) + + def visit_document(self, node): + self.new_state(0) + def depart_document(self, node): + self.end_state() + self.body = '\n'.join(line and (' '*indent + line) + for indent, lines in self.states[0] + for line in lines) + # XXX header/footer? + + def visit_highlightlang(self, node): + raise nodes.SkipNode + + def visit_section(self, node): + self._title_char = self.sectionchars[self.sectionlevel] + self.sectionlevel += 1 + def depart_section(self, node): + self.sectionlevel -= 1 + + def visit_topic(self, node): + self.new_state(0) + def depart_topic(self, node): + self.end_state() + + visit_sidebar = visit_topic + depart_sidebar = depart_topic + + def visit_rubric(self, node): + self.new_state(0) + self.add_text('-[ ') + def depart_rubric(self, node): + self.add_text(' ]-') + self.end_state() + + def visit_compound(self, node): + pass + def depart_compound(self, node): + pass + + def visit_glossary(self, node): + pass + def depart_glossary(self, node): + pass + + def visit_title(self, node): + if isinstance(node.parent, nodes.Admonition): + self.add_text(node.astext()+': ') + raise nodes.SkipNode + self.new_state(0) + def depart_title(self, node): + if isinstance(node.parent, nodes.section): + char = self._title_char + else: + char = '^' + text = ''.join(x[1] for x in self.states.pop() if x[0] == -1) + self.stateindent.pop() + self.states[-1].append((0, ['', text, '%s' % (char * len(text)), ''])) + + def visit_subtitle(self, node): + pass + def depart_subtitle(self, node): + pass + + def visit_attribution(self, node): + self.add_text('-- ') + def depart_attribution(self, node): + pass + + def visit_module(self, node): + if node.has_key('platform'): + self.new_state(0) + self.add_text(_('Platform: %s') % node['platform']) + self.end_state() + raise nodes.SkipNode + + def visit_desc(self, node): + pass + def depart_desc(self, node): + pass + + def visit_desc_signature(self, node): + self.new_state(0) + if node.parent['desctype'] in ('class', 'exception'): + self.add_text('%s ' % node.parent['desctype']) + def depart_desc_signature(self, node): + # XXX: wrap signatures in a way that makes sense + self.end_state(wrap=False, end=None) + + def visit_desc_name(self, node): + pass + def depart_desc_name(self, node): + pass + + def visit_desc_addname(self, node): + pass + def depart_desc_addname(self, node): + pass + + def visit_desc_type(self, node): + pass + def depart_desc_type(self, node): + pass + + def visit_desc_parameterlist(self, node): + self.add_text('(') + self.first_param = 1 + def depart_desc_parameterlist(self, node): + self.add_text(')') + + def visit_desc_parameter(self, node): + if not self.first_param: + self.add_text(', ') + else: + self.first_param = 0 + self.add_text(node.astext()) + raise nodes.SkipNode + + def visit_desc_optional(self, node): + self.add_text('[') + def depart_desc_optional(self, node): + self.add_text(']') + + def visit_desc_annotation(self, node): + pass + def depart_desc_annotation(self, node): + pass + + def visit_refcount(self, node): + pass + def depart_refcount(self, node): + pass + + def visit_desc_content(self, node): + self.new_state() + self.add_text('\n') + def depart_desc_content(self, node): + self.end_state() + + def visit_figure(self, node): + self.new_state() + def depart_figure(self, node): + self.end_state() + + def visit_caption(self, node): + pass + def depart_caption(self, node): + pass + + def visit_productionlist(self, node): + self.new_state() + names = [] + for production in node: + names.append(production['tokenname']) + maxlen = max(len(name) for name in names) + for production in node: + if production['tokenname']: + self.add_text(production['tokenname'].ljust(maxlen) + ' ::=') + lastname = production['tokenname'] + else: + self.add_text('%s ' % (' '*len(lastname))) + self.add_text(production.astext() + '\n') + self.end_state(wrap=False) + raise nodes.SkipNode + + def visit_seealso(self, node): + self.new_state() + def depart_seealso(self, node): + self.end_state(first='') + + def visit_footnote(self, node): + self._footnote = node.children[0].astext().strip() + self.new_state(len(self._footnote) + 3) + def depart_footnote(self, node): + self.end_state(first='[%s] ' % self._footnote) + + def visit_citation(self, node): + if len(node) and isinstance(node[0], nodes.label): + self._citlabel = node[0].astext() + else: + self._citlabel = '' + self.new_state(len(self._citlabel) + 3) + def depart_citation(self, node): + self.end_state(first='[%s] ' % self._citlabel) + + def visit_label(self, node): + raise nodes.SkipNode + + # XXX: option list could use some better styling + + def visit_option_list(self, node): + pass + def depart_option_list(self, node): + pass + + def visit_option_list_item(self, node): + self.new_state(0) + def depart_option_list_item(self, node): + self.end_state() + + def visit_option_group(self, node): + self._firstoption = True + def depart_option_group(self, node): + self.add_text(' ') + + def visit_option(self, node): + if self._firstoption: + self._firstoption = False + else: + self.add_text(', ') + def depart_option(self, node): + pass + + def visit_option_string(self, node): + pass + def depart_option_string(self, node): + pass + + def visit_option_argument(self, node): + self.add_text(node['delimiter']) + def depart_option_argument(self, node): + pass + + def visit_description(self, node): + pass + def depart_description(self, node): + pass + + def visit_tabular_col_spec(self, node): + raise nodes.SkipNode + + def visit_colspec(self, node): + self.table[0].append(node['colwidth']) + raise nodes.SkipNode + + def visit_tgroup(self, node): + pass + def depart_tgroup(self, node): + pass + + def visit_thead(self, node): + pass + def depart_thead(self, node): + pass + + def visit_tbody(self, node): + self.table.append('sep') + def depart_tbody(self, node): + pass + + def visit_row(self, node): + self.table.append([]) + def depart_row(self, node): + pass + + def visit_entry(self, node): + if node.has_key('morerows') or node.has_key('morecols'): + raise NotImplementedError('Column or row spanning cells are ' + 'not implemented.') + self.new_state(0) + def depart_entry(self, node): + text = '\n'.join('\n'.join(x[1]) for x in self.states.pop()) + self.stateindent.pop() + self.table[-1].append(text) + + def visit_table(self, node): + if self.table: + raise NotImplementedError('Nested tables are not supported.') + self.new_state(0) + self.table = [[]] + def depart_table(self, node): + lines = self.table[1:] + fmted_rows = [] + colwidths = self.table[0] + realwidths = colwidths[:] + separator = 0 + # don't allow paragraphs in table cells for now + for line in lines: + if line == 'sep': + separator = len(fmted_rows) + else: + cells = [] + for i, cell in enumerate(line): + par = textwrap.wrap(cell, width=colwidths[i]) + if par: + maxwidth = max(map(len, par)) + else: + maxwidth = 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.add_text(''.join(out) + '\n') + + 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.add_text(''.join(out) + '\n') + + for i, row in enumerate(fmted_rows): + if separator and i == separator: + writesep('=') + else: + writesep('-') + writerow(row) + writesep('-') + self.table = None + self.end_state(wrap=False) + + def visit_acks(self, node): + self.new_state(0) + self.add_text(', '.join(n.astext() for n in node.children[0].children) + '.') + self.end_state() + raise nodes.SkipNode + + def visit_image(self, node): + self.add_text(_('[image]')) + raise nodes.SkipNode + + def visit_transition(self, node): + indent = sum(self.stateindent) + self.new_state(0) + self.add_text('=' * (MAXWIDTH - indent)) + self.end_state() + raise nodes.SkipNode + + def visit_bullet_list(self, node): + self._list_counter = -1 + def depart_bullet_list(self, node): + pass + + def visit_enumerated_list(self, node): + self._list_counter = 0 + def depart_enumerated_list(self, node): + pass + + def visit_definition_list(self, node): + self._list_counter = -2 + def depart_definition_list(self, node): + pass + + def visit_list_item(self, node): + if self._list_counter == -1: + # bullet list + self.new_state(2) + elif self._list_counter == -2: + # definition list + pass + else: + # enumerated list + self._list_counter += 1 + self.new_state(len(str(self._list_counter)) + 2) + def depart_list_item(self, node): + if self._list_counter == -1: + self.end_state(first='* ', end=None) + elif self._list_counter == -2: + pass + else: + self.end_state(first='%s. ' % self._list_counter, end=None) + + def visit_definition_list_item(self, node): + self._li_has_classifier = len(node) >= 2 and \ + isinstance(node[1], nodes.classifier) + def depart_definition_list_item(self, node): + pass + + def visit_term(self, node): + self.new_state(0) + def depart_term(self, node): + if not self._li_has_classifier: + self.end_state(end=None) + + def visit_classifier(self, node): + self.add_text(' : ') + def depart_classifier(self, node): + self.end_state(end=None) + + def visit_definition(self, node): + self.new_state() + def depart_definition(self, node): + self.end_state() + + def visit_field_list(self, node): + pass + def depart_field_list(self, node): + pass + + def visit_field(self, node): + pass + def depart_field(self, node): + pass + + def visit_field_name(self, node): + self.new_state(0) + def depart_field_name(self, node): + self.add_text(':') + self.end_state(end=None) + + def visit_field_body(self, node): + self.new_state() + def depart_field_body(self, node): + self.end_state() + + def visit_centered(self, node): + pass + def depart_centered(self, node): + pass + + def visit_admonition(self, node): + self.new_state(0) + def depart_admonition(self, node): + self.end_state() + + def _visit_admonition(self, node): + self.new_state(2) + def _make_depart_admonition(name): + def depart_admonition(self, node): + self.end_state(first=admonitionlabels[name] + ': ') + return depart_admonition + + visit_attention = _visit_admonition + depart_attention = _make_depart_admonition('attention') + visit_caution = _visit_admonition + depart_caution = _make_depart_admonition('caution') + visit_danger = _visit_admonition + depart_danger = _make_depart_admonition('danger') + visit_error = _visit_admonition + depart_error = _make_depart_admonition('error') + visit_hint = _visit_admonition + depart_hint = _make_depart_admonition('hint') + visit_important = _visit_admonition + depart_important = _make_depart_admonition('important') + visit_note = _visit_admonition + depart_note = _make_depart_admonition('note') + visit_tip = _visit_admonition + depart_tip = _make_depart_admonition('tip') + visit_warning = _visit_admonition + depart_warning = _make_depart_admonition('warning') + + def visit_versionmodified(self, node): + self.new_state(0) + if node.children: + self.add_text(versionlabels[node['type']] % node['version'] + ': ') + else: + self.add_text(versionlabels[node['type']] % node['version'] + '.') + def depart_versionmodified(self, node): + self.end_state() + + def visit_literal_block(self, node): + self.new_state() + def depart_literal_block(self, node): + self.end_state(wrap=False) + + def visit_doctest_block(self, node): + self.new_state(0) + def depart_doctest_block(self, node): + self.end_state(wrap=False) + + def visit_line_block(self, node): + self.new_state(0) + def depart_line_block(self, node): + self.end_state(wrap=False) + + def visit_line(self, node): + pass + def depart_line(self, node): + pass + + def visit_block_quote(self, node): + self.new_state() + def depart_block_quote(self, node): + self.end_state() + + def visit_compact_paragraph(self, node): + pass + def depart_compact_paragraph(self, node): + pass + + def visit_paragraph(self, node): + if not isinstance(node.parent, nodes.Admonition) or \ + isinstance(node.parent, addnodes.seealso): + self.new_state(0) + def depart_paragraph(self, node): + if not isinstance(node.parent, nodes.Admonition) or \ + isinstance(node.parent, addnodes.seealso): + self.end_state() + + def visit_target(self, node): + raise nodes.SkipNode + + def visit_index(self, node): + raise nodes.SkipNode + + def visit_substitution_definition(self, node): + raise nodes.SkipNode + + def visit_pending_xref(self, node): + pass + def depart_pending_xref(self, node): + pass + + def visit_reference(self, node): + pass + def depart_reference(self, node): + pass + + def visit_emphasis(self, node): + self.add_text('*') + def depart_emphasis(self, node): + self.add_text('*') + + def visit_literal_emphasis(self, node): + self.add_text('*') + def depart_literal_emphasis(self, node): + self.add_text('*') + + def visit_strong(self, node): + self.add_text('**') + def depart_strong(self, node): + self.add_text('**') + + def visit_title_reference(self, node): + self.add_text('*') + def depart_title_reference(self, node): + self.add_text('*') + + def visit_literal(self, node): + self.add_text('``') + def depart_literal(self, node): + self.add_text('``') + + def visit_subscript(self, node): + self.add_text('_') + def depart_subscript(self, node): + pass + + def visit_superscript(self, node): + self.add_text('^') + def depart_superscript(self, node): + pass + + def visit_footnote_reference(self, node): + self.add_text('[%s]' % node.astext()) + raise nodes.SkipNode + + def visit_citation_reference(self, node): + self.add_text('[%s]' % node.astext()) + raise nodes.SkipNode + + def visit_Text(self, node): + self.add_text(node.astext()) + def depart_Text(self, node): + pass + + def visit_problematic(self, node): + self.add_text('>>') + def depart_problematic(self, node): + self.add_text('<<') + + def visit_system_message(self, node): + self.new_state(0) + self.add_text('' % node.astext()) + self.end_state() + raise nodes.SkipNode + + def visit_comment(self, node): + raise nodes.SkipNode + + def visit_meta(self, node): + # only valid for HTML + raise nodes.SkipNode + + def unknown_visit(self, node): + raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/tests/test_build.py b/tests/test_build.py index 8ca17938..0443aada 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -20,7 +20,7 @@ from util import * from etree13 import ElementTree as ET from sphinx.builder import StandaloneHTMLBuilder, LaTeXBuilder -from sphinx.latexwriter import LaTeXTranslator +from sphinx.writers.latex import LaTeXTranslator html_warnfile = StringIO() diff --git a/tests/test_markup.py b/tests/test_markup.py index f1125103..a4b7cf77 100644 --- a/tests/test_markup.py +++ b/tests/test_markup.py @@ -17,8 +17,8 @@ from docutils import frontend, utils, nodes from docutils.parsers import rst from sphinx import addnodes -from sphinx.htmlwriter import HTMLWriter, SmartyPantsHTMLTranslator -from sphinx.latexwriter import LaTeXWriter, LaTeXTranslator +from sphinx.writers.html import HTMLWriter, SmartyPantsHTMLTranslator +from sphinx.writers.latex import LaTeXWriter, LaTeXTranslator def setup_module(): global app, settings, parser -- cgit v1.2.1 From f8f41e1341f4aeb4458f74e4e4e47833210abdcb Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 29 Nov 2008 20:03:56 +0100 Subject: This is version 0.6. --- sphinx/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 2df41707..9a41d4a0 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -13,8 +13,8 @@ import sys from os import path __revision__ = '$Revision$' -__version__ = '0.5' -__released__ = '0.5' +__version__ = '0.6' +__released__ = '0.6 (hg)' package_dir = path.abspath(path.dirname(__file__)) -- cgit v1.2.1 From e9c79382e51d6aca7600addf51c53c4bb0344196 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 29 Nov 2008 20:04:11 +0100 Subject: Some more fixes after the great renaming. --- doc/builders.rst | 8 +++++++- doc/config.rst | 6 +++--- doc/ext/appapi.rst | 2 +- doc/ext/builderapi.rst | 2 +- doc/glossary.rst | 2 +- doc/templating.rst | 4 ++-- sphinx/ext/coverage.py | 2 +- sphinx/ext/doctest.py | 2 +- 8 files changed, 17 insertions(+), 11 deletions(-) diff --git a/doc/builders.rst b/doc/builders.rst index 508ab3c5..dd07a96a 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -3,7 +3,7 @@ Available builders ================== -.. module:: sphinx.builder +.. module:: sphinx.builders :synopsis: Available built-in builder classes. These are the built-in Sphinx builders. More builders can be added by @@ -13,6 +13,7 @@ The builder's "name" must be given to the **-b** command-line option of :program:`sphinx-build` to select a builder. +.. module:: sphinx.builders.html .. class:: StandaloneHTMLBuilder This is the standard HTML builder. Its output is a directory with HTML @@ -30,6 +31,7 @@ The builder's "name" must be given to the **-b** command-line option of Its name is ``htmlhelp``. +.. module:: sphinx.builders.latex .. class:: LaTeXBuilder This builder produces a bunch of LaTeX files in the output directory. You @@ -50,6 +52,7 @@ The builder's "name" must be given to the **-b** command-line option of Its name is ``latex``. +.. module:: sphinx.builders.text .. class:: TextBuilder This builder produces a text file for each reST file -- this is almost the @@ -60,6 +63,7 @@ The builder's "name" must be given to the **-b** command-line option of .. versionadded:: 0.4 +.. currentmodule:: sphinx.builders.html .. class:: SerializingHTMLBuilder This builder uses a module that implements the Python serialization API @@ -135,6 +139,7 @@ The builder's "name" must be given to the **-b** command-line option of .. versionadded:: 0.5 +.. module:: sphinx.builders.changes .. class:: ChangesBuilder This builder produces an HTML overview of all :dir:`versionadded`, @@ -144,6 +149,7 @@ The builder's "name" must be given to the **-b** command-line option of Its name is ``changes``. +.. module:: sphinx.builders.linkcheck .. class:: CheckExternalLinksBuilder This builder scans all documents for external links, tries to open them with diff --git a/doc/config.rst b/doc/config.rst index 819bf468..78671b68 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -22,8 +22,8 @@ Important points to note: * The term "fully-qualified name" refers to a string that names an importable Python object inside a module; for example, the FQN - ``"sphinx.builder.Builder"`` means the ``Builder`` class in the - ``sphinx.builder`` module. + ``"sphinx.builders.Builder"`` means the ``Builder`` class in the + ``sphinx.builders`` module. * Remember that document names use ``/`` as the path separator and don't contain the file name extension. @@ -412,7 +412,7 @@ that use Sphinx' HTMLWriter class. .. confval:: html_translator_class A string with the fully-qualified name of a HTML Translator class, that is, a - subclass of Sphinx' :class:`~sphinx.htmlwriter.HTMLTranslator`, that is used + subclass of Sphinx' :class:`~sphinx.writers.html.HTMLTranslator`, that is used to translate document trees to HTML. Default is ``None`` (use the builtin translator). diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index fcc29e38..355e42bd 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -13,7 +13,7 @@ the following public API: .. method:: Sphinx.add_builder(builder) Register a new builder. *builder* must be a class that inherits from - :class:`~sphinx.builder.Builder`. + :class:`~sphinx.builders.Builder`. .. method:: Sphinx.add_config_value(name, default, rebuild_env) diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst index adc41016..72c388fb 100644 --- a/doc/ext/builderapi.rst +++ b/doc/ext/builderapi.rst @@ -5,7 +5,7 @@ Writing new builders .. todo:: Expand this. -.. currentmodule:: sphinx.builder +.. currentmodule:: sphinx.builders .. class:: Builder diff --git a/doc/glossary.rst b/doc/glossary.rst index 6a80ad36..7ec787ff 100644 --- a/doc/glossary.rst +++ b/doc/glossary.rst @@ -6,7 +6,7 @@ Glossary .. glossary:: builder - A class (inheriting from :class:`~sphinx.builder.Builder`) that takes + A class (inheriting from :class:`~sphinx.builders.Builder`) that takes parsed documents and performs an action on them. Normally, builders translate the documents to an output format, but it is also possible to use the builder builders that e.g. check for broken links in the diff --git a/doc/templating.rst b/doc/templating.rst index 61a8a72b..fa6f2682 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -19,10 +19,10 @@ No. You have several other options: configuration value accordingly. * You can :ref:`write a custom builder ` that derives from - :class:`~sphinx.builder.StandaloneHTMLBuilder` and calls your template engine + :class:`~sphinx.builders.StandaloneHTMLBuilder` and calls your template engine of choice. -* You can use the :class:`~sphinx.builder.PickleHTMLBuilder` that produces +* You can use the :class:`~sphinx.builders.PickleHTMLBuilder` that produces pickle files with the page contents, and postprocess them using a custom tool, or use them in your Web application. diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py index f03dbc1e..dfe01419 100644 --- a/sphinx/ext/coverage.py +++ b/sphinx/ext/coverage.py @@ -16,7 +16,7 @@ import inspect import cPickle as pickle from os import path -from sphinx.builder import Builder +from sphinx.builders import Builder # utility diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index badd50ff..aa38bc71 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -21,7 +21,7 @@ doctest = __import__('doctest') from docutils import nodes from docutils.parsers.rst import directives -from sphinx.builder import Builder +from sphinx.builders import Builder from sphinx.util.console import bold blankline_re = re.compile(r'^\s*', re.MULTILINE) -- cgit v1.2.1 From 229d3eb16b0c949ec87c21555345a83087317fe7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 30 Nov 2008 16:33:56 +0100 Subject: Allow giving values for dict type config values in the overrides. --- CHANGES | 12 ++++++++++++ doc/intro.rst | 8 ++++++-- sphinx/config.py | 6 ++++++ tests/test_config.py | 4 +++- 4 files changed, 27 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index 63321df1..5d9bc20c 100644 --- a/CHANGES +++ b/CHANGES @@ -1,3 +1,15 @@ +Release 0.6 (in development) +============================ + +New features added +------------------ + +* Other changes: + + - Allow giving config overrides for single dict keys on the command + line. + + Release 0.5 (Nov 23, 2008) -- Birthday release! =============================================== diff --git a/doc/intro.rst b/doc/intro.rst index 47e016b3..7ce9d1fa 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -111,8 +111,12 @@ The :program:`sphinx-build` script has several more options: .. versionadded:: 0.5 **-D** *setting=value* - Override a configuration value set in the :file:`conf.py` file. (The value - must be a string value.) + Override a configuration value set in the :file:`conf.py` file. The value + must be a string or dictionary value. For the latter, supply the setting + name and key like this: ``-D latex_elements.docclass=scrartcl``. + + .. versionchanged:: 0.6 + The value can now be a dictionary value. **-A** *name=value* Make the *name* assigned to *value* in the HTML templates. diff --git a/sphinx/config.py b/sphinx/config.py index fa04ac2a..a9cae4cd 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -111,6 +111,12 @@ class Config(object): def init_values(self): config = self._raw_config + for valname, value in self.overrides.iteritems(): + if '.' in valname: + realvalname, key = valname.split('.', 1) + config.setdefault(realvalname, {})[key] = value + else: + config[valname] = value config.update(self.overrides) for name in config: if name in self.values: diff --git a/tests/test_config.py b/tests/test_config.py index 57d1936b..53cba59c 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -15,7 +15,8 @@ from util import * from sphinx.application import ExtensionError -@with_app(confoverrides={'master_doc': 'master', 'nonexisting_value': 'True'}) +@with_app(confoverrides={'master_doc': 'master', 'nonexisting_value': 'True', + 'latex_elements.docclass': 'scrartcl'}) def test_core_config(app): cfg = app.config @@ -26,6 +27,7 @@ def test_core_config(app): # overrides assert cfg.master_doc == 'master' + assert cfg.latex_elements['docclass'] == 'scrartcl' # simple default values assert 'exclude_dirs' not in cfg.__dict__ -- cgit v1.2.1 From 4b201975a442d45a3ae5118a38c3baa07940f9b3 Mon Sep 17 00:00:00 2001 From: mitsuhiko Date: Sun, 30 Nov 2008 19:55:59 +0100 Subject: Changed an `__import__` call in the highlighter module because that trigger a bug in the python importer. --- sphinx/highlighting.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/highlighting.py b/sphinx/highlighting.py index 1637b2c3..3017133a 100644 --- a/sphinx/highlighting.py +++ b/sphinx/highlighting.py @@ -89,7 +89,7 @@ class PygmentsBridge(object): style = SphinxStyle elif '.' in stylename: module, stylename = stylename.rsplit('.', 1) - style = getattr(__import__(module, None, None, ['']), stylename) + style = getattr(__import__(module, None, None, ['__name__']), stylename) else: style = get_style_by_name(stylename) self.hfmter = {False: HtmlFormatter(style=style), -- cgit v1.2.1 From 0647cdecb439fa4dfd9bbdf094409e262cf33483 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 30 Nov 2008 19:58:29 +0100 Subject: Add Sphinx.add_lexer(). --- CHANGES | 4 ++++ doc/ext/appapi.rst | 7 +++++++ sphinx/application.py | 6 ++++++ sphinx/highlighting.py | 1 + tests/test_highlighting.py | 37 +++++++++++++++++++++++++++++++++++++ 5 files changed, 55 insertions(+) create mode 100644 tests/test_highlighting.py diff --git a/CHANGES b/CHANGES index 5d9bc20c..b45ce66c 100644 --- a/CHANGES +++ b/CHANGES @@ -4,6 +4,10 @@ Release 0.6 (in development) New features added ------------------ +* Extension API: + + - Add Sphinx.add_lexer() to add custom Pygments lexers. + * Other changes: - Allow giving config overrides for single dict keys on the command diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 355e42bd..3dd5282b 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -167,6 +167,13 @@ the following public API: :confval:`the docs for the config value `. .. versionadded:: 0.5 + +.. method:: Sphinx.add_lexer(alias, lexer) + + Use *lexer*, which must be an instance of a Pygments lexer class, to + highlight code blocks with the given language *alias*. + + .. versionadded:: 0.6 .. method:: Sphinx.connect(event, callback) diff --git a/sphinx/application.py b/sphinx/application.py index 6c644bbe..f7c57592 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -297,6 +297,12 @@ class Sphinx(object): StandaloneHTMLBuilder.script_files.append( posixpath.join('_static', filename)) + def add_lexer(self, alias, lexer): + from sphinx.highlighting import lexers + if lexers is None: + return + lexers[alias] = lexer + class TemplateBridge(object): """ diff --git a/sphinx/highlighting.py b/sphinx/highlighting.py index 3017133a..d85aac23 100644 --- a/sphinx/highlighting.py +++ b/sphinx/highlighting.py @@ -30,6 +30,7 @@ try: from pygments.token import Generic, Comment, Number except ImportError: pygments = None + lexers = None else: class SphinxStyle(Style): """ diff --git a/tests/test_highlighting.py b/tests/test_highlighting.py new file mode 100644 index 00000000..5c353946 --- /dev/null +++ b/tests/test_highlighting.py @@ -0,0 +1,37 @@ +# -*- coding: utf-8 -*- +""" + test_highlighting + ~~~~~~~~~~~~~~~~~ + + Test the Pygments highlighting bridge. + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" + +from util import * + +from pygments.lexer import RegexLexer +from pygments.token import Text, Name + +from sphinx.highlighting import PygmentsBridge + + +class MyLexer(RegexLexer): + name = 'testlexer' + + tokens = { + 'root': [ + ('a', Name), + ('b', Text), + ], + } + + +@with_app() +def test_add_lexer(app): + app.add_lexer('test', MyLexer()) + + bridge = PygmentsBridge('html') + ret = bridge.highlight_block('ab', 'test') + assert 'ab' in ret -- cgit v1.2.1 From c001d82adcbb31d9c392ed5dd77a821f96a0c8db Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 30 Nov 2008 20:29:34 +0100 Subject: Allow using different Pygments formatters. --- sphinx/highlighting.py | 28 ++++++++++++++++++---------- tests/test_highlighting.py | 14 ++++++++++++++ 2 files changed, 32 insertions(+), 10 deletions(-) diff --git a/sphinx/highlighting.py b/sphinx/highlighting.py index d85aac23..927b42d9 100644 --- a/sphinx/highlighting.py +++ b/sphinx/highlighting.py @@ -82,7 +82,12 @@ if sys.version_info < (2, 5): class PygmentsBridge(object): - def __init__(self, dest='html', stylename='sphinx'): + # Set these attributes if you want to have different Pygments formatters + # than the default ones. + html_formatter = HtmlFormatter + latex_formatter = LatexFormatter + + def __init__(self, dest='html', stylename='sphinx', ): self.dest = dest if not pygments: return @@ -93,11 +98,14 @@ class PygmentsBridge(object): style = getattr(__import__(module, None, None, ['__name__']), stylename) else: style = get_style_by_name(stylename) - self.hfmter = {False: HtmlFormatter(style=style), - True: HtmlFormatter(style=style, linenos=True)} - self.lfmter = {False: LatexFormatter(style=style, commandprefix='PYG'), - True: LatexFormatter(style=style, linenos=True, - commandprefix='PYG')} + if dest == 'html': + self.fmter = {False: self.html_formatter(style=style), + True: self.html_formatter(style=style, linenos=True)} + else: + self.fmter = {False: self.latex_formatter(style=style, + commandprefix='PYG'), + True: self.latex_formatter(style=style, linenos=True, + commandprefix='PYG')} def unhighlighted(self, source): if self.dest == 'html': @@ -171,9 +179,9 @@ class PygmentsBridge(object): lexer.add_filter('raiseonerror') try: if self.dest == 'html': - return highlight(source, lexer, self.hfmter[bool(linenos)]) + return highlight(source, lexer, self.fmter[bool(linenos)]) else: - hlsource = highlight(source, lexer, self.lfmter[bool(linenos)]) + hlsource = highlight(source, lexer, self.fmter[bool(linenos)]) return hlsource.translate(tex_hl_escape_map) except ErrorToken: # this is most probably not the selected language, @@ -187,9 +195,9 @@ class PygmentsBridge(object): # no HTML styles needed return '' if self.dest == 'html': - return self.hfmter[0].get_style_defs() + return self.fmter[0].get_style_defs() else: - styledefs = self.lfmter[0].get_style_defs() + styledefs = self.fmter[0].get_style_defs() # workaround for Pygments < 0.12 if styledefs.startswith('\\newcommand\\at{@}'): styledefs += _LATEX_STYLES diff --git a/tests/test_highlighting.py b/tests/test_highlighting.py index 5c353946..067c37cb 100644 --- a/tests/test_highlighting.py +++ b/tests/test_highlighting.py @@ -13,6 +13,7 @@ from util import * from pygments.lexer import RegexLexer from pygments.token import Text, Name +from pygments.formatters.html import HtmlFormatter from sphinx.highlighting import PygmentsBridge @@ -27,6 +28,10 @@ class MyLexer(RegexLexer): ], } +class MyFormatter(HtmlFormatter): + def format(self, tokensource, outfile): + outfile.write('test') + @with_app() def test_add_lexer(app): @@ -35,3 +40,12 @@ def test_add_lexer(app): bridge = PygmentsBridge('html') ret = bridge.highlight_block('ab', 'test') assert 'ab' in ret + +def test_set_formatter(): + PygmentsBridge.html_formatter = MyFormatter + try: + bridge = PygmentsBridge('html') + ret = bridge.highlight_block('foo', 'python') + assert ret == 'test' + finally: + PygmentsBridge.html_formatter = HtmlFormatter -- cgit v1.2.1 From f1bd7914bd3fb656b58e7bf72d64bec06f3034d7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 30 Nov 2008 20:38:59 +0100 Subject: Add html_add_permalinks config value. --- CHANGES | 13 ++++++++++--- doc/config.rst | 9 +++++++++ sphinx/builders/html.py | 3 +-- sphinx/builders/htmlhelp.py | 3 +-- sphinx/config.py | 1 + sphinx/writers/html.py | 5 +++-- 6 files changed, 25 insertions(+), 9 deletions(-) diff --git a/CHANGES b/CHANGES index b45ce66c..bf865f60 100644 --- a/CHANGES +++ b/CHANGES @@ -4,14 +4,21 @@ Release 0.6 (in development) New features added ------------------ +* Configuration: + + - The new ``html_add_permalinks`` config value can be used to + switch off the generated "paragraph sign" permalinks for each + heading and definition environment. + * Extension API: - - Add Sphinx.add_lexer() to add custom Pygments lexers. + - There is now a Sphinx.add_lexer() method to add custom Pygments + lexers. * Other changes: - - Allow giving config overrides for single dict keys on the command - line. + - Config overrides for single dict keys can now be given on the + command line. Release 0.5 (Nov 23, 2008) -- Birthday release! diff --git a/doc/config.rst b/doc/config.rst index 78671b68..b6c33460 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -332,6 +332,15 @@ that use Sphinx' HTMLWriter class. If true, *SmartyPants* will be used to convert quotes and dashes to typographically correct entities. Default: ``True``. +.. confval:: html_add_permalinks + + If true, Sphinx will add "permalinks" for each heading and description + environment as paragraph signs that become visible when the mouse hovers over + them. Default: ``True``. + + .. versionadded:: 0.6 + Previously, this was always activated. + .. confval:: html_sidebars Custom sidebar templates, must be a dictionary that maps document names to diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index adf58be1..7592dced 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -53,8 +53,7 @@ class StandaloneHTMLBuilder(Builder): supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', 'image/jpeg'] searchindex_filename = 'searchindex.js' - add_header_links = True - add_definition_links = True + add_permalinks = True # This is a class attribute because it is mutated by Sphinx.add_javascript. script_files = ['_static/jquery.js', '_static/doctools.js'] diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py index 23900f36..20bb0d5c 100644 --- a/sphinx/builders/htmlhelp.py +++ b/sphinx/builders/htmlhelp.py @@ -132,8 +132,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): supported_image_types = ['image/png', 'image/gif', 'image/jpeg'] # don't add links - add_header_links = False - add_definition_links = False + add_permalinks = False def init(self): StandaloneHTMLBuilder.init(self) diff --git a/sphinx/config.py b/sphinx/config.py index a9cae4cd..1ea5f66f 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -65,6 +65,7 @@ class Config(object): html_sidebars = ({}, False), html_additional_pages = ({}, False), html_use_modindex = (True, False), + html_add_permalinks = (True, False), html_use_index = (True, False), html_split_index = (False, False), html_copy_source = (True, False), diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index b82d7ccc..1b9205ce 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -58,6 +58,7 @@ class HTMLTranslator(BaseTranslator): self.highlightlang = builder.config.highlight_language self.highlightlinenothreshold = sys.maxint self.protect_literal_text = 0 + self.add_permalinks = builder.config.html_add_permalinks def visit_desc(self, node): self.body.append(self.starttag(node, 'dl', CLASS=node['desctype'])) @@ -73,7 +74,7 @@ class HTMLTranslator(BaseTranslator): if node.parent['desctype'] in ('class', 'exception'): self.body.append('%s ' % node.parent['desctype']) def depart_desc_signature(self, node): - if node['ids'] and self.builder.add_definition_links: + if node['ids'] and self.add_permalinks and self.builder.add_permalinks: self.body.append(u'\u00B6' % _('Permalink to this definition')) @@ -388,7 +389,7 @@ class HTMLTranslator(BaseTranslator): def depart_title(self, node): close_tag = self.context[-1] - if self.builder.add_header_links and \ + if self.add_permalinks and self.builder.add_permalinks and \ (close_tag.startswith(' Date: Fri, 5 Dec 2008 12:26:40 +0100 Subject: Fix #69: a "self" too much. --- sphinx/builders/htmlhelp.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py index 20bb0d5c..b1c7fbc5 100644 --- a/sphinx/builders/htmlhelp.py +++ b/sphinx/builders/htmlhelp.py @@ -140,7 +140,7 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): self.out_suffix = '.html' def handle_finish(self): - self.build_hhx(self, self.outdir, self.config.htmlhelp_basename) + self.build_hhx(self.outdir, self.config.htmlhelp_basename) def build_hhx(self, outdir, outname): self.info('dumping stopword list...') -- cgit v1.2.1 From 41cdb9e79dd86a337e8978c80d2af0938758ac0c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 5 Dec 2008 12:27:08 +0100 Subject: Fix #64: import error in intersphinx. --- sphinx/ext/intersphinx.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/intersphinx.py b/sphinx/ext/intersphinx.py index 5d9607c9..85733ac4 100644 --- a/sphinx/ext/intersphinx.py +++ b/sphinx/ext/intersphinx.py @@ -31,7 +31,7 @@ from os import path from docutils import nodes -from sphinx.builders import INVENTORY_FILENAME +from sphinx.builders.html import INVENTORY_FILENAME def fetch_inventory(app, uri, inv): -- cgit v1.2.1 From 2353c3dbea3b132c00fdfabbcc4c06d0decc35d6 Mon Sep 17 00:00:00 2001 From: mitsuhiko Date: Sun, 7 Dec 2008 23:17:29 +0100 Subject: Added better error message for missing roman.py --- sphinx/__init__.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/sphinx/__init__.py b/sphinx/__init__.py index 9a41d4a0..43343ff2 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -31,17 +31,23 @@ def main(argv=sys.argv): errstr = str(err) if errstr.lower().startswith('no module named'): whichmod = errstr[16:] + hint = '' if whichmod.startswith('docutils'): whichmod = 'Docutils library' elif whichmod.startswith('jinja'): whichmod = 'Jinja library' elif whichmod == 'roman': whichmod = 'roman module (which is distributed with Docutils)' + hint = ('This can happen if you upgraded docutils using\n' + 'easy_install without uninstalling the old version' + 'first.') else: whichmod += ' module' print >>sys.stderr, \ 'Error: The %s cannot be found. Did you install Sphinx '\ 'and its dependencies correctly?' % whichmod + if hint: + print >> sys.stderr, hint return 1 raise return cmdline.main(argv) -- cgit v1.2.1 From 03d6c8b26c27a480f9c8fe3079fa8fa2c2e7ed23 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 8 Dec 2008 08:59:51 +0100 Subject: Move again. --- sphinx/builders/htmlhelp.py | 220 ++++++++ sphinx/builders/linkcheck.py | 130 +++++ sphinx/htmlhelp.py | 220 -------- sphinx/htmlwriter.py | 457 ---------------- sphinx/latexwriter.py | 1185 ------------------------------------------ sphinx/linkcheck.py | 130 ----- sphinx/textwriter.py | 679 ------------------------ sphinx/writers/html.py | 457 ++++++++++++++++ sphinx/writers/latex.py | 1185 ++++++++++++++++++++++++++++++++++++++++++ sphinx/writers/text.py | 679 ++++++++++++++++++++++++ 10 files changed, 2671 insertions(+), 2671 deletions(-) create mode 100644 sphinx/builders/htmlhelp.py create mode 100644 sphinx/builders/linkcheck.py delete mode 100644 sphinx/htmlhelp.py delete mode 100644 sphinx/htmlwriter.py delete mode 100644 sphinx/latexwriter.py delete mode 100644 sphinx/linkcheck.py delete mode 100644 sphinx/textwriter.py create mode 100644 sphinx/writers/html.py create mode 100644 sphinx/writers/latex.py create mode 100644 sphinx/writers/text.py diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py new file mode 100644 index 00000000..4cc68bc9 --- /dev/null +++ b/sphinx/builders/htmlhelp.py @@ -0,0 +1,220 @@ +# -*- coding: utf-8 -*- +""" + sphinx.htmlhelp + ~~~~~~~~~~~~~~~ + + Build HTML help support files. + Adapted from the original Doc/tools/prechm.py. + + :copyright: 2007-2008 by Georg Brandl. + :license: BSD. +""" + +import os +import cgi +from os import path + +from docutils import nodes + +from sphinx import addnodes + +# Project file (*.hhp) template. 'outname' is the file basename (like +# the pythlp in pythlp.hhp); 'version' is the doc version number (like +# the 2.2 in Python 2.2). +# The magical numbers in the long line under [WINDOWS] set most of the +# user-visible features (visible buttons, tabs, etc). +# About 0x10384e: This defines the buttons in the help viewer. The +# following defns are taken from htmlhelp.h. Not all possibilities +# actually work, and not all those that work are available from the Help +# Workshop GUI. In particular, the Zoom/Font button works and is not +# available from the GUI. The ones we're using are marked with 'x': +# +# 0x000002 Hide/Show x +# 0x000004 Back x +# 0x000008 Forward x +# 0x000010 Stop +# 0x000020 Refresh +# 0x000040 Home x +# 0x000080 Forward +# 0x000100 Back +# 0x000200 Notes +# 0x000400 Contents +# 0x000800 Locate x +# 0x001000 Options x +# 0x002000 Print x +# 0x004000 Index +# 0x008000 Search +# 0x010000 History +# 0x020000 Favorites +# 0x040000 Jump 1 +# 0x080000 Jump 2 +# 0x100000 Zoom/Font x +# 0x200000 TOC Next +# 0x400000 TOC Prev + +project_template = '''\ +[OPTIONS] +Binary TOC=Yes +Binary Index=No +Compiled file=%(outname)s.chm +Contents file=%(outname)s.hhc +Default Window=%(outname)s +Default topic=index.html +Display compile progress=No +Full text search stop list file=%(outname)s.stp +Full-text search=Yes +Index file=%(outname)s.hhk +Language=0x409 +Title=%(title)s + +[WINDOWS] +%(outname)s="%(title)s","%(outname)s.hhc","%(outname)s.hhk",\ +"index.html","index.html",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0 + +[FILES] +''' + +contents_header = '''\ + + + + + + + + + + +
      +''' + +contents_footer = '''\ +
    +''' + +object_sitemap = '''\ + + + + +''' + +# List of words the full text search facility shouldn't index. This +# becomes file outname.stp. Note that this list must be pretty small! +# Different versions of the MS docs claim the file has a maximum size of +# 256 or 512 bytes (including \r\n at the end of each line). +# Note that "and", "or", "not" and "near" are operators in the search +# language, so no point indexing them even if we wanted to. +stopwords = """ +a and are as at +be but by +for +if in into is it +near no not +of on or +such +that the their then there these they this to +was will with +""".split() + + +def build_hhx(builder, outdir, outname): + builder.info('dumping stopword list...') + f = open(path.join(outdir, outname+'.stp'), 'w') + try: + for word in sorted(stopwords): + print >>f, word + finally: + f.close() + + builder.info('writing project file...') + f = open(path.join(outdir, outname+'.hhp'), 'w') + try: + f.write(project_template % {'outname': outname, + 'title': builder.config.html_title, + 'version': builder.config.version, + 'project': builder.config.project}) + if not outdir.endswith(os.sep): + outdir += os.sep + olen = len(outdir) + for root, dirs, files in os.walk(outdir): + staticdir = (root == path.join(outdir, '_static')) + for fn in files: + if (staticdir and not fn.endswith('.js')) or fn.endswith('.html'): + print >>f, path.join(root, fn)[olen:].replace(os.sep, '\\') + finally: + f.close() + + builder.info('writing TOC file...') + f = open(path.join(outdir, outname+'.hhc'), 'w') + try: + f.write(contents_header) + # special books + f.write('
  • ' + object_sitemap % (builder.config.html_short_title, + 'index.html')) + if builder.config.html_use_modindex: + f.write('
  • ' + object_sitemap % (_('Global Module Index'), + 'modindex.html')) + # the TOC + tocdoc = builder.env.get_and_resolve_doctree(builder.config.master_doc, builder, + prune_toctrees=False) + def write_toc(node, ullevel=0): + if isinstance(node, nodes.list_item): + f.write('
  • ') + for subnode in node: + write_toc(subnode, ullevel) + elif isinstance(node, nodes.reference): + link = node['refuri'] + title = cgi.escape(node.astext()).replace('"','"') + item = object_sitemap % (title, link) + f.write(item.encode('ascii', 'xmlcharrefreplace')) + elif isinstance(node, nodes.bullet_list): + if ullevel != 0: + f.write('
      \n') + for subnode in node: + write_toc(subnode, ullevel+1) + if ullevel != 0: + f.write('
    \n') + elif isinstance(node, addnodes.compact_paragraph): + for subnode in node: + write_toc(subnode, ullevel) + istoctree = lambda node: isinstance(node, addnodes.compact_paragraph) and \ + node.has_key('toctree') + for node in tocdoc.traverse(istoctree): + write_toc(node) + f.write(contents_footer) + finally: + f.close() + + builder.info('writing index file...') + index = builder.env.create_index(builder) + f = open(path.join(outdir, outname+'.hhk'), 'w') + try: + f.write('
      \n') + def write_index(title, refs, subitems): + def write_param(name, value): + item = ' \n' % (name, value) + f.write(item.encode('ascii', 'xmlcharrefreplace')) + title = cgi.escape(title) + f.write('
    • \n') + write_param('Keyword', title) + if len(refs) == 0: + write_param('See Also', title) + elif len(refs) == 1: + write_param('Local', refs[0]) + else: + for i, ref in enumerate(refs): + write_param('Name', '[%d] %s' % (i, ref)) # XXX: better title? + write_param('Local', ref) + f.write('\n') + if subitems: + f.write('
        ') + for subitem in subitems: + write_index(subitem[0], subitem[1], []) + f.write('
      ') + for (key, group) in index: + for title, (refs, subitems) in group: + write_index(title, refs, subitems) + f.write('
    \n') + finally: + f.close() diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py new file mode 100644 index 00000000..37aeb7a7 --- /dev/null +++ b/sphinx/builders/linkcheck.py @@ -0,0 +1,130 @@ +# -*- coding: utf-8 -*- +""" + sphinx.linkcheck + ~~~~~~~~~~~~~~~~ + + The CheckExternalLinksBuilder class. + + :copyright: 2008 by Georg Brandl, Thomas Lamb. + :license: BSD. +""" + +import socket +from os import path +from urllib2 import build_opener, HTTPError + +from docutils import nodes + +from sphinx.builder import Builder +from sphinx.util.console import purple, red, darkgreen + +# create an opener that will simulate a browser user-agent +opener = build_opener() +opener.addheaders = [('User-agent', 'Mozilla/5.0')] + + +class CheckExternalLinksBuilder(Builder): + """ + Checks for broken external links. + """ + name = 'linkcheck' + + def init(self): + self.good = set() + self.broken = {} + self.redirected = {} + # set a timeout for non-responding servers + socket.setdefaulttimeout(5.0) + # create output file + open(path.join(self.outdir, 'output.txt'), 'w').close() + + def get_target_uri(self, docname, typ=None): + return '' + + def get_outdated_docs(self): + return self.env.found_docs + + def prepare_writing(self, docnames): + return + + def write_doc(self, docname, doctree): + self.info() + for node in doctree.traverse(nodes.reference): + try: + self.check(node, docname) + except KeyError: + continue + + def check(self, node, docname): + uri = node['refuri'] + + if '#' in uri: + uri = uri.split('#')[0] + + if uri in self.good: + return + + lineno = None + while lineno is None and node: + node = node.parent + lineno = node.line + + if uri[0:5] == 'http:' or uri[0:6] == 'https:': + self.info(uri, nonl=1) + + if uri in self.broken: + (r, s) = self.broken[uri] + elif uri in self.redirected: + (r, s) = self.redirected[uri] + else: + (r, s) = self.resolve(uri) + + if r == 0: + self.info(' - ' + darkgreen('working')) + self.good.add(uri) + elif r == 2: + self.info(' - ' + red('broken: ') + s) + self.write_entry('broken', docname, lineno, uri + ': ' + s) + self.broken[uri] = (r, s) + if self.app.quiet: + self.warn('%s:%s: broken link: %s' % (docname, lineno, uri)) + else: + self.info(' - ' + purple('redirected') + ' to ' + s) + self.write_entry('redirected', docname, lineno, uri + ' to ' + s) + self.redirected[uri] = (r, s) + elif len(uri) == 0 or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:': + return + else: + self.warn(uri + ' - ' + red('malformed!')) + self.write_entry('malformed', docname, lineno, uri) + if self.app.quiet: + self.warn('%s:%s: malformed link: %s' % (docname, lineno, uri)) + self.app.statuscode = 1 + + if self.broken: + self.app.statuscode = 1 + + def write_entry(self, what, docname, line, uri): + output = open(path.join(self.outdir, 'output.txt'), 'a') + output.write("%s:%s: [%s] %s\n" % (self.env.doc2path(docname, None), + line, what, uri)) + output.close() + + def resolve(self, uri): + try: + f = opener.open(uri) + f.close() + except HTTPError, err: + #if err.code == 403 and uri.startswith('http://en.wikipedia.org/'): + # # Wikipedia blocks requests from urllib User-Agent + # return (0, 0) + return (2, str(err)) + except Exception, err: + return (2, str(err)) + if f.url.rstrip('/') == uri.rstrip('/'): + return (0, 0) + else: + return (1, f.url) + + def finish(self): + return diff --git a/sphinx/htmlhelp.py b/sphinx/htmlhelp.py deleted file mode 100644 index 4cc68bc9..00000000 --- a/sphinx/htmlhelp.py +++ /dev/null @@ -1,220 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.htmlhelp - ~~~~~~~~~~~~~~~ - - Build HTML help support files. - Adapted from the original Doc/tools/prechm.py. - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -import os -import cgi -from os import path - -from docutils import nodes - -from sphinx import addnodes - -# Project file (*.hhp) template. 'outname' is the file basename (like -# the pythlp in pythlp.hhp); 'version' is the doc version number (like -# the 2.2 in Python 2.2). -# The magical numbers in the long line under [WINDOWS] set most of the -# user-visible features (visible buttons, tabs, etc). -# About 0x10384e: This defines the buttons in the help viewer. The -# following defns are taken from htmlhelp.h. Not all possibilities -# actually work, and not all those that work are available from the Help -# Workshop GUI. In particular, the Zoom/Font button works and is not -# available from the GUI. The ones we're using are marked with 'x': -# -# 0x000002 Hide/Show x -# 0x000004 Back x -# 0x000008 Forward x -# 0x000010 Stop -# 0x000020 Refresh -# 0x000040 Home x -# 0x000080 Forward -# 0x000100 Back -# 0x000200 Notes -# 0x000400 Contents -# 0x000800 Locate x -# 0x001000 Options x -# 0x002000 Print x -# 0x004000 Index -# 0x008000 Search -# 0x010000 History -# 0x020000 Favorites -# 0x040000 Jump 1 -# 0x080000 Jump 2 -# 0x100000 Zoom/Font x -# 0x200000 TOC Next -# 0x400000 TOC Prev - -project_template = '''\ -[OPTIONS] -Binary TOC=Yes -Binary Index=No -Compiled file=%(outname)s.chm -Contents file=%(outname)s.hhc -Default Window=%(outname)s -Default topic=index.html -Display compile progress=No -Full text search stop list file=%(outname)s.stp -Full-text search=Yes -Index file=%(outname)s.hhk -Language=0x409 -Title=%(title)s - -[WINDOWS] -%(outname)s="%(title)s","%(outname)s.hhc","%(outname)s.hhk",\ -"index.html","index.html",,,,,0x63520,220,0x10384e,[0,0,1024,768],,,,,,,0 - -[FILES] -''' - -contents_header = '''\ - - - - - - - - - - -
      -''' - -contents_footer = '''\ -
    -''' - -object_sitemap = '''\ - - - - -''' - -# List of words the full text search facility shouldn't index. This -# becomes file outname.stp. Note that this list must be pretty small! -# Different versions of the MS docs claim the file has a maximum size of -# 256 or 512 bytes (including \r\n at the end of each line). -# Note that "and", "or", "not" and "near" are operators in the search -# language, so no point indexing them even if we wanted to. -stopwords = """ -a and are as at -be but by -for -if in into is it -near no not -of on or -such -that the their then there these they this to -was will with -""".split() - - -def build_hhx(builder, outdir, outname): - builder.info('dumping stopword list...') - f = open(path.join(outdir, outname+'.stp'), 'w') - try: - for word in sorted(stopwords): - print >>f, word - finally: - f.close() - - builder.info('writing project file...') - f = open(path.join(outdir, outname+'.hhp'), 'w') - try: - f.write(project_template % {'outname': outname, - 'title': builder.config.html_title, - 'version': builder.config.version, - 'project': builder.config.project}) - if not outdir.endswith(os.sep): - outdir += os.sep - olen = len(outdir) - for root, dirs, files in os.walk(outdir): - staticdir = (root == path.join(outdir, '_static')) - for fn in files: - if (staticdir and not fn.endswith('.js')) or fn.endswith('.html'): - print >>f, path.join(root, fn)[olen:].replace(os.sep, '\\') - finally: - f.close() - - builder.info('writing TOC file...') - f = open(path.join(outdir, outname+'.hhc'), 'w') - try: - f.write(contents_header) - # special books - f.write('
  • ' + object_sitemap % (builder.config.html_short_title, - 'index.html')) - if builder.config.html_use_modindex: - f.write('
  • ' + object_sitemap % (_('Global Module Index'), - 'modindex.html')) - # the TOC - tocdoc = builder.env.get_and_resolve_doctree(builder.config.master_doc, builder, - prune_toctrees=False) - def write_toc(node, ullevel=0): - if isinstance(node, nodes.list_item): - f.write('
  • ') - for subnode in node: - write_toc(subnode, ullevel) - elif isinstance(node, nodes.reference): - link = node['refuri'] - title = cgi.escape(node.astext()).replace('"','"') - item = object_sitemap % (title, link) - f.write(item.encode('ascii', 'xmlcharrefreplace')) - elif isinstance(node, nodes.bullet_list): - if ullevel != 0: - f.write('
      \n') - for subnode in node: - write_toc(subnode, ullevel+1) - if ullevel != 0: - f.write('
    \n') - elif isinstance(node, addnodes.compact_paragraph): - for subnode in node: - write_toc(subnode, ullevel) - istoctree = lambda node: isinstance(node, addnodes.compact_paragraph) and \ - node.has_key('toctree') - for node in tocdoc.traverse(istoctree): - write_toc(node) - f.write(contents_footer) - finally: - f.close() - - builder.info('writing index file...') - index = builder.env.create_index(builder) - f = open(path.join(outdir, outname+'.hhk'), 'w') - try: - f.write('
      \n') - def write_index(title, refs, subitems): - def write_param(name, value): - item = ' \n' % (name, value) - f.write(item.encode('ascii', 'xmlcharrefreplace')) - title = cgi.escape(title) - f.write('
    • \n') - write_param('Keyword', title) - if len(refs) == 0: - write_param('See Also', title) - elif len(refs) == 1: - write_param('Local', refs[0]) - else: - for i, ref in enumerate(refs): - write_param('Name', '[%d] %s' % (i, ref)) # XXX: better title? - write_param('Local', ref) - f.write('\n') - if subitems: - f.write('
        ') - for subitem in subitems: - write_index(subitem[0], subitem[1], []) - f.write('
      ') - for (key, group) in index: - for title, (refs, subitems) in group: - write_index(title, refs, subitems) - f.write('
    \n') - finally: - f.close() diff --git a/sphinx/htmlwriter.py b/sphinx/htmlwriter.py deleted file mode 100644 index 0505fd08..00000000 --- a/sphinx/htmlwriter.py +++ /dev/null @@ -1,457 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.htmlwriter - ~~~~~~~~~~~~~~~~~ - - docutils writers handling Sphinx' custom nodes. - - :copyright: 2007-2008 by Georg Brandl. - :license: BSD. -""" - -import sys -import posixpath -import os - -from docutils import nodes -from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator - -from sphinx.locale import admonitionlabels, versionlabels -from sphinx.highlighting import PygmentsBridge -from sphinx.util.smartypants import sphinx_smarty_pants - -try: - import Image # check for the Python Imaging Library -except ImportError: - Image = None - -class HTMLWriter(Writer): - def __init__(self, builder): - Writer.__init__(self) - self.builder = builder - - def translate(self): - # sadly, this is mostly copied from parent class - self.visitor = visitor = self.builder.translator_class(self.builder, - self.document) - self.document.walkabout(visitor) - self.output = visitor.astext() - for attr in ('head_prefix', 'stylesheet', 'head', 'body_prefix', - 'body_pre_docinfo', 'docinfo', 'body', 'fragment', - 'body_suffix', 'meta', 'title', 'subtitle', 'header', - 'footer', 'html_prolog', 'html_head', 'html_title', - 'html_subtitle', 'html_body', ): - setattr(self, attr, getattr(visitor, attr, None)) - self.clean_meta = ''.join(visitor.meta[2:]) - - -class HTMLTranslator(BaseTranslator): - """ - Our custom HTML translator. - """ - - def __init__(self, builder, *args, **kwds): - BaseTranslator.__init__(self, *args, **kwds) - self.highlighter = PygmentsBridge('html', builder.config.pygments_style) - self.no_smarty = 0 - self.builder = builder - self.highlightlang = builder.config.highlight_language - self.highlightlinenothreshold = sys.maxint - self.protect_literal_text = 0 - - def visit_desc(self, node): - self.body.append(self.starttag(node, 'dl', CLASS=node['desctype'])) - def depart_desc(self, node): - self.body.append('\n\n') - - def visit_desc_signature(self, node): - # the id is set automatically - self.body.append(self.starttag(node, 'dt')) - # anchor for per-desc interactive data - if node.parent['desctype'] != 'describe' and node['ids'] and node['first']: - self.body.append('' % node['ids'][0]) - if node.parent['desctype'] in ('class', 'exception'): - self.body.append('%s ' % node.parent['desctype']) - def depart_desc_signature(self, node): - if node['ids'] and self.builder.add_definition_links: - self.body.append(u'\u00B6' % - _('Permalink to this definition')) - self.body.append('\n') - - def visit_desc_addname(self, node): - self.body.append(self.starttag(node, 'tt', '', CLASS='descclassname')) - def depart_desc_addname(self, node): - self.body.append('') - - def visit_desc_type(self, node): - pass - def depart_desc_type(self, node): - pass - - def visit_desc_name(self, node): - self.body.append(self.starttag(node, 'tt', '', CLASS='descname')) - def depart_desc_name(self, node): - self.body.append('') - - def visit_desc_parameterlist(self, node): - self.body.append('(') - self.first_param = 1 - def depart_desc_parameterlist(self, node): - self.body.append(')') - - def visit_desc_parameter(self, node): - if not self.first_param: - self.body.append(', ') - else: - self.first_param = 0 - if not node.hasattr('noemph'): - self.body.append('') - def depart_desc_parameter(self, node): - if not node.hasattr('noemph'): - self.body.append('') - - def visit_desc_optional(self, node): - self.body.append('[') - def depart_desc_optional(self, node): - self.body.append(']') - - def visit_desc_annotation(self, node): - self.body.append(self.starttag(node, 'em', CLASS='property')) - def depart_desc_annotation(self, node): - self.body.append('') - - def visit_desc_content(self, node): - self.body.append(self.starttag(node, 'dd', '')) - def depart_desc_content(self, node): - self.body.append('') - - def visit_refcount(self, node): - self.body.append(self.starttag(node, 'em', '', CLASS='refcount')) - def depart_refcount(self, node): - self.body.append('') - - def visit_versionmodified(self, node): - self.body.append(self.starttag(node, 'p')) - text = versionlabels[node['type']] % node['version'] - if len(node): - text += ': ' - else: - text += '.' - self.body.append('%s' % text) - def depart_versionmodified(self, node): - self.body.append('

    \n') - - # overwritten - def visit_reference(self, node): - BaseTranslator.visit_reference(self, node) - if node.hasattr('reftitle'): - # ugly hack to add a title attribute - starttag = self.body[-1] - if not starttag.startswith(' tag - self.section_level += 1 - self.body.append(self.starttag(node, 'div', CLASS='section')) - - def visit_title(self, node): - # don't move the id attribute inside the tag - BaseTranslator.visit_title(self, node, move_ids=0) - - # overwritten - def visit_literal_block(self, node): - if node.rawsource != node.astext(): - # most probably a parsed-literal block -- don't highlight - return BaseTranslator.visit_literal_block(self, node) - lang = self.highlightlang - linenos = node.rawsource.count('\n') >= self.highlightlinenothreshold - 1 - if node.has_key('language'): - # code-block directives - lang = node['language'] - if node.has_key('linenos'): - linenos = node['linenos'] - highlighted = self.highlighter.highlight_block(node.rawsource, lang, linenos) - starttag = self.starttag(node, 'div', suffix='', CLASS='highlight-%s' % lang) - self.body.append(starttag + highlighted + '\n') - raise nodes.SkipNode - - def visit_doctest_block(self, node): - self.visit_literal_block(node) - - # overwritten - def visit_literal(self, node): - if len(node.children) == 1 and \ - node.children[0] in ('None', 'True', 'False'): - node['classes'].append('xref') - self.body.append(self.starttag(node, 'tt', '', CLASS='docutils literal')) - self.protect_literal_text += 1 - def depart_literal(self, node): - self.protect_literal_text -= 1 - self.body.append('') - - def visit_productionlist(self, node): - self.body.append(self.starttag(node, 'pre')) - names = [] - for production in node: - names.append(production['tokenname']) - maxlen = max(len(name) for name in names) - for production in node: - if production['tokenname']: - lastname = production['tokenname'].ljust(maxlen) - self.body.append(self.starttag(production, 'strong', '')) - self.body.append(lastname + ' ::= ') - else: - self.body.append('%s ' % (' '*len(lastname))) - production.walkabout(self) - self.body.append('\n') - self.body.append('\n') - raise nodes.SkipNode - def depart_productionlist(self, node): - pass - - def visit_production(self, node): - pass - def depart_production(self, node): - pass - - def visit_centered(self, node): - self.body.append(self.starttag(node, 'p', CLASS="centered") + '') - def depart_centered(self, node): - self.body.append('

    ') - - def visit_compact_paragraph(self, node): - pass - def depart_compact_paragraph(self, node): - pass - - def visit_highlightlang(self, node): - self.highlightlang = node['lang'] - self.highlightlinenothreshold = node['linenothreshold'] - def depart_highlightlang(self, node): - pass - - # overwritten - def visit_image(self, node): - olduri = node['uri'] - # rewrite the URI if the environment knows about it - if olduri in self.builder.images: - node['uri'] = posixpath.join(self.builder.imgpath, - self.builder.images[olduri]) - - if node.has_key('scale'): - if Image and not (node.has_key('width') - and node.has_key('height')): - try: - im = Image.open(os.path.join(self.builder.srcdir, - olduri)) - except (IOError, # Source image can't be found or opened - UnicodeError): # PIL doesn't like Unicode paths. - print olduri - pass - else: - if not node.has_key('width'): - node['width'] = str(im.size[0]) - if not node.has_key('height'): - node['height'] = str(im.size[1]) - del im - BaseTranslator.visit_image(self, node) - - def visit_toctree(self, node): - # this only happens when formatting a toc from env.tocs -- in this - # case we don't want to include the subtree - raise nodes.SkipNode - - def visit_index(self, node): - raise nodes.SkipNode - - def visit_tabular_col_spec(self, node): - raise nodes.SkipNode - - def visit_glossary(self, node): - pass - def depart_glossary(self, node): - pass - - def visit_acks(self, node): - pass - def depart_acks(self, node): - pass - - def visit_module(self, node): - pass - def depart_module(self, node): - pass - - def bulk_text_processor(self, text): - return text - - # overwritten - def visit_Text(self, node): - text = node.astext() - encoded = self.encode(text) - if self.protect_literal_text: - # moved here from base class's visit_literal to support - # more formatting in literal nodes - for token in self.words_and_spaces.findall(encoded): - if token.strip(): - # protect literal text from line wrapping - self.body.append('%s' % token) - elif token in ' \n': - # allow breaks at whitespace - self.body.append(token) - else: - # protect runs of multiple spaces; the last one can wrap - self.body.append(' ' * (len(token)-1) + ' ') - else: - if self.in_mailto and self.settings.cloak_email_addresses: - encoded = self.cloak_email(encoded) - else: - encoded = self.bulk_text_processor(encoded) - self.body.append(encoded) - - # these are all for docutils 0.5 compatibility - - def visit_note(self, node): - self.visit_admonition(node, 'note') - def depart_note(self, node): - self.depart_admonition(node) - - def visit_warning(self, node): - self.visit_admonition(node, 'warning') - def depart_warning(self, node): - self.depart_admonition(node) - - def visit_attention(self, node): - self.visit_admonition(node, 'attention') - - def depart_attention(self, node): - self.depart_admonition() - - def visit_caution(self, node): - self.visit_admonition(node, 'caution') - def depart_caution(self, node): - self.depart_admonition() - - def visit_danger(self, node): - self.visit_admonition(node, 'danger') - def depart_danger(self, node): - self.depart_admonition() - - def visit_error(self, node): - self.visit_admonition(node, 'error') - def depart_error(self, node): - self.depart_admonition() - - def visit_hint(self, node): - self.visit_admonition(node, 'hint') - def depart_hint(self, node): - self.depart_admonition() - - def visit_important(self, node): - self.visit_admonition(node, 'important') - def depart_important(self, node): - self.depart_admonition() - - def visit_tip(self, node): - self.visit_admonition(node, 'tip') - def depart_tip(self, node): - self.depart_admonition() - - # these are only handled specially in the SmartyPantsHTMLTranslator - def visit_literal_emphasis(self, node): - return self.visit_emphasis(node) - def depart_literal_emphasis(self, node): - return self.depart_emphasis(node) - - def depart_title(self, node): - close_tag = self.context[-1] - if self.builder.add_header_links and \ - (close_tag.startswith('\u00B6    ' % - _('Permalink to this headline')) - BaseTranslator.depart_title(self, node) - - def unknown_visit(self, node): - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) - - -class SmartyPantsHTMLTranslator(HTMLTranslator): - """ - Handle ordinary text via smartypants, converting quotes and dashes - to the correct entities. - """ - - def __init__(self, *args, **kwds): - self.no_smarty = 0 - HTMLTranslator.__init__(self, *args, **kwds) - - def visit_literal(self, node): - self.no_smarty += 1 - try: - # this raises SkipNode - HTMLTranslator.visit_literal(self, node) - finally: - self.no_smarty -= 1 - - def visit_literal_emphasis(self, node): - self.no_smarty += 1 - self.visit_emphasis(node) - - def depart_literal_emphasis(self, node): - self.depart_emphasis(node) - self.no_smarty -= 1 - - def visit_desc_signature(self, node): - self.no_smarty += 1 - HTMLTranslator.visit_desc_signature(self, node) - - def depart_desc_signature(self, node): - self.no_smarty -= 1 - HTMLTranslator.depart_desc_signature(self, node) - - def visit_productionlist(self, node): - self.no_smarty += 1 - try: - HTMLTranslator.visit_productionlist(self, node) - finally: - self.no_smarty -= 1 - - def visit_option(self, node): - self.no_smarty += 1 - HTMLTranslator.visit_option(self, node) - def depart_option(self, node): - self.no_smarty -= 1 - HTMLTranslator.depart_option(self, node) - - def bulk_text_processor(self, text): - if self.no_smarty <= 0: - return sphinx_smarty_pants(text) - return text diff --git a/sphinx/latexwriter.py b/sphinx/latexwriter.py deleted file mode 100644 index 94cb23db..00000000 --- a/sphinx/latexwriter.py +++ /dev/null @@ -1,1185 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.latexwriter - ~~~~~~~~~~~~~~~~~~ - - Custom docutils writer for LaTeX. - - Much of this code is adapted from Dave Kuhlman's "docpy" writer from his - docutils sandbox. - - :copyright: 2007-2008 by Georg Brandl, Dave Kuhlman. - :license: BSD. -""" - -import re -import sys -from os import path - -from docutils import nodes, writers -from docutils.writers.latex2e import Babel - -from sphinx import addnodes -from sphinx import highlighting -from sphinx.locale import admonitionlabels, versionlabels -from sphinx.util import ustrftime -from sphinx.util.texescape import tex_escape_map -from sphinx.util.smartypants import educateQuotesLatex - -HEADER = r'''%% Generated by Sphinx. -\documentclass[%(papersize)s,%(pointsize)s%(classoptions)s]{%(docclass)s} -%(inputenc)s -%(fontenc)s -%(babel)s -%(fontpkg)s -%(fncychap)s -\usepackage{sphinx} -%(preamble)s - -\title{%(title)s} -\date{%(date)s} -\release{%(release)s} -\author{%(author)s} -\newcommand{\sphinxlogo}{%(logo)s} -\renewcommand{\releasename}{%(releasename)s} -%(makeindex)s -%(makemodindex)s -''' - -BEGIN_DOC = r''' -\begin{document} -%(shorthandoff)s -%(maketitle)s -%(tableofcontents)s -''' - -FOOTER = r''' -%(footer)s -\renewcommand{\indexname}{%(modindexname)s} -%(printmodindex)s -\renewcommand{\indexname}{%(indexname)s} -%(printindex)s -\end{document} -''' - - -class LaTeXWriter(writers.Writer): - - supported = ('sphinxlatex',) - - settings_spec = ('LaTeX writer options', '', ( - ('Document name', ['--docname'], {'default': ''}), - ('Document class', ['--docclass'], {'default': 'manual'}), - ('Author', ['--author'], {'default': ''}), - )) - settings_defaults = {} - - output = None - - def __init__(self, builder): - writers.Writer.__init__(self) - self.builder = builder - - def translate(self): - visitor = LaTeXTranslator(self.document, self.builder) - self.document.walkabout(visitor) - self.output = visitor.astext() - - -# Helper classes - -class ExtBabel(Babel): - def get_shorthandoff(self): - shortlang = self.language.split('_')[0] - if shortlang in ('de', 'sl', 'pt', 'es', 'nl', 'pl'): - return '\\shorthandoff{"}' - return '' - - _ISO639_TO_BABEL = Babel._ISO639_TO_BABEL.copy() - _ISO639_TO_BABEL['sl'] = 'slovene' - - -class Table(object): - def __init__(self): - self.col = 0 - self.colcount = 0 - self.colspec = None - self.had_head = False - self.has_verbatim = False - self.caption = None - - -class Desc(object): - def __init__(self, node): - self.env = LaTeXTranslator.desc_map.get(node['desctype'], 'describe') - self.type = self.cls = self.name = self.params = self.annotation = '' - self.count = 0 - - -class LaTeXTranslator(nodes.NodeVisitor): - sectionnames = ["part", "chapter", "section", "subsection", - "subsubsection", "paragraph", "subparagraph"] - - ignore_missing_images = False - - default_elements = { - 'docclass': 'manual', - 'papersize': 'letterpaper', - 'pointsize': '10pt', - 'classoptions': '', - 'inputenc': '\\usepackage[utf8]{inputenc}', - 'fontenc': '\\usepackage[T1]{fontenc}', - 'babel': '\\usepackage{babel}', - 'fontpkg': '\\usepackage{times}', - 'fncychap': '\\usepackage[Bjarne]{fncychap}', - 'preamble': '', - 'title': '', - 'date': '', - 'release': '', - 'author': '', - 'logo': '', - 'releasename': 'Release', - 'makeindex': '\\makeindex', - 'makemodindex': '\\makemodindex', - 'shorthandoff': '', - 'maketitle': '\\maketitle', - 'tableofcontents': '\\tableofcontents', - 'footer': '', - 'printmodindex': '\\printmodindex', - 'printindex': '\\printindex', - } - - def __init__(self, document, builder): - nodes.NodeVisitor.__init__(self, document) - self.builder = builder - self.body = [] - - # sort out some elements - papersize = builder.config.latex_paper_size + 'paper' - if papersize == 'paper': # e.g. command line "-D latex_paper_size=" - papersize = 'letterpaper' - - self.elements = self.default_elements.copy() - self.elements.update({ - 'docclass': document.settings.docclass, - 'papersize': papersize, - 'pointsize': builder.config.latex_font_size, - # if empty, the title is set to the first section title - 'title': document.settings.title, - 'date': ustrftime(builder.config.today_fmt or _('%B %d, %Y')), - 'release': builder.config.release, - 'author': document.settings.author, - 'releasename': _('Release'), - 'preamble': builder.config.latex_preamble, - 'modindexname': _('Module Index'), - 'indexname': _('Index'), - }) - if builder.config.latex_logo: - self.elements['logo'] = '\\includegraphics{%s}\\par' % \ - path.basename(builder.config.latex_logo) - if builder.config.language: - babel = ExtBabel(builder.config.language) - lang = babel.get_language() - if lang: - self.elements['classoptions'] += ',' + babel.get_language() - else: - self.builder.warn('no Babel option known for language %r' % - builder.config.language) - self.elements['shorthandoff'] = babel.get_shorthandoff() - self.elements['fncychap'] = '\\usepackage[Sonny]{fncychap}' - else: - self.elements['classoptions'] += ',english' - if not builder.config.latex_use_modindex: - self.elements['makemodindex'] = '' - self.elements['printmodindex'] = '' - # allow the user to override them all - self.elements.update(builder.config.latex_elements) - - self.highlighter = highlighting.PygmentsBridge( - 'latex', builder.config.pygments_style) - self.context = [] - self.descstack = [] - self.bibitems = [] - self.table = None - self.next_table_colspec = None - self.highlightlang = builder.config.highlight_language - self.highlightlinenothreshold = sys.maxint - self.written_ids = set() - self.footnotestack = [] - if self.elements['docclass'] == 'manual': - if builder.config.latex_use_parts: - self.top_sectionlevel = 0 - else: - self.top_sectionlevel = 1 - else: - self.top_sectionlevel = 2 - self.next_section_target = None - # flags - self.verbatim = None - self.in_title = 0 - self.in_production_list = 0 - self.first_document = 1 - self.this_is_the_title = 1 - self.literal_whitespace = 0 - self.no_contractions = 0 - - def astext(self): - return (HEADER % self.elements + self.highlighter.get_stylesheet() + - u''.join(self.body) + FOOTER % self.elements) - - def visit_document(self, node): - self.footnotestack.append(self.collect_footnotes(node)) - if self.first_document == 1: - # the first document is all the regular content ... - self.body.append(BEGIN_DOC % self.elements) - self.first_document = 0 - elif self.first_document == 0: - # ... and all others are the appendices - self.body.append('\n\\appendix\n') - self.first_document = -1 - # "- 1" because the level is increased before the title is visited - self.sectionlevel = self.top_sectionlevel - 1 - def depart_document(self, node): - if self.bibitems: - widest_label = "" - for bi in self.bibitems: - if len(widest_label) < len(bi[0]): - widest_label = bi[0] - self.body.append('\n\\begin{thebibliography}{%s}\n' % widest_label) - for bi in self.bibitems: - # cite_key: underscores must not be escaped - cite_key = bi[0].replace(r"\_", "_") - self.body.append('\\bibitem[%s]{%s}{%s}\n' % (bi[0], cite_key, bi[1])) - self.body.append('\\end{thebibliography}\n') - self.bibitems = [] - - def visit_start_of_file(self, node): - # This marks the begin of a new file; therefore the current module and - # class must be reset - self.body.append('\n\\resetcurrentobjects\n') - # and also, new footnotes - self.footnotestack.append(self.collect_footnotes(node)) - - def collect_footnotes(self, node): - fnotes = {} - def footnotes_under(n): - if isinstance(n, nodes.footnote): - yield n - else: - for c in n.children: - if isinstance(c, addnodes.start_of_file): - continue - for k in footnotes_under(c): - yield k - for fn in footnotes_under(node): - num = fn.children[0].astext().strip() - fnotes[num] = fn - fn.parent.remove(fn) - return fnotes - - def depart_start_of_file(self, node): - self.footnotestack.pop() - - def visit_highlightlang(self, node): - self.highlightlang = node['lang'] - self.highlightlinenothreshold = node['linenothreshold'] - raise nodes.SkipNode - - def visit_section(self, node): - if not self.this_is_the_title: - self.sectionlevel += 1 - self.body.append('\n\n') - if self.next_section_target: - self.body.append(r'\hypertarget{%s}{}' % self.next_section_target) - self.next_section_target = None - #if node.get('ids'): - # for id in node['ids']: - # if id not in self.written_ids: - # self.body.append(r'\hypertarget{%s}{}' % id) - # self.written_ids.add(id) - def depart_section(self, node): - self.sectionlevel = max(self.sectionlevel - 1, self.top_sectionlevel - 1) - - def visit_problematic(self, node): - self.body.append(r'{\color{red}\bfseries{}') - def depart_problematic(self, node): - self.body.append('}') - - def visit_topic(self, node): - self.body.append('\\setbox0\\vbox{\n' - '\\begin{minipage}{0.95\\textwidth}\n') - def depart_topic(self, node): - self.body.append('\\end{minipage}}\n' - '\\begin{center}\\setlength{\\fboxsep}{5pt}' - '\\shadowbox{\\box0}\\end{center}\n') - visit_sidebar = visit_topic - depart_sidebar = depart_topic - - def visit_glossary(self, node): - pass - def depart_glossary(self, node): - pass - - def visit_productionlist(self, node): - self.body.append('\n\n\\begin{productionlist}\n') - self.in_production_list = 1 - def depart_productionlist(self, node): - self.body.append('\\end{productionlist}\n\n') - self.in_production_list = 0 - - def visit_production(self, node): - if node['tokenname']: - self.body.append('\\production{%s}{' % self.encode(node['tokenname'])) - else: - self.body.append('\\productioncont{') - def depart_production(self, node): - self.body.append('}\n') - - def visit_transition(self, node): - self.body.append('\n\n\\bigskip\\hrule{}\\bigskip\n\n') - def depart_transition(self, node): - pass - - def visit_title(self, node): - parent = node.parent - if isinstance(parent, addnodes.seealso): - # the environment already handles this - raise nodes.SkipNode - elif self.this_is_the_title: - if len(node.children) != 1 and not isinstance(node.children[0], nodes.Text): - self.builder.warn('document title is not a single Text node') - if not self.elements['title']: - # text needs to be escaped since it is inserted into - # the output literally - self.elements['title'] = node.astext().translate(tex_escape_map) - self.this_is_the_title = 0 - raise nodes.SkipNode - elif isinstance(parent, nodes.section): - try: - self.body.append(r'\%s{' % self.sectionnames[self.sectionlevel]) - except IndexError: - from sphinx.application import SphinxError - raise SphinxError('too many nesting section levels for LaTeX, ' - 'at heading: %s' % node.astext()) - self.context.append('}\n') - elif isinstance(parent, (nodes.topic, nodes.sidebar)): - self.body.append(r'\textbf{') - self.context.append('}\n\n\medskip\n\n') - elif isinstance(parent, nodes.Admonition): - self.body.append('{') - self.context.append('}\n') - elif isinstance(parent, nodes.table): - self.table.caption = self.encode(node.astext()) - raise nodes.SkipNode - else: - self.builder.warn('encountered title node not in section, topic, ' - 'table, admonition or sidebar') - self.body.append('\\textbf{') - self.context.append('}\n') - self.in_title = 1 - def depart_title(self, node): - self.in_title = 0 - self.body.append(self.context.pop()) - - def visit_subtitle(self, node): - if isinstance(node.parent, nodes.sidebar): - self.body.append('~\\\\\n\\textbf{') - self.context.append('}\n\\smallskip\n') - else: - self.context.append('') - def depart_subtitle(self, node): - self.body.append(self.context.pop()) - - desc_map = { - 'function' : 'funcdesc', - 'class': 'classdesc', - 'method': 'methoddesc', - 'staticmethod': 'staticmethoddesc', - 'exception': 'excdesc', - 'data': 'datadesc', - 'attribute': 'memberdesc', - 'opcode': 'opcodedesc', - - 'cfunction': 'cfuncdesc', - 'cmember': 'cmemberdesc', - 'cmacro': 'csimplemacrodesc', - 'ctype': 'ctypedesc', - 'cvar': 'cvardesc', - - 'describe': 'describe', - # and all others are 'describe' too - } - - def visit_desc(self, node): - self.descstack.append(Desc(node)) - def depart_desc(self, node): - d = self.descstack.pop() - self.body.append("\\end{%s}\n" % d.env) - - def visit_desc_signature(self, node): - d = self.descstack[-1] - # reset these for every signature - d.type = d.cls = d.name = d.params = '' - def depart_desc_signature(self, node): - d = self.descstack[-1] - d.cls = d.cls.rstrip('.') - if node.parent['desctype'] != 'describe' and node['ids']: - hyper = '\\hypertarget{%s}{}' % node['ids'][0] - else: - hyper = '' - if d.count == 0: - t1 = "\n\n%s\\begin{%s}" % (hyper, d.env) - else: - t1 = "\n%s\\%sline" % (hyper, d.env[:-4]) - d.count += 1 - if d.env in ('funcdesc', 'classdesc', 'excclassdesc'): - t2 = "{%s}{%s}" % (d.name, d.params) - elif d.env in ('datadesc', 'excdesc', 'csimplemacrodesc'): - t2 = "{%s}" % (d.name) - elif d.env in ('methoddesc', 'staticmethoddesc'): - if d.cls: - t2 = "[%s]{%s}{%s}" % (d.cls, d.name, d.params) - else: - t2 = "{%s}{%s}" % (d.name, d.params) - elif d.env == 'memberdesc': - if d.cls: - t2 = "[%s]{%s}" % (d.cls, d.name) - else: - t2 = "{%s}" % d.name - elif d.env == 'cfuncdesc': - if d.cls: - # C++ class names - d.name = '%s::%s' % (d.cls, d.name) - t2 = "{%s}{%s}{%s}" % (d.type, d.name, d.params) - elif d.env == 'cmemberdesc': - try: - type, container = d.type.rsplit(' ', 1) - container = container.rstrip('.') - except ValueError: - container = '' - type = d.type - t2 = "{%s}{%s}{%s}" % (container, type, d.name) - elif d.env == 'cvardesc': - t2 = "{%s}{%s}" % (d.type, d.name) - elif d.env == 'ctypedesc': - t2 = "{%s}" % (d.name) - elif d.env == 'opcodedesc': - t2 = "{%s}{%s}" % (d.name, d.params) - elif d.env == 'describe': - t2 = "{%s}" % d.name - self.body.append(t1 + t2) - - def visit_desc_type(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].type = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_desc_name(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].name = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_desc_addname(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].cls = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_desc_parameterlist(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].params = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_desc_annotation(self, node): - d = self.descstack[-1] - if d.env == 'describe': - d.name += self.encode(node.astext()) - else: - self.descstack[-1].annotation = self.encode(node.astext().strip()) - raise nodes.SkipNode - - def visit_refcount(self, node): - self.body.append("\\emph{") - def depart_refcount(self, node): - self.body.append("}\\\\") - - def visit_desc_content(self, node): - if node.children and not isinstance(node.children[0], nodes.paragraph): - # avoid empty desc environment which causes a formatting bug - self.body.append('~') - def depart_desc_content(self, node): - pass - - def visit_seealso(self, node): - self.body.append("\n\n\\strong{%s:}\n\n" % admonitionlabels['seealso']) - def depart_seealso(self, node): - self.body.append("\n\n") - - def visit_rubric(self, node): - if len(node.children) == 1 and node.children[0].astext() == 'Footnotes': - raise nodes.SkipNode - self.body.append('\\paragraph{') - self.context.append('}\n') - def depart_rubric(self, node): - self.body.append(self.context.pop()) - - def visit_footnote(self, node): - pass - def depart_footnote(self, node): - pass - - def visit_label(self, node): - if isinstance(node.parent, nodes.citation): - self.bibitems[-1][0] = node.astext() - raise nodes.SkipNode - - def visit_tabular_col_spec(self, node): - self.next_table_colspec = node['spec'] - raise nodes.SkipNode - - def visit_table(self, node): - if self.table: - raise NotImplementedError('Nested tables are not supported.') - self.table = Table() - self.tablebody = [] - # Redirect body output until table is finished. - self._body = self.body - self.body = self.tablebody - def depart_table(self, node): - self.body = self._body - if self.table.caption is not None: - self.body.append('\n\\begin{threeparttable}\n' - '\\caption{%s}\n' % self.table.caption) - if self.table.has_verbatim: - self.body.append('\n\\begin{tabular}') - else: - self.body.append('\n\\begin{tabulary}{\\textwidth}') - if self.table.colspec: - self.body.append(self.table.colspec) - else: - if self.table.has_verbatim: - colwidth = 0.95 / self.table.colcount - colspec = ('p{%.3f\\textwidth}|' % colwidth) * self.table.colcount - self.body.append('{|' + colspec + '}\n') - else: - self.body.append('{|' + ('L|' * self.table.colcount) + '}\n') - self.body.extend(self.tablebody) - if self.table.has_verbatim: - self.body.append('\\end{tabular}\n\n') - else: - self.body.append('\\end{tabulary}\n\n') - if self.table.caption is not None: - self.body.append('\\end{threeparttable}\n\n') - self.table = None - self.tablebody = None - - def visit_colspec(self, node): - self.table.colcount += 1 - def depart_colspec(self, node): - pass - - def visit_tgroup(self, node): - pass - def depart_tgroup(self, node): - pass - - def visit_thead(self, node): - if self.next_table_colspec: - self.table.colspec = '{%s}\n' % self.next_table_colspec - self.next_table_colspec = None - self.body.append('\\hline\n') - self.table.had_head = True - def depart_thead(self, node): - self.body.append('\\hline\n') - - def visit_tbody(self, node): - if not self.table.had_head: - self.visit_thead(node) - def depart_tbody(self, node): - self.body.append('\\hline\n') - - def visit_row(self, node): - self.table.col = 0 - def depart_row(self, node): - self.body.append('\\\\\n') - - def visit_entry(self, node): - if node.has_key('morerows') or node.has_key('morecols'): - raise NotImplementedError('Column or row spanning cells are ' - 'not implemented.') - if self.table.col > 0: - self.body.append(' & ') - self.table.col += 1 - if isinstance(node.parent.parent, nodes.thead): - self.body.append('\\textbf{') - self.context.append('}') - else: - self.context.append('') - def depart_entry(self, node): - self.body.append(self.context.pop()) # header - - def visit_acks(self, node): - # this is a list in the source, but should be rendered as a - # comma-separated list here - self.body.append('\n\n') - self.body.append(', '.join(n.astext() for n in node.children[0].children) + '.') - self.body.append('\n\n') - raise nodes.SkipNode - - def visit_bullet_list(self, node): - self.body.append('\\begin{itemize}\n' ) - def depart_bullet_list(self, node): - self.body.append('\\end{itemize}\n' ) - - def visit_enumerated_list(self, node): - self.body.append('\\begin{enumerate}\n' ) - def depart_enumerated_list(self, node): - self.body.append('\\end{enumerate}\n' ) - - def visit_list_item(self, node): - # Append "{}" in case the next character is "[", which would break - # LaTeX's list environment (no numbering and the "[" is not printed). - self.body.append(r'\item {} ') - def depart_list_item(self, node): - self.body.append('\n') - - def visit_definition_list(self, node): - self.body.append('\\begin{description}\n') - def depart_definition_list(self, node): - self.body.append('\\end{description}\n') - - def visit_definition_list_item(self, node): - pass - def depart_definition_list_item(self, node): - pass - - def visit_term(self, node): - ctx = ']' - if node.has_key('ids') and node['ids']: - ctx += '\\hypertarget{%s}{}' % node['ids'][0] - self.body.append('\\item[') - self.context.append(ctx) - def depart_term(self, node): - self.body.append(self.context.pop()) - - def visit_classifier(self, node): - self.body.append('{[}') - def depart_classifier(self, node): - self.body.append('{]}') - - def visit_definition(self, node): - pass - def depart_definition(self, node): - self.body.append('\n') - - def visit_field_list(self, node): - self.body.append('\\begin{quote}\\begin{description}\n') - def depart_field_list(self, node): - self.body.append('\\end{description}\\end{quote}\n') - - def visit_field(self, node): - pass - def depart_field(self, node): - pass - - visit_field_name = visit_term - depart_field_name = depart_term - - visit_field_body = visit_definition - depart_field_body = depart_definition - - def visit_paragraph(self, node): - self.body.append('\n') - def depart_paragraph(self, node): - self.body.append('\n') - - def visit_centered(self, node): - self.body.append('\n\\begin{centering}') - def depart_centered(self, node): - self.body.append('\n\\end{centering}') - - def visit_module(self, node): - modname = node['modname'] - self.body.append('\n\\declaremodule[%s]{}{%s}' % (modname.replace('_', ''), - self.encode(modname))) - self.body.append('\n\\modulesynopsis{%s}' % self.encode(node['synopsis'])) - if node.has_key('platform'): - self.body.append('\\platform{%s}' % self.encode(node['platform'])) - def depart_module(self, node): - pass - - def latex_image_length(self, width_str): - match = re.match('(\d*\.?\d*)\s*(\S*)', width_str) - if not match: - # fallback - return width_str - res = width_str - amount, unit = match.groups()[:2] - if not unit or unit == "px": - # pixels: let LaTeX alone - return None - elif unit == "%": - res = "%.3f\\linewidth" % (float(amount) / 100.0) - return res - - def visit_image(self, node): - attrs = node.attributes - pre = [] # in reverse order - post = [] - include_graphics_options = [] - inline = isinstance(node.parent, nodes.TextElement) - if attrs.has_key('scale'): - # Could also be done with ``scale`` option to - # ``\includegraphics``; doing it this way for consistency. - pre.append('\\scalebox{%f}{' % (attrs['scale'] / 100.0,)) - post.append('}') - if attrs.has_key('width'): - w = self.latex_image_length(attrs['width']) - if w: - include_graphics_options.append('width=%s' % w) - if attrs.has_key('height'): - h = self.latex_image_length(attrs['height']) - include_graphics_options.append('height=%s' % h) - if attrs.has_key('align'): - align_prepost = { - # By default latex aligns the top of an image. - (1, 'top'): ('', ''), - (1, 'middle'): ('\\raisebox{-0.5\\height}{', '}'), - (1, 'bottom'): ('\\raisebox{-\\height}{', '}'), - (0, 'center'): ('{\\hfill', '\\hfill}'), - # These 2 don't exactly do the right thing. The image should - # be floated alongside the paragraph. See - # http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG - (0, 'left'): ('{', '\\hfill}'), - (0, 'right'): ('{\\hfill', '}'),} - try: - pre.append(align_prepost[inline, attrs['align']][0]) - post.append(align_prepost[inline, attrs['align']][1]) - except KeyError: - pass # XXX complain here? - if not inline: - pre.append('\n') - post.append('\n') - pre.reverse() - if node['uri'] in self.builder.images: - uri = self.builder.images[node['uri']] - else: - # missing image! - if self.ignore_missing_images: - return - uri = node['uri'] - if uri.find('://') != -1: - # ignore remote images - return - self.body.extend(pre) - options = '' - if include_graphics_options: - options = '[%s]' % ','.join(include_graphics_options) - self.body.append('\\includegraphics%s{%s}' % (options, uri)) - self.body.extend(post) - def depart_image(self, node): - pass - - def visit_figure(self, node): - if (not node.attributes.has_key('align') or - node.attributes['align'] == 'center'): - # centering does not add vertical space like center. - align = '\n\\centering' - align_end = '' - else: - # TODO non vertical space for other alignments. - align = '\\begin{flush%s}' % node.attributes['align'] - align_end = '\\end{flush%s}' % node.attributes['align'] - self.body.append('\\begin{figure}[htbp]%s\n' % align) - self.context.append('%s\\end{figure}\n' % align_end) - def depart_figure(self, node): - self.body.append(self.context.pop()) - - def visit_caption(self, node): - self.body.append('\\caption{') - def depart_caption(self, node): - self.body.append('}') - - def visit_legend(self, node): - self.body.append('{\\small ') - def depart_legend(self, node): - self.body.append('}') - - def visit_admonition(self, node): - self.body.append('\n\\begin{notice}{note}') - def depart_admonition(self, node): - self.body.append('\\end{notice}\n') - - def _make_visit_admonition(name): - def visit_admonition(self, node): - self.body.append('\n\\begin{notice}{%s}{%s:}' % - (name, admonitionlabels[name])) - return visit_admonition - def _depart_named_admonition(self, node): - self.body.append('\\end{notice}\n') - - visit_attention = _make_visit_admonition('attention') - depart_attention = _depart_named_admonition - visit_caution = _make_visit_admonition('caution') - depart_caution = _depart_named_admonition - visit_danger = _make_visit_admonition('danger') - depart_danger = _depart_named_admonition - visit_error = _make_visit_admonition('error') - depart_error = _depart_named_admonition - visit_hint = _make_visit_admonition('hint') - depart_hint = _depart_named_admonition - visit_important = _make_visit_admonition('important') - depart_important = _depart_named_admonition - visit_note = _make_visit_admonition('note') - depart_note = _depart_named_admonition - visit_tip = _make_visit_admonition('tip') - depart_tip = _depart_named_admonition - visit_warning = _make_visit_admonition('warning') - depart_warning = _depart_named_admonition - - def visit_versionmodified(self, node): - intro = versionlabels[node['type']] % node['version'] - if node.children: - intro += ': ' - else: - intro += '.' - self.body.append(intro) - def depart_versionmodified(self, node): - pass - - def visit_target(self, node): - def add_target(id): - # indexing uses standard LaTeX index markup, so the targets - # will be generated differently - if not id.startswith('index-'): - self.body.append(r'\hypertarget{%s}{}' % id) - - if node.has_key('refid') and node['refid'] not in self.written_ids: - parindex = node.parent.index(node) - try: - next = node.parent[parindex+1] - if isinstance(next, nodes.section): - self.next_section_target = node['refid'] - return - except IndexError: - pass - add_target(node['refid']) - self.written_ids.add(node['refid']) - def depart_target(self, node): - pass - - def visit_attribution(self, node): - self.body.append('\n\\begin{flushright}\n') - self.body.append('---') - def depart_attribution(self, node): - self.body.append('\n\\end{flushright}\n') - - def visit_index(self, node, scre=re.compile(r';\s*')): - entries = node['entries'] - for type, string, tid, _ in entries: - if type == 'single': - self.body.append(r'\index{%s}' % scre.sub('!', self.encode(string))) - elif type == 'pair': - parts = tuple(self.encode(x.strip()) for x in string.split(';', 1)) - self.body.append(r'\indexii{%s}{%s}' % parts) - elif type == 'triple': - parts = tuple(self.encode(x.strip()) for x in string.split(';', 2)) - self.body.append(r'\indexiii{%s}{%s}{%s}' % parts) - else: - self.builder.warn('unknown index entry type %s found' % type) - raise nodes.SkipNode - - def visit_raw(self, node): - if 'latex' in node.get('format', '').split(): - self.body.append(node.astext()) - raise nodes.SkipNode - - def visit_reference(self, node): - uri = node.get('refuri', '') - if self.in_title or not uri: - self.context.append('') - elif uri.startswith('mailto:') or uri.startswith('http:') or \ - uri.startswith('https:') or uri.startswith('ftp:'): - self.body.append('\\href{%s}{' % self.encode(uri)) - self.context.append('}') - elif uri.startswith('#'): - self.body.append('\\hyperlink{%s}{' % uri[1:]) - self.context.append('}') - elif uri.startswith('@token'): - if self.in_production_list: - self.body.append('\\token{') - else: - self.body.append('\\grammartoken{') - self.context.append('}') - else: - self.builder.warn('unusable reference target found: %s' % uri) - self.context.append('') - def depart_reference(self, node): - self.body.append(self.context.pop()) - - def visit_pending_xref(self, node): - pass - def depart_pending_xref(self, node): - pass - - def visit_emphasis(self, node): - self.body.append(r'\emph{') - def depart_emphasis(self, node): - self.body.append('}') - - def visit_literal_emphasis(self, node): - self.body.append(r'\emph{\texttt{') - self.no_contractions += 1 - def depart_literal_emphasis(self, node): - self.body.append('}}') - self.no_contractions -= 1 - - def visit_strong(self, node): - self.body.append(r'\textbf{') - def depart_strong(self, node): - self.body.append('}') - - def visit_title_reference(self, node): - self.body.append(r'\emph{') - def depart_title_reference(self, node): - self.body.append('}') - - def visit_citation(self, node): - # TODO maybe use cite bibitems - self.bibitems.append(['', '']) - self.context.append(len(self.body)) - def depart_citation(self, node): - size = self.context.pop() - text = ''.join(self.body[size:]) - del self.body[size:] - self.bibitems[-1][1] = text - - def visit_citation_reference(self, node): - citeid = node.astext() - self.body.append('\\cite{%s}' % citeid) - raise nodes.SkipNode - - def visit_literal(self, node): - content = self.encode(node.astext().strip()) - if self.in_title: - self.body.append(r'\texttt{%s}' % content) - elif node.has_key('role') and node['role'] == 'samp': - self.body.append(r'\samp{%s}' % content) - else: - self.body.append(r'\code{%s}' % content) - raise nodes.SkipNode - - def visit_footnote_reference(self, node): - num = node.astext().strip() - try: - fn = self.footnotestack[-1][num] - except (KeyError, IndexError): - raise nodes.SkipNode - self.body.append('\\footnote{') - fn.walkabout(self) - raise nodes.SkipChildren - def depart_footnote_reference(self, node): - self.body.append('}') - - def visit_literal_block(self, node): - self.verbatim = '' - def depart_literal_block(self, node): - code = self.verbatim.rstrip('\n') - lang = self.highlightlang - linenos = code.count('\n') >= self.highlightlinenothreshold - 1 - if node.has_key('language'): - # code-block directives - lang = node['language'] - if node.has_key('linenos'): - linenos = node['linenos'] - hlcode = self.highlighter.highlight_block(code, lang, linenos) - # workaround for Unicode issue - hlcode = hlcode.replace(u'€', u'@texteuro[]') - # must use original Verbatim environment and "tabular" environment - if self.table: - hlcode = hlcode.replace('\\begin{Verbatim}', - '\\begin{OriginalVerbatim}') - self.table.has_verbatim = True - # get consistent trailer - hlcode = hlcode.rstrip()[:-14] # strip \end{Verbatim} - hlcode = hlcode.rstrip() + '\n' - self.body.append('\n' + hlcode + '\\end{%sVerbatim}\n' % - (self.table and 'Original' or '')) - self.verbatim = None - visit_doctest_block = visit_literal_block - depart_doctest_block = depart_literal_block - - def visit_line_block(self, node): - """line-block: - * whitespace (including linebreaks) is significant - * inline markup is supported. - * serif typeface - """ - self.body.append('{\\raggedright{}') - self.literal_whitespace = 1 - def depart_line_block(self, node): - self.literal_whitespace = 0 - # remove the last \\ - del self.body[-1] - self.body.append('}\n') - - def visit_line(self, node): - self._line_start = len(self.body) - def depart_line(self, node): - if self._line_start == len(self.body): - # no output in this line -- add a nonbreaking space, else the - # \\ command will give an error - self.body.append('~') - if self.table is not None: - self.body.append('\\newline\n') - else: - self.body.append('\\\\\n') - - def visit_block_quote(self, node): - # If the block quote contains a single object and that object - # is a list, then generate a list not a block quote. - # This lets us indent lists. - done = 0 - if len(node.children) == 1: - child = node.children[0] - if isinstance(child, nodes.bullet_list) or \ - isinstance(child, nodes.enumerated_list): - done = 1 - if not done: - self.body.append('\\begin{quote}\n') - def depart_block_quote(self, node): - done = 0 - if len(node.children) == 1: - child = node.children[0] - if isinstance(child, nodes.bullet_list) or \ - isinstance(child, nodes.enumerated_list): - done = 1 - if not done: - self.body.append('\\end{quote}\n') - - # option node handling copied from docutils' latex writer - - def visit_option(self, node): - if self.context[-1]: - # this is not the first option - self.body.append(', ') - def depart_option(self, node): - # flag that the first option is done. - self.context[-1] += 1 - - def visit_option_argument(self, node): - """The delimiter betweeen an option and its argument.""" - self.body.append(node.get('delimiter', ' ')) - def depart_option_argument(self, node): - pass - - def visit_option_group(self, node): - self.body.append('\\item [') - # flag for first option - self.context.append(0) - def depart_option_group(self, node): - self.context.pop() # the flag - self.body.append('] ') - - def visit_option_list(self, node): - self.body.append('\\begin{optionlist}{3cm}\n') - def depart_option_list(self, node): - self.body.append('\\end{optionlist}\n') - - def visit_option_list_item(self, node): - pass - def depart_option_list_item(self, node): - pass - - def visit_option_string(self, node): - ostring = node.astext() - self.body.append(self.encode(ostring.replace('--', u'-{-}'))) - raise nodes.SkipNode - - def visit_description(self, node): - self.body.append( ' ' ) - def depart_description(self, node): - pass - - def visit_superscript(self, node): - self.body.append('$^{\\text{') - def depart_superscript(self, node): - self.body.append('}}$') - - def visit_subscript(self, node): - self.body.append('$_{\\text{') - def depart_subscript(self, node): - self.body.append('}}$') - - def visit_substitution_definition(self, node): - raise nodes.SkipNode - - def visit_substitution_reference(self, node): - raise nodes.SkipNode - - def visit_generated(self, node): - pass - def depart_generated(self, node): - pass - - def visit_compound(self, node): - pass - def depart_compound(self, node): - pass - - def visit_container(self, node): - pass - def depart_container(self, node): - pass - - def visit_decoration(self, node): - pass - def depart_decoration(self, node): - pass - - # text handling - - def encode(self, text): - text = unicode(text).translate(tex_escape_map) - if self.literal_whitespace: - # Insert a blank before the newline, to avoid - # ! LaTeX Error: There's no line here to end. - text = text.replace(u'\n', u'~\\\\\n').replace(u' ', u'~') - if self.no_contractions: - text = text.replace('--', u'-{-}') - return text - - def visit_Text(self, node): - if self.verbatim is not None: - self.verbatim += node.astext() - else: - text = self.encode(node.astext()) - self.body.append(educateQuotesLatex(text)) - def depart_Text(self, node): - pass - - def visit_comment(self, node): - raise nodes.SkipNode - - def visit_meta(self, node): - # only valid for HTML - raise nodes.SkipNode - - def visit_system_message(self, node): - pass - def depart_system_message(self, node): - self.body.append('\n') - - def unknown_visit(self, node): - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/linkcheck.py b/sphinx/linkcheck.py deleted file mode 100644 index 37aeb7a7..00000000 --- a/sphinx/linkcheck.py +++ /dev/null @@ -1,130 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.linkcheck - ~~~~~~~~~~~~~~~~ - - The CheckExternalLinksBuilder class. - - :copyright: 2008 by Georg Brandl, Thomas Lamb. - :license: BSD. -""" - -import socket -from os import path -from urllib2 import build_opener, HTTPError - -from docutils import nodes - -from sphinx.builder import Builder -from sphinx.util.console import purple, red, darkgreen - -# create an opener that will simulate a browser user-agent -opener = build_opener() -opener.addheaders = [('User-agent', 'Mozilla/5.0')] - - -class CheckExternalLinksBuilder(Builder): - """ - Checks for broken external links. - """ - name = 'linkcheck' - - def init(self): - self.good = set() - self.broken = {} - self.redirected = {} - # set a timeout for non-responding servers - socket.setdefaulttimeout(5.0) - # create output file - open(path.join(self.outdir, 'output.txt'), 'w').close() - - def get_target_uri(self, docname, typ=None): - return '' - - def get_outdated_docs(self): - return self.env.found_docs - - def prepare_writing(self, docnames): - return - - def write_doc(self, docname, doctree): - self.info() - for node in doctree.traverse(nodes.reference): - try: - self.check(node, docname) - except KeyError: - continue - - def check(self, node, docname): - uri = node['refuri'] - - if '#' in uri: - uri = uri.split('#')[0] - - if uri in self.good: - return - - lineno = None - while lineno is None and node: - node = node.parent - lineno = node.line - - if uri[0:5] == 'http:' or uri[0:6] == 'https:': - self.info(uri, nonl=1) - - if uri in self.broken: - (r, s) = self.broken[uri] - elif uri in self.redirected: - (r, s) = self.redirected[uri] - else: - (r, s) = self.resolve(uri) - - if r == 0: - self.info(' - ' + darkgreen('working')) - self.good.add(uri) - elif r == 2: - self.info(' - ' + red('broken: ') + s) - self.write_entry('broken', docname, lineno, uri + ': ' + s) - self.broken[uri] = (r, s) - if self.app.quiet: - self.warn('%s:%s: broken link: %s' % (docname, lineno, uri)) - else: - self.info(' - ' + purple('redirected') + ' to ' + s) - self.write_entry('redirected', docname, lineno, uri + ' to ' + s) - self.redirected[uri] = (r, s) - elif len(uri) == 0 or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:': - return - else: - self.warn(uri + ' - ' + red('malformed!')) - self.write_entry('malformed', docname, lineno, uri) - if self.app.quiet: - self.warn('%s:%s: malformed link: %s' % (docname, lineno, uri)) - self.app.statuscode = 1 - - if self.broken: - self.app.statuscode = 1 - - def write_entry(self, what, docname, line, uri): - output = open(path.join(self.outdir, 'output.txt'), 'a') - output.write("%s:%s: [%s] %s\n" % (self.env.doc2path(docname, None), - line, what, uri)) - output.close() - - def resolve(self, uri): - try: - f = opener.open(uri) - f.close() - except HTTPError, err: - #if err.code == 403 and uri.startswith('http://en.wikipedia.org/'): - # # Wikipedia blocks requests from urllib User-Agent - # return (0, 0) - return (2, str(err)) - except Exception, err: - return (2, str(err)) - if f.url.rstrip('/') == uri.rstrip('/'): - return (0, 0) - else: - return (1, f.url) - - def finish(self): - return diff --git a/sphinx/textwriter.py b/sphinx/textwriter.py deleted file mode 100644 index 4aa18039..00000000 --- a/sphinx/textwriter.py +++ /dev/null @@ -1,679 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx.textwriter - ~~~~~~~~~~~~~~~~~ - - Custom docutils writer for plain text. - - :copyright: 2008 by Georg Brandl. - :license: BSD. -""" - -import re -import textwrap - -from docutils import nodes, writers - -from sphinx import addnodes -from sphinx.locale import admonitionlabels, versionlabels - - -class TextWriter(writers.Writer): - supported = ('text',) - settings_spec = ('No options here.', '', ()) - settings_defaults = {} - - output = None - - def __init__(self, builder): - writers.Writer.__init__(self) - self.builder = builder - - def translate(self): - visitor = TextTranslator(self.document, self.builder) - self.document.walkabout(visitor) - self.output = visitor.body - -# monkey-patch... -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 -textwrap.TextWrapper.wordsep_re = new_wordsep_re - -MAXWIDTH = 70 -STDINDENT = 3 - - -class TextTranslator(nodes.NodeVisitor): - sectionchars = '*=-~"+' - - def __init__(self, document, builder): - nodes.NodeVisitor.__init__(self, document) - - self.states = [[]] - self.stateindent = [0] - self.sectionlevel = 0 - self.table = None - - def add_text(self, text): - self.states[-1].append((-1, text)) - def new_state(self, indent=STDINDENT): - self.states.append([]) - self.stateindent.append(indent) - def end_state(self, wrap=True, end=[''], first=None): - content = self.states.pop() - maxindent = sum(self.stateindent) - indent = self.stateindent.pop() - result = [] - toformat = [] - def do_format(): - if not toformat: - return - if wrap: - res = textwrap.wrap(''.join(toformat), width=MAXWIDTH-maxindent) - else: - res = ''.join(toformat).splitlines() - if end: - res += end - result.append((indent, res)) - for itemindent, item in content: - if itemindent == -1: - toformat.append(item) - else: - do_format() - result.append((indent + itemindent, item)) - toformat = [] - do_format() - if first is not None and result: - itemindent, item = result[0] - if item: - result.insert(0, (itemindent - indent, [first + item[0]])) - result[1] = (itemindent, item[1:]) - self.states[-1].extend(result) - - def visit_document(self, node): - self.new_state(0) - def depart_document(self, node): - self.end_state() - self.body = '\n'.join(line and (' '*indent + line) - for indent, lines in self.states[0] - for line in lines) - # XXX header/footer? - - def visit_highlightlang(self, node): - raise nodes.SkipNode - - def visit_section(self, node): - self._title_char = self.sectionchars[self.sectionlevel] - self.sectionlevel += 1 - def depart_section(self, node): - self.sectionlevel -= 1 - - def visit_topic(self, node): - self.new_state(0) - def depart_topic(self, node): - self.end_state() - - visit_sidebar = visit_topic - depart_sidebar = depart_topic - - def visit_rubric(self, node): - self.new_state(0) - self.add_text('-[ ') - def depart_rubric(self, node): - self.add_text(' ]-') - self.end_state() - - def visit_compound(self, node): - pass - def depart_compound(self, node): - pass - - def visit_glossary(self, node): - pass - def depart_glossary(self, node): - pass - - def visit_title(self, node): - if isinstance(node.parent, nodes.Admonition): - self.add_text(node.astext()+': ') - raise nodes.SkipNode - self.new_state(0) - def depart_title(self, node): - if isinstance(node.parent, nodes.section): - char = self._title_char - else: - char = '^' - text = ''.join(x[1] for x in self.states.pop() if x[0] == -1) - self.stateindent.pop() - self.states[-1].append((0, ['', text, '%s' % (char * len(text)), ''])) - - def visit_subtitle(self, node): - pass - def depart_subtitle(self, node): - pass - - def visit_attribution(self, node): - self.add_text('-- ') - def depart_attribution(self, node): - pass - - def visit_module(self, node): - if node.has_key('platform'): - self.new_state(0) - self.add_text(_('Platform: %s') % node['platform']) - self.end_state() - raise nodes.SkipNode - - def visit_desc(self, node): - pass - def depart_desc(self, node): - pass - - def visit_desc_signature(self, node): - self.new_state(0) - if node.parent['desctype'] in ('class', 'exception'): - self.add_text('%s ' % node.parent['desctype']) - def depart_desc_signature(self, node): - # XXX: wrap signatures in a way that makes sense - self.end_state(wrap=False, end=None) - - def visit_desc_name(self, node): - pass - def depart_desc_name(self, node): - pass - - def visit_desc_addname(self, node): - pass - def depart_desc_addname(self, node): - pass - - def visit_desc_type(self, node): - pass - def depart_desc_type(self, node): - pass - - def visit_desc_parameterlist(self, node): - self.add_text('(') - self.first_param = 1 - def depart_desc_parameterlist(self, node): - self.add_text(')') - - def visit_desc_parameter(self, node): - if not self.first_param: - self.add_text(', ') - else: - self.first_param = 0 - self.add_text(node.astext()) - raise nodes.SkipNode - - def visit_desc_optional(self, node): - self.add_text('[') - def depart_desc_optional(self, node): - self.add_text(']') - - def visit_desc_annotation(self, node): - pass - def depart_desc_annotation(self, node): - pass - - def visit_refcount(self, node): - pass - def depart_refcount(self, node): - pass - - def visit_desc_content(self, node): - self.new_state() - self.add_text('\n') - def depart_desc_content(self, node): - self.end_state() - - def visit_figure(self, node): - self.new_state() - def depart_figure(self, node): - self.end_state() - - def visit_caption(self, node): - pass - def depart_caption(self, node): - pass - - def visit_productionlist(self, node): - self.new_state() - names = [] - for production in node: - names.append(production['tokenname']) - maxlen = max(len(name) for name in names) - for production in node: - if production['tokenname']: - self.add_text(production['tokenname'].ljust(maxlen) + ' ::=') - lastname = production['tokenname'] - else: - self.add_text('%s ' % (' '*len(lastname))) - self.add_text(production.astext() + '\n') - self.end_state(wrap=False) - raise nodes.SkipNode - - def visit_seealso(self, node): - self.new_state() - def depart_seealso(self, node): - self.end_state(first='') - - def visit_footnote(self, node): - self._footnote = node.children[0].astext().strip() - self.new_state(len(self._footnote) + 3) - def depart_footnote(self, node): - self.end_state(first='[%s] ' % self._footnote) - - def visit_citation(self, node): - if len(node) and isinstance(node[0], nodes.label): - self._citlabel = node[0].astext() - else: - self._citlabel = '' - self.new_state(len(self._citlabel) + 3) - def depart_citation(self, node): - self.end_state(first='[%s] ' % self._citlabel) - - def visit_label(self, node): - raise nodes.SkipNode - - # XXX: option list could use some better styling - - def visit_option_list(self, node): - pass - def depart_option_list(self, node): - pass - - def visit_option_list_item(self, node): - self.new_state(0) - def depart_option_list_item(self, node): - self.end_state() - - def visit_option_group(self, node): - self._firstoption = True - def depart_option_group(self, node): - self.add_text(' ') - - def visit_option(self, node): - if self._firstoption: - self._firstoption = False - else: - self.add_text(', ') - def depart_option(self, node): - pass - - def visit_option_string(self, node): - pass - def depart_option_string(self, node): - pass - - def visit_option_argument(self, node): - self.add_text(node['delimiter']) - def depart_option_argument(self, node): - pass - - def visit_description(self, node): - pass - def depart_description(self, node): - pass - - def visit_tabular_col_spec(self, node): - raise nodes.SkipNode - - def visit_colspec(self, node): - self.table[0].append(node['colwidth']) - raise nodes.SkipNode - - def visit_tgroup(self, node): - pass - def depart_tgroup(self, node): - pass - - def visit_thead(self, node): - pass - def depart_thead(self, node): - pass - - def visit_tbody(self, node): - self.table.append('sep') - def depart_tbody(self, node): - pass - - def visit_row(self, node): - self.table.append([]) - def depart_row(self, node): - pass - - def visit_entry(self, node): - if node.has_key('morerows') or node.has_key('morecols'): - raise NotImplementedError('Column or row spanning cells are ' - 'not implemented.') - self.new_state(0) - def depart_entry(self, node): - text = '\n'.join('\n'.join(x[1]) for x in self.states.pop()) - self.stateindent.pop() - self.table[-1].append(text) - - def visit_table(self, node): - if self.table: - raise NotImplementedError('Nested tables are not supported.') - self.new_state(0) - self.table = [[]] - def depart_table(self, node): - lines = self.table[1:] - fmted_rows = [] - colwidths = self.table[0] - realwidths = colwidths[:] - separator = 0 - # don't allow paragraphs in table cells for now - for line in lines: - if line == 'sep': - separator = len(fmted_rows) - else: - cells = [] - for i, cell in enumerate(line): - par = textwrap.wrap(cell, width=colwidths[i]) - if par: - maxwidth = max(map(len, par)) - else: - maxwidth = 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.add_text(''.join(out) + '\n') - - 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.add_text(''.join(out) + '\n') - - for i, row in enumerate(fmted_rows): - if separator and i == separator: - writesep('=') - else: - writesep('-') - writerow(row) - writesep('-') - self.table = None - self.end_state(wrap=False) - - def visit_acks(self, node): - self.new_state(0) - self.add_text(', '.join(n.astext() for n in node.children[0].children) + '.') - self.end_state() - raise nodes.SkipNode - - def visit_image(self, node): - self.add_text(_('[image]')) - raise nodes.SkipNode - - def visit_transition(self, node): - indent = sum(self.stateindent) - self.new_state(0) - self.add_text('=' * (MAXWIDTH - indent)) - self.end_state() - raise nodes.SkipNode - - def visit_bullet_list(self, node): - self._list_counter = -1 - def depart_bullet_list(self, node): - pass - - def visit_enumerated_list(self, node): - self._list_counter = 0 - def depart_enumerated_list(self, node): - pass - - def visit_definition_list(self, node): - self._list_counter = -2 - def depart_definition_list(self, node): - pass - - def visit_list_item(self, node): - if self._list_counter == -1: - # bullet list - self.new_state(2) - elif self._list_counter == -2: - # definition list - pass - else: - # enumerated list - self._list_counter += 1 - self.new_state(len(str(self._list_counter)) + 2) - def depart_list_item(self, node): - if self._list_counter == -1: - self.end_state(first='* ', end=None) - elif self._list_counter == -2: - pass - else: - self.end_state(first='%s. ' % self._list_counter, end=None) - - def visit_definition_list_item(self, node): - self._li_has_classifier = len(node) >= 2 and \ - isinstance(node[1], nodes.classifier) - def depart_definition_list_item(self, node): - pass - - def visit_term(self, node): - self.new_state(0) - def depart_term(self, node): - if not self._li_has_classifier: - self.end_state(end=None) - - def visit_classifier(self, node): - self.add_text(' : ') - def depart_classifier(self, node): - self.end_state(end=None) - - def visit_definition(self, node): - self.new_state() - def depart_definition(self, node): - self.end_state() - - def visit_field_list(self, node): - pass - def depart_field_list(self, node): - pass - - def visit_field(self, node): - pass - def depart_field(self, node): - pass - - def visit_field_name(self, node): - self.new_state(0) - def depart_field_name(self, node): - self.add_text(':') - self.end_state(end=None) - - def visit_field_body(self, node): - self.new_state() - def depart_field_body(self, node): - self.end_state() - - def visit_centered(self, node): - pass - def depart_centered(self, node): - pass - - def visit_admonition(self, node): - self.new_state(0) - def depart_admonition(self, node): - self.end_state() - - def _visit_admonition(self, node): - self.new_state(2) - def _make_depart_admonition(name): - def depart_admonition(self, node): - self.end_state(first=admonitionlabels[name] + ': ') - return depart_admonition - - visit_attention = _visit_admonition - depart_attention = _make_depart_admonition('attention') - visit_caution = _visit_admonition - depart_caution = _make_depart_admonition('caution') - visit_danger = _visit_admonition - depart_danger = _make_depart_admonition('danger') - visit_error = _visit_admonition - depart_error = _make_depart_admonition('error') - visit_hint = _visit_admonition - depart_hint = _make_depart_admonition('hint') - visit_important = _visit_admonition - depart_important = _make_depart_admonition('important') - visit_note = _visit_admonition - depart_note = _make_depart_admonition('note') - visit_tip = _visit_admonition - depart_tip = _make_depart_admonition('tip') - visit_warning = _visit_admonition - depart_warning = _make_depart_admonition('warning') - - def visit_versionmodified(self, node): - self.new_state(0) - if node.children: - self.add_text(versionlabels[node['type']] % node['version'] + ': ') - else: - self.add_text(versionlabels[node['type']] % node['version'] + '.') - def depart_versionmodified(self, node): - self.end_state() - - def visit_literal_block(self, node): - self.new_state() - def depart_literal_block(self, node): - self.end_state(wrap=False) - - def visit_doctest_block(self, node): - self.new_state(0) - def depart_doctest_block(self, node): - self.end_state(wrap=False) - - def visit_line_block(self, node): - self.new_state(0) - def depart_line_block(self, node): - self.end_state(wrap=False) - - def visit_line(self, node): - pass - def depart_line(self, node): - pass - - def visit_block_quote(self, node): - self.new_state() - def depart_block_quote(self, node): - self.end_state() - - def visit_compact_paragraph(self, node): - pass - def depart_compact_paragraph(self, node): - pass - - def visit_paragraph(self, node): - if not isinstance(node.parent, nodes.Admonition) or \ - isinstance(node.parent, addnodes.seealso): - self.new_state(0) - def depart_paragraph(self, node): - if not isinstance(node.parent, nodes.Admonition) or \ - isinstance(node.parent, addnodes.seealso): - self.end_state() - - def visit_target(self, node): - raise nodes.SkipNode - - def visit_index(self, node): - raise nodes.SkipNode - - def visit_substitution_definition(self, node): - raise nodes.SkipNode - - def visit_pending_xref(self, node): - pass - def depart_pending_xref(self, node): - pass - - def visit_reference(self, node): - pass - def depart_reference(self, node): - pass - - def visit_emphasis(self, node): - self.add_text('*') - def depart_emphasis(self, node): - self.add_text('*') - - def visit_literal_emphasis(self, node): - self.add_text('*') - def depart_literal_emphasis(self, node): - self.add_text('*') - - def visit_strong(self, node): - self.add_text('**') - def depart_strong(self, node): - self.add_text('**') - - def visit_title_reference(self, node): - self.add_text('*') - def depart_title_reference(self, node): - self.add_text('*') - - def visit_literal(self, node): - self.add_text('``') - def depart_literal(self, node): - self.add_text('``') - - def visit_subscript(self, node): - self.add_text('_') - def depart_subscript(self, node): - pass - - def visit_superscript(self, node): - self.add_text('^') - def depart_superscript(self, node): - pass - - def visit_footnote_reference(self, node): - self.add_text('[%s]' % node.astext()) - raise nodes.SkipNode - - def visit_citation_reference(self, node): - self.add_text('[%s]' % node.astext()) - raise nodes.SkipNode - - def visit_Text(self, node): - self.add_text(node.astext()) - def depart_Text(self, node): - pass - - def visit_problematic(self, node): - self.add_text('>>') - def depart_problematic(self, node): - self.add_text('<<') - - def visit_system_message(self, node): - self.new_state(0) - self.add_text('' % node.astext()) - self.end_state() - raise nodes.SkipNode - - def visit_comment(self, node): - raise nodes.SkipNode - - def visit_meta(self, node): - # only valid for HTML - raise nodes.SkipNode - - def unknown_visit(self, node): - raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py new file mode 100644 index 00000000..0505fd08 --- /dev/null +++ b/sphinx/writers/html.py @@ -0,0 +1,457 @@ +# -*- coding: utf-8 -*- +""" + sphinx.htmlwriter + ~~~~~~~~~~~~~~~~~ + + docutils writers handling Sphinx' custom nodes. + + :copyright: 2007-2008 by Georg Brandl. + :license: BSD. +""" + +import sys +import posixpath +import os + +from docutils import nodes +from docutils.writers.html4css1 import Writer, HTMLTranslator as BaseTranslator + +from sphinx.locale import admonitionlabels, versionlabels +from sphinx.highlighting import PygmentsBridge +from sphinx.util.smartypants import sphinx_smarty_pants + +try: + import Image # check for the Python Imaging Library +except ImportError: + Image = None + +class HTMLWriter(Writer): + def __init__(self, builder): + Writer.__init__(self) + self.builder = builder + + def translate(self): + # sadly, this is mostly copied from parent class + self.visitor = visitor = self.builder.translator_class(self.builder, + self.document) + self.document.walkabout(visitor) + self.output = visitor.astext() + for attr in ('head_prefix', 'stylesheet', 'head', 'body_prefix', + 'body_pre_docinfo', 'docinfo', 'body', 'fragment', + 'body_suffix', 'meta', 'title', 'subtitle', 'header', + 'footer', 'html_prolog', 'html_head', 'html_title', + 'html_subtitle', 'html_body', ): + setattr(self, attr, getattr(visitor, attr, None)) + self.clean_meta = ''.join(visitor.meta[2:]) + + +class HTMLTranslator(BaseTranslator): + """ + Our custom HTML translator. + """ + + def __init__(self, builder, *args, **kwds): + BaseTranslator.__init__(self, *args, **kwds) + self.highlighter = PygmentsBridge('html', builder.config.pygments_style) + self.no_smarty = 0 + self.builder = builder + self.highlightlang = builder.config.highlight_language + self.highlightlinenothreshold = sys.maxint + self.protect_literal_text = 0 + + def visit_desc(self, node): + self.body.append(self.starttag(node, 'dl', CLASS=node['desctype'])) + def depart_desc(self, node): + self.body.append('\n\n') + + def visit_desc_signature(self, node): + # the id is set automatically + self.body.append(self.starttag(node, 'dt')) + # anchor for per-desc interactive data + if node.parent['desctype'] != 'describe' and node['ids'] and node['first']: + self.body.append('' % node['ids'][0]) + if node.parent['desctype'] in ('class', 'exception'): + self.body.append('%s ' % node.parent['desctype']) + def depart_desc_signature(self, node): + if node['ids'] and self.builder.add_definition_links: + self.body.append(u'\u00B6' % + _('Permalink to this definition')) + self.body.append('\n') + + def visit_desc_addname(self, node): + self.body.append(self.starttag(node, 'tt', '', CLASS='descclassname')) + def depart_desc_addname(self, node): + self.body.append('') + + def visit_desc_type(self, node): + pass + def depart_desc_type(self, node): + pass + + def visit_desc_name(self, node): + self.body.append(self.starttag(node, 'tt', '', CLASS='descname')) + def depart_desc_name(self, node): + self.body.append('') + + def visit_desc_parameterlist(self, node): + self.body.append('(') + self.first_param = 1 + def depart_desc_parameterlist(self, node): + self.body.append(')') + + def visit_desc_parameter(self, node): + if not self.first_param: + self.body.append(', ') + else: + self.first_param = 0 + if not node.hasattr('noemph'): + self.body.append('') + def depart_desc_parameter(self, node): + if not node.hasattr('noemph'): + self.body.append('') + + def visit_desc_optional(self, node): + self.body.append('[') + def depart_desc_optional(self, node): + self.body.append(']') + + def visit_desc_annotation(self, node): + self.body.append(self.starttag(node, 'em', CLASS='property')) + def depart_desc_annotation(self, node): + self.body.append('') + + def visit_desc_content(self, node): + self.body.append(self.starttag(node, 'dd', '')) + def depart_desc_content(self, node): + self.body.append('') + + def visit_refcount(self, node): + self.body.append(self.starttag(node, 'em', '', CLASS='refcount')) + def depart_refcount(self, node): + self.body.append('') + + def visit_versionmodified(self, node): + self.body.append(self.starttag(node, 'p')) + text = versionlabels[node['type']] % node['version'] + if len(node): + text += ': ' + else: + text += '.' + self.body.append('%s' % text) + def depart_versionmodified(self, node): + self.body.append('

    \n') + + # overwritten + def visit_reference(self, node): + BaseTranslator.visit_reference(self, node) + if node.hasattr('reftitle'): + # ugly hack to add a title attribute + starttag = self.body[-1] + if not starttag.startswith(' tag + self.section_level += 1 + self.body.append(self.starttag(node, 'div', CLASS='section')) + + def visit_title(self, node): + # don't move the id attribute inside the tag + BaseTranslator.visit_title(self, node, move_ids=0) + + # overwritten + def visit_literal_block(self, node): + if node.rawsource != node.astext(): + # most probably a parsed-literal block -- don't highlight + return BaseTranslator.visit_literal_block(self, node) + lang = self.highlightlang + linenos = node.rawsource.count('\n') >= self.highlightlinenothreshold - 1 + if node.has_key('language'): + # code-block directives + lang = node['language'] + if node.has_key('linenos'): + linenos = node['linenos'] + highlighted = self.highlighter.highlight_block(node.rawsource, lang, linenos) + starttag = self.starttag(node, 'div', suffix='', CLASS='highlight-%s' % lang) + self.body.append(starttag + highlighted + '\n') + raise nodes.SkipNode + + def visit_doctest_block(self, node): + self.visit_literal_block(node) + + # overwritten + def visit_literal(self, node): + if len(node.children) == 1 and \ + node.children[0] in ('None', 'True', 'False'): + node['classes'].append('xref') + self.body.append(self.starttag(node, 'tt', '', CLASS='docutils literal')) + self.protect_literal_text += 1 + def depart_literal(self, node): + self.protect_literal_text -= 1 + self.body.append('') + + def visit_productionlist(self, node): + self.body.append(self.starttag(node, 'pre')) + names = [] + for production in node: + names.append(production['tokenname']) + maxlen = max(len(name) for name in names) + for production in node: + if production['tokenname']: + lastname = production['tokenname'].ljust(maxlen) + self.body.append(self.starttag(production, 'strong', '')) + self.body.append(lastname + ' ::= ') + else: + self.body.append('%s ' % (' '*len(lastname))) + production.walkabout(self) + self.body.append('\n') + self.body.append('\n') + raise nodes.SkipNode + def depart_productionlist(self, node): + pass + + def visit_production(self, node): + pass + def depart_production(self, node): + pass + + def visit_centered(self, node): + self.body.append(self.starttag(node, 'p', CLASS="centered") + '') + def depart_centered(self, node): + self.body.append('

    ') + + def visit_compact_paragraph(self, node): + pass + def depart_compact_paragraph(self, node): + pass + + def visit_highlightlang(self, node): + self.highlightlang = node['lang'] + self.highlightlinenothreshold = node['linenothreshold'] + def depart_highlightlang(self, node): + pass + + # overwritten + def visit_image(self, node): + olduri = node['uri'] + # rewrite the URI if the environment knows about it + if olduri in self.builder.images: + node['uri'] = posixpath.join(self.builder.imgpath, + self.builder.images[olduri]) + + if node.has_key('scale'): + if Image and not (node.has_key('width') + and node.has_key('height')): + try: + im = Image.open(os.path.join(self.builder.srcdir, + olduri)) + except (IOError, # Source image can't be found or opened + UnicodeError): # PIL doesn't like Unicode paths. + print olduri + pass + else: + if not node.has_key('width'): + node['width'] = str(im.size[0]) + if not node.has_key('height'): + node['height'] = str(im.size[1]) + del im + BaseTranslator.visit_image(self, node) + + def visit_toctree(self, node): + # this only happens when formatting a toc from env.tocs -- in this + # case we don't want to include the subtree + raise nodes.SkipNode + + def visit_index(self, node): + raise nodes.SkipNode + + def visit_tabular_col_spec(self, node): + raise nodes.SkipNode + + def visit_glossary(self, node): + pass + def depart_glossary(self, node): + pass + + def visit_acks(self, node): + pass + def depart_acks(self, node): + pass + + def visit_module(self, node): + pass + def depart_module(self, node): + pass + + def bulk_text_processor(self, text): + return text + + # overwritten + def visit_Text(self, node): + text = node.astext() + encoded = self.encode(text) + if self.protect_literal_text: + # moved here from base class's visit_literal to support + # more formatting in literal nodes + for token in self.words_and_spaces.findall(encoded): + if token.strip(): + # protect literal text from line wrapping + self.body.append('%s' % token) + elif token in ' \n': + # allow breaks at whitespace + self.body.append(token) + else: + # protect runs of multiple spaces; the last one can wrap + self.body.append(' ' * (len(token)-1) + ' ') + else: + if self.in_mailto and self.settings.cloak_email_addresses: + encoded = self.cloak_email(encoded) + else: + encoded = self.bulk_text_processor(encoded) + self.body.append(encoded) + + # these are all for docutils 0.5 compatibility + + def visit_note(self, node): + self.visit_admonition(node, 'note') + def depart_note(self, node): + self.depart_admonition(node) + + def visit_warning(self, node): + self.visit_admonition(node, 'warning') + def depart_warning(self, node): + self.depart_admonition(node) + + def visit_attention(self, node): + self.visit_admonition(node, 'attention') + + def depart_attention(self, node): + self.depart_admonition() + + def visit_caution(self, node): + self.visit_admonition(node, 'caution') + def depart_caution(self, node): + self.depart_admonition() + + def visit_danger(self, node): + self.visit_admonition(node, 'danger') + def depart_danger(self, node): + self.depart_admonition() + + def visit_error(self, node): + self.visit_admonition(node, 'error') + def depart_error(self, node): + self.depart_admonition() + + def visit_hint(self, node): + self.visit_admonition(node, 'hint') + def depart_hint(self, node): + self.depart_admonition() + + def visit_important(self, node): + self.visit_admonition(node, 'important') + def depart_important(self, node): + self.depart_admonition() + + def visit_tip(self, node): + self.visit_admonition(node, 'tip') + def depart_tip(self, node): + self.depart_admonition() + + # these are only handled specially in the SmartyPantsHTMLTranslator + def visit_literal_emphasis(self, node): + return self.visit_emphasis(node) + def depart_literal_emphasis(self, node): + return self.depart_emphasis(node) + + def depart_title(self, node): + close_tag = self.context[-1] + if self.builder.add_header_links and \ + (close_tag.startswith('\u00B6    ' % + _('Permalink to this headline')) + BaseTranslator.depart_title(self, node) + + def unknown_visit(self, node): + raise NotImplementedError('Unknown node: ' + node.__class__.__name__) + + +class SmartyPantsHTMLTranslator(HTMLTranslator): + """ + Handle ordinary text via smartypants, converting quotes and dashes + to the correct entities. + """ + + def __init__(self, *args, **kwds): + self.no_smarty = 0 + HTMLTranslator.__init__(self, *args, **kwds) + + def visit_literal(self, node): + self.no_smarty += 1 + try: + # this raises SkipNode + HTMLTranslator.visit_literal(self, node) + finally: + self.no_smarty -= 1 + + def visit_literal_emphasis(self, node): + self.no_smarty += 1 + self.visit_emphasis(node) + + def depart_literal_emphasis(self, node): + self.depart_emphasis(node) + self.no_smarty -= 1 + + def visit_desc_signature(self, node): + self.no_smarty += 1 + HTMLTranslator.visit_desc_signature(self, node) + + def depart_desc_signature(self, node): + self.no_smarty -= 1 + HTMLTranslator.depart_desc_signature(self, node) + + def visit_productionlist(self, node): + self.no_smarty += 1 + try: + HTMLTranslator.visit_productionlist(self, node) + finally: + self.no_smarty -= 1 + + def visit_option(self, node): + self.no_smarty += 1 + HTMLTranslator.visit_option(self, node) + def depart_option(self, node): + self.no_smarty -= 1 + HTMLTranslator.depart_option(self, node) + + def bulk_text_processor(self, text): + if self.no_smarty <= 0: + return sphinx_smarty_pants(text) + return text diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py new file mode 100644 index 00000000..94cb23db --- /dev/null +++ b/sphinx/writers/latex.py @@ -0,0 +1,1185 @@ +# -*- coding: utf-8 -*- +""" + sphinx.latexwriter + ~~~~~~~~~~~~~~~~~~ + + Custom docutils writer for LaTeX. + + Much of this code is adapted from Dave Kuhlman's "docpy" writer from his + docutils sandbox. + + :copyright: 2007-2008 by Georg Brandl, Dave Kuhlman. + :license: BSD. +""" + +import re +import sys +from os import path + +from docutils import nodes, writers +from docutils.writers.latex2e import Babel + +from sphinx import addnodes +from sphinx import highlighting +from sphinx.locale import admonitionlabels, versionlabels +from sphinx.util import ustrftime +from sphinx.util.texescape import tex_escape_map +from sphinx.util.smartypants import educateQuotesLatex + +HEADER = r'''%% Generated by Sphinx. +\documentclass[%(papersize)s,%(pointsize)s%(classoptions)s]{%(docclass)s} +%(inputenc)s +%(fontenc)s +%(babel)s +%(fontpkg)s +%(fncychap)s +\usepackage{sphinx} +%(preamble)s + +\title{%(title)s} +\date{%(date)s} +\release{%(release)s} +\author{%(author)s} +\newcommand{\sphinxlogo}{%(logo)s} +\renewcommand{\releasename}{%(releasename)s} +%(makeindex)s +%(makemodindex)s +''' + +BEGIN_DOC = r''' +\begin{document} +%(shorthandoff)s +%(maketitle)s +%(tableofcontents)s +''' + +FOOTER = r''' +%(footer)s +\renewcommand{\indexname}{%(modindexname)s} +%(printmodindex)s +\renewcommand{\indexname}{%(indexname)s} +%(printindex)s +\end{document} +''' + + +class LaTeXWriter(writers.Writer): + + supported = ('sphinxlatex',) + + settings_spec = ('LaTeX writer options', '', ( + ('Document name', ['--docname'], {'default': ''}), + ('Document class', ['--docclass'], {'default': 'manual'}), + ('Author', ['--author'], {'default': ''}), + )) + settings_defaults = {} + + output = None + + def __init__(self, builder): + writers.Writer.__init__(self) + self.builder = builder + + def translate(self): + visitor = LaTeXTranslator(self.document, self.builder) + self.document.walkabout(visitor) + self.output = visitor.astext() + + +# Helper classes + +class ExtBabel(Babel): + def get_shorthandoff(self): + shortlang = self.language.split('_')[0] + if shortlang in ('de', 'sl', 'pt', 'es', 'nl', 'pl'): + return '\\shorthandoff{"}' + return '' + + _ISO639_TO_BABEL = Babel._ISO639_TO_BABEL.copy() + _ISO639_TO_BABEL['sl'] = 'slovene' + + +class Table(object): + def __init__(self): + self.col = 0 + self.colcount = 0 + self.colspec = None + self.had_head = False + self.has_verbatim = False + self.caption = None + + +class Desc(object): + def __init__(self, node): + self.env = LaTeXTranslator.desc_map.get(node['desctype'], 'describe') + self.type = self.cls = self.name = self.params = self.annotation = '' + self.count = 0 + + +class LaTeXTranslator(nodes.NodeVisitor): + sectionnames = ["part", "chapter", "section", "subsection", + "subsubsection", "paragraph", "subparagraph"] + + ignore_missing_images = False + + default_elements = { + 'docclass': 'manual', + 'papersize': 'letterpaper', + 'pointsize': '10pt', + 'classoptions': '', + 'inputenc': '\\usepackage[utf8]{inputenc}', + 'fontenc': '\\usepackage[T1]{fontenc}', + 'babel': '\\usepackage{babel}', + 'fontpkg': '\\usepackage{times}', + 'fncychap': '\\usepackage[Bjarne]{fncychap}', + 'preamble': '', + 'title': '', + 'date': '', + 'release': '', + 'author': '', + 'logo': '', + 'releasename': 'Release', + 'makeindex': '\\makeindex', + 'makemodindex': '\\makemodindex', + 'shorthandoff': '', + 'maketitle': '\\maketitle', + 'tableofcontents': '\\tableofcontents', + 'footer': '', + 'printmodindex': '\\printmodindex', + 'printindex': '\\printindex', + } + + def __init__(self, document, builder): + nodes.NodeVisitor.__init__(self, document) + self.builder = builder + self.body = [] + + # sort out some elements + papersize = builder.config.latex_paper_size + 'paper' + if papersize == 'paper': # e.g. command line "-D latex_paper_size=" + papersize = 'letterpaper' + + self.elements = self.default_elements.copy() + self.elements.update({ + 'docclass': document.settings.docclass, + 'papersize': papersize, + 'pointsize': builder.config.latex_font_size, + # if empty, the title is set to the first section title + 'title': document.settings.title, + 'date': ustrftime(builder.config.today_fmt or _('%B %d, %Y')), + 'release': builder.config.release, + 'author': document.settings.author, + 'releasename': _('Release'), + 'preamble': builder.config.latex_preamble, + 'modindexname': _('Module Index'), + 'indexname': _('Index'), + }) + if builder.config.latex_logo: + self.elements['logo'] = '\\includegraphics{%s}\\par' % \ + path.basename(builder.config.latex_logo) + if builder.config.language: + babel = ExtBabel(builder.config.language) + lang = babel.get_language() + if lang: + self.elements['classoptions'] += ',' + babel.get_language() + else: + self.builder.warn('no Babel option known for language %r' % + builder.config.language) + self.elements['shorthandoff'] = babel.get_shorthandoff() + self.elements['fncychap'] = '\\usepackage[Sonny]{fncychap}' + else: + self.elements['classoptions'] += ',english' + if not builder.config.latex_use_modindex: + self.elements['makemodindex'] = '' + self.elements['printmodindex'] = '' + # allow the user to override them all + self.elements.update(builder.config.latex_elements) + + self.highlighter = highlighting.PygmentsBridge( + 'latex', builder.config.pygments_style) + self.context = [] + self.descstack = [] + self.bibitems = [] + self.table = None + self.next_table_colspec = None + self.highlightlang = builder.config.highlight_language + self.highlightlinenothreshold = sys.maxint + self.written_ids = set() + self.footnotestack = [] + if self.elements['docclass'] == 'manual': + if builder.config.latex_use_parts: + self.top_sectionlevel = 0 + else: + self.top_sectionlevel = 1 + else: + self.top_sectionlevel = 2 + self.next_section_target = None + # flags + self.verbatim = None + self.in_title = 0 + self.in_production_list = 0 + self.first_document = 1 + self.this_is_the_title = 1 + self.literal_whitespace = 0 + self.no_contractions = 0 + + def astext(self): + return (HEADER % self.elements + self.highlighter.get_stylesheet() + + u''.join(self.body) + FOOTER % self.elements) + + def visit_document(self, node): + self.footnotestack.append(self.collect_footnotes(node)) + if self.first_document == 1: + # the first document is all the regular content ... + self.body.append(BEGIN_DOC % self.elements) + self.first_document = 0 + elif self.first_document == 0: + # ... and all others are the appendices + self.body.append('\n\\appendix\n') + self.first_document = -1 + # "- 1" because the level is increased before the title is visited + self.sectionlevel = self.top_sectionlevel - 1 + def depart_document(self, node): + if self.bibitems: + widest_label = "" + for bi in self.bibitems: + if len(widest_label) < len(bi[0]): + widest_label = bi[0] + self.body.append('\n\\begin{thebibliography}{%s}\n' % widest_label) + for bi in self.bibitems: + # cite_key: underscores must not be escaped + cite_key = bi[0].replace(r"\_", "_") + self.body.append('\\bibitem[%s]{%s}{%s}\n' % (bi[0], cite_key, bi[1])) + self.body.append('\\end{thebibliography}\n') + self.bibitems = [] + + def visit_start_of_file(self, node): + # This marks the begin of a new file; therefore the current module and + # class must be reset + self.body.append('\n\\resetcurrentobjects\n') + # and also, new footnotes + self.footnotestack.append(self.collect_footnotes(node)) + + def collect_footnotes(self, node): + fnotes = {} + def footnotes_under(n): + if isinstance(n, nodes.footnote): + yield n + else: + for c in n.children: + if isinstance(c, addnodes.start_of_file): + continue + for k in footnotes_under(c): + yield k + for fn in footnotes_under(node): + num = fn.children[0].astext().strip() + fnotes[num] = fn + fn.parent.remove(fn) + return fnotes + + def depart_start_of_file(self, node): + self.footnotestack.pop() + + def visit_highlightlang(self, node): + self.highlightlang = node['lang'] + self.highlightlinenothreshold = node['linenothreshold'] + raise nodes.SkipNode + + def visit_section(self, node): + if not self.this_is_the_title: + self.sectionlevel += 1 + self.body.append('\n\n') + if self.next_section_target: + self.body.append(r'\hypertarget{%s}{}' % self.next_section_target) + self.next_section_target = None + #if node.get('ids'): + # for id in node['ids']: + # if id not in self.written_ids: + # self.body.append(r'\hypertarget{%s}{}' % id) + # self.written_ids.add(id) + def depart_section(self, node): + self.sectionlevel = max(self.sectionlevel - 1, self.top_sectionlevel - 1) + + def visit_problematic(self, node): + self.body.append(r'{\color{red}\bfseries{}') + def depart_problematic(self, node): + self.body.append('}') + + def visit_topic(self, node): + self.body.append('\\setbox0\\vbox{\n' + '\\begin{minipage}{0.95\\textwidth}\n') + def depart_topic(self, node): + self.body.append('\\end{minipage}}\n' + '\\begin{center}\\setlength{\\fboxsep}{5pt}' + '\\shadowbox{\\box0}\\end{center}\n') + visit_sidebar = visit_topic + depart_sidebar = depart_topic + + def visit_glossary(self, node): + pass + def depart_glossary(self, node): + pass + + def visit_productionlist(self, node): + self.body.append('\n\n\\begin{productionlist}\n') + self.in_production_list = 1 + def depart_productionlist(self, node): + self.body.append('\\end{productionlist}\n\n') + self.in_production_list = 0 + + def visit_production(self, node): + if node['tokenname']: + self.body.append('\\production{%s}{' % self.encode(node['tokenname'])) + else: + self.body.append('\\productioncont{') + def depart_production(self, node): + self.body.append('}\n') + + def visit_transition(self, node): + self.body.append('\n\n\\bigskip\\hrule{}\\bigskip\n\n') + def depart_transition(self, node): + pass + + def visit_title(self, node): + parent = node.parent + if isinstance(parent, addnodes.seealso): + # the environment already handles this + raise nodes.SkipNode + elif self.this_is_the_title: + if len(node.children) != 1 and not isinstance(node.children[0], nodes.Text): + self.builder.warn('document title is not a single Text node') + if not self.elements['title']: + # text needs to be escaped since it is inserted into + # the output literally + self.elements['title'] = node.astext().translate(tex_escape_map) + self.this_is_the_title = 0 + raise nodes.SkipNode + elif isinstance(parent, nodes.section): + try: + self.body.append(r'\%s{' % self.sectionnames[self.sectionlevel]) + except IndexError: + from sphinx.application import SphinxError + raise SphinxError('too many nesting section levels for LaTeX, ' + 'at heading: %s' % node.astext()) + self.context.append('}\n') + elif isinstance(parent, (nodes.topic, nodes.sidebar)): + self.body.append(r'\textbf{') + self.context.append('}\n\n\medskip\n\n') + elif isinstance(parent, nodes.Admonition): + self.body.append('{') + self.context.append('}\n') + elif isinstance(parent, nodes.table): + self.table.caption = self.encode(node.astext()) + raise nodes.SkipNode + else: + self.builder.warn('encountered title node not in section, topic, ' + 'table, admonition or sidebar') + self.body.append('\\textbf{') + self.context.append('}\n') + self.in_title = 1 + def depart_title(self, node): + self.in_title = 0 + self.body.append(self.context.pop()) + + def visit_subtitle(self, node): + if isinstance(node.parent, nodes.sidebar): + self.body.append('~\\\\\n\\textbf{') + self.context.append('}\n\\smallskip\n') + else: + self.context.append('') + def depart_subtitle(self, node): + self.body.append(self.context.pop()) + + desc_map = { + 'function' : 'funcdesc', + 'class': 'classdesc', + 'method': 'methoddesc', + 'staticmethod': 'staticmethoddesc', + 'exception': 'excdesc', + 'data': 'datadesc', + 'attribute': 'memberdesc', + 'opcode': 'opcodedesc', + + 'cfunction': 'cfuncdesc', + 'cmember': 'cmemberdesc', + 'cmacro': 'csimplemacrodesc', + 'ctype': 'ctypedesc', + 'cvar': 'cvardesc', + + 'describe': 'describe', + # and all others are 'describe' too + } + + def visit_desc(self, node): + self.descstack.append(Desc(node)) + def depart_desc(self, node): + d = self.descstack.pop() + self.body.append("\\end{%s}\n" % d.env) + + def visit_desc_signature(self, node): + d = self.descstack[-1] + # reset these for every signature + d.type = d.cls = d.name = d.params = '' + def depart_desc_signature(self, node): + d = self.descstack[-1] + d.cls = d.cls.rstrip('.') + if node.parent['desctype'] != 'describe' and node['ids']: + hyper = '\\hypertarget{%s}{}' % node['ids'][0] + else: + hyper = '' + if d.count == 0: + t1 = "\n\n%s\\begin{%s}" % (hyper, d.env) + else: + t1 = "\n%s\\%sline" % (hyper, d.env[:-4]) + d.count += 1 + if d.env in ('funcdesc', 'classdesc', 'excclassdesc'): + t2 = "{%s}{%s}" % (d.name, d.params) + elif d.env in ('datadesc', 'excdesc', 'csimplemacrodesc'): + t2 = "{%s}" % (d.name) + elif d.env in ('methoddesc', 'staticmethoddesc'): + if d.cls: + t2 = "[%s]{%s}{%s}" % (d.cls, d.name, d.params) + else: + t2 = "{%s}{%s}" % (d.name, d.params) + elif d.env == 'memberdesc': + if d.cls: + t2 = "[%s]{%s}" % (d.cls, d.name) + else: + t2 = "{%s}" % d.name + elif d.env == 'cfuncdesc': + if d.cls: + # C++ class names + d.name = '%s::%s' % (d.cls, d.name) + t2 = "{%s}{%s}{%s}" % (d.type, d.name, d.params) + elif d.env == 'cmemberdesc': + try: + type, container = d.type.rsplit(' ', 1) + container = container.rstrip('.') + except ValueError: + container = '' + type = d.type + t2 = "{%s}{%s}{%s}" % (container, type, d.name) + elif d.env == 'cvardesc': + t2 = "{%s}{%s}" % (d.type, d.name) + elif d.env == 'ctypedesc': + t2 = "{%s}" % (d.name) + elif d.env == 'opcodedesc': + t2 = "{%s}{%s}" % (d.name, d.params) + elif d.env == 'describe': + t2 = "{%s}" % d.name + self.body.append(t1 + t2) + + def visit_desc_type(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].type = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_desc_name(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].name = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_desc_addname(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].cls = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_desc_parameterlist(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].params = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_desc_annotation(self, node): + d = self.descstack[-1] + if d.env == 'describe': + d.name += self.encode(node.astext()) + else: + self.descstack[-1].annotation = self.encode(node.astext().strip()) + raise nodes.SkipNode + + def visit_refcount(self, node): + self.body.append("\\emph{") + def depart_refcount(self, node): + self.body.append("}\\\\") + + def visit_desc_content(self, node): + if node.children and not isinstance(node.children[0], nodes.paragraph): + # avoid empty desc environment which causes a formatting bug + self.body.append('~') + def depart_desc_content(self, node): + pass + + def visit_seealso(self, node): + self.body.append("\n\n\\strong{%s:}\n\n" % admonitionlabels['seealso']) + def depart_seealso(self, node): + self.body.append("\n\n") + + def visit_rubric(self, node): + if len(node.children) == 1 and node.children[0].astext() == 'Footnotes': + raise nodes.SkipNode + self.body.append('\\paragraph{') + self.context.append('}\n') + def depart_rubric(self, node): + self.body.append(self.context.pop()) + + def visit_footnote(self, node): + pass + def depart_footnote(self, node): + pass + + def visit_label(self, node): + if isinstance(node.parent, nodes.citation): + self.bibitems[-1][0] = node.astext() + raise nodes.SkipNode + + def visit_tabular_col_spec(self, node): + self.next_table_colspec = node['spec'] + raise nodes.SkipNode + + def visit_table(self, node): + if self.table: + raise NotImplementedError('Nested tables are not supported.') + self.table = Table() + self.tablebody = [] + # Redirect body output until table is finished. + self._body = self.body + self.body = self.tablebody + def depart_table(self, node): + self.body = self._body + if self.table.caption is not None: + self.body.append('\n\\begin{threeparttable}\n' + '\\caption{%s}\n' % self.table.caption) + if self.table.has_verbatim: + self.body.append('\n\\begin{tabular}') + else: + self.body.append('\n\\begin{tabulary}{\\textwidth}') + if self.table.colspec: + self.body.append(self.table.colspec) + else: + if self.table.has_verbatim: + colwidth = 0.95 / self.table.colcount + colspec = ('p{%.3f\\textwidth}|' % colwidth) * self.table.colcount + self.body.append('{|' + colspec + '}\n') + else: + self.body.append('{|' + ('L|' * self.table.colcount) + '}\n') + self.body.extend(self.tablebody) + if self.table.has_verbatim: + self.body.append('\\end{tabular}\n\n') + else: + self.body.append('\\end{tabulary}\n\n') + if self.table.caption is not None: + self.body.append('\\end{threeparttable}\n\n') + self.table = None + self.tablebody = None + + def visit_colspec(self, node): + self.table.colcount += 1 + def depart_colspec(self, node): + pass + + def visit_tgroup(self, node): + pass + def depart_tgroup(self, node): + pass + + def visit_thead(self, node): + if self.next_table_colspec: + self.table.colspec = '{%s}\n' % self.next_table_colspec + self.next_table_colspec = None + self.body.append('\\hline\n') + self.table.had_head = True + def depart_thead(self, node): + self.body.append('\\hline\n') + + def visit_tbody(self, node): + if not self.table.had_head: + self.visit_thead(node) + def depart_tbody(self, node): + self.body.append('\\hline\n') + + def visit_row(self, node): + self.table.col = 0 + def depart_row(self, node): + self.body.append('\\\\\n') + + def visit_entry(self, node): + if node.has_key('morerows') or node.has_key('morecols'): + raise NotImplementedError('Column or row spanning cells are ' + 'not implemented.') + if self.table.col > 0: + self.body.append(' & ') + self.table.col += 1 + if isinstance(node.parent.parent, nodes.thead): + self.body.append('\\textbf{') + self.context.append('}') + else: + self.context.append('') + def depart_entry(self, node): + self.body.append(self.context.pop()) # header + + def visit_acks(self, node): + # this is a list in the source, but should be rendered as a + # comma-separated list here + self.body.append('\n\n') + self.body.append(', '.join(n.astext() for n in node.children[0].children) + '.') + self.body.append('\n\n') + raise nodes.SkipNode + + def visit_bullet_list(self, node): + self.body.append('\\begin{itemize}\n' ) + def depart_bullet_list(self, node): + self.body.append('\\end{itemize}\n' ) + + def visit_enumerated_list(self, node): + self.body.append('\\begin{enumerate}\n' ) + def depart_enumerated_list(self, node): + self.body.append('\\end{enumerate}\n' ) + + def visit_list_item(self, node): + # Append "{}" in case the next character is "[", which would break + # LaTeX's list environment (no numbering and the "[" is not printed). + self.body.append(r'\item {} ') + def depart_list_item(self, node): + self.body.append('\n') + + def visit_definition_list(self, node): + self.body.append('\\begin{description}\n') + def depart_definition_list(self, node): + self.body.append('\\end{description}\n') + + def visit_definition_list_item(self, node): + pass + def depart_definition_list_item(self, node): + pass + + def visit_term(self, node): + ctx = ']' + if node.has_key('ids') and node['ids']: + ctx += '\\hypertarget{%s}{}' % node['ids'][0] + self.body.append('\\item[') + self.context.append(ctx) + def depart_term(self, node): + self.body.append(self.context.pop()) + + def visit_classifier(self, node): + self.body.append('{[}') + def depart_classifier(self, node): + self.body.append('{]}') + + def visit_definition(self, node): + pass + def depart_definition(self, node): + self.body.append('\n') + + def visit_field_list(self, node): + self.body.append('\\begin{quote}\\begin{description}\n') + def depart_field_list(self, node): + self.body.append('\\end{description}\\end{quote}\n') + + def visit_field(self, node): + pass + def depart_field(self, node): + pass + + visit_field_name = visit_term + depart_field_name = depart_term + + visit_field_body = visit_definition + depart_field_body = depart_definition + + def visit_paragraph(self, node): + self.body.append('\n') + def depart_paragraph(self, node): + self.body.append('\n') + + def visit_centered(self, node): + self.body.append('\n\\begin{centering}') + def depart_centered(self, node): + self.body.append('\n\\end{centering}') + + def visit_module(self, node): + modname = node['modname'] + self.body.append('\n\\declaremodule[%s]{}{%s}' % (modname.replace('_', ''), + self.encode(modname))) + self.body.append('\n\\modulesynopsis{%s}' % self.encode(node['synopsis'])) + if node.has_key('platform'): + self.body.append('\\platform{%s}' % self.encode(node['platform'])) + def depart_module(self, node): + pass + + def latex_image_length(self, width_str): + match = re.match('(\d*\.?\d*)\s*(\S*)', width_str) + if not match: + # fallback + return width_str + res = width_str + amount, unit = match.groups()[:2] + if not unit or unit == "px": + # pixels: let LaTeX alone + return None + elif unit == "%": + res = "%.3f\\linewidth" % (float(amount) / 100.0) + return res + + def visit_image(self, node): + attrs = node.attributes + pre = [] # in reverse order + post = [] + include_graphics_options = [] + inline = isinstance(node.parent, nodes.TextElement) + if attrs.has_key('scale'): + # Could also be done with ``scale`` option to + # ``\includegraphics``; doing it this way for consistency. + pre.append('\\scalebox{%f}{' % (attrs['scale'] / 100.0,)) + post.append('}') + if attrs.has_key('width'): + w = self.latex_image_length(attrs['width']) + if w: + include_graphics_options.append('width=%s' % w) + if attrs.has_key('height'): + h = self.latex_image_length(attrs['height']) + include_graphics_options.append('height=%s' % h) + if attrs.has_key('align'): + align_prepost = { + # By default latex aligns the top of an image. + (1, 'top'): ('', ''), + (1, 'middle'): ('\\raisebox{-0.5\\height}{', '}'), + (1, 'bottom'): ('\\raisebox{-\\height}{', '}'), + (0, 'center'): ('{\\hfill', '\\hfill}'), + # These 2 don't exactly do the right thing. The image should + # be floated alongside the paragraph. See + # http://www.w3.org/TR/html4/struct/objects.html#adef-align-IMG + (0, 'left'): ('{', '\\hfill}'), + (0, 'right'): ('{\\hfill', '}'),} + try: + pre.append(align_prepost[inline, attrs['align']][0]) + post.append(align_prepost[inline, attrs['align']][1]) + except KeyError: + pass # XXX complain here? + if not inline: + pre.append('\n') + post.append('\n') + pre.reverse() + if node['uri'] in self.builder.images: + uri = self.builder.images[node['uri']] + else: + # missing image! + if self.ignore_missing_images: + return + uri = node['uri'] + if uri.find('://') != -1: + # ignore remote images + return + self.body.extend(pre) + options = '' + if include_graphics_options: + options = '[%s]' % ','.join(include_graphics_options) + self.body.append('\\includegraphics%s{%s}' % (options, uri)) + self.body.extend(post) + def depart_image(self, node): + pass + + def visit_figure(self, node): + if (not node.attributes.has_key('align') or + node.attributes['align'] == 'center'): + # centering does not add vertical space like center. + align = '\n\\centering' + align_end = '' + else: + # TODO non vertical space for other alignments. + align = '\\begin{flush%s}' % node.attributes['align'] + align_end = '\\end{flush%s}' % node.attributes['align'] + self.body.append('\\begin{figure}[htbp]%s\n' % align) + self.context.append('%s\\end{figure}\n' % align_end) + def depart_figure(self, node): + self.body.append(self.context.pop()) + + def visit_caption(self, node): + self.body.append('\\caption{') + def depart_caption(self, node): + self.body.append('}') + + def visit_legend(self, node): + self.body.append('{\\small ') + def depart_legend(self, node): + self.body.append('}') + + def visit_admonition(self, node): + self.body.append('\n\\begin{notice}{note}') + def depart_admonition(self, node): + self.body.append('\\end{notice}\n') + + def _make_visit_admonition(name): + def visit_admonition(self, node): + self.body.append('\n\\begin{notice}{%s}{%s:}' % + (name, admonitionlabels[name])) + return visit_admonition + def _depart_named_admonition(self, node): + self.body.append('\\end{notice}\n') + + visit_attention = _make_visit_admonition('attention') + depart_attention = _depart_named_admonition + visit_caution = _make_visit_admonition('caution') + depart_caution = _depart_named_admonition + visit_danger = _make_visit_admonition('danger') + depart_danger = _depart_named_admonition + visit_error = _make_visit_admonition('error') + depart_error = _depart_named_admonition + visit_hint = _make_visit_admonition('hint') + depart_hint = _depart_named_admonition + visit_important = _make_visit_admonition('important') + depart_important = _depart_named_admonition + visit_note = _make_visit_admonition('note') + depart_note = _depart_named_admonition + visit_tip = _make_visit_admonition('tip') + depart_tip = _depart_named_admonition + visit_warning = _make_visit_admonition('warning') + depart_warning = _depart_named_admonition + + def visit_versionmodified(self, node): + intro = versionlabels[node['type']] % node['version'] + if node.children: + intro += ': ' + else: + intro += '.' + self.body.append(intro) + def depart_versionmodified(self, node): + pass + + def visit_target(self, node): + def add_target(id): + # indexing uses standard LaTeX index markup, so the targets + # will be generated differently + if not id.startswith('index-'): + self.body.append(r'\hypertarget{%s}{}' % id) + + if node.has_key('refid') and node['refid'] not in self.written_ids: + parindex = node.parent.index(node) + try: + next = node.parent[parindex+1] + if isinstance(next, nodes.section): + self.next_section_target = node['refid'] + return + except IndexError: + pass + add_target(node['refid']) + self.written_ids.add(node['refid']) + def depart_target(self, node): + pass + + def visit_attribution(self, node): + self.body.append('\n\\begin{flushright}\n') + self.body.append('---') + def depart_attribution(self, node): + self.body.append('\n\\end{flushright}\n') + + def visit_index(self, node, scre=re.compile(r';\s*')): + entries = node['entries'] + for type, string, tid, _ in entries: + if type == 'single': + self.body.append(r'\index{%s}' % scre.sub('!', self.encode(string))) + elif type == 'pair': + parts = tuple(self.encode(x.strip()) for x in string.split(';', 1)) + self.body.append(r'\indexii{%s}{%s}' % parts) + elif type == 'triple': + parts = tuple(self.encode(x.strip()) for x in string.split(';', 2)) + self.body.append(r'\indexiii{%s}{%s}{%s}' % parts) + else: + self.builder.warn('unknown index entry type %s found' % type) + raise nodes.SkipNode + + def visit_raw(self, node): + if 'latex' in node.get('format', '').split(): + self.body.append(node.astext()) + raise nodes.SkipNode + + def visit_reference(self, node): + uri = node.get('refuri', '') + if self.in_title or not uri: + self.context.append('') + elif uri.startswith('mailto:') or uri.startswith('http:') or \ + uri.startswith('https:') or uri.startswith('ftp:'): + self.body.append('\\href{%s}{' % self.encode(uri)) + self.context.append('}') + elif uri.startswith('#'): + self.body.append('\\hyperlink{%s}{' % uri[1:]) + self.context.append('}') + elif uri.startswith('@token'): + if self.in_production_list: + self.body.append('\\token{') + else: + self.body.append('\\grammartoken{') + self.context.append('}') + else: + self.builder.warn('unusable reference target found: %s' % uri) + self.context.append('') + def depart_reference(self, node): + self.body.append(self.context.pop()) + + def visit_pending_xref(self, node): + pass + def depart_pending_xref(self, node): + pass + + def visit_emphasis(self, node): + self.body.append(r'\emph{') + def depart_emphasis(self, node): + self.body.append('}') + + def visit_literal_emphasis(self, node): + self.body.append(r'\emph{\texttt{') + self.no_contractions += 1 + def depart_literal_emphasis(self, node): + self.body.append('}}') + self.no_contractions -= 1 + + def visit_strong(self, node): + self.body.append(r'\textbf{') + def depart_strong(self, node): + self.body.append('}') + + def visit_title_reference(self, node): + self.body.append(r'\emph{') + def depart_title_reference(self, node): + self.body.append('}') + + def visit_citation(self, node): + # TODO maybe use cite bibitems + self.bibitems.append(['', '']) + self.context.append(len(self.body)) + def depart_citation(self, node): + size = self.context.pop() + text = ''.join(self.body[size:]) + del self.body[size:] + self.bibitems[-1][1] = text + + def visit_citation_reference(self, node): + citeid = node.astext() + self.body.append('\\cite{%s}' % citeid) + raise nodes.SkipNode + + def visit_literal(self, node): + content = self.encode(node.astext().strip()) + if self.in_title: + self.body.append(r'\texttt{%s}' % content) + elif node.has_key('role') and node['role'] == 'samp': + self.body.append(r'\samp{%s}' % content) + else: + self.body.append(r'\code{%s}' % content) + raise nodes.SkipNode + + def visit_footnote_reference(self, node): + num = node.astext().strip() + try: + fn = self.footnotestack[-1][num] + except (KeyError, IndexError): + raise nodes.SkipNode + self.body.append('\\footnote{') + fn.walkabout(self) + raise nodes.SkipChildren + def depart_footnote_reference(self, node): + self.body.append('}') + + def visit_literal_block(self, node): + self.verbatim = '' + def depart_literal_block(self, node): + code = self.verbatim.rstrip('\n') + lang = self.highlightlang + linenos = code.count('\n') >= self.highlightlinenothreshold - 1 + if node.has_key('language'): + # code-block directives + lang = node['language'] + if node.has_key('linenos'): + linenos = node['linenos'] + hlcode = self.highlighter.highlight_block(code, lang, linenos) + # workaround for Unicode issue + hlcode = hlcode.replace(u'€', u'@texteuro[]') + # must use original Verbatim environment and "tabular" environment + if self.table: + hlcode = hlcode.replace('\\begin{Verbatim}', + '\\begin{OriginalVerbatim}') + self.table.has_verbatim = True + # get consistent trailer + hlcode = hlcode.rstrip()[:-14] # strip \end{Verbatim} + hlcode = hlcode.rstrip() + '\n' + self.body.append('\n' + hlcode + '\\end{%sVerbatim}\n' % + (self.table and 'Original' or '')) + self.verbatim = None + visit_doctest_block = visit_literal_block + depart_doctest_block = depart_literal_block + + def visit_line_block(self, node): + """line-block: + * whitespace (including linebreaks) is significant + * inline markup is supported. + * serif typeface + """ + self.body.append('{\\raggedright{}') + self.literal_whitespace = 1 + def depart_line_block(self, node): + self.literal_whitespace = 0 + # remove the last \\ + del self.body[-1] + self.body.append('}\n') + + def visit_line(self, node): + self._line_start = len(self.body) + def depart_line(self, node): + if self._line_start == len(self.body): + # no output in this line -- add a nonbreaking space, else the + # \\ command will give an error + self.body.append('~') + if self.table is not None: + self.body.append('\\newline\n') + else: + self.body.append('\\\\\n') + + def visit_block_quote(self, node): + # If the block quote contains a single object and that object + # is a list, then generate a list not a block quote. + # This lets us indent lists. + done = 0 + if len(node.children) == 1: + child = node.children[0] + if isinstance(child, nodes.bullet_list) or \ + isinstance(child, nodes.enumerated_list): + done = 1 + if not done: + self.body.append('\\begin{quote}\n') + def depart_block_quote(self, node): + done = 0 + if len(node.children) == 1: + child = node.children[0] + if isinstance(child, nodes.bullet_list) or \ + isinstance(child, nodes.enumerated_list): + done = 1 + if not done: + self.body.append('\\end{quote}\n') + + # option node handling copied from docutils' latex writer + + def visit_option(self, node): + if self.context[-1]: + # this is not the first option + self.body.append(', ') + def depart_option(self, node): + # flag that the first option is done. + self.context[-1] += 1 + + def visit_option_argument(self, node): + """The delimiter betweeen an option and its argument.""" + self.body.append(node.get('delimiter', ' ')) + def depart_option_argument(self, node): + pass + + def visit_option_group(self, node): + self.body.append('\\item [') + # flag for first option + self.context.append(0) + def depart_option_group(self, node): + self.context.pop() # the flag + self.body.append('] ') + + def visit_option_list(self, node): + self.body.append('\\begin{optionlist}{3cm}\n') + def depart_option_list(self, node): + self.body.append('\\end{optionlist}\n') + + def visit_option_list_item(self, node): + pass + def depart_option_list_item(self, node): + pass + + def visit_option_string(self, node): + ostring = node.astext() + self.body.append(self.encode(ostring.replace('--', u'-{-}'))) + raise nodes.SkipNode + + def visit_description(self, node): + self.body.append( ' ' ) + def depart_description(self, node): + pass + + def visit_superscript(self, node): + self.body.append('$^{\\text{') + def depart_superscript(self, node): + self.body.append('}}$') + + def visit_subscript(self, node): + self.body.append('$_{\\text{') + def depart_subscript(self, node): + self.body.append('}}$') + + def visit_substitution_definition(self, node): + raise nodes.SkipNode + + def visit_substitution_reference(self, node): + raise nodes.SkipNode + + def visit_generated(self, node): + pass + def depart_generated(self, node): + pass + + def visit_compound(self, node): + pass + def depart_compound(self, node): + pass + + def visit_container(self, node): + pass + def depart_container(self, node): + pass + + def visit_decoration(self, node): + pass + def depart_decoration(self, node): + pass + + # text handling + + def encode(self, text): + text = unicode(text).translate(tex_escape_map) + if self.literal_whitespace: + # Insert a blank before the newline, to avoid + # ! LaTeX Error: There's no line here to end. + text = text.replace(u'\n', u'~\\\\\n').replace(u' ', u'~') + if self.no_contractions: + text = text.replace('--', u'-{-}') + return text + + def visit_Text(self, node): + if self.verbatim is not None: + self.verbatim += node.astext() + else: + text = self.encode(node.astext()) + self.body.append(educateQuotesLatex(text)) + def depart_Text(self, node): + pass + + def visit_comment(self, node): + raise nodes.SkipNode + + def visit_meta(self, node): + # only valid for HTML + raise nodes.SkipNode + + def visit_system_message(self, node): + pass + def depart_system_message(self, node): + self.body.append('\n') + + def unknown_visit(self, node): + raise NotImplementedError('Unknown node: ' + node.__class__.__name__) diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py new file mode 100644 index 00000000..4aa18039 --- /dev/null +++ b/sphinx/writers/text.py @@ -0,0 +1,679 @@ +# -*- coding: utf-8 -*- +""" + sphinx.textwriter + ~~~~~~~~~~~~~~~~~ + + Custom docutils writer for plain text. + + :copyright: 2008 by Georg Brandl. + :license: BSD. +""" + +import re +import textwrap + +from docutils import nodes, writers + +from sphinx import addnodes +from sphinx.locale import admonitionlabels, versionlabels + + +class TextWriter(writers.Writer): + supported = ('text',) + settings_spec = ('No options here.', '', ()) + settings_defaults = {} + + output = None + + def __init__(self, builder): + writers.Writer.__init__(self) + self.builder = builder + + def translate(self): + visitor = TextTranslator(self.document, self.builder) + self.document.walkabout(visitor) + self.output = visitor.body + +# monkey-patch... +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 +textwrap.TextWrapper.wordsep_re = new_wordsep_re + +MAXWIDTH = 70 +STDINDENT = 3 + + +class TextTranslator(nodes.NodeVisitor): + sectionchars = '*=-~"+' + + def __init__(self, document, builder): + nodes.NodeVisitor.__init__(self, document) + + self.states = [[]] + self.stateindent = [0] + self.sectionlevel = 0 + self.table = None + + def add_text(self, text): + self.states[-1].append((-1, text)) + def new_state(self, indent=STDINDENT): + self.states.append([]) + self.stateindent.append(indent) + def end_state(self, wrap=True, end=[''], first=None): + content = self.states.pop() + maxindent = sum(self.stateindent) + indent = self.stateindent.pop() + result = [] + toformat = [] + def do_format(): + if not toformat: + return + if wrap: + res = textwrap.wrap(''.join(toformat), width=MAXWIDTH-maxindent) + else: + res = ''.join(toformat).splitlines() + if end: + res += end + result.append((indent, res)) + for itemindent, item in content: + if itemindent == -1: + toformat.append(item) + else: + do_format() + result.append((indent + itemindent, item)) + toformat = [] + do_format() + if first is not None and result: + itemindent, item = result[0] + if item: + result.insert(0, (itemindent - indent, [first + item[0]])) + result[1] = (itemindent, item[1:]) + self.states[-1].extend(result) + + def visit_document(self, node): + self.new_state(0) + def depart_document(self, node): + self.end_state() + self.body = '\n'.join(line and (' '*indent + line) + for indent, lines in self.states[0] + for line in lines) + # XXX header/footer? + + def visit_highlightlang(self, node): + raise nodes.SkipNode + + def visit_section(self, node): + self._title_char = self.sectionchars[self.sectionlevel] + self.sectionlevel += 1 + def depart_section(self, node): + self.sectionlevel -= 1 + + def visit_topic(self, node): + self.new_state(0) + def depart_topic(self, node): + self.end_state() + + visit_sidebar = visit_topic + depart_sidebar = depart_topic + + def visit_rubric(self, node): + self.new_state(0) + self.add_text('-[ ') + def depart_rubric(self, node): + self.add_text(' ]-') + self.end_state() + + def visit_compound(self, node): + pass + def depart_compound(self, node): + pass + + def visit_glossary(self, node): + pass + def depart_glossary(self, node): + pass + + def visit_title(self, node): + if isinstance(node.parent, nodes.Admonition): + self.add_text(node.astext()+': ') + raise nodes.SkipNode + self.new_state(0) + def depart_title(self, node): + if isinstance(node.parent, nodes.section): + char = self._title_char + else: + char = '^' + text = ''.join(x[1] for x in self.states.pop() if x[0] == -1) + self.stateindent.pop() + self.states[-1].append((0, ['', text, '%s' % (char * len(text)), ''])) + + def visit_subtitle(self, node): + pass + def depart_subtitle(self, node): + pass + + def visit_attribution(self, node): + self.add_text('-- ') + def depart_attribution(self, node): + pass + + def visit_module(self, node): + if node.has_key('platform'): + self.new_state(0) + self.add_text(_('Platform: %s') % node['platform']) + self.end_state() + raise nodes.SkipNode + + def visit_desc(self, node): + pass + def depart_desc(self, node): + pass + + def visit_desc_signature(self, node): + self.new_state(0) + if node.parent['desctype'] in ('class', 'exception'): + self.add_text('%s ' % node.parent['desctype']) + def depart_desc_signature(self, node): + # XXX: wrap signatures in a way that makes sense + self.end_state(wrap=False, end=None) + + def visit_desc_name(self, node): + pass + def depart_desc_name(self, node): + pass + + def visit_desc_addname(self, node): + pass + def depart_desc_addname(self, node): + pass + + def visit_desc_type(self, node): + pass + def depart_desc_type(self, node): + pass + + def visit_desc_parameterlist(self, node): + self.add_text('(') + self.first_param = 1 + def depart_desc_parameterlist(self, node): + self.add_text(')') + + def visit_desc_parameter(self, node): + if not self.first_param: + self.add_text(', ') + else: + self.first_param = 0 + self.add_text(node.astext()) + raise nodes.SkipNode + + def visit_desc_optional(self, node): + self.add_text('[') + def depart_desc_optional(self, node): + self.add_text(']') + + def visit_desc_annotation(self, node): + pass + def depart_desc_annotation(self, node): + pass + + def visit_refcount(self, node): + pass + def depart_refcount(self, node): + pass + + def visit_desc_content(self, node): + self.new_state() + self.add_text('\n') + def depart_desc_content(self, node): + self.end_state() + + def visit_figure(self, node): + self.new_state() + def depart_figure(self, node): + self.end_state() + + def visit_caption(self, node): + pass + def depart_caption(self, node): + pass + + def visit_productionlist(self, node): + self.new_state() + names = [] + for production in node: + names.append(production['tokenname']) + maxlen = max(len(name) for name in names) + for production in node: + if production['tokenname']: + self.add_text(production['tokenname'].ljust(maxlen) + ' ::=') + lastname = production['tokenname'] + else: + self.add_text('%s ' % (' '*len(lastname))) + self.add_text(production.astext() + '\n') + self.end_state(wrap=False) + raise nodes.SkipNode + + def visit_seealso(self, node): + self.new_state() + def depart_seealso(self, node): + self.end_state(first='') + + def visit_footnote(self, node): + self._footnote = node.children[0].astext().strip() + self.new_state(len(self._footnote) + 3) + def depart_footnote(self, node): + self.end_state(first='[%s] ' % self._footnote) + + def visit_citation(self, node): + if len(node) and isinstance(node[0], nodes.label): + self._citlabel = node[0].astext() + else: + self._citlabel = '' + self.new_state(len(self._citlabel) + 3) + def depart_citation(self, node): + self.end_state(first='[%s] ' % self._citlabel) + + def visit_label(self, node): + raise nodes.SkipNode + + # XXX: option list could use some better styling + + def visit_option_list(self, node): + pass + def depart_option_list(self, node): + pass + + def visit_option_list_item(self, node): + self.new_state(0) + def depart_option_list_item(self, node): + self.end_state() + + def visit_option_group(self, node): + self._firstoption = True + def depart_option_group(self, node): + self.add_text(' ') + + def visit_option(self, node): + if self._firstoption: + self._firstoption = False + else: + self.add_text(', ') + def depart_option(self, node): + pass + + def visit_option_string(self, node): + pass + def depart_option_string(self, node): + pass + + def visit_option_argument(self, node): + self.add_text(node['delimiter']) + def depart_option_argument(self, node): + pass + + def visit_description(self, node): + pass + def depart_description(self, node): + pass + + def visit_tabular_col_spec(self, node): + raise nodes.SkipNode + + def visit_colspec(self, node): + self.table[0].append(node['colwidth']) + raise nodes.SkipNode + + def visit_tgroup(self, node): + pass + def depart_tgroup(self, node): + pass + + def visit_thead(self, node): + pass + def depart_thead(self, node): + pass + + def visit_tbody(self, node): + self.table.append('sep') + def depart_tbody(self, node): + pass + + def visit_row(self, node): + self.table.append([]) + def depart_row(self, node): + pass + + def visit_entry(self, node): + if node.has_key('morerows') or node.has_key('morecols'): + raise NotImplementedError('Column or row spanning cells are ' + 'not implemented.') + self.new_state(0) + def depart_entry(self, node): + text = '\n'.join('\n'.join(x[1]) for x in self.states.pop()) + self.stateindent.pop() + self.table[-1].append(text) + + def visit_table(self, node): + if self.table: + raise NotImplementedError('Nested tables are not supported.') + self.new_state(0) + self.table = [[]] + def depart_table(self, node): + lines = self.table[1:] + fmted_rows = [] + colwidths = self.table[0] + realwidths = colwidths[:] + separator = 0 + # don't allow paragraphs in table cells for now + for line in lines: + if line == 'sep': + separator = len(fmted_rows) + else: + cells = [] + for i, cell in enumerate(line): + par = textwrap.wrap(cell, width=colwidths[i]) + if par: + maxwidth = max(map(len, par)) + else: + maxwidth = 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.add_text(''.join(out) + '\n') + + 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.add_text(''.join(out) + '\n') + + for i, row in enumerate(fmted_rows): + if separator and i == separator: + writesep('=') + else: + writesep('-') + writerow(row) + writesep('-') + self.table = None + self.end_state(wrap=False) + + def visit_acks(self, node): + self.new_state(0) + self.add_text(', '.join(n.astext() for n in node.children[0].children) + '.') + self.end_state() + raise nodes.SkipNode + + def visit_image(self, node): + self.add_text(_('[image]')) + raise nodes.SkipNode + + def visit_transition(self, node): + indent = sum(self.stateindent) + self.new_state(0) + self.add_text('=' * (MAXWIDTH - indent)) + self.end_state() + raise nodes.SkipNode + + def visit_bullet_list(self, node): + self._list_counter = -1 + def depart_bullet_list(self, node): + pass + + def visit_enumerated_list(self, node): + self._list_counter = 0 + def depart_enumerated_list(self, node): + pass + + def visit_definition_list(self, node): + self._list_counter = -2 + def depart_definition_list(self, node): + pass + + def visit_list_item(self, node): + if self._list_counter == -1: + # bullet list + self.new_state(2) + elif self._list_counter == -2: + # definition list + pass + else: + # enumerated list + self._list_counter += 1 + self.new_state(len(str(self._list_counter)) + 2) + def depart_list_item(self, node): + if self._list_counter == -1: + self.end_state(first='* ', end=None) + elif self._list_counter == -2: + pass + else: + self.end_state(first='%s. ' % self._list_counter, end=None) + + def visit_definition_list_item(self, node): + self._li_has_classifier = len(node) >= 2 and \ + isinstance(node[1], nodes.classifier) + def depart_definition_list_item(self, node): + pass + + def visit_term(self, node): + self.new_state(0) + def depart_term(self, node): + if not self._li_has_classifier: + self.end_state(end=None) + + def visit_classifier(self, node): + self.add_text(' : ') + def depart_classifier(self, node): + self.end_state(end=None) + + def visit_definition(self, node): + self.new_state() + def depart_definition(self, node): + self.end_state() + + def visit_field_list(self, node): + pass + def depart_field_list(self, node): + pass + + def visit_field(self, node): + pass + def depart_field(self, node): + pass + + def visit_field_name(self, node): + self.new_state(0) + def depart_field_name(self, node): + self.add_text(':') + self.end_state(end=None) + + def visit_field_body(self, node): + self.new_state() + def depart_field_body(self, node): + self.end_state() + + def visit_centered(self, node): + pass + def depart_centered(self, node): + pass + + def visit_admonition(self, node): + self.new_state(0) + def depart_admonition(self, node): + self.end_state() + + def _visit_admonition(self, node): + self.new_state(2) + def _make_depart_admonition(name): + def depart_admonition(self, node): + self.end_state(first=admonitionlabels[name] + ': ') + return depart_admonition + + visit_attention = _visit_admonition + depart_attention = _make_depart_admonition('attention') + visit_caution = _visit_admonition + depart_caution = _make_depart_admonition('caution') + visit_danger = _visit_admonition + depart_danger = _make_depart_admonition('danger') + visit_error = _visit_admonition + depart_error = _make_depart_admonition('error') + visit_hint = _visit_admonition + depart_hint = _make_depart_admonition('hint') + visit_important = _visit_admonition + depart_important = _make_depart_admonition('important') + visit_note = _visit_admonition + depart_note = _make_depart_admonition('note') + visit_tip = _visit_admonition + depart_tip = _make_depart_admonition('tip') + visit_warning = _visit_admonition + depart_warning = _make_depart_admonition('warning') + + def visit_versionmodified(self, node): + self.new_state(0) + if node.children: + self.add_text(versionlabels[node['type']] % node['version'] + ': ') + else: + self.add_text(versionlabels[node['type']] % node['version'] + '.') + def depart_versionmodified(self, node): + self.end_state() + + def visit_literal_block(self, node): + self.new_state() + def depart_literal_block(self, node): + self.end_state(wrap=False) + + def visit_doctest_block(self, node): + self.new_state(0) + def depart_doctest_block(self, node): + self.end_state(wrap=False) + + def visit_line_block(self, node): + self.new_state(0) + def depart_line_block(self, node): + self.end_state(wrap=False) + + def visit_line(self, node): + pass + def depart_line(self, node): + pass + + def visit_block_quote(self, node): + self.new_state() + def depart_block_quote(self, node): + self.end_state() + + def visit_compact_paragraph(self, node): + pass + def depart_compact_paragraph(self, node): + pass + + def visit_paragraph(self, node): + if not isinstance(node.parent, nodes.Admonition) or \ + isinstance(node.parent, addnodes.seealso): + self.new_state(0) + def depart_paragraph(self, node): + if not isinstance(node.parent, nodes.Admonition) or \ + isinstance(node.parent, addnodes.seealso): + self.end_state() + + def visit_target(self, node): + raise nodes.SkipNode + + def visit_index(self, node): + raise nodes.SkipNode + + def visit_substitution_definition(self, node): + raise nodes.SkipNode + + def visit_pending_xref(self, node): + pass + def depart_pending_xref(self, node): + pass + + def visit_reference(self, node): + pass + def depart_reference(self, node): + pass + + def visit_emphasis(self, node): + self.add_text('*') + def depart_emphasis(self, node): + self.add_text('*') + + def visit_literal_emphasis(self, node): + self.add_text('*') + def depart_literal_emphasis(self, node): + self.add_text('*') + + def visit_strong(self, node): + self.add_text('**') + def depart_strong(self, node): + self.add_text('**') + + def visit_title_reference(self, node): + self.add_text('*') + def depart_title_reference(self, node): + self.add_text('*') + + def visit_literal(self, node): + self.add_text('``') + def depart_literal(self, node): + self.add_text('``') + + def visit_subscript(self, node): + self.add_text('_') + def depart_subscript(self, node): + pass + + def visit_superscript(self, node): + self.add_text('^') + def depart_superscript(self, node): + pass + + def visit_footnote_reference(self, node): + self.add_text('[%s]' % node.astext()) + raise nodes.SkipNode + + def visit_citation_reference(self, node): + self.add_text('[%s]' % node.astext()) + raise nodes.SkipNode + + def visit_Text(self, node): + self.add_text(node.astext()) + def depart_Text(self, node): + pass + + def visit_problematic(self, node): + self.add_text('>>') + def depart_problematic(self, node): + self.add_text('<<') + + def visit_system_message(self, node): + self.new_state(0) + self.add_text('' % node.astext()) + self.end_state() + raise nodes.SkipNode + + def visit_comment(self, node): + raise nodes.SkipNode + + def visit_meta(self, node): + # only valid for HTML + raise nodes.SkipNode + + def unknown_visit(self, node): + raise NotImplementedError('Unknown node: ' + node.__class__.__name__) -- cgit v1.2.1 From bb0febdac28daeed9e1fe265dbbe40405a68ca3b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 15 Dec 2008 10:21:01 +0100 Subject: Add Italian locale, translation by Sandro Dentella. --- CHANGES | 4 + doc/config.rst | 1 + sphinx/locale/it/LC_MESSAGES/sphinx.js | 1 + sphinx/locale/it/LC_MESSAGES/sphinx.mo | Bin 0 -> 8415 bytes sphinx/locale/it/LC_MESSAGES/sphinx.po | 599 +++++++++++++++++++++++++++++++++ sphinx/writers/latex.py | 2 +- 6 files changed, 606 insertions(+), 1 deletion(-) create mode 100644 sphinx/locale/it/LC_MESSAGES/sphinx.js create mode 100644 sphinx/locale/it/LC_MESSAGES/sphinx.mo create mode 100644 sphinx/locale/it/LC_MESSAGES/sphinx.po diff --git a/CHANGES b/CHANGES index aaf635f5..c54577ea 100644 --- a/CHANGES +++ b/CHANGES @@ -10,6 +10,10 @@ New features added switch off the generated "paragraph sign" permalinks for each heading and definition environment. +* New translations: + + - Italian by Sandro Dentella. + * Extension API: - There is now a Sphinx.add_lexer() method to add custom Pygments diff --git a/doc/config.rst b/doc/config.rst index 53816cc7..91cc7c3f 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -205,6 +205,7 @@ Project information * ``en`` -- English * ``es`` -- Spanish * ``fr`` -- French + * ``it`` -- Italian * ``nl`` -- Dutch * ``pl`` -- Polish * ``pt_BR`` -- Brazilian Portuguese diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.js b/sphinx/locale/it/LC_MESSAGES/sphinx.js new file mode 100644 index 00000000..c2c8be7b --- /dev/null +++ b/sphinx/locale/it/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "it", "plural_expr": "(n != 1)", "messages": {"module, in ": "modulo, in", "Preparing search...": "Preparazione della ricerca", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "La tua ricerca non ha trovato alcun risultato. Controlla la corettezzadei termini di ricerca e di avere selezionato un numero sufficiente di categorie", "Search finished, found %s page(s) matching the search query.": "Ricera terminata, trovate %s pagine corrispondenti alla ricerca.", ", in ": ", in ", "Permalink to this headline": "link permanente per questa inestazione", "Searching": "Ricerca in corso", "Permalink to this definition": "link permanente per questa definizione", "Hide Search Matches": "Nascondi i risultati della ricerca", "Search Results": "Risultati della ricerca"}}); \ No newline at end of file diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.mo b/sphinx/locale/it/LC_MESSAGES/sphinx.mo new file mode 100644 index 00000000..7818e876 Binary files /dev/null and b/sphinx/locale/it/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.po b/sphinx/locale/it/LC_MESSAGES/sphinx.po new file mode 100644 index 00000000..e7c796b0 --- /dev/null +++ b/sphinx/locale/it/LC_MESSAGES/sphinx.po @@ -0,0 +1,599 @@ +# Translations template for Sphinx. +# Copyright (C) 2008 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# Sandro Dentella , 2008. +# +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.5\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2008-11-27 18:39+0100\n" +"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" +"Last-Translator: FULL NAME \n" +"Language-Team: LANGUAGE \n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.4\n" + +#: sphinx/builder.py:408 +#, python-format +msgid "%b %d, %Y" +msgstr "%d/%b/%Y" + +#: sphinx/builder.py:427 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Indice generale" + +#: sphinx/builder.py:427 +msgid "index" +msgstr "indice" + +#: sphinx/builder.py:429 sphinx/htmlhelp.py:156 +#: sphinx/templates/defindex.html:19 sphinx/templates/modindex.html:2 +#: sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Indice dei moduli" + +#: sphinx/builder.py:429 +msgid "modules" +msgstr "moduli" + +#: sphinx/builder.py:466 +msgid "next" +msgstr "successivo" + +#: sphinx/builder.py:473 +msgid "previous" +msgstr "precedente" + +#: sphinx/builder.py:1054 +msgid " (in " +msgstr " (in " + +#: sphinx/builder.py:1129 +msgid "Builtins" +msgstr "Builtin" + +#: sphinx/builder.py:1131 +msgid "Module level" +msgstr "Modulo" + +#: sphinx/environment.py:102 sphinx/latexwriter.py:169 +#, python-format +msgid "%B %d, %Y" +msgstr "%d %B %Y" + +#: sphinx/environment.py:291 sphinx/latexwriter.py:175 +#: sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:130 +msgid "Index" +msgstr "Indice" + +#: sphinx/environment.py:292 sphinx/latexwriter.py:174 +msgid "Module Index" +msgstr "Indice dei Moduli" + +#: sphinx/environment.py:293 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Cerca" + +#: sphinx/htmlwriter.py:79 sphinx/static/doctools.js:145 +msgid "Permalink to this definition" +msgstr "link permanente per questa definizione" + +#: sphinx/htmlwriter.py:399 sphinx/static/doctools.js:139 +msgid "Permalink to this headline" +msgstr "link permanente per questa inestazione" + +#: sphinx/latexwriter.py:172 +msgid "Relelase" +msgstr "Release" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:537 +#, python-format +msgid "environment variable; %s" +msgstr "variabile dámbiente, %s" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "Python Enhancement Proposals!PEP %s" + +#: sphinx/textwriter.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Piattaforma: %s" + +#: sphinx/textwriter.py:422 +msgid "[image]" +msgstr "[immagine]" + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "%s() (funzione built-in)" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "%s() (nel modulo %s)" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "%s (variabile built-in)" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#, python-format +msgid "%s (in module %s)" +msgstr "%s (nel modulo %s)" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "%s (classe built-in)" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "%s (classe in %s)" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "%s() (%s.%s metodo)" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "%s() (%s metodo)" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "%s() (%s.%s metodo statico)" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "%s() (%s metodo statico)" + +#: sphinx/directives/desc.py:70 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "%s (%s.%s attributo)" + +#: sphinx/directives/desc.py:72 +#, python-format +msgid "%s (%s attribute)" +msgstr "%s (%s attributo)" + +#: sphinx/directives/desc.py:74 +#, python-format +msgid "%s (C function)" +msgstr "%s (functione C)" + +#: sphinx/directives/desc.py:76 +#, python-format +msgid "%s (C member)" +msgstr "%s (membro C )" + +#: sphinx/directives/desc.py:78 +#, python-format +msgid "%s (C macro)" +msgstr "%s (macro C)" + +#: sphinx/directives/desc.py:80 +#, python-format +msgid "%s (C type)" +msgstr "%s (tipo C)" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (C variable)" +msgstr "%s (variabile C)" + +#: sphinx/directives/desc.py:100 +msgid "Raises" +msgstr "Solleva" + +#: sphinx/directives/desc.py:104 +msgid "Variable" +msgstr "Variabile" + +#: sphinx/directives/desc.py:107 +msgid "Returns" +msgstr "Ritorna" + +#: sphinx/directives/desc.py:116 +msgid "Return type" +msgstr "Tipo di ritorno" + +#: sphinx/directives/desc.py:143 +msgid "Parameters" +msgstr "Parametri" + +#: sphinx/directives/desc.py:423 +#, python-format +msgid "%scommand line option; %s" +msgstr "%sopzione di linea di comando; %s" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Piattaforme:" + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (modulo)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Autore della sezione" + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Autore del modulo" + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Autore: " + +#: sphinx/directives/other.py:246 +msgid "See also" +msgstr "Vedi anche" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Da fare" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(La riga originale si trova in %s, linea %d e può essere trovata " + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "qui" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Attenzione" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Attenzione" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Pericolo" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Errore" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Consiglio" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Importante" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Nota" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Vedi anche" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Suggerimento" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Avvertimento" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Nuovo nella versione %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Cambiato nella versione %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Deprecato dalla versione %s" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "modulo" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "keyword" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "operatore" + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "oggetto" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "eccezione" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "statement" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "funzione built-in" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Nascondi i risultati della ricerca" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Ricerca in corso" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Preparazione della ricerca" + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "modulo, in" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", in " + +#: sphinx/static/searchtools.js:447 sphinx/templates/search.html:18 +msgid "Search Results" +msgstr "Risultati della ricerca" + +#: sphinx/static/searchtools.js:449 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" +"La tua ricerca non ha trovato alcun risultato. Controlla la corettezza" +"dei termini di ricerca e di avere selezionato un numero sufficiente di categorie" + +#: sphinx/static/searchtools.js:451 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "Ricera terminata, trovate %s pagine corrispondenti alla ricerca." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Sintesi" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "Indici e tabelle:" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "Tabella dei contenuti completa" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "elenca l'insieme delle sezioni e sottosezioni" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "cerca in questa documentazione" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "accesso veloce ai moduli" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "tutte le funzioni, classi e moduli" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "Indice – %(key)s" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Indice completo in una pagina" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Indice delle pagine per lettera" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "può essere enorme" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Navigazione" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Tablella dei contenuti" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "Argomento precedente" + +#: sphinx/templates/layout.html:47 +msgid "previous chapter" +msgstr "capitolo precedente" + +#: sphinx/templates/layout.html:50 +msgid "Next topic" +msgstr "Argomento successivo" + +#: sphinx/templates/layout.html:51 +msgid "next chapter" +msgstr "capitolo successivo" + +#: sphinx/templates/layout.html:55 +msgid "This Page" +msgstr "Questa pagina" + +#: sphinx/templates/layout.html:59 +msgid "Suggest Change" +msgstr "Suggerisci una modifica" + +#: sphinx/templates/layout.html:60 sphinx/templates/layout.html:62 +msgid "Show Source" +msgstr "Mostra sorgente" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Ricerca veloce" + +#: sphinx/templates/layout.html:71 +msgid "Keyword search" +msgstr "Ricerca per parola chiave" + +#: sphinx/templates/layout.html:73 +msgid "Go" +msgstr "Vai" + +#: sphinx/templates/layout.html:78 +msgid "Enter a module, class or function name." +msgstr "Inserisci un modulo, classe o nome di funzione" + +#: sphinx/templates/layout.html:119 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "Cerca in %(docstitle)s" + +#: sphinx/templates/layout.html:128 +msgid "About these documents" +msgstr "A proposito di questi documenti" + +#: sphinx/templates/layout.html:131 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Cerca" + +#: sphinx/templates/layout.html:133 +msgid "Copyright" +msgstr "Copyright" + +#: sphinx/templates/layout.html:178 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "© Copyright %(copyright)s." + +#: sphinx/templates/layout.html:180 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "© Copyright %(copyright)s." + +#: sphinx/templates/layout.html:183 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "Ultimo Aggiornamento on %(last_updated)s." + +#: sphinx/templates/layout.html:186 +#, python-format +msgid "" +"Created using Sphinx " +"%(sphinx_version)s." +msgstr "" +"Creato con Sphinx " +"%(sphinx_version)s." + +#: sphinx/templates/modindex.html:15 +msgid "Most popular modules:" +msgstr "Moduli più utilizzati" + +#: sphinx/templates/modindex.html:24 +msgid "Show modules only available on these platforms" +msgstr "Mostra solo i moduli disponibili su questa piattaforma" + +#: sphinx/templates/modindex.html:56 +msgid "Deprecated" +msgstr "Deprecato" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "Cerca %(docstitle)s" + +#: sphinx/templates/page.html:8 +msgid "" +"Note: You requested an out-of-date URL from this server." +" We've tried to redirect you to the new location of this page, but it may" +" not be the right one." +msgstr "" +"Nota: Hai chiesto un URL non più valido." +" Abbiamo provato a ridirigerti verso il nuovo indirizzo, ma potrebbe " +" non essere quello giusto" + +#: sphinx/templates/search.html:7 +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "" +"Puoi effettuare una ricerca in questi documenti. Immetti le parole chiave \n" +" della tua ricerca nel riquadro sottostante \"search\". Nota che la funzione\n" +" di ricerca cerca automaticamente per tutte le parole. Le pagine\n" +" che contendono meno parole non compariranno nei risultati di ricerca." + +#: sphinx/templates/search.html:14 +msgid "search" +msgstr "cerca" + +#: sphinx/templates/search.html:20 +msgid "Your search did not match any results." +msgstr "La tua ricerca non ha ottenuto risultati" + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Modifiche nella Versione %(version)s — %(docstitle)s" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "%(filename)s — %(docstitle)s" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Lista delle modifiche generata automaticamente nella versione %(version)s" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "Modifiche nela libreria" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "Modifche nelle API C" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "Altre modifiche" + diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 8191cb91..952042d8 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -91,7 +91,7 @@ class LaTeXWriter(writers.Writer): class ExtBabel(Babel): def get_shorthandoff(self): shortlang = self.language.split('_')[0] - if shortlang in ('de', 'sl', 'pt', 'es', 'nl', 'pl'): + if shortlang in ('de', 'sl', 'pt', 'es', 'nl', 'pl', 'it'): return '\\shorthandoff{"}' return '' -- cgit v1.2.1 From c0ee529e88d68c1564b96b525c8ec225a1525282 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 15 Dec 2008 12:33:13 +0100 Subject: Add "doctest_global_setup" conf val. --- CHANGES | 7 +++++-- doc/ext/doctest.rst | 8 ++++++++ sphinx/ext/doctest.py | 12 ++++++++++-- 3 files changed, 23 insertions(+), 4 deletions(-) diff --git a/CHANGES b/CHANGES index 4892c7e2..b2c07ad5 100644 --- a/CHANGES +++ b/CHANGES @@ -16,14 +16,17 @@ New features added * Extension API: - - There is now a Sphinx.add_lexer() method to add custom Pygments - lexers. + - There is now a ``Sphinx.add_lexer()`` method to be able to use + custom Pygments lexers easily. * Other changes: - Config overrides for single dict keys can now be given on the command line. + - There is now a ``doctest_global_setup`` config value that can + be used to give setup code for all doctests in the documentation. + Release 0.5.1 (in development) ============================== diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 9de6ba9e..7117f6a9 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -149,6 +149,14 @@ There are also these config values for customizing the doctest extension: A list of directories that will be added to :data:`sys.path` when the doctest builder is used. (Make sure it contains absolute paths.) +.. confval:: doctest_global_setup + + Python code that is treated like it were put in a ``testsetup`` directive for + *every* file that is tested, and for every group. You can use this to + e.g. import modules you will always need in your doctests. + + .. versionadded:: 0.6 + .. confval:: doctest_test_doctest_blocks If this is a nonempty string (the default is ``'default'``), standard reST diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index aa38bc71..b03f42fb 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -98,9 +98,12 @@ class TestGroup(object): self.setup = [] self.tests = [] - def add_code(self, code): + def add_code(self, code, prepend=False): if code.type == 'testsetup': - self.setup.append(code) + if prepend: + self.setup.insert(0, code) + else: + self.setup.append(code) elif code.type == 'doctest': self.tests.append([code]) elif code.type == 'testcode': @@ -243,6 +246,10 @@ Doctest summary for code in add_to_all_groups: for group in groups.itervalues(): group.add_code(code) + if self.config.doctest_global_setup: + code = TestCode(self.config.doctest_global_setup, 'testsetup', lineno=0) + for group in groups.itervalues(): + group.add_code(code, prepend=True) if not groups: return @@ -322,3 +329,4 @@ def setup(app): # this config value adds to sys.path app.add_config_value('doctest_path', [], False) app.add_config_value('doctest_test_doctest_blocks', 'default', False) + app.add_config_value('doctest_global_setup', '', False) -- cgit v1.2.1 From bf841f36c1265a31ad82c1f8c4bceac238d3081f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 15 Dec 2008 12:49:40 +0100 Subject: The ``autodoc_skip_member`` event now also gets to decide whether to skip members whose name starts with underscores. Previously, these members were always automatically skipped. Therefore, if you handle this event, add something like this to your event handler to restore the old behavior:: if name.startswith('_'): return True --- CHANGES | 11 +++++++++++ sphinx/ext/autodoc.py | 13 +++++++------ tests/test_autodoc.py | 12 ++++++++++++ 3 files changed, 30 insertions(+), 6 deletions(-) diff --git a/CHANGES b/CHANGES index 2e8a9743..7834e94a 100644 --- a/CHANGES +++ b/CHANGES @@ -4,6 +4,17 @@ Release 0.6 (in development) New features added ------------------ +* Incompatible changes: + + - The ``autodoc_skip_member`` event now also gets to decide + whether to skip members whose name starts with underscores. + Previously, these members were always automatically skipped. + Therefore, if you handle this event, add something like this + to your event handler to restore the old behavior:: + + if name.startswith('_'): + return True + * Configuration: - The new ``html_add_permalinks`` config value can be used to diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index ddaba04c..6b8da386 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -525,14 +525,15 @@ class RstGenerator(object): all_members = sorted(todoc.__dict__.iteritems()) else: all_members = [(mname, getattr(todoc, mname)) for mname in members] + for (membername, member) in all_members: - # ignore members whose name starts with _ by default if _all and membername.startswith('_'): - continue - - # ignore undocumented members if :undoc-members: is not given - doc = getattr(member, '__doc__', None) - skip = not self.options.undoc_members and not doc + # ignore members whose name starts with _ by default + skip = True + else: + # ignore undocumented members if :undoc-members: is not given + doc = getattr(member, '__doc__', None) + skip = not self.options.undoc_members and not doc # give the user a chance to decide whether this member should be skipped if self.env.app: # let extensions preprocess docstrings diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index ee3fdf1d..746c9b42 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -24,6 +24,7 @@ def setup_module(): app.builder.env.app = app app.connect('autodoc-process-docstring', process_docstring) app.connect('autodoc-process-signature', process_signature) + app.connect('autodoc-skip-member', skip_member) options = Struct( inherited_members = False, @@ -71,6 +72,13 @@ def process_signature(app, what, name, obj, options, args, retann): return '42', None +def skip_member(app, what, name, obj, skip, options): + if name.startswith('_'): + return True + if name == 'skipmeth': + return True + + def test_resolve_name(): # for modules assert gen.resolve_name('module', 'test_autodoc') == \ @@ -380,6 +388,10 @@ class Class(Base): def undocmeth(self): pass + def skipmeth(self): + """Method that should be skipped.""" + pass + @property def prop(self): """Property.""" -- cgit v1.2.1 From ccf4f7068170e90a4f8618c4dcf8cf54b424b1ca Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 15 Dec 2008 13:38:39 +0100 Subject: The new ``html_show_sourcelink`` config value can be used to switch off the links to the reST sources in the sidebar. --- CHANGES | 3 +++ doc/config.rst | 7 +++++++ sphinx/builders/html.py | 1 + sphinx/config.py | 1 + sphinx/quickstart.py | 4 ++-- sphinx/templates/layout.html | 14 +++----------- 6 files changed, 17 insertions(+), 13 deletions(-) diff --git a/CHANGES b/CHANGES index 7834e94a..63fb2db8 100644 --- a/CHANGES +++ b/CHANGES @@ -21,6 +21,9 @@ New features added switch off the generated "paragraph sign" permalinks for each heading and definition environment. + - The new ``html_show_sourcelink`` config value can be used to + switch off the links to the reST sources in the sidebar. + * New translations: - Italian by Sandro Dentella. diff --git a/doc/config.rst b/doc/config.rst index 91cc7c3f..a090da1c 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -409,6 +409,13 @@ that use Sphinx' HTMLWriter class. will only display the titles of matching documents, and no excerpt from the matching contents. +.. confval:: html_show_sourcelink + + If true (and :confval:`html_copy_source` is true as well), links to the + reST sources will be added to the sidebar. The default is ``True``. + + .. versionadded:: 0.6 + .. confval:: html_use_opensearch If nonempty, an `OpenSearch ` description file will be diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 67b3557d..fbe61717 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -142,6 +142,7 @@ class StandaloneHTMLBuilder(Builder): shorttitle = self.config.html_short_title, show_sphinx = self.config.html_show_sphinx, has_source = self.config.html_copy_source, + show_source = self.config.html_show_sourcelink, file_suffix = self.out_suffix, script_files = self.script_files, sphinx_version = __version__, diff --git a/sphinx/config.py b/sphinx/config.py index 1ea5f66f..d12b8e90 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -69,6 +69,7 @@ class Config(object): html_use_index = (True, False), html_split_index = (False, False), html_copy_source = (True, False), + html_show_sourcelink = (True, False), html_use_opensearch = ('', False), html_file_suffix = (None, False), html_show_sphinx = (True, False), diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 1f076575..91213f32 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -165,8 +165,8 @@ html_static_path = ['%(dot)sstatic'] # If true, the index is split into individual pages for each letter. #html_split_index = False -# If true, the reST sources are included in the HTML build as _sources/. -#html_copy_source = True +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True # If true, an OpenSearch description file will be output, and all pages will # contain a tag referring to it. The value of this option must be the diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index d9c9045d..0ef14e45 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -51,16 +51,10 @@

    {{ next.title }}

    {%- endif %} {%- endblock %} - {%- if sourcename %} + {%- if show_source and has_source %}

    {{ _('This Page') }}

    {%- endif %} {%- if customsidebar %} @@ -68,15 +62,13 @@ {%- endif %} {%- block sidebarsearch %} {%- if pagename != "search" %} -

    {% if builder == 'web' %}{{ _('Keyword search')}}{% else %}{{ _('Quick search') }}{% endif %}

    +

    {{ _('Quick search') }}

    - {%- if builder == 'web' %} -

    {{ _('Enter a module, class or function name.') }}

    - {%- endif %} +

    {{ _('Enter search terms or a module, class or function name.') }}

    {%- endif %} {%- endblock %} -- cgit v1.2.1 From be7d070b44f2ceea19d42cda4c021b6dad874914 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 15 Dec 2008 13:50:54 +0100 Subject: Add a DeprecationWarning for sphinx.builder. --- sphinx/builder.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/sphinx/builder.py b/sphinx/builder.py index 2a19b751..a8f8497d 100644 --- a/sphinx/builder.py +++ b/sphinx/builder.py @@ -12,6 +12,8 @@ :license: BSD. """ +import warnings + from sphinx.builders import Builder from sphinx.builders.text import TextBuilder from sphinx.builders.html import StandaloneHTMLBuilder, WebHTMLBuilder, \ @@ -20,3 +22,7 @@ from sphinx.builders.latex import LaTeXBuilder from sphinx.builders.changes import ChangesBuilder from sphinx.builders.htmlhelp import HTMLHelpBuilder from sphinx.builders.linkcheck import CheckExternalLinksBuilder + +warnings.warn('The sphinx.builder module is deprecated; please import ' + 'builders from the respective sphinx.builders submodules.', + DeprecationWarning) -- cgit v1.2.1 From cab6cf69065f313e1748422d1255bb873354cb86 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 15 Dec 2008 14:06:05 +0100 Subject: Remove last web leftovers. --- sphinx/templates/layout.html | 8 -------- sphinx/templates/modindex.html | 20 -------------------- sphinx/templates/page.html | 8 -------- 3 files changed, 36 deletions(-) diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index 0ef14e45..bd1b2853 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -84,16 +84,8 @@ {%- set titlesuffix = " — " + docstitle|e %} {%- endif %} {{ title|striptags }}{{ titlesuffix }} - {%- if builder == 'web' %} - - {%- for link, type, title in page_links %} - - {%- endfor %} - {%- else %} - {%- endif %} {%- if builder != 'htmlhelp' %} -- cgit v1.2.1 From 8b649f402b93faee0e811347eaca237e8b61bd58 Mon Sep 17 00:00:00 2001 From: gbrandl Date: Mon, 29 Dec 2008 20:20:17 +0100 Subject: fix whitespace glitch --- sphinx/templates/layout.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index bf203a60..e011f643 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -76,7 +76,7 @@ {%- endif %} -{%- endmacro -%} +{%- endmacro %} -- cgit v1.2.1 From 22996b2579717271d02302787cd614ce7ee730c7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 29 Dec 2008 20:22:18 +0100 Subject: Add pgen2 and custom utilities. --- sphinx/pycode/Grammar.txt | 155 +++++++++++++++ sphinx/pycode/__init__.py | 142 ++++++++++++++ sphinx/pycode/pgen2/__init__.py | 4 + sphinx/pycode/pgen2/driver.py | 145 ++++++++++++++ sphinx/pycode/pgen2/grammar.py | 171 +++++++++++++++++ sphinx/pycode/pgen2/literals.py | 60 ++++++ sphinx/pycode/pgen2/parse.py | 201 ++++++++++++++++++++ sphinx/pycode/pgen2/pgen.py | 384 +++++++++++++++++++++++++++++++++++++ sphinx/pycode/pgen2/token.py | 82 ++++++++ sphinx/pycode/pgen2/tokenize.py | 405 ++++++++++++++++++++++++++++++++++++++++ sphinx/pycode/pytree.py | 295 +++++++++++++++++++++++++++++ 11 files changed, 2044 insertions(+) create mode 100644 sphinx/pycode/Grammar.txt create mode 100644 sphinx/pycode/__init__.py create mode 100644 sphinx/pycode/pgen2/__init__.py create mode 100644 sphinx/pycode/pgen2/driver.py create mode 100644 sphinx/pycode/pgen2/grammar.py create mode 100644 sphinx/pycode/pgen2/literals.py create mode 100644 sphinx/pycode/pgen2/parse.py create mode 100644 sphinx/pycode/pgen2/pgen.py create mode 100755 sphinx/pycode/pgen2/token.py create mode 100644 sphinx/pycode/pgen2/tokenize.py create mode 100644 sphinx/pycode/pytree.py diff --git a/sphinx/pycode/Grammar.txt b/sphinx/pycode/Grammar.txt new file mode 100644 index 00000000..1f4a50ff --- /dev/null +++ b/sphinx/pycode/Grammar.txt @@ -0,0 +1,155 @@ +# Grammar for Python + +# Note: Changing the grammar specified in this file will most likely +# require corresponding changes in the parser module +# (../Modules/parsermodule.c). If you can't make the changes to +# that module yourself, please co-ordinate the required changes +# with someone who can; ask around on python-dev for help. Fred +# Drake will probably be listening there. + +# NOTE WELL: You should also follow all the steps listed in PEP 306, +# "How to Change Python's Grammar" + +# Commands for Kees Blom's railroad program +#diagram:token NAME +#diagram:token NUMBER +#diagram:token STRING +#diagram:token NEWLINE +#diagram:token ENDMARKER +#diagram:token INDENT +#diagram:output\input python.bla +#diagram:token DEDENT +#diagram:output\textwidth 20.04cm\oddsidemargin 0.0cm\evensidemargin 0.0cm +#diagram:rules + +# Start symbols for the grammar: +# file_input is a module or sequence of commands read from an input file; +# single_input is a single interactive statement; +# eval_input is the input for the eval() and input() functions. +# NB: compound_stmt in single_input is followed by extra NEWLINE! +file_input: (NEWLINE | stmt)* ENDMARKER +single_input: NEWLINE | simple_stmt | compound_stmt NEWLINE +eval_input: testlist NEWLINE* ENDMARKER + +decorator: '@' dotted_name [ '(' [arglist] ')' ] NEWLINE +decorators: decorator+ +decorated: decorators (classdef | funcdef) +funcdef: 'def' NAME parameters ['->' test] ':' suite +parameters: '(' [typedargslist] ')' +typedargslist: ((tfpdef ['=' test] ',')* + ('*' [tname] (',' tname ['=' test])* [',' '**' tname] | '**' tname) + | tfpdef ['=' test] (',' tfpdef ['=' test])* [',']) +tname: NAME [':' test] +tfpdef: tname | '(' tfplist ')' +tfplist: tfpdef (',' tfpdef)* [','] +varargslist: ((vfpdef ['=' test] ',')* + ('*' [vname] (',' vname ['=' test])* [',' '**' vname] | '**' vname) + | vfpdef ['=' test] (',' vfpdef ['=' test])* [',']) +vname: NAME +vfpdef: vname | '(' vfplist ')' +vfplist: vfpdef (',' vfpdef)* [','] + +stmt: simple_stmt | compound_stmt +simple_stmt: small_stmt (';' small_stmt)* [';'] NEWLINE +small_stmt: (expr_stmt | print_stmt | del_stmt | pass_stmt | flow_stmt | + import_stmt | global_stmt | exec_stmt | assert_stmt) +expr_stmt: testlist (augassign (yield_expr|testlist) | + ('=' (yield_expr|testlist))*) +augassign: ('+=' | '-=' | '*=' | '/=' | '%=' | '&=' | '|=' | '^=' | + '<<=' | '>>=' | '**=' | '//=') +# For normal assignments, additional restrictions enforced by the interpreter +print_stmt: 'print' ( [ test (',' test)* [','] ] | + '>>' test [ (',' test)+ [','] ] ) +del_stmt: 'del' exprlist +pass_stmt: 'pass' +flow_stmt: break_stmt | continue_stmt | return_stmt | raise_stmt | yield_stmt +break_stmt: 'break' +continue_stmt: 'continue' +return_stmt: 'return' [testlist] +yield_stmt: yield_expr +raise_stmt: 'raise' [test ['from' test | ',' test [',' test]]] +import_stmt: import_name | import_from +import_name: 'import' dotted_as_names +import_from: ('from' ('.'* dotted_name | '.'+) + 'import' ('*' | '(' import_as_names ')' | import_as_names)) +import_as_name: NAME ['as' NAME] +dotted_as_name: dotted_name ['as' NAME] +import_as_names: import_as_name (',' import_as_name)* [','] +dotted_as_names: dotted_as_name (',' dotted_as_name)* +dotted_name: NAME ('.' NAME)* +global_stmt: ('global' | 'nonlocal') NAME (',' NAME)* +exec_stmt: 'exec' expr ['in' test [',' test]] +assert_stmt: 'assert' test [',' test] + +compound_stmt: if_stmt | while_stmt | for_stmt | try_stmt | with_stmt | funcdef | classdef | decorated +if_stmt: 'if' test ':' suite ('elif' test ':' suite)* ['else' ':' suite] +while_stmt: 'while' test ':' suite ['else' ':' suite] +for_stmt: 'for' exprlist 'in' testlist ':' suite ['else' ':' suite] +try_stmt: ('try' ':' suite + ((except_clause ':' suite)+ + ['else' ':' suite] + ['finally' ':' suite] | + 'finally' ':' suite)) +with_stmt: 'with' test [ with_var ] ':' suite +with_var: 'as' expr +# NB compile.c makes sure that the default except clause is last +except_clause: 'except' [test [(',' | 'as') test]] +suite: simple_stmt | NEWLINE INDENT stmt+ DEDENT + +# Backward compatibility cruft to support: +# [ x for x in lambda: True, lambda: False if x() ] +# even while also allowing: +# lambda x: 5 if x else 2 +# (But not a mix of the two) +testlist_safe: old_test [(',' old_test)+ [',']] +old_test: or_test | old_lambdef +old_lambdef: 'lambda' [varargslist] ':' old_test + +test: or_test ['if' or_test 'else' test] | lambdef +or_test: and_test ('or' and_test)* +and_test: not_test ('and' not_test)* +not_test: 'not' not_test | comparison +comparison: expr (comp_op expr)* +comp_op: '<'|'>'|'=='|'>='|'<='|'<>'|'!='|'in'|'not' 'in'|'is'|'is' 'not' +expr: xor_expr ('|' xor_expr)* +xor_expr: and_expr ('^' and_expr)* +and_expr: shift_expr ('&' shift_expr)* +shift_expr: arith_expr (('<<'|'>>') arith_expr)* +arith_expr: term (('+'|'-') term)* +term: factor (('*'|'/'|'%'|'//') factor)* +factor: ('+'|'-'|'~') factor | power +power: atom trailer* ['**' factor] +atom: ('(' [yield_expr|testlist_gexp] ')' | + '[' [listmaker] ']' | + '{' [dictsetmaker] '}' | + '`' testlist1 '`' | + NAME | NUMBER | STRING+ | '.' '.' '.') +listmaker: test ( comp_for | (',' test)* [','] ) +testlist_gexp: test ( comp_for | (',' test)* [','] ) +lambdef: 'lambda' [varargslist] ':' test +trailer: '(' [arglist] ')' | '[' subscriptlist ']' | '.' NAME +subscriptlist: subscript (',' subscript)* [','] +subscript: test | [test] ':' [test] [sliceop] +sliceop: ':' [test] +exprlist: expr (',' expr)* [','] +testlist: test (',' test)* [','] +dictsetmaker: ( (test ':' test (comp_for | (',' test ':' test)* [','])) | + (test (comp_for | (',' test)* [','])) ) + +classdef: 'class' NAME ['(' [arglist] ')'] ':' suite + +arglist: (argument ',')* (argument [','] + |'*' test (',' argument)* [',' '**' test] + |'**' test) +argument: test [comp_for] | test '=' test # Really [keyword '='] test + +comp_iter: comp_for | comp_if +comp_for: 'for' exprlist 'in' testlist_safe [comp_iter] +comp_if: 'if' old_test [comp_iter] + +testlist1: test (',' test)* + +# not used in grammar, but may appear in "node" passed from Parser to Compiler +encoding_decl: NAME + +yield_expr: 'yield' [testlist] diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py new file mode 100644 index 00000000..b5d83e67 --- /dev/null +++ b/sphinx/pycode/__init__.py @@ -0,0 +1,142 @@ +# -*- coding: utf-8 -*- +""" + sphinx.pycode + ~~~~~~~~~~~~~ + + Utilities parsing and analyzing Python code. + + :copyright: 2008 by Georg Brandl. + :license: BSD, see LICENSE for details. +""" + +import sys +from os import path + +from sphinx.pycode import pytree +from sphinx.pycode.pgen2 import driver, token + + +# load the Python grammar +_grammarfile = path.join(path.dirname(__file__), 'Grammar.txt') +pygrammar = driver.load_grammar(_grammarfile) +pydriver = driver.Driver(pygrammar, convert=pytree.convert) + +class sym: pass +for k, v in pygrammar.symbol2number.iteritems(): + setattr(sym, k, v) + +# a dict mapping terminal and nonterminal numbers to their names +number2name = pygrammar.number2symbol.copy() +number2name.update(token.tok_name) + + +def prepare_commentdoc(s): + result = [] + lines = [line.strip() for line in s.expandtabs().splitlines()] + for line in lines: + if line.startswith('#: '): + result.append(line[3:]) + if result and result[-1]: + result.append('') + return '\n'.join(result) + + +_eq = pytree.Leaf(token.EQUAL, '=') + + +class ClassAttrVisitor(pytree.NodeVisitor): + def init(self): + self.namespace = [] + + def visit_classdef(self, node): + self.namespace.append(node[1].value) + self.generic_visit(node) + self.namespace.pop() + + def visit_expr_stmt(self, node): + if _eq in node.children: + prefix = node[0].get_prefix() + if not prefix: + prev = node[0].get_prev_leaf() + if prev and prev.type == token.INDENT: + prefix = prev.prefix + doc = prepare_commentdoc(prefix) + if doc: + targ = '.'.join(self.namespace + [node[0].compact()]) + print targ + print doc + + def visit_funcdef(self, node): + return + + +class ModuleAnalyzer(object): + + def __init__(self, tree, modname, srcname): + self.tree = tree + self.modname = modname + self.srcname = srcname + + @classmethod + def for_string(cls, string, modname, srcname=''): + return cls(pydriver.parse_string(string), modname, srcname) + + @classmethod + def for_file(cls, filename, modname): + # XXX if raises + fileobj = open(filename, 'r') + try: + return cls(pydriver.parse_stream(fileobj), modname, filename) + finally: + fileobj.close() + + @classmethod + def for_module(cls, modname): + if modname not in sys.modules: + # XXX + __import__(modname) + mod = sys.modules[modname] + if hasattr(mod, '__loader__'): + # XXX raises + source = mod.__loader__.get_source(modname) + return cls.for_string(source, modname) + filename = getattr(mod, '__file__', None) + if filename is None: + # XXX + raise RuntimeError('no source found') + if filename.lower().endswith('.pyo') or \ + filename.lower().endswith('.pyc'): + filename = filename[:-1] + elif not filename.lower().endswith('.py'): + raise RuntimeError('not a .py file') + if not path.isfile(filename): + # XXX + raise RuntimeError('source not present') + return cls.for_file(filename, modname) + + def find_defs(self): + attr_visitor = ClassAttrVisitor(number2name) + attr_visitor.namespace = [self.modname] + attr_visitor.visit(self.tree) + +class Test: + """doc""" + + #: testing... + x = 1 + """doc""" + + #: testing more... + x = 2 + + +#ma = ModuleAnalyzer.for_file(__file__.rstrip('c')) +import time +x0=time.time() +ma = ModuleAnalyzer.for_module('sphinx.builders.latex') +x1=time.time() +ma.find_defs() +x2=time.time() +print "%.4f %.4f" % (x1-x0, x2-x1) + +#print pytree.nice_repr(ma.tree, number2name, True) diff --git a/sphinx/pycode/pgen2/__init__.py b/sphinx/pycode/pgen2/__init__.py new file mode 100644 index 00000000..af390484 --- /dev/null +++ b/sphinx/pycode/pgen2/__init__.py @@ -0,0 +1,4 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""The pgen2 package.""" diff --git a/sphinx/pycode/pgen2/driver.py b/sphinx/pycode/pgen2/driver.py new file mode 100644 index 00000000..3e9e1043 --- /dev/null +++ b/sphinx/pycode/pgen2/driver.py @@ -0,0 +1,145 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +# Modifications: +# Copyright 2006 Google, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""Parser driver. + +This provides a high-level interface to parse a file into a syntax tree. + +""" + +__author__ = "Guido van Rossum " + +__all__ = ["Driver", "load_grammar"] + +# Python imports +import os +import logging +import sys + +# Pgen imports +from sphinx.pycode.pgen2 import grammar, parse, token, tokenize, pgen + + +class Driver(object): + + def __init__(self, grammar, convert=None, logger=None): + self.grammar = grammar + if logger is None: + logger = logging.getLogger() + self.logger = logger + self.convert = convert + + def parse_tokens(self, tokens, debug=False): + """Parse a series of tokens and return the syntax tree.""" + # XXX Move the prefix computation into a wrapper around tokenize. + p = parse.Parser(self.grammar, self.convert) + p.setup() + lineno = 1 + column = 0 + type = value = start = end = line_text = None + prefix = "" + for quintuple in tokens: + type, value, start, end, line_text = quintuple + if start != (lineno, column): + assert (lineno, column) <= start, ((lineno, column), start) + s_lineno, s_column = start + if lineno < s_lineno: + prefix += "\n" * (s_lineno - lineno) + lineno = s_lineno + column = 0 + if column < s_column: + prefix += line_text[column:s_column] + column = s_column + if type in (tokenize.COMMENT, tokenize.NL): + prefix += value + lineno, column = end + if value.endswith("\n"): + lineno += 1 + column = 0 + continue + if type == token.OP: + type = grammar.opmap[value] + if debug: + self.logger.debug("%s %r (prefix=%r)", + token.tok_name[type], value, prefix) + if p.addtoken(type, value, (prefix, start)): + if debug: + self.logger.debug("Stop.") + break + prefix = "" + lineno, column = end + if value.endswith("\n"): + lineno += 1 + column = 0 + else: + # We never broke out -- EOF is too soon (how can this happen???) + raise parse.ParseError("incomplete input", t, v, x) + return p.rootnode + + def parse_stream_raw(self, stream, debug=False): + """Parse a stream and return the syntax tree.""" + tokens = tokenize.generate_tokens(stream.readline) + return self.parse_tokens(tokens, debug) + + def parse_stream(self, stream, debug=False): + """Parse a stream and return the syntax tree.""" + return self.parse_stream_raw(stream, debug) + + def parse_file(self, filename, debug=False): + """Parse a file and return the syntax tree.""" + stream = open(filename) + try: + return self.parse_stream(stream, debug) + finally: + stream.close() + + def parse_string(self, text, debug=False): + """Parse a string and return the syntax tree.""" + tokens = tokenize.generate_tokens(generate_lines(text).next) + return self.parse_tokens(tokens, debug) + + +def generate_lines(text): + """Generator that behaves like readline without using StringIO.""" + for line in text.splitlines(True): + yield line + while True: + yield "" + + +def load_grammar(gt="Grammar.txt", gp=None, + save=True, force=False, logger=None): + """Load the grammar (maybe from a pickle).""" + if logger is None: + logger = logging.getLogger() + if gp is None: + head, tail = os.path.splitext(gt) + if tail == ".txt": + tail = "" + gp = head + tail + ".".join(map(str, sys.version_info)) + ".pickle" + if force or not _newer(gp, gt): + logger.info("Generating grammar tables from %s", gt) + g = pgen.generate_grammar(gt) + if save: + logger.info("Writing grammar tables to %s", gp) + try: + g.dump(gp) + except IOError, e: + logger.info("Writing failed:"+str(e)) + else: + g = grammar.Grammar() + g.load(gp) + return g + + +def _newer(a, b): + """Inquire whether file a was written since file b.""" + if not os.path.exists(a): + return False + if not os.path.exists(b): + return True + return os.path.getmtime(a) >= os.path.getmtime(b) diff --git a/sphinx/pycode/pgen2/grammar.py b/sphinx/pycode/pgen2/grammar.py new file mode 100644 index 00000000..381d80e8 --- /dev/null +++ b/sphinx/pycode/pgen2/grammar.py @@ -0,0 +1,171 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""This module defines the data structures used to represent a grammar. + +These are a bit arcane because they are derived from the data +structures used by Python's 'pgen' parser generator. + +There's also a table here mapping operators to their names in the +token module; the Python tokenize module reports all operators as the +fallback token code OP, but the parser needs the actual token code. + +""" + +# Python imports +import pickle + +# Local imports +from sphinx.pycode.pgen2 import token, tokenize + + +class Grammar(object): + """Pgen parsing tables tables conversion class. + + Once initialized, this class supplies the grammar tables for the + parsing engine implemented by parse.py. The parsing engine + accesses the instance variables directly. The class here does not + provide initialization of the tables; several subclasses exist to + do this (see the conv and pgen modules). + + The load() method reads the tables from a pickle file, which is + much faster than the other ways offered by subclasses. The pickle + file is written by calling dump() (after loading the grammar + tables using a subclass). The report() method prints a readable + representation of the tables to stdout, for debugging. + + The instance variables are as follows: + + symbol2number -- a dict mapping symbol names to numbers. Symbol + numbers are always 256 or higher, to distinguish + them from token numbers, which are between 0 and + 255 (inclusive). + + number2symbol -- a dict mapping numbers to symbol names; + these two are each other's inverse. + + states -- a list of DFAs, where each DFA is a list of + states, each state is is a list of arcs, and each + arc is a (i, j) pair where i is a label and j is + a state number. The DFA number is the index into + this list. (This name is slightly confusing.) + Final states are represented by a special arc of + the form (0, j) where j is its own state number. + + dfas -- a dict mapping symbol numbers to (DFA, first) + pairs, where DFA is an item from the states list + above, and first is a set of tokens that can + begin this grammar rule (represented by a dict + whose values are always 1). + + labels -- a list of (x, y) pairs where x is either a token + number or a symbol number, and y is either None + or a string; the strings are keywords. The label + number is the index in this list; label numbers + are used to mark state transitions (arcs) in the + DFAs. + + start -- the number of the grammar's start symbol. + + keywords -- a dict mapping keyword strings to arc labels. + + tokens -- a dict mapping token numbers to arc labels. + + """ + + def __init__(self): + self.symbol2number = {} + self.number2symbol = {} + self.states = [] + self.dfas = {} + self.labels = [(0, "EMPTY")] + self.keywords = {} + self.tokens = {} + self.symbol2label = {} + self.start = 256 + + def dump(self, filename): + """Dump the grammar tables to a pickle file.""" + f = open(filename, "wb") + pickle.dump(self.__dict__, f, 2) + f.close() + + def load(self, filename): + """Load the grammar tables from a pickle file.""" + f = open(filename, "rb") + d = pickle.load(f) + f.close() + self.__dict__.update(d) + + def report(self): + """Dump the grammar tables to standard output, for debugging.""" + from pprint import pprint + print "s2n" + pprint(self.symbol2number) + print "n2s" + pprint(self.number2symbol) + print "states" + pprint(self.states) + print "dfas" + pprint(self.dfas) + print "labels" + pprint(self.labels) + print "start", self.start + + +# Map from operator to number (since tokenize doesn't do this) + +opmap_raw = """ +( LPAR +) RPAR +[ LSQB +] RSQB +: COLON +, COMMA +; SEMI ++ PLUS +- MINUS +* STAR +/ SLASH +| VBAR +& AMPER +< LESS +> GREATER += EQUAL +. DOT +% PERCENT +` BACKQUOTE +{ LBRACE +} RBRACE +@ AT +== EQEQUAL +!= NOTEQUAL +<> NOTEQUAL +<= LESSEQUAL +>= GREATEREQUAL +~ TILDE +^ CIRCUMFLEX +<< LEFTSHIFT +>> RIGHTSHIFT +** DOUBLESTAR ++= PLUSEQUAL +-= MINEQUAL +*= STAREQUAL +/= SLASHEQUAL +%= PERCENTEQUAL +&= AMPEREQUAL +|= VBAREQUAL +^= CIRCUMFLEXEQUAL +<<= LEFTSHIFTEQUAL +>>= RIGHTSHIFTEQUAL +**= DOUBLESTAREQUAL +// DOUBLESLASH +//= DOUBLESLASHEQUAL +-> RARROW +""" + +opmap = {} +for line in opmap_raw.splitlines(): + if line: + op, name = line.split() + opmap[op] = getattr(token, name) diff --git a/sphinx/pycode/pgen2/literals.py b/sphinx/pycode/pgen2/literals.py new file mode 100644 index 00000000..0b3948a5 --- /dev/null +++ b/sphinx/pycode/pgen2/literals.py @@ -0,0 +1,60 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""Safely evaluate Python string literals without using eval().""" + +import re + +simple_escapes = {"a": "\a", + "b": "\b", + "f": "\f", + "n": "\n", + "r": "\r", + "t": "\t", + "v": "\v", + "'": "'", + '"': '"', + "\\": "\\"} + +def escape(m): + all, tail = m.group(0, 1) + assert all.startswith("\\") + esc = simple_escapes.get(tail) + if esc is not None: + return esc + if tail.startswith("x"): + hexes = tail[1:] + if len(hexes) < 2: + raise ValueError("invalid hex string escape ('\\%s')" % tail) + try: + i = int(hexes, 16) + except ValueError: + raise ValueError("invalid hex string escape ('\\%s')" % tail) + else: + try: + i = int(tail, 8) + except ValueError: + raise ValueError("invalid octal string escape ('\\%s')" % tail) + return chr(i) + +def evalString(s): + assert s.startswith("'") or s.startswith('"'), repr(s[:1]) + q = s[0] + if s[:3] == q*3: + q = q*3 + assert s.endswith(q), repr(s[-len(q):]) + assert len(s) >= 2*len(q) + s = s[len(q):-len(q)] + return re.sub(r"\\(\'|\"|\\|[abfnrtv]|x.{0,2}|[0-7]{1,3})", escape, s) + +def test(): + for i in range(256): + c = chr(i) + s = repr(c) + e = evalString(s) + if e != c: + print i, c, s, e + + +if __name__ == "__main__": + test() diff --git a/sphinx/pycode/pgen2/parse.py b/sphinx/pycode/pgen2/parse.py new file mode 100644 index 00000000..60eec05e --- /dev/null +++ b/sphinx/pycode/pgen2/parse.py @@ -0,0 +1,201 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""Parser engine for the grammar tables generated by pgen. + +The grammar table must be loaded first. + +See Parser/parser.c in the Python distribution for additional info on +how this parsing engine works. + +""" + +# Local imports +from sphinx.pycode.pgen2 import token + +class ParseError(Exception): + """Exception to signal the parser is stuck.""" + + def __init__(self, msg, type, value, context): + Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + (msg, type, value, context)) + self.msg = msg + self.type = type + self.value = value + self.context = context + +class Parser(object): + """Parser engine. + + The proper usage sequence is: + + p = Parser(grammar, [converter]) # create instance + p.setup([start]) # prepare for parsing + : + if p.addtoken(...): # parse a token; may raise ParseError + break + root = p.rootnode # root of abstract syntax tree + + A Parser instance may be reused by calling setup() repeatedly. + + A Parser instance contains state pertaining to the current token + sequence, and should not be used concurrently by different threads + to parse separate token sequences. + + See driver.py for how to get input tokens by tokenizing a file or + string. + + Parsing is complete when addtoken() returns True; the root of the + abstract syntax tree can then be retrieved from the rootnode + instance variable. When a syntax error occurs, addtoken() raises + the ParseError exception. There is no error recovery; the parser + cannot be used after a syntax error was reported (but it can be + reinitialized by calling setup()). + + """ + + def __init__(self, grammar, convert=None): + """Constructor. + + The grammar argument is a grammar.Grammar instance; see the + grammar module for more information. + + The parser is not ready yet for parsing; you must call the + setup() method to get it started. + + The optional convert argument is a function mapping concrete + syntax tree nodes to abstract syntax tree nodes. If not + given, no conversion is done and the syntax tree produced is + the concrete syntax tree. If given, it must be a function of + two arguments, the first being the grammar (a grammar.Grammar + instance), and the second being the concrete syntax tree node + to be converted. The syntax tree is converted from the bottom + up. + + A concrete syntax tree node is a (type, value, context, nodes) + tuple, where type is the node type (a token or symbol number), + value is None for symbols and a string for tokens, context is + None or an opaque value used for error reporting (typically a + (lineno, offset) pair), and nodes is a list of children for + symbols, and None for tokens. + + An abstract syntax tree node may be anything; this is entirely + up to the converter function. + + """ + self.grammar = grammar + self.convert = convert or (lambda grammar, node: node) + + def setup(self, start=None): + """Prepare for parsing. + + This *must* be called before starting to parse. + + The optional argument is an alternative start symbol; it + defaults to the grammar's start symbol. + + You can use a Parser instance to parse any number of programs; + each time you call setup() the parser is reset to an initial + state determined by the (implicit or explicit) start symbol. + + """ + if start is None: + start = self.grammar.start + # Each stack entry is a tuple: (dfa, state, node). + # A node is a tuple: (type, value, context, children), + # where children is a list of nodes or None, and context may be None. + newnode = (start, None, None, []) + stackentry = (self.grammar.dfas[start], 0, newnode) + self.stack = [stackentry] + self.rootnode = None + self.used_names = set() # Aliased to self.rootnode.used_names in pop() + + def addtoken(self, type, value, context): + """Add a token; return True iff this is the end of the program.""" + # Map from token to label + ilabel = self.classify(type, value, context) + # Loop until the token is shifted; may raise exceptions + while True: + dfa, state, node = self.stack[-1] + states, first = dfa + arcs = states[state] + # Look for a state with this label + for i, newstate in arcs: + t, v = self.grammar.labels[i] + if ilabel == i: + # Look it up in the list of labels + assert t < 256 + # Shift a token; we're done with it + self.shift(type, value, newstate, context) + # Pop while we are in an accept-only state + state = newstate + while states[state] == [(0, state)]: + self.pop() + if not self.stack: + # Done parsing! + return True + dfa, state, node = self.stack[-1] + states, first = dfa + # Done with this token + return False + elif t >= 256: + # See if it's a symbol and if we're in its first set + itsdfa = self.grammar.dfas[t] + itsstates, itsfirst = itsdfa + if ilabel in itsfirst: + # Push a symbol + self.push(t, self.grammar.dfas[t], newstate, context) + break # To continue the outer while loop + else: + if (0, state) in arcs: + # An accepting state, pop it and try something else + self.pop() + if not self.stack: + # Done parsing, but another token is input + raise ParseError("too much input", + type, value, context) + else: + # No success finding a transition + raise ParseError("bad input", type, value, context) + + def classify(self, type, value, context): + """Turn a token into a label. (Internal)""" + if type == token.NAME: + # Keep a listing of all used names + self.used_names.add(value) + # Check for reserved words + ilabel = self.grammar.keywords.get(value) + if ilabel is not None: + return ilabel + ilabel = self.grammar.tokens.get(type) + if ilabel is None: + raise ParseError("bad token", type, value, context) + return ilabel + + def shift(self, type, value, newstate, context): + """Shift a token. (Internal)""" + dfa, state, node = self.stack[-1] + newnode = (type, value, context, None) + newnode = self.convert(self.grammar, newnode) + if newnode is not None: + node[-1].append(newnode) + self.stack[-1] = (dfa, newstate, node) + + def push(self, type, newdfa, newstate, context): + """Push a nonterminal. (Internal)""" + dfa, state, node = self.stack[-1] + newnode = (type, None, context, []) + self.stack[-1] = (dfa, newstate, node) + self.stack.append((newdfa, 0, newnode)) + + def pop(self): + """Pop a nonterminal. (Internal)""" + popdfa, popstate, popnode = self.stack.pop() + newnode = self.convert(self.grammar, popnode) + if newnode is not None: + if self.stack: + dfa, state, node = self.stack[-1] + node[-1].append(newnode) + else: + self.rootnode = newnode + self.rootnode.used_names = self.used_names diff --git a/sphinx/pycode/pgen2/pgen.py b/sphinx/pycode/pgen2/pgen.py new file mode 100644 index 00000000..d6895eae --- /dev/null +++ b/sphinx/pycode/pgen2/pgen.py @@ -0,0 +1,384 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +# Pgen imports +from sphinx.pycode.pgen2 import grammar, token, tokenize + +class PgenGrammar(grammar.Grammar): + pass + +class ParserGenerator(object): + + def __init__(self, filename, stream=None): + close_stream = None + if stream is None: + stream = open(filename) + close_stream = stream.close + self.filename = filename + self.stream = stream + self.generator = tokenize.generate_tokens(stream.readline) + self.gettoken() # Initialize lookahead + self.dfas, self.startsymbol = self.parse() + if close_stream is not None: + close_stream() + self.first = {} # map from symbol name to set of tokens + self.addfirstsets() + + def make_grammar(self): + c = PgenGrammar() + names = self.dfas.keys() + names.sort() + names.remove(self.startsymbol) + names.insert(0, self.startsymbol) + for name in names: + i = 256 + len(c.symbol2number) + c.symbol2number[name] = i + c.number2symbol[i] = name + for name in names: + dfa = self.dfas[name] + states = [] + for state in dfa: + arcs = [] + for label, next in state.arcs.iteritems(): + arcs.append((self.make_label(c, label), dfa.index(next))) + if state.isfinal: + arcs.append((0, dfa.index(state))) + states.append(arcs) + c.states.append(states) + c.dfas[c.symbol2number[name]] = (states, self.make_first(c, name)) + c.start = c.symbol2number[self.startsymbol] + return c + + def make_first(self, c, name): + rawfirst = self.first[name] + first = {} + for label in rawfirst: + ilabel = self.make_label(c, label) + ##assert ilabel not in first # XXX failed on <> ... != + first[ilabel] = 1 + return first + + def make_label(self, c, label): + # XXX Maybe this should be a method on a subclass of converter? + ilabel = len(c.labels) + if label[0].isalpha(): + # Either a symbol name or a named token + if label in c.symbol2number: + # A symbol name (a non-terminal) + if label in c.symbol2label: + return c.symbol2label[label] + else: + c.labels.append((c.symbol2number[label], None)) + c.symbol2label[label] = ilabel + return ilabel + else: + # A named token (NAME, NUMBER, STRING) + itoken = getattr(token, label, None) + assert isinstance(itoken, int), label + assert itoken in token.tok_name, label + if itoken in c.tokens: + return c.tokens[itoken] + else: + c.labels.append((itoken, None)) + c.tokens[itoken] = ilabel + return ilabel + else: + # Either a keyword or an operator + assert label[0] in ('"', "'"), label + value = eval(label) + if value[0].isalpha(): + # A keyword + if value in c.keywords: + return c.keywords[value] + else: + c.labels.append((token.NAME, value)) + c.keywords[value] = ilabel + return ilabel + else: + # An operator (any non-numeric token) + itoken = grammar.opmap[value] # Fails if unknown token + if itoken in c.tokens: + return c.tokens[itoken] + else: + c.labels.append((itoken, None)) + c.tokens[itoken] = ilabel + return ilabel + + def addfirstsets(self): + names = self.dfas.keys() + names.sort() + for name in names: + if name not in self.first: + self.calcfirst(name) + #print name, self.first[name].keys() + + def calcfirst(self, name): + dfa = self.dfas[name] + self.first[name] = None # dummy to detect left recursion + state = dfa[0] + totalset = {} + overlapcheck = {} + for label, next in state.arcs.iteritems(): + if label in self.dfas: + if label in self.first: + fset = self.first[label] + if fset is None: + raise ValueError("recursion for rule %r" % name) + else: + self.calcfirst(label) + fset = self.first[label] + totalset.update(fset) + overlapcheck[label] = fset + else: + totalset[label] = 1 + overlapcheck[label] = {label: 1} + inverse = {} + for label, itsfirst in overlapcheck.iteritems(): + for symbol in itsfirst: + if symbol in inverse: + raise ValueError("rule %s is ambiguous; %s is in the" + " first sets of %s as well as %s" % + (name, symbol, label, inverse[symbol])) + inverse[symbol] = label + self.first[name] = totalset + + def parse(self): + dfas = {} + startsymbol = None + # MSTART: (NEWLINE | RULE)* ENDMARKER + while self.type != token.ENDMARKER: + while self.type == token.NEWLINE: + self.gettoken() + # RULE: NAME ':' RHS NEWLINE + name = self.expect(token.NAME) + self.expect(token.OP, ":") + a, z = self.parse_rhs() + self.expect(token.NEWLINE) + #self.dump_nfa(name, a, z) + dfa = self.make_dfa(a, z) + #self.dump_dfa(name, dfa) + oldlen = len(dfa) + self.simplify_dfa(dfa) + newlen = len(dfa) + dfas[name] = dfa + #print name, oldlen, newlen + if startsymbol is None: + startsymbol = name + return dfas, startsymbol + + def make_dfa(self, start, finish): + # To turn an NFA into a DFA, we define the states of the DFA + # to correspond to *sets* of states of the NFA. Then do some + # state reduction. Let's represent sets as dicts with 1 for + # values. + assert isinstance(start, NFAState) + assert isinstance(finish, NFAState) + def closure(state): + base = {} + addclosure(state, base) + return base + def addclosure(state, base): + assert isinstance(state, NFAState) + if state in base: + return + base[state] = 1 + for label, next in state.arcs: + if label is None: + addclosure(next, base) + states = [DFAState(closure(start), finish)] + for state in states: # NB states grows while we're iterating + arcs = {} + for nfastate in state.nfaset: + for label, next in nfastate.arcs: + if label is not None: + addclosure(next, arcs.setdefault(label, {})) + for label, nfaset in arcs.iteritems(): + for st in states: + if st.nfaset == nfaset: + break + else: + st = DFAState(nfaset, finish) + states.append(st) + state.addarc(st, label) + return states # List of DFAState instances; first one is start + + def dump_nfa(self, name, start, finish): + print "Dump of NFA for", name + todo = [start] + for i, state in enumerate(todo): + print " State", i, state is finish and "(final)" or "" + for label, next in state.arcs: + if next in todo: + j = todo.index(next) + else: + j = len(todo) + todo.append(next) + if label is None: + print " -> %d" % j + else: + print " %s -> %d" % (label, j) + + def dump_dfa(self, name, dfa): + print "Dump of DFA for", name + for i, state in enumerate(dfa): + print " State", i, state.isfinal and "(final)" or "" + for label, next in state.arcs.iteritems(): + print " %s -> %d" % (label, dfa.index(next)) + + def simplify_dfa(self, dfa): + # This is not theoretically optimal, but works well enough. + # Algorithm: repeatedly look for two states that have the same + # set of arcs (same labels pointing to the same nodes) and + # unify them, until things stop changing. + + # dfa is a list of DFAState instances + changes = True + while changes: + changes = False + for i, state_i in enumerate(dfa): + for j in range(i+1, len(dfa)): + state_j = dfa[j] + if state_i == state_j: + #print " unify", i, j + del dfa[j] + for state in dfa: + state.unifystate(state_j, state_i) + changes = True + break + + def parse_rhs(self): + # RHS: ALT ('|' ALT)* + a, z = self.parse_alt() + if self.value != "|": + return a, z + else: + aa = NFAState() + zz = NFAState() + aa.addarc(a) + z.addarc(zz) + while self.value == "|": + self.gettoken() + a, z = self.parse_alt() + aa.addarc(a) + z.addarc(zz) + return aa, zz + + def parse_alt(self): + # ALT: ITEM+ + a, b = self.parse_item() + while (self.value in ("(", "[") or + self.type in (token.NAME, token.STRING)): + c, d = self.parse_item() + b.addarc(c) + b = d + return a, b + + def parse_item(self): + # ITEM: '[' RHS ']' | ATOM ['+' | '*'] + if self.value == "[": + self.gettoken() + a, z = self.parse_rhs() + self.expect(token.OP, "]") + a.addarc(z) + return a, z + else: + a, z = self.parse_atom() + value = self.value + if value not in ("+", "*"): + return a, z + self.gettoken() + z.addarc(a) + if value == "+": + return a, z + else: + return a, a + + def parse_atom(self): + # ATOM: '(' RHS ')' | NAME | STRING + if self.value == "(": + self.gettoken() + a, z = self.parse_rhs() + self.expect(token.OP, ")") + return a, z + elif self.type in (token.NAME, token.STRING): + a = NFAState() + z = NFAState() + a.addarc(z, self.value) + self.gettoken() + return a, z + else: + self.raise_error("expected (...) or NAME or STRING, got %s/%s", + self.type, self.value) + + def expect(self, type, value=None): + if self.type != type or (value is not None and self.value != value): + self.raise_error("expected %s/%s, got %s/%s", + type, value, self.type, self.value) + value = self.value + self.gettoken() + return value + + def gettoken(self): + tup = self.generator.next() + while tup[0] in (tokenize.COMMENT, tokenize.NL): + tup = self.generator.next() + self.type, self.value, self.begin, self.end, self.line = tup + #print token.tok_name[self.type], repr(self.value) + + def raise_error(self, msg, *args): + if args: + try: + msg = msg % args + except: + msg = " ".join([msg] + map(str, args)) + raise SyntaxError(msg, (self.filename, self.end[0], + self.end[1], self.line)) + +class NFAState(object): + + def __init__(self): + self.arcs = [] # list of (label, NFAState) pairs + + def addarc(self, next, label=None): + assert label is None or isinstance(label, str) + assert isinstance(next, NFAState) + self.arcs.append((label, next)) + +class DFAState(object): + + def __init__(self, nfaset, final): + assert isinstance(nfaset, dict) + assert isinstance(iter(nfaset).next(), NFAState) + assert isinstance(final, NFAState) + self.nfaset = nfaset + self.isfinal = final in nfaset + self.arcs = {} # map from label to DFAState + + def addarc(self, next, label): + assert isinstance(label, str) + assert label not in self.arcs + assert isinstance(next, DFAState) + self.arcs[label] = next + + def unifystate(self, old, new): + for label, next in self.arcs.iteritems(): + if next is old: + self.arcs[label] = new + + def __eq__(self, other): + # Equality test -- ignore the nfaset instance variable + assert isinstance(other, DFAState) + if self.isfinal != other.isfinal: + return False + # Can't just return self.arcs == other.arcs, because that + # would invoke this method recursively, with cycles... + if len(self.arcs) != len(other.arcs): + return False + for label, next in self.arcs.iteritems(): + if next is not other.arcs.get(label): + return False + return True + +def generate_grammar(filename="Grammar.txt"): + p = ParserGenerator(filename) + return p.make_grammar() diff --git a/sphinx/pycode/pgen2/token.py b/sphinx/pycode/pgen2/token.py new file mode 100755 index 00000000..61468b31 --- /dev/null +++ b/sphinx/pycode/pgen2/token.py @@ -0,0 +1,82 @@ +#! /usr/bin/env python + +"""Token constants (from "token.h").""" + +# Taken from Python (r53757) and modified to include some tokens +# originally monkeypatched in by pgen2.tokenize + +#--start constants-- +ENDMARKER = 0 +NAME = 1 +NUMBER = 2 +STRING = 3 +NEWLINE = 4 +INDENT = 5 +DEDENT = 6 +LPAR = 7 +RPAR = 8 +LSQB = 9 +RSQB = 10 +COLON = 11 +COMMA = 12 +SEMI = 13 +PLUS = 14 +MINUS = 15 +STAR = 16 +SLASH = 17 +VBAR = 18 +AMPER = 19 +LESS = 20 +GREATER = 21 +EQUAL = 22 +DOT = 23 +PERCENT = 24 +BACKQUOTE = 25 +LBRACE = 26 +RBRACE = 27 +EQEQUAL = 28 +NOTEQUAL = 29 +LESSEQUAL = 30 +GREATEREQUAL = 31 +TILDE = 32 +CIRCUMFLEX = 33 +LEFTSHIFT = 34 +RIGHTSHIFT = 35 +DOUBLESTAR = 36 +PLUSEQUAL = 37 +MINEQUAL = 38 +STAREQUAL = 39 +SLASHEQUAL = 40 +PERCENTEQUAL = 41 +AMPEREQUAL = 42 +VBAREQUAL = 43 +CIRCUMFLEXEQUAL = 44 +LEFTSHIFTEQUAL = 45 +RIGHTSHIFTEQUAL = 46 +DOUBLESTAREQUAL = 47 +DOUBLESLASH = 48 +DOUBLESLASHEQUAL = 49 +AT = 50 +OP = 51 +COMMENT = 52 +NL = 53 +RARROW = 54 +ERRORTOKEN = 55 +N_TOKENS = 56 +NT_OFFSET = 256 +#--end constants-- + +tok_name = {} +for _name, _value in globals().items(): + if type(_value) is type(0): + tok_name[_value] = _name + + +def ISTERMINAL(x): + return x < NT_OFFSET + +def ISNONTERMINAL(x): + return x >= NT_OFFSET + +def ISEOF(x): + return x == ENDMARKER diff --git a/sphinx/pycode/pgen2/tokenize.py b/sphinx/pycode/pgen2/tokenize.py new file mode 100644 index 00000000..46ee7842 --- /dev/null +++ b/sphinx/pycode/pgen2/tokenize.py @@ -0,0 +1,405 @@ +# Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006 Python Software Foundation. +# All rights reserved. + +"""Tokenization help for Python programs. + +generate_tokens(readline) is a generator that breaks a stream of +text into Python tokens. It accepts a readline-like method which is called +repeatedly to get the next line of input (or "" for EOF). It generates +5-tuples with these members: + + the token type (see token.py) + the token (a string) + the starting (row, column) indices of the token (a 2-tuple of ints) + the ending (row, column) indices of the token (a 2-tuple of ints) + the original line (string) + +It is designed to match the working of the Python tokenizer exactly, except +that it produces COMMENT tokens for comments and gives type OP for all +operators + +Older entry points + tokenize_loop(readline, tokeneater) + tokenize(readline, tokeneater=printtoken) +are the same, except instead of generating tokens, tokeneater is a callback +function to which the 5 fields described above are passed as 5 arguments, +each time a new token is found.""" + +__author__ = 'Ka-Ping Yee ' +__credits__ = \ + 'GvR, ESR, Tim Peters, Thomas Wouters, Fred Drake, Skip Montanaro' + +import string, re +from sphinx.pycode.pgen2.token import * +from sphinx.pycode.pgen2 import token + +__all__ = [x for x in dir(token) if x[0] != '_'] + ["tokenize", + "generate_tokens", "untokenize"] +del token + +def group(*choices): return '(' + '|'.join(choices) + ')' +def any(*choices): return group(*choices) + '*' +def maybe(*choices): return group(*choices) + '?' + +Whitespace = r'[ \f\t]*' +Comment = r'#[^\r\n]*' +Ignore = Whitespace + any(r'\\\r?\n' + Whitespace) + maybe(Comment) +Name = r'[a-zA-Z_]\w*' + +Binnumber = r'0[bB][01]*' +Hexnumber = r'0[xX][\da-fA-F]*[lL]?' +Octnumber = r'0[oO]?[0-7]*[lL]?' +Decnumber = r'[1-9]\d*[lL]?' +Intnumber = group(Binnumber, Hexnumber, Octnumber, Decnumber) +Exponent = r'[eE][-+]?\d+' +Pointfloat = group(r'\d+\.\d*', r'\.\d+') + maybe(Exponent) +Expfloat = r'\d+' + Exponent +Floatnumber = group(Pointfloat, Expfloat) +Imagnumber = group(r'\d+[jJ]', Floatnumber + r'[jJ]') +Number = group(Imagnumber, Floatnumber, Intnumber) + +# Tail end of ' string. +Single = r"[^'\\]*(?:\\.[^'\\]*)*'" +# Tail end of " string. +Double = r'[^"\\]*(?:\\.[^"\\]*)*"' +# Tail end of ''' string. +Single3 = r"[^'\\]*(?:(?:\\.|'(?!''))[^'\\]*)*'''" +# Tail end of """ string. +Double3 = r'[^"\\]*(?:(?:\\.|"(?!""))[^"\\]*)*"""' +Triple = group("[ubUB]?[rR]?'''", '[ubUB]?[rR]?"""') +# Single-line ' or " string. +String = group(r"[uU]?[rR]?'[^\n'\\]*(?:\\.[^\n'\\]*)*'", + r'[uU]?[rR]?"[^\n"\\]*(?:\\.[^\n"\\]*)*"') + +# Because of leftmost-then-longest match semantics, be sure to put the +# longest operators first (e.g., if = came before ==, == would get +# recognized as two instances of =). +Operator = group(r"\*\*=?", r">>=?", r"<<=?", r"<>", r"!=", + r"//=?", r"->", + r"[+\-*/%&|^=<>]=?", + r"~") + +Bracket = '[][(){}]' +Special = group(r'\r?\n', r'[:;.,`@]') +Funny = group(Operator, Bracket, Special) + +PlainToken = group(Number, Funny, String, Name) +Token = Ignore + PlainToken + +# First (or only) line of ' or " string. +ContStr = group(r"[uUbB]?[rR]?'[^\n'\\]*(?:\\.[^\n'\\]*)*" + + group("'", r'\\\r?\n'), + r'[uUbB]?[rR]?"[^\n"\\]*(?:\\.[^\n"\\]*)*' + + group('"', r'\\\r?\n')) +PseudoExtras = group(r'\\\r?\n', Comment, Triple) +PseudoToken = Whitespace + group(PseudoExtras, Number, Funny, ContStr, Name) + +tokenprog, pseudoprog, single3prog, double3prog = map( + re.compile, (Token, PseudoToken, Single3, Double3)) +endprogs = {"'": re.compile(Single), '"': re.compile(Double), + "'''": single3prog, '"""': double3prog, + "r'''": single3prog, 'r"""': double3prog, + "u'''": single3prog, 'u"""': double3prog, + "b'''": single3prog, 'b"""': double3prog, + "ur'''": single3prog, 'ur"""': double3prog, + "br'''": single3prog, 'br"""': double3prog, + "R'''": single3prog, 'R"""': double3prog, + "U'''": single3prog, 'U"""': double3prog, + "B'''": single3prog, 'B"""': double3prog, + "uR'''": single3prog, 'uR"""': double3prog, + "Ur'''": single3prog, 'Ur"""': double3prog, + "UR'''": single3prog, 'UR"""': double3prog, + "bR'''": single3prog, 'bR"""': double3prog, + "Br'''": single3prog, 'Br"""': double3prog, + "BR'''": single3prog, 'BR"""': double3prog, + 'r': None, 'R': None, + 'u': None, 'U': None, + 'b': None, 'B': None} + +triple_quoted = {} +for t in ("'''", '"""', + "r'''", 'r"""', "R'''", 'R"""', + "u'''", 'u"""', "U'''", 'U"""', + "b'''", 'b"""', "B'''", 'B"""', + "ur'''", 'ur"""', "Ur'''", 'Ur"""', + "uR'''", 'uR"""', "UR'''", 'UR"""', + "br'''", 'br"""', "Br'''", 'Br"""', + "bR'''", 'bR"""', "BR'''", 'BR"""',): + triple_quoted[t] = t +single_quoted = {} +for t in ("'", '"', + "r'", 'r"', "R'", 'R"', + "u'", 'u"', "U'", 'U"', + "b'", 'b"', "B'", 'B"', + "ur'", 'ur"', "Ur'", 'Ur"', + "uR'", 'uR"', "UR'", 'UR"', + "br'", 'br"', "Br'", 'Br"', + "bR'", 'bR"', "BR'", 'BR"', ): + single_quoted[t] = t + +tabsize = 8 + +class TokenError(Exception): pass + +class StopTokenizing(Exception): pass + +def printtoken(type, token, (srow, scol), (erow, ecol), line): # for testing + print "%d,%d-%d,%d:\t%s\t%s" % \ + (srow, scol, erow, ecol, tok_name[type], repr(token)) + +def tokenize(readline, tokeneater=printtoken): + """ + The tokenize() function accepts two parameters: one representing the + input stream, and one providing an output mechanism for tokenize(). + + The first parameter, readline, must be a callable object which provides + the same interface as the readline() method of built-in file objects. + Each call to the function should return one line of input as a string. + + The second parameter, tokeneater, must also be a callable object. It is + called once for each token, with five arguments, corresponding to the + tuples generated by generate_tokens(). + """ + try: + tokenize_loop(readline, tokeneater) + except StopTokenizing: + pass + +# backwards compatible interface +def tokenize_loop(readline, tokeneater): + for token_info in generate_tokens(readline): + tokeneater(*token_info) + +class Untokenizer: + + def __init__(self): + self.tokens = [] + self.prev_row = 1 + self.prev_col = 0 + + def add_whitespace(self, start): + row, col = start + assert row <= self.prev_row + col_offset = col - self.prev_col + if col_offset: + self.tokens.append(" " * col_offset) + + def untokenize(self, iterable): + for t in iterable: + if len(t) == 2: + self.compat(t, iterable) + break + tok_type, token, start, end, line = t + self.add_whitespace(start) + self.tokens.append(token) + self.prev_row, self.prev_col = end + if tok_type in (NEWLINE, NL): + self.prev_row += 1 + self.prev_col = 0 + return "".join(self.tokens) + + def compat(self, token, iterable): + startline = False + indents = [] + toks_append = self.tokens.append + toknum, tokval = token + if toknum in (NAME, NUMBER): + tokval += ' ' + if toknum in (NEWLINE, NL): + startline = True + for tok in iterable: + toknum, tokval = tok[:2] + + if toknum in (NAME, NUMBER): + tokval += ' ' + + if toknum == INDENT: + indents.append(tokval) + continue + elif toknum == DEDENT: + indents.pop() + continue + elif toknum in (NEWLINE, NL): + startline = True + elif startline and indents: + toks_append(indents[-1]) + startline = False + toks_append(tokval) + +def untokenize(iterable): + """Transform tokens back into Python source code. + + Each element returned by the iterable must be a token sequence + with at least two elements, a token number and token value. If + only two tokens are passed, the resulting output is poor. + + Round-trip invariant for full input: + Untokenized source will match input source exactly + + Round-trip invariant for limited intput: + # Output text will tokenize the back to the input + t1 = [tok[:2] for tok in generate_tokens(f.readline)] + newcode = untokenize(t1) + readline = iter(newcode.splitlines(1)).next + t2 = [tok[:2] for tokin generate_tokens(readline)] + assert t1 == t2 + """ + ut = Untokenizer() + return ut.untokenize(iterable) + +def generate_tokens(readline): + """ + The generate_tokens() generator requires one argment, readline, which + must be a callable object which provides the same interface as the + readline() method of built-in file objects. Each call to the function + should return one line of input as a string. Alternately, readline + can be a callable function terminating with StopIteration: + readline = open(myfile).next # Example of alternate readline + + The generator produces 5-tuples with these members: the token type; the + token string; a 2-tuple (srow, scol) of ints specifying the row and + column where the token begins in the source; a 2-tuple (erow, ecol) of + ints specifying the row and column where the token ends in the source; + and the line on which the token was found. The line passed is the + logical line; continuation lines are included. + """ + lnum = parenlev = continued = 0 + namechars, numchars = string.ascii_letters + '_', '0123456789' + contstr, needcont = '', 0 + contline = None + indents = [0] + + while 1: # loop over lines in stream + try: + line = readline() + except StopIteration: + line = '' + lnum = lnum + 1 + pos, max = 0, len(line) + + if contstr: # continued string + if not line: + raise TokenError, ("EOF in multi-line string", strstart) + endmatch = endprog.match(line) + if endmatch: + pos = end = endmatch.end(0) + yield (STRING, contstr + line[:end], + strstart, (lnum, end), contline + line) + contstr, needcont = '', 0 + contline = None + elif needcont and line[-2:] != '\\\n' and line[-3:] != '\\\r\n': + yield (ERRORTOKEN, contstr + line, + strstart, (lnum, len(line)), contline) + contstr = '' + contline = None + continue + else: + contstr = contstr + line + contline = contline + line + continue + + elif parenlev == 0 and not continued: # new statement + if not line: break + column = 0 + while pos < max: # measure leading whitespace + if line[pos] == ' ': column = column + 1 + elif line[pos] == '\t': column = (column/tabsize + 1)*tabsize + elif line[pos] == '\f': column = 0 + else: break + pos = pos + 1 + if pos == max: break + + if line[pos] in '#\r\n': # skip comments or blank lines + if line[pos] == '#': + comment_token = line[pos:].rstrip('\r\n') + nl_pos = pos + len(comment_token) + yield (COMMENT, comment_token, + (lnum, pos), (lnum, pos + len(comment_token)), line) + yield (NL, line[nl_pos:], + (lnum, nl_pos), (lnum, len(line)), line) + else: + yield ((NL, COMMENT)[line[pos] == '#'], line[pos:], + (lnum, pos), (lnum, len(line)), line) + continue + + if column > indents[-1]: # count indents or dedents + indents.append(column) + yield (INDENT, line[:pos], (lnum, 0), (lnum, pos), line) + while column < indents[-1]: + if column not in indents: + raise IndentationError( + "unindent does not match any outer indentation level", + ("", lnum, pos, line)) + indents = indents[:-1] + yield (DEDENT, '', (lnum, pos), (lnum, pos), line) + + else: # continued statement + if not line: + raise TokenError, ("EOF in multi-line statement", (lnum, 0)) + continued = 0 + + while pos < max: + pseudomatch = pseudoprog.match(line, pos) + if pseudomatch: # scan for tokens + start, end = pseudomatch.span(1) + spos, epos, pos = (lnum, start), (lnum, end), end + token, initial = line[start:end], line[start] + + if initial in numchars or \ + (initial == '.' and token != '.'): # ordinary number + yield (NUMBER, token, spos, epos, line) + elif initial in '\r\n': + newline = NEWLINE + if parenlev > 0: + newline = NL + yield (newline, token, spos, epos, line) + elif initial == '#': + assert not token.endswith("\n") + yield (COMMENT, token, spos, epos, line) + elif token in triple_quoted: + endprog = endprogs[token] + endmatch = endprog.match(line, pos) + if endmatch: # all on one line + pos = endmatch.end(0) + token = line[start:pos] + yield (STRING, token, spos, (lnum, pos), line) + else: + strstart = (lnum, start) # multiple lines + contstr = line[start:] + contline = line + break + elif initial in single_quoted or \ + token[:2] in single_quoted or \ + token[:3] in single_quoted: + if token[-1] == '\n': # continued string + strstart = (lnum, start) + endprog = (endprogs[initial] or endprogs[token[1]] or + endprogs[token[2]]) + contstr, needcont = line[start:], 1 + contline = line + break + else: # ordinary string + yield (STRING, token, spos, epos, line) + elif initial in namechars: # ordinary name + yield (NAME, token, spos, epos, line) + elif initial == '\\': # continued stmt + # This yield is new; needed for better idempotency: + yield (NL, token, spos, (lnum, pos), line) + continued = 1 + else: + if initial in '([{': parenlev = parenlev + 1 + elif initial in ')]}': parenlev = parenlev - 1 + yield (OP, token, spos, epos, line) + else: + yield (ERRORTOKEN, line[pos], + (lnum, pos), (lnum, pos+1), line) + pos = pos + 1 + + for indent in indents[1:]: # pop remaining indent levels + yield (DEDENT, '', (lnum, 0), (lnum, 0), '') + yield (ENDMARKER, '', (lnum, 0), (lnum, 0), '') + +if __name__ == '__main__': # testing + import sys + if len(sys.argv) > 1: tokenize(open(sys.argv[1]).readline) + else: tokenize(sys.stdin.readline) diff --git a/sphinx/pycode/pytree.py b/sphinx/pycode/pytree.py new file mode 100644 index 00000000..950319c5 --- /dev/null +++ b/sphinx/pycode/pytree.py @@ -0,0 +1,295 @@ +# Copyright 2006 Google, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""Python parse tree definitions. + +This is a very concrete parse tree; we need to keep every token and +even the comments and whitespace between tokens. + +Adapted for read-only nodes from pytree.py in Python's 2to3 tool, and +added a few bits. +""" + +__author__ = "Guido van Rossum " + + +class Base(object): + + """Abstract base class for Node and Leaf. + + This provides some default functionality and boilerplate using the + template pattern. + + A node may be a subnode of at most one parent. + """ + + # Default values for instance variables + type = None # int: token number (< 256) or symbol number (>= 256) + parent = None # Parent node pointer, or None + children = () # Tuple of subnodes + was_changed = False + + def __new__(cls, *args, **kwds): + """Constructor that prevents Base from being instantiated.""" + assert cls is not Base, "Cannot instantiate Base" + return object.__new__(cls) + + def __eq__(self, other): + """Compares two nodes for equality. + + This calls the method _eq(). + """ + if self.__class__ is not other.__class__: + return NotImplemented + return self._eq(other) + + def __ne__(self, other): + """Compares two nodes for inequality. + + This calls the method _eq(). + """ + if self.__class__ is not other.__class__: + return NotImplemented + return not self._eq(other) + + def _eq(self, other): + """Compares two nodes for equality. + + This is called by __eq__ and __ne__. It is only called if the + two nodes have the same type. This must be implemented by the + concrete subclass. Nodes should be considered equal if they + have the same structure, ignoring the prefix string and other + context information. + """ + raise NotImplementedError + + def get_lineno(self): + """Returns the line number which generated the invocant node.""" + node = self + while not isinstance(node, Leaf): + if not node.children: + return + node = node.children[0] + return node.lineno + + def get_next_sibling(self): + """Return the node immediately following the invocant in their + parent's children list. If the invocant does not have a next + sibling, return None.""" + if self.parent is None: + return None + + # Can't use index(); we need to test by identity + for i, child in enumerate(self.parent.children): + if child is self: + try: + return self.parent.children[i+1] + except IndexError: + return None + + def get_prev_sibling(self): + """Return the node immediately preceding the invocant in their + parent's children list. If the invocant does not have a previous + sibling, return None.""" + if self.parent is None: + return None + + # Can't use index(); we need to test by identity + for i, child in enumerate(self.parent.children): + if child is self: + if i == 0: + return None + return self.parent.children[i-1] + + def get_prev_leaf(self): + """Return the leaf node that precedes this node in the parse tree.""" + def last_child(node): + if isinstance(node, Leaf): + return node + elif not node.children: + return None + else: + return last_child(node.children[-1]) + if self.parent is None: + return None + prev = self.get_prev_sibling() + if isinstance(prev, Leaf): + return prev + elif prev is not None: + return last_child(prev) + return self.parent.get_prev_leaf() + + def get_suffix(self): + """Return the string immediately following the invocant node. This + is effectively equivalent to node.get_next_sibling().get_prefix()""" + next_sib = self.get_next_sibling() + if next_sib is None: + return "" + return next_sib.get_prefix() + + +class Node(Base): + + """Concrete implementation for interior nodes.""" + + def __init__(self, type, children, context=None, prefix=None): + """Initializer. + + Takes a type constant (a symbol number >= 256), a sequence of + child nodes, and an optional context keyword argument. + + As a side effect, the parent pointers of the children are updated. + """ + assert type >= 256, type + self.type = type + self.children = list(children) + for ch in self.children: + assert ch.parent is None, repr(ch) + ch.parent = self + if prefix is not None: + self.set_prefix(prefix) + + def __repr__(self): + return "%s(%s, %r)" % (self.__class__.__name__, + self.type, self.children) + + def __str__(self): + """This reproduces the input source exactly.""" + return "".join(map(str, self.children)) + + def compact(self): + return ''.join(child.compact() for child in self.children) + + def __getitem__(self, index): + return self.children[index] + + def __iter__(self): + return iter(self.children) + + def _eq(self, other): + """Compares two nodes for equality.""" + return (self.type, self.children) == (other.type, other.children) + + def post_order(self): + """Returns a post-order iterator for the tree.""" + for child in self.children: + for node in child.post_order(): + yield node + yield self + + def pre_order(self): + """Returns a pre-order iterator for the tree.""" + yield self + for child in self.children: + for node in child.post_order(): + yield node + + def get_prefix(self): + """Returns the prefix for the node. + + This passes the call on to the first child. + """ + if not self.children: + return "" + return self.children[0].get_prefix() + + +class Leaf(Base): + + """Concrete implementation for leaf nodes.""" + + # Default values for instance variables + prefix = "" # Whitespace and comments preceding this token in the input + lineno = 0 # Line where this token starts in the input + column = 0 # Column where this token tarts in the input + + def __init__(self, type, value, context=None, prefix=None): + """Initializer. + + Takes a type constant (a token number < 256), a string value, + and an optional context keyword argument. + """ + assert 0 <= type < 256, type + if context is not None: + self.prefix, (self.lineno, self.column) = context + self.type = type + self.value = value + if prefix is not None: + self.prefix = prefix + + def __repr__(self): + return "%s(%r, %r)" % (self.__class__.__name__, + self.type, self.value) + + def __str__(self): + """This reproduces the input source exactly.""" + return self.prefix + str(self.value) + + def compact(self): + return str(self.value) + + def _eq(self, other): + """Compares two nodes for equality.""" + return (self.type, self.value) == (other.type, other.value) + + def post_order(self): + """Returns a post-order iterator for the tree.""" + yield self + + def pre_order(self): + """Returns a pre-order iterator for the tree.""" + yield self + + def get_prefix(self): + """Returns the prefix for the node.""" + return self.prefix + + +def convert(grammar, raw_node): + """Convert raw node to a Node or Leaf instance.""" + type, value, context, children = raw_node + if children or type in grammar.number2symbol: + # If there's exactly one child, return that child instead of + # creating a new node. + if len(children) == 1: + return children[0] + return Node(type, children, context=context) + else: + return Leaf(type, value, context=context) + + +def nice_repr(node, number2name, prefix=False): + def _repr(node): + if isinstance(node, Leaf): + return "%s(%r)" % (number2name[node.type], node.value) + else: + return "%s(%s)" % (number2name[node.type], + ', '.join(map(_repr, node.children))) + def _prepr(node): + if isinstance(node, Leaf): + return "%s(%r, %r)" % (number2name[node.type], node.prefix, node.value) + else: + return "%s(%s)" % (number2name[node.type], + ', '.join(map(_prepr, node.children))) + return (prefix and _prepr or _repr)(node) + + +class NodeVisitor(object): + def __init__(self, number2name): + self.number2name = number2name + self.init() + + def init(self): + pass + + def visit(self, node): + """Visit a node.""" + method = 'visit_' + self.number2name[node.type] + visitor = getattr(self, method, self.generic_visit) + return visitor(node) + + def generic_visit(self, node): + """Called if no explicit visitor function exists for a node.""" + if isinstance(node, Node): + for child in node: + self.visit(child) -- cgit v1.2.1 From 76d544d815fe9b3bb6f2150dbd4e11832fb8d47e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 29 Dec 2008 20:37:30 +0100 Subject: Cleanup; add scoping to ClassAttrVisitor. --- sphinx/pycode/__init__.py | 61 ++++++++++++++++++++++------------------------- sphinx/pycode/pytree.py | 6 ++--- 2 files changed, 31 insertions(+), 36 deletions(-) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index b5d83e67..e006ce16 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -10,6 +10,7 @@ """ import sys +import time from os import path from sphinx.pycode import pytree @@ -45,8 +46,10 @@ _eq = pytree.Leaf(token.EQUAL, '=') class ClassAttrVisitor(pytree.NodeVisitor): - def init(self): + def init(self, scope): + self.scope = scope self.namespace = [] + self.collected = [] def visit_classdef(self, node): self.namespace.append(node[1].value) @@ -54,17 +57,21 @@ class ClassAttrVisitor(pytree.NodeVisitor): self.namespace.pop() def visit_expr_stmt(self, node): - if _eq in node.children: - prefix = node[0].get_prefix() - if not prefix: - prev = node[0].get_prev_leaf() - if prev and prev.type == token.INDENT: - prefix = prev.prefix - doc = prepare_commentdoc(prefix) - if doc: - targ = '.'.join(self.namespace + [node[0].compact()]) - print targ - print doc + if _eq not in node.children: + # not an assignment (we don't care for augmented assignments) + return + prefix = node[0].get_prefix() + if not prefix: + # if this assignment is the first thing in a class block, + # the comment will be the prefix of the preceding INDENT token + prev = node[0].get_prev_leaf() + if prev and prev.type == token.INDENT: + prefix = prev.prefix + doc = prepare_commentdoc(prefix) + if doc: + name = '.'.join(self.namespace + [node[0].compact()]) + if name.startswith(self.scope): + self.collected.append((name, doc)) def visit_funcdef(self, node): return @@ -115,28 +122,16 @@ class ModuleAnalyzer(object): return cls.for_file(filename, modname) def find_defs(self): - attr_visitor = ClassAttrVisitor(number2name) - attr_visitor.namespace = [self.modname] + attr_visitor = ClassAttrVisitor(number2name, '') attr_visitor.visit(self.tree) + for name, doc in attr_visitor.collected: + print '>>', name + print doc -class Test: - """doc""" - - #: testing... - x = 1 - """doc""" - - #: testing more... - x = 2 - -#ma = ModuleAnalyzer.for_file(__file__.rstrip('c')) -import time -x0=time.time() -ma = ModuleAnalyzer.for_module('sphinx.builders.latex') -x1=time.time() +x0 = time.time() +ma = ModuleAnalyzer.for_module('sphinx.builders.html') +x1 = time.time() ma.find_defs() -x2=time.time() -print "%.4f %.4f" % (x1-x0, x2-x1) - -#print pytree.nice_repr(ma.tree, number2name, True) +x2 = time.time() +print "parsing %.4f, finding %.4f" % (x1-x0, x2-x1) diff --git a/sphinx/pycode/pytree.py b/sphinx/pycode/pytree.py index 950319c5..a0e83b63 100644 --- a/sphinx/pycode/pytree.py +++ b/sphinx/pycode/pytree.py @@ -275,11 +275,11 @@ def nice_repr(node, number2name, prefix=False): class NodeVisitor(object): - def __init__(self, number2name): + def __init__(self, number2name, *args): self.number2name = number2name - self.init() + self.init(*args) - def init(self): + def init(self, *args): pass def visit(self, node): -- cgit v1.2.1 From d59cb5c2dfeae2282b804459b76a4ef5f9243ccf Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 29 Dec 2008 20:39:14 +0100 Subject: Add comment. --- sphinx/pycode/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index e006ce16..26d3579d 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -74,6 +74,7 @@ class ClassAttrVisitor(pytree.NodeVisitor): self.collected.append((name, doc)) def visit_funcdef(self, node): + # don't descend into functions -- nothing interesting there return -- cgit v1.2.1 From fb41d84eca01e3a622780dbd15b6c7606b0bbc4f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 29 Dec 2008 20:47:32 +0100 Subject: Improve error handling. --- sphinx/pycode/__init__.py | 51 ++++++++++++++++++++++++++++++----------------- 1 file changed, 33 insertions(+), 18 deletions(-) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index 26d3579d..0ebf683c 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -14,7 +14,7 @@ import time from os import path from sphinx.pycode import pytree -from sphinx.pycode.pgen2 import driver, token +from sphinx.pycode.pgen2 import driver, token, parse # load the Python grammar @@ -78,6 +78,14 @@ class ClassAttrVisitor(pytree.NodeVisitor): return +class PycodeError(Exception): + def __str__(self): + res = self.args[0] + if len(self.args) > 1: + res += ' (exception was: %r)' % self.args[1] + return res + + class ModuleAnalyzer(object): def __init__(self, tree, modname, srcname): @@ -91,48 +99,55 @@ class ModuleAnalyzer(object): @classmethod def for_file(cls, filename, modname): - # XXX if raises - fileobj = open(filename, 'r') try: - return cls(pydriver.parse_stream(fileobj), modname, filename) + fileobj = open(filename, 'r') + except Exception, err: + raise PycodeError('error opening %r' % filename, err) + try: + try: + return cls(pydriver.parse_stream(fileobj), modname, filename) + except parse.ParseError, err: + raise PycodeError('error parsing %r' % filename, err) finally: fileobj.close() @classmethod def for_module(cls, modname): if modname not in sys.modules: - # XXX - __import__(modname) + try: + __import__(modname) + except ImportError, err: + raise PycodeError('error importing %r' % modname, err) mod = sys.modules[modname] if hasattr(mod, '__loader__'): - # XXX raises - source = mod.__loader__.get_source(modname) + try: + source = mod.__loader__.get_source(modname) + except Exception, err: + raise PycodeError('error getting source for %r' % modname, err) return cls.for_string(source, modname) filename = getattr(mod, '__file__', None) if filename is None: - # XXX - raise RuntimeError('no source found') + raise PycodeError('no source found for module %r' % modname) if filename.lower().endswith('.pyo') or \ filename.lower().endswith('.pyc'): filename = filename[:-1] elif not filename.lower().endswith('.py'): - raise RuntimeError('not a .py file') + raise PycodeError('source is not a .py file: %r' % filename) if not path.isfile(filename): - # XXX - raise RuntimeError('source not present') + raise PycodeError('source file is not present: %r' % filename) return cls.for_file(filename, modname) - def find_defs(self): + def find_attrs(self): attr_visitor = ClassAttrVisitor(number2name, '') attr_visitor.visit(self.tree) - for name, doc in attr_visitor.collected: - print '>>', name - print doc + return attr_visitor.collected x0 = time.time() ma = ModuleAnalyzer.for_module('sphinx.builders.html') x1 = time.time() -ma.find_defs() +for name, doc in ma.find_attrs(): + print '>>', name + print doc x2 = time.time() print "parsing %.4f, finding %.4f" % (x1-x0, x2-x1) -- cgit v1.2.1 From e51906609b6959386593da6fa2ede65ca9129b62 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 29 Dec 2008 22:25:15 +0100 Subject: Fix handling of INDENT/DEDENT tokens. --- sphinx/pycode/__init__.py | 39 ++++++++++++++++++++++++++++----------- sphinx/pycode/pytree.py | 3 +++ 2 files changed, 31 insertions(+), 11 deletions(-) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index 0ebf683c..ab34af1c 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -32,6 +32,10 @@ number2name.update(token.tok_name) def prepare_commentdoc(s): + """ + Extract documentation comment lines (starting with #:) and return them as a + list of lines. Returns an empty list if there is no documentation. + """ result = [] lines = [line.strip() for line in s.expandtabs().splitlines()] for line in lines: @@ -46,6 +50,10 @@ _eq = pytree.Leaf(token.EQUAL, '=') class ClassAttrVisitor(pytree.NodeVisitor): + """ + Visitor that collects comments appearing before attribute assignments + on toplevel and in classes. + """ def init(self, scope): self.scope = scope self.namespace = [] @@ -60,18 +68,27 @@ class ClassAttrVisitor(pytree.NodeVisitor): if _eq not in node.children: # not an assignment (we don't care for augmented assignments) return - prefix = node[0].get_prefix() - if not prefix: - # if this assignment is the first thing in a class block, - # the comment will be the prefix of the preceding INDENT token - prev = node[0].get_prev_leaf() - if prev and prev.type == token.INDENT: - prefix = prev.prefix - doc = prepare_commentdoc(prefix) - if doc: - name = '.'.join(self.namespace + [node[0].compact()]) + pnode = node[0] + prefix = pnode.get_prefix() + # if the assignment is the first statement on a new indentation + # level, its preceding whitespace and comments are not assigned + # to that token, but the first INDENT or DEDENT token + while not prefix: + pnode = pnode.get_prev_leaf() + if not pnode or pnode.type not in (token.INDENT, token.DEDENT): + break + docstring = prepare_commentdoc(prefix) + if not docstring: + return + # add an item for each assignment target + for i in range(0, len(node) - 1, 2): + target = node[i] + if target.type != token.NAME: + # don't care about complex targets + continue + name = '.'.join(self.namespace + [target.value]) if name.startswith(self.scope): - self.collected.append((name, doc)) + self.collected.append((name, docstring)) def visit_funcdef(self, node): # don't descend into functions -- nothing interesting there diff --git a/sphinx/pycode/pytree.py b/sphinx/pycode/pytree.py index a0e83b63..bd72bc99 100644 --- a/sphinx/pycode/pytree.py +++ b/sphinx/pycode/pytree.py @@ -166,6 +166,9 @@ class Node(Base): def __iter__(self): return iter(self.children) + def __len__(self): + return len(self.children) + def _eq(self, other): """Compares two nodes for equality.""" return (self.type, self.children) == (other.type, other.children) -- cgit v1.2.1 From c5bd95ae02352a05a3899b0cbad8a85a95804935 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 29 Dec 2008 22:30:00 +0100 Subject: Another fix for DEDENT/INDENT handling. --- sphinx/builders/html.py | 3 ++- sphinx/pycode/__init__.py | 1 + sphinx/pycode/pytree.py | 4 ++-- 3 files changed, 5 insertions(+), 3 deletions(-) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 4ce30ad8..2bcd54ec 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -37,8 +37,9 @@ except ImportError: except ImportError: json = None - +#: the filename for the inventory of objects INVENTORY_FILENAME = 'objects.inv' +#: the filename for the "last build" file (for serializing builders) LAST_BUILD_FILENAME = 'last_build' diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index ab34af1c..dd32d470 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -77,6 +77,7 @@ class ClassAttrVisitor(pytree.NodeVisitor): pnode = pnode.get_prev_leaf() if not pnode or pnode.type not in (token.INDENT, token.DEDENT): break + prefix = pnode.get_prefix() docstring = prepare_commentdoc(prefix) if not docstring: return diff --git a/sphinx/pycode/pytree.py b/sphinx/pycode/pytree.py index bd72bc99..46017a95 100644 --- a/sphinx/pycode/pytree.py +++ b/sphinx/pycode/pytree.py @@ -221,8 +221,8 @@ class Leaf(Base): self.prefix = prefix def __repr__(self): - return "%s(%r, %r)" % (self.__class__.__name__, - self.type, self.value) + return "%s(%r, %r, %r)" % (self.__class__.__name__, + self.type, self.value, self.prefix) def __str__(self): """This reproduces the input source exactly.""" -- cgit v1.2.1 From e177eeb750aad12d964a16b750a8839f194a03bd Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 29 Dec 2008 22:30:41 +0100 Subject: Ignore grammar pickle files. --- .hgignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.hgignore b/.hgignore index a6b6e37a..37589422 100644 --- a/.hgignore +++ b/.hgignore @@ -2,6 +2,7 @@ .*\.egg build/ dist/ +sphinx/pycode/Grammar.*pickle Sphinx.egg-info/ doc/_build/ TAGS -- cgit v1.2.1 From 484625cc327f4fab73313f785b9aaeb94080e5be Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 01:29:49 +0100 Subject: Some speedups in pytree. Add Cython parse.py replacement, yielding a 2x speedup in parsing. --- sphinx/pycode/pgen2/parse.pyx | 156 ++++++++++++++++++++++++++++++++++++++++++ sphinx/pycode/pytree.py | 23 +++---- 2 files changed, 165 insertions(+), 14 deletions(-) create mode 100644 sphinx/pycode/pgen2/parse.pyx diff --git a/sphinx/pycode/pgen2/parse.pyx b/sphinx/pycode/pgen2/parse.pyx new file mode 100644 index 00000000..6a11ee6b --- /dev/null +++ b/sphinx/pycode/pgen2/parse.pyx @@ -0,0 +1,156 @@ +# Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. +# Licensed to PSF under a Contributor Agreement. + +"""Parser engine for the grammar tables generated by pgen. + +The grammar table must be loaded first. + +See Parser/parser.c in the Python distribution for additional info on +how this parsing engine works. + +""" + +from sphinx.pycode.pytree import Node, Leaf + +DEF NAME = 1 + +class ParseError(Exception): + """Exception to signal the parser is stuck.""" + + def __init__(self, msg, type, value, context): + Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + (msg, type, value, context)) + self.msg = msg + self.type = type + self.value = value + self.context = context + + +cdef class Parser: + cdef public grammar, stack, rootnode, used_names + cdef _grammar_dfas, _grammar_labels, _grammar_keywords, _grammar_tokens + cdef _grammar_number2symbol + + def __init__(self, grammar, convert=None): + self.grammar = grammar + #self.convert = convert or noconvert + + self._grammar_dfas = grammar.dfas + self._grammar_labels = grammar.labels + self._grammar_keywords = grammar.keywords + self._grammar_tokens = grammar.tokens + self._grammar_number2symbol = grammar.number2symbol + + def setup(self, start=None): + if start is None: + start = self.grammar.start + # Each stack entry is a tuple: (dfa, state, node). + # A node is a tuple: (type, value, context, children), + # where children is a list of nodes or None, and context may be None. + newnode = (start, None, None, []) + stackentry = (self._grammar_dfas[start], 0, newnode) + self.stack = [stackentry] + self.rootnode = None + self.used_names = set() # Aliased to self.rootnode.used_names in pop() + + def addtoken(self, type, value, context): + """Add a token; return True iff this is the end of the program.""" + cdef int ilabel, i, t, state, newstate + # Map from token to label + ilabel = self.classify(type, value, context) + # Loop until the token is shifted; may raise exceptions + while True: + dfa, state, node = self.stack[-1] + states, first = dfa + arcs = states[state] + # Look for a state with this label + for i, newstate in arcs: + t, v = self._grammar_labels[i] + if ilabel == i: + # Look it up in the list of labels + ## assert t < 256 + # Shift a token; we're done with it + self.shift(type, value, newstate, context) + # Pop while we are in an accept-only state + state = newstate + while states[state] == [(0, state)]: + self.pop() + if not self.stack: + # Done parsing! + return True + dfa, state, node = self.stack[-1] + states, first = dfa + # Done with this token + return False + elif t >= 256: + # See if it's a symbol and if we're in its first set + itsdfa = self._grammar_dfas[t] + itsstates, itsfirst = itsdfa + if ilabel in itsfirst: + # Push a symbol + self.push(t, itsdfa, newstate, context) + break # To continue the outer while loop + else: + if (0, state) in arcs: + # An accepting state, pop it and try something else + self.pop() + if not self.stack: + # Done parsing, but another token is input + raise ParseError("too much input", + type, value, context) + else: + # No success finding a transition + raise ParseError("bad input", type, value, context) + + cdef int classify(self, type, value, context): + """Turn a token into a label. (Internal)""" + if type == NAME: + # Keep a listing of all used names + self.used_names.add(value) + # Check for reserved words + ilabel = self._grammar_keywords.get(value) + if ilabel is not None: + return ilabel + ilabel = self._grammar_tokens.get(type) + if ilabel is None: + raise ParseError("bad token", type, value, context) + return ilabel + + cdef void shift(self, type, value, newstate, context): + """Shift a token. (Internal)""" + dfa, state, node = self.stack[-1] + newnode = (type, value, context, None) + newnode = self.convert(newnode) + if newnode is not None: + node[-1].append(newnode) + self.stack[-1] = (dfa, newstate, node) + + cdef void push(self, type, newdfa, newstate, context): + """Push a nonterminal. (Internal)""" + dfa, state, node = self.stack[-1] + newnode = (type, None, context, []) + self.stack[-1] = (dfa, newstate, node) + self.stack.append((newdfa, 0, newnode)) + + cdef void pop(self): + """Pop a nonterminal. (Internal)""" + popdfa, popstate, popnode = self.stack.pop() + newnode = self.convert(popnode) + if newnode is not None: + if self.stack: + dfa, state, node = self.stack[-1] + node[-1].append(newnode) + else: + self.rootnode = newnode + self.rootnode.used_names = self.used_names + + cdef convert(self, raw_node): + type, value, context, children = raw_node + if children or type in self._grammar_number2symbol: + # If there's exactly one child, return that child instead of + # creating a new node. + if len(children) == 1: + return children[0] + return Node(type, children, context=context) + else: + return Leaf(type, value, context=context) diff --git a/sphinx/pycode/pytree.py b/sphinx/pycode/pytree.py index 46017a95..063e39ec 100644 --- a/sphinx/pycode/pytree.py +++ b/sphinx/pycode/pytree.py @@ -29,11 +29,6 @@ class Base(object): children = () # Tuple of subnodes was_changed = False - def __new__(cls, *args, **kwds): - """Constructor that prevents Base from being instantiated.""" - assert cls is not Base, "Cannot instantiate Base" - return object.__new__(cls) - def __eq__(self, other): """Compares two nodes for equality. @@ -132,7 +127,7 @@ class Node(Base): """Concrete implementation for interior nodes.""" - def __init__(self, type, children, context=None, prefix=None): + def __init__(self, type, children, context=None): """Initializer. Takes a type constant (a symbol number >= 256), a sequence of @@ -140,14 +135,14 @@ class Node(Base): As a side effect, the parent pointers of the children are updated. """ - assert type >= 256, type + # assert type >= 256, type self.type = type self.children = list(children) for ch in self.children: - assert ch.parent is None, repr(ch) + # assert ch.parent is None, repr(ch) ch.parent = self - if prefix is not None: - self.set_prefix(prefix) + # if prefix is not None: + # self.set_prefix(prefix) def __repr__(self): return "%s(%s, %r)" % (self.__class__.__name__, @@ -206,19 +201,19 @@ class Leaf(Base): lineno = 0 # Line where this token starts in the input column = 0 # Column where this token tarts in the input - def __init__(self, type, value, context=None, prefix=None): + def __init__(self, type, value, context=None): """Initializer. Takes a type constant (a token number < 256), a string value, and an optional context keyword argument. """ - assert 0 <= type < 256, type + # assert 0 <= type < 256, type if context is not None: self.prefix, (self.lineno, self.column) = context self.type = type self.value = value - if prefix is not None: - self.prefix = prefix + # if prefix is not None: + # self.prefix = prefix def __repr__(self): return "%s(%r, %r, %r)" % (self.__class__.__name__, -- cgit v1.2.1 From bc4c6b9214603c8a04b965eae7ddebaa61727530 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 01:32:01 +0100 Subject: Move benchmark into __main__ block. --- sphinx/pycode/__init__.py | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index dd32d470..373d4a48 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -160,12 +160,12 @@ class ModuleAnalyzer(object): attr_visitor.visit(self.tree) return attr_visitor.collected - -x0 = time.time() -ma = ModuleAnalyzer.for_module('sphinx.builders.html') -x1 = time.time() -for name, doc in ma.find_attrs(): - print '>>', name - print doc -x2 = time.time() -print "parsing %.4f, finding %.4f" % (x1-x0, x2-x1) +if __name__ == '__main__': + x0 = time.time() + ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') + x1 = time.time() + for name, doc in ma.find_attrs(): + print '>>', name + print doc + x2 = time.time() + print "parsing %.4f, finding %.4f" % (x1-x0, x2-x1) -- cgit v1.2.1 From b16fc1a0ae62ebb0c97511da7ae04d890c7a9ad3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 02:09:29 +0100 Subject: First iteration of an autodoc that handles attribute documentation. --- sphinx/ext/autodoc.py | 55 +++++++++++++++++++++++++++++++++++------------ sphinx/pycode/__init__.py | 27 +++++++++++++++-------- 2 files changed, 59 insertions(+), 23 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index f94afc75..ddea1e44 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -22,6 +22,7 @@ from docutils.parsers.rst import directives from docutils.statemachine import ViewList from sphinx.util import rpartition, nested_parse_with_titles +from sphinx.pycode import ModuleAnalyzer, PycodeError clstypes = (type, ClassType) try: @@ -313,7 +314,7 @@ class RstGenerator(object): 'for automodule %s' % name) return (path or '') + base, [], None, None - elif what in ('exception', 'function', 'class'): + elif what in ('exception', 'function', 'class', 'data'): if mod is None: if path: mod = path.rstrip('.') @@ -434,7 +435,9 @@ class RstGenerator(object): modfile = None # e.g. for builtin and C modules for part in objpath: todoc = getattr(todoc, part) - except (ImportError, AttributeError), err: + # also get a source code analyzer for attribute docs + analyzer = ModuleAnalyzer.for_module(mod) + except (ImportError, AttributeError, PycodeError), err: self.warn('autodoc can\'t import/find %s %r, it reported error: "%s", ' 'please check your spelling and sys.path' % (what, str(fullname), err)) @@ -503,6 +506,15 @@ class RstGenerator(object): else: sourcename = 'docstring of %s' % fullname + # add content from attribute documentation + attr_docs = analyzer.find_attr_docs() + if what in ('data', 'attribute'): + key = ('.'.join(objpath[:-1]), objpath[-1]) + if key in attr_docs: + no_docstring = True + for i, line in enumerate(attr_docs[key]): + self.result.append(indent + line, sourcename, i) + # add content from docstrings if not no_docstring: for i, line in enumerate(self.get_doc(what, fullname, todoc)): @@ -524,9 +536,9 @@ class RstGenerator(object): self.env.autodoc_current_class = objpath[0] # add members, if possible - _all = members == ['__all__'] + all_members = members == ['__all__'] members_check_module = False - if _all: + if all_members: # unqualified :members: given if what == 'module': if hasattr(todoc, '__all__'): @@ -555,14 +567,28 @@ class RstGenerator(object): else: all_members = [(mname, getattr(todoc, mname)) for mname in members] + # search for members in source code too + namespace = '.'.join(objpath) # will be empty for modules + for (membername, member) in all_members: - if _all and membername.startswith('_'): + # if isattr is True, the member is documented as an attribute + isattr = False + # if content is not None, no extra content from docstrings will be added + content = None + + if all_members and membername.startswith('_'): # ignore members whose name starts with _ by default skip = True else: - # ignore undocumented members if :undoc-members: is not given - doc = getattr(member, '__doc__', None) - skip = not self.options.undoc_members and not doc + if (namespace, membername) in attr_docs: + # keep documented attributes + skip = False + isattr = True + else: + # ignore undocumented members if :undoc-members: is not given + doc = getattr(member, '__doc__', None) + skip = not self.options.undoc_members and not doc + # give the user a chance to decide whether this member should be skipped if self.env.app: # let extensions preprocess docstrings @@ -573,10 +599,11 @@ class RstGenerator(object): if skip: continue - content = None if what == 'module': if isinstance(member, (FunctionType, BuiltinFunctionType)): memberwhat = 'function' + elif isattr: + memberwhat = 'attribute' elif isinstance(member, clstypes): if member.__name__ != membername: # assume it's aliased @@ -588,10 +615,13 @@ class RstGenerator(object): else: memberwhat = 'class' else: - # XXX: todo -- attribute docs continue else: - if isinstance(member, clstypes): + if inspect.isroutine(member): + memberwhat = 'method' + elif isattr: + memberwhat = 'attribute' + elif isinstance(member, clstypes): if member.__name__ != membername: # assume it's aliased memberwhat = 'attribute' @@ -599,12 +629,9 @@ class RstGenerator(object): source='') else: memberwhat = 'class' - elif inspect.isroutine(member): - memberwhat = 'method' elif isdescriptor(member): memberwhat = 'attribute' else: - # XXX: todo -- attribute docs continue # give explicitly separated module name, so that members of inner classes # can be documented diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index 373d4a48..0d4058bd 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -43,7 +43,7 @@ def prepare_commentdoc(s): result.append(line[3:]) if result and result[-1]: result.append('') - return '\n'.join(result) + return result _eq = pytree.Leaf(token.EQUAL, '=') @@ -57,7 +57,7 @@ class ClassAttrVisitor(pytree.NodeVisitor): def init(self, scope): self.scope = scope self.namespace = [] - self.collected = [] + self.collected = {} def visit_classdef(self, node): self.namespace.append(node[1].value) @@ -87,9 +87,9 @@ class ClassAttrVisitor(pytree.NodeVisitor): if target.type != token.NAME: # don't care about complex targets continue - name = '.'.join(self.namespace + [target.value]) - if name.startswith(self.scope): - self.collected.append((name, docstring)) + namespace = '.'.join(self.namespace) + if namespace.startswith(self.scope): + self.collected[namespace, target.value] = docstring def visit_funcdef(self, node): # don't descend into functions -- nothing interesting there @@ -105,6 +105,8 @@ class PycodeError(Exception): class ModuleAnalyzer(object): + # cache for analyzer objects + cache = {} def __init__(self, tree, modname, srcname): self.tree = tree @@ -131,6 +133,8 @@ class ModuleAnalyzer(object): @classmethod def for_module(cls, modname): + if modname in cls.cache: + return cls.cache[modname] if modname not in sys.modules: try: __import__(modname) @@ -142,7 +146,9 @@ class ModuleAnalyzer(object): source = mod.__loader__.get_source(modname) except Exception, err: raise PycodeError('error getting source for %r' % modname, err) - return cls.for_string(source, modname) + obj = cls.for_string(source, modname) + cls.cache[modname] = obj + return obj filename = getattr(mod, '__file__', None) if filename is None: raise PycodeError('no source found for module %r' % modname) @@ -153,13 +159,16 @@ class ModuleAnalyzer(object): raise PycodeError('source is not a .py file: %r' % filename) if not path.isfile(filename): raise PycodeError('source file is not present: %r' % filename) - return cls.for_file(filename, modname) + obj = cls.for_file(filename, modname) + cls.cache[modname] = obj + return obj - def find_attrs(self): - attr_visitor = ClassAttrVisitor(number2name, '') + def find_attr_docs(self, scope=''): + attr_visitor = ClassAttrVisitor(number2name, scope) attr_visitor.visit(self.tree) return attr_visitor.collected + if __name__ == '__main__': x0 = time.time() ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') -- cgit v1.2.1 From 7124a1e1760c7704a555b2eda54d1970783b1d56 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 02:26:47 +0100 Subject: Also find attribute docs in the "other" style: docstrings after the assignment. --- sphinx/pycode/__init__.py | 75 ++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 61 insertions(+), 14 deletions(-) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index 0d4058bd..f4bd1b1d 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -14,7 +14,7 @@ import time from os import path from sphinx.pycode import pytree -from sphinx.pycode.pgen2 import driver, token, parse +from sphinx.pycode.pgen2 import driver, token, parse, literals # load the Python grammar @@ -46,13 +46,42 @@ def prepare_commentdoc(s): return result +def prepare_literaldoc(s): + # first, "evaluate" the string + s = literals.evalString(s) + # then, prepare (XXX copied from ext/autodoc) + lines = s.expandtabs().splitlines() + # Find minimum indentation of any non-blank lines after first line. + margin = sys.maxint + for line in lines[1:]: + content = len(line.lstrip()) + if content: + indent = len(line) - content + margin = min(margin, indent) + # Remove indentation. + if lines: + lines[0] = lines[0].lstrip() + if margin < sys.maxint: + for i in range(1, len(lines)): lines[i] = lines[i][margin:] + # Remove any leading blank lines. + while lines and not lines[0]: + lines.pop(0) + # make sure there is an empty line at the end + if lines and lines[-1]: + lines.append('') + return lines + + _eq = pytree.Leaf(token.EQUAL, '=') -class ClassAttrVisitor(pytree.NodeVisitor): +class AttrDocVisitor(pytree.NodeVisitor): """ - Visitor that collects comments appearing before attribute assignments - on toplevel and in classes. + Visitor that collects docstrings for attribute assignments on toplevel and + in classes. + + The docstrings can either be in special '#:' comments before the assignment + or in a docstring after it. """ def init(self, scope): self.scope = scope @@ -65,6 +94,7 @@ class ClassAttrVisitor(pytree.NodeVisitor): self.namespace.pop() def visit_expr_stmt(self, node): + """Visit an assignment which may have a special comment before it.""" if _eq not in node.children: # not an assignment (we don't care for augmented assignments) return @@ -79,8 +109,27 @@ class ClassAttrVisitor(pytree.NodeVisitor): break prefix = pnode.get_prefix() docstring = prepare_commentdoc(prefix) - if not docstring: + if docstring: + self.add_docstring(node, docstring) + + def visit_simple_stmt(self, node): + """Visit a docstring statement which may have an assignment before.""" + if node[0].type != token.STRING: + # not a docstring; but still need to visit children + return self.generic_visit(node) + prev = node.get_prev_sibling() + if not prev: return + if prev.type == sym.simple_stmt and \ + prev[0].type == sym.expr_stmt and _eq in prev[0].children: + docstring = prepare_literaldoc(node[0].value) + self.add_docstring(prev[0], docstring) + + def visit_funcdef(self, node): + # don't descend into functions -- nothing interesting there + return + + def add_docstring(self, node, docstring): # add an item for each assignment target for i in range(0, len(node) - 1, 2): target = node[i] @@ -91,10 +140,6 @@ class ClassAttrVisitor(pytree.NodeVisitor): if namespace.startswith(self.scope): self.collected[namespace, target.value] = docstring - def visit_funcdef(self, node): - # don't descend into functions -- nothing interesting there - return - class PycodeError(Exception): def __str__(self): @@ -164,17 +209,19 @@ class ModuleAnalyzer(object): return obj def find_attr_docs(self, scope=''): - attr_visitor = ClassAttrVisitor(number2name, scope) + attr_visitor = AttrDocVisitor(number2name, scope) attr_visitor.visit(self.tree) return attr_visitor.collected if __name__ == '__main__': x0 = time.time() - ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') + #ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') + ma = ModuleAnalyzer.for_file(__file__.rstrip('c'), 'sphinx.builders.html') x1 = time.time() - for name, doc in ma.find_attrs(): - print '>>', name - print doc + for (ns, name), doc in ma.find_attr_docs().iteritems(): + print '>>', ns, name + print '\n'.join(doc) x2 = time.time() + #print pytree.nice_repr(ma.tree, number2name) print "parsing %.4f, finding %.4f" % (x1-x0, x2-x1) -- cgit v1.2.1 From 47cf3c5630c790fff8b52e9c0350d47a067094cc Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 02:37:01 +0100 Subject: Ignore .so files. --- .hgignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.hgignore b/.hgignore index 37589422..99fc8d87 100644 --- a/.hgignore +++ b/.hgignore @@ -1,5 +1,6 @@ .*\.pyc .*\.egg +.*\.so build/ dist/ sphinx/pycode/Grammar.*pickle -- cgit v1.2.1 From 6bec10bbcf957d4a26dc5b3db2f4a099382abf56 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 02:37:20 +0100 Subject: Move docstring processing to an util module. --- sphinx/ext/autodoc.py | 30 +------------------------ sphinx/pycode/__init__.py | 51 +++++------------------------------------- sphinx/util/docstrings.py | 56 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 63 insertions(+), 74 deletions(-) create mode 100644 sphinx/util/docstrings.py diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index ddea1e44..55f0d58f 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -23,6 +23,7 @@ from docutils.statemachine import ViewList from sphinx.util import rpartition, nested_parse_with_titles from sphinx.pycode import ModuleAnalyzer, PycodeError +from sphinx.util.docstrings import prepare_docstring clstypes = (type, ClassType) try: @@ -172,35 +173,6 @@ def isdescriptor(x): return False -def prepare_docstring(s): - """ - Convert a docstring into lines of parseable reST. Return it as a list of - lines usable for inserting into a docutils ViewList (used as argument - of nested_parse().) An empty line is added to act as a separator between - this docstring and following content. - """ - lines = s.expandtabs().splitlines() - # Find minimum indentation of any non-blank lines after first line. - margin = sys.maxint - for line in lines[1:]: - content = len(line.lstrip()) - if content: - indent = len(line) - content - margin = min(margin, indent) - # Remove indentation. - if lines: - lines[0] = lines[0].lstrip() - if margin < sys.maxint: - for i in range(1, len(lines)): lines[i] = lines[i][margin:] - # Remove any leading blank lines. - while lines and not lines[0]: - lines.pop(0) - # make sure there is an empty line at the end - if lines and lines[-1]: - lines.append('') - return lines - - def get_module_charset(module): """Return the charset of the given module (cached in _module_charsets).""" if module in _module_charsets: diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index f4bd1b1d..e52a231d 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -10,11 +10,11 @@ """ import sys -import time from os import path from sphinx.pycode import pytree from sphinx.pycode.pgen2 import driver, token, parse, literals +from sphinx.util.docstrings import prepare_docstring, prepare_commentdoc # load the Python grammar @@ -31,47 +31,6 @@ number2name = pygrammar.number2symbol.copy() number2name.update(token.tok_name) -def prepare_commentdoc(s): - """ - Extract documentation comment lines (starting with #:) and return them as a - list of lines. Returns an empty list if there is no documentation. - """ - result = [] - lines = [line.strip() for line in s.expandtabs().splitlines()] - for line in lines: - if line.startswith('#: '): - result.append(line[3:]) - if result and result[-1]: - result.append('') - return result - - -def prepare_literaldoc(s): - # first, "evaluate" the string - s = literals.evalString(s) - # then, prepare (XXX copied from ext/autodoc) - lines = s.expandtabs().splitlines() - # Find minimum indentation of any non-blank lines after first line. - margin = sys.maxint - for line in lines[1:]: - content = len(line.lstrip()) - if content: - indent = len(line) - content - margin = min(margin, indent) - # Remove indentation. - if lines: - lines[0] = lines[0].lstrip() - if margin < sys.maxint: - for i in range(1, len(lines)): lines[i] = lines[i][margin:] - # Remove any leading blank lines. - while lines and not lines[0]: - lines.pop(0) - # make sure there is an empty line at the end - if lines and lines[-1]: - lines.append('') - return lines - - _eq = pytree.Leaf(token.EQUAL, '=') @@ -122,7 +81,8 @@ class AttrDocVisitor(pytree.NodeVisitor): return if prev.type == sym.simple_stmt and \ prev[0].type == sym.expr_stmt and _eq in prev[0].children: - docstring = prepare_literaldoc(node[0].value) + # need to "eval" the string because it's returned in its original form + docstring = prepare_docstring(literals.evalString(node[0].value)) self.add_docstring(prev[0], docstring) def visit_funcdef(self, node): @@ -215,9 +175,10 @@ class ModuleAnalyzer(object): if __name__ == '__main__': + import time x0 = time.time() - #ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') - ma = ModuleAnalyzer.for_file(__file__.rstrip('c'), 'sphinx.builders.html') + ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') + #ma = ModuleAnalyzer.for_file(__file__.rstrip('c'), 'sphinx.builders.html') x1 = time.time() for (ns, name), doc in ma.find_attr_docs().iteritems(): print '>>', ns, name diff --git a/sphinx/util/docstrings.py b/sphinx/util/docstrings.py new file mode 100644 index 00000000..d7e20e4c --- /dev/null +++ b/sphinx/util/docstrings.py @@ -0,0 +1,56 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.docstrings + ~~~~~~~~~~~~~~~~~~~~~~ + + Utilities for docstring processing. + + :copyright: 2008 by Georg Brandl. + :license: BSD, see LICENSE for details. +""" + +import sys + + +def prepare_docstring(s): + """ + Convert a docstring into lines of parseable reST. Return it as a list of + lines usable for inserting into a docutils ViewList (used as argument + of nested_parse().) An empty line is added to act as a separator between + this docstring and following content. + """ + lines = s.expandtabs().splitlines() + # Find minimum indentation of any non-blank lines after first line. + margin = sys.maxint + for line in lines[1:]: + content = len(line.lstrip()) + if content: + indent = len(line) - content + margin = min(margin, indent) + # Remove indentation. + if lines: + lines[0] = lines[0].lstrip() + if margin < sys.maxint: + for i in range(1, len(lines)): lines[i] = lines[i][margin:] + # Remove any leading blank lines. + while lines and not lines[0]: + lines.pop(0) + # make sure there is an empty line at the end + if lines and lines[-1]: + lines.append('') + return lines + + +def prepare_commentdoc(s): + """ + Extract documentation comment lines (starting with #:) and return them as a + list of lines. Returns an empty list if there is no documentation. + """ + result = [] + lines = [line.strip() for line in s.expandtabs().splitlines()] + for line in lines: + if line.startswith('#: '): + result.append(line[3:]) + if result and result[-1]: + result.append('') + return result -- cgit v1.2.1 From 998660e41e99b171d029a0e6aa7b85fc0ba62373 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 12:42:26 +0100 Subject: * Add a tag-finding method based on tokens. * Don't parse immediately if tokenizing suffices. * Also cache by file name. --- sphinx/pycode/__init__.py | 139 +++++++++++++++++++++++++++++++++--------- sphinx/pycode/pgen2/driver.py | 18 +++--- 2 files changed, 118 insertions(+), 39 deletions(-) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index e52a231d..f456cfe6 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -11,9 +11,10 @@ import sys from os import path +from cStringIO import StringIO from sphinx.pycode import pytree -from sphinx.pycode.pgen2 import driver, token, parse, literals +from sphinx.pycode.pgen2 import driver, token, tokenize, parse, literals from sphinx.util.docstrings import prepare_docstring, prepare_commentdoc @@ -22,9 +23,12 @@ _grammarfile = path.join(path.dirname(__file__), 'Grammar.txt') pygrammar = driver.load_grammar(_grammarfile) pydriver = driver.Driver(pygrammar, convert=pytree.convert) +# an object with attributes corresponding to token and symbol names class sym: pass for k, v in pygrammar.symbol2number.iteritems(): setattr(sym, k, v) +for k, v in token.tok_name.iteritems(): + setattr(sym, v, k) # a dict mapping terminal and nonterminal numbers to their names number2name = pygrammar.number2symbol.copy() @@ -110,36 +114,29 @@ class PycodeError(Exception): class ModuleAnalyzer(object): - # cache for analyzer objects + # cache for analyzer objects -- caches both by module and file name cache = {} - def __init__(self, tree, modname, srcname): - self.tree = tree - self.modname = modname - self.srcname = srcname - @classmethod def for_string(cls, string, modname, srcname=''): - return cls(pydriver.parse_string(string), modname, srcname) + return cls(StringIO(string), modname, srcname) @classmethod def for_file(cls, filename, modname): + if ('file', filename) in cls.cache: + return cls.cache['file', filename] try: fileobj = open(filename, 'r') except Exception, err: raise PycodeError('error opening %r' % filename, err) - try: - try: - return cls(pydriver.parse_stream(fileobj), modname, filename) - except parse.ParseError, err: - raise PycodeError('error parsing %r' % filename, err) - finally: - fileobj.close() + obj = cls(fileobj, modname, filename) + cls.cache['file', filename] = obj + return obj @classmethod def for_module(cls, modname): - if modname in cls.cache: - return cls.cache[modname] + if ('module', modname) in cls.cache: + return cls.cache['module', modname] if modname not in sys.modules: try: __import__(modname) @@ -152,37 +149,119 @@ class ModuleAnalyzer(object): except Exception, err: raise PycodeError('error getting source for %r' % modname, err) obj = cls.for_string(source, modname) - cls.cache[modname] = obj + cls.cache['module', modname] = obj return obj filename = getattr(mod, '__file__', None) if filename is None: raise PycodeError('no source found for module %r' % modname) - if filename.lower().endswith('.pyo') or \ - filename.lower().endswith('.pyc'): + filename = path.normpath(filename) + lfilename = filename.lower() + if lfilename.endswith('.pyo') or lfilename.endswith('.pyc'): filename = filename[:-1] - elif not filename.lower().endswith('.py'): + elif not lfilename.endswith('.py'): raise PycodeError('source is not a .py file: %r' % filename) if not path.isfile(filename): raise PycodeError('source file is not present: %r' % filename) obj = cls.for_file(filename, modname) - cls.cache[modname] = obj + cls.cache['module', modname] = obj return obj + def __init__(self, source, modname, srcname): + self.modname = modname + self.srcname = srcname + # file-like object yielding source lines + self.source = source + + # will be filled by tokenize() + self.tokens = None + # will be filled by parse() + self.parsetree = None + + def tokenize(self): + """Generate tokens from the source.""" + if self.tokens is not None: + return + self.tokens = list(tokenize.generate_tokens(self.source.readline)) + self.source.close() + + def parse(self): + """Parse the generated source tokens.""" + if self.parsetree is not None: + return + self.tokenize() + self.parsetree = pydriver.parse_tokens(self.tokens) + def find_attr_docs(self, scope=''): + """Find class and module-level attributes and their documentation.""" + self.parse() attr_visitor = AttrDocVisitor(number2name, scope) - attr_visitor.visit(self.tree) + attr_visitor.visit(self.parsetree) return attr_visitor.collected + def find_tags(self): + """Find class, function and method definitions and their location.""" + self.tokenize() + result = {} + namespace = [] + stack = [] + indent = 0 + defline = False + expect_indent = False + def tokeniter(ignore = (token.COMMENT, token.NL)): + for tokentup in self.tokens: + if tokentup[0] not in ignore: + yield tokentup + tokeniter = tokeniter() + for type, tok, spos, epos, line in tokeniter: + if expect_indent: + if type != token.INDENT: + # no suite -- one-line definition + assert stack + dtype, fullname, startline, _ = stack.pop() + endline = epos[0] + namespace.pop() + result[dtype, fullname] = (startline, endline) + expect_indent = False + if tok in ('def', 'class'): + name = tokeniter.next()[1] + namespace.append(name) + fullname = '.'.join(namespace) + stack.append((tok, fullname, spos[0], indent)) + defline = True + elif type == token.INDENT: + expect_indent = False + indent += 1 + elif type == token.DEDENT: + indent -= 1 + # if the stacklevel is the same as it was before the last def/class block, + # this dedent closes that block + if stack and indent == stack[-1][3]: + dtype, fullname, startline, _ = stack.pop() + endline = spos[0] + namespace.pop() + result[dtype, fullname] = (startline, endline) + elif type == token.NEWLINE: + # if this line contained a definition, expect an INDENT to start the + # suite; if there is no such INDENT it's a one-line definition + if defline: + defline = False + expect_indent = True + return result + if __name__ == '__main__': - import time + import time, pprint x0 = time.time() - ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') #ma = ModuleAnalyzer.for_file(__file__.rstrip('c'), 'sphinx.builders.html') + ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') + ma.tokenize() x1 = time.time() - for (ns, name), doc in ma.find_attr_docs().iteritems(): - print '>>', ns, name - print '\n'.join(doc) + ma.parse() x2 = time.time() - #print pytree.nice_repr(ma.tree, number2name) - print "parsing %.4f, finding %.4f" % (x1-x0, x2-x1) + #for (ns, name), doc in ma.find_attr_docs().iteritems(): + # print '>>', ns, name + # print '\n'.join(doc) + pprint.pprint(ma.find_tags()) + x3 = time.time() + #print pytree.nice_repr(ma.parsetree, number2name) + print "tokenizing %.4f, parsing %.4f, finding %.4f" % (x1-x0, x2-x1, x3-x2) diff --git a/sphinx/pycode/pgen2/driver.py b/sphinx/pycode/pgen2/driver.py index 3e9e1043..edc882fa 100644 --- a/sphinx/pycode/pgen2/driver.py +++ b/sphinx/pycode/pgen2/driver.py @@ -42,8 +42,8 @@ class Driver(object): column = 0 type = value = start = end = line_text = None prefix = "" - for quintuple in tokens: - type, value, start, end, line_text = quintuple + opmap = grammar.opmap + for type, value, start, end, line_text in tokens: if start != (lineno, column): assert (lineno, column) <= start, ((lineno, column), start) s_lineno, s_column = start @@ -62,13 +62,13 @@ class Driver(object): column = 0 continue if type == token.OP: - type = grammar.opmap[value] - if debug: - self.logger.debug("%s %r (prefix=%r)", - token.tok_name[type], value, prefix) + type = opmap[value] + # if debug: + # self.logger.debug("%s %r (prefix=%r)", + # token.tok_name[type], value, prefix) if p.addtoken(type, value, (prefix, start)): - if debug: - self.logger.debug("Stop.") + # if debug: + # self.logger.debug("Stop.") break prefix = "" lineno, column = end @@ -77,7 +77,7 @@ class Driver(object): column = 0 else: # We never broke out -- EOF is too soon (how can this happen???) - raise parse.ParseError("incomplete input", t, v, x) + raise parse.ParseError("incomplete input", type, value, line_text) return p.rootnode def parse_stream_raw(self, stream, debug=False): -- cgit v1.2.1 From 2cfbedc3766a17d9991589f482eadc76e4b3d687 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 15:41:21 +0100 Subject: Add "object" option to literalinclude directive. --- sphinx/directives/code.py | 50 +++++++++++++++++++++++++++++++++-------------- sphinx/pycode/__init__.py | 4 ++-- 2 files changed, 37 insertions(+), 17 deletions(-) diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index b4364535..7ac9a1c3 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -68,32 +68,52 @@ def literalinclude_directive(name, arguments, options, content, lineno, lineno - state_machine.input_offset - 1))) fn = path.normpath(path.join(source_dir, rel_fn)) + fromline = toline = None + objectname = options.get('object') + if objectname is not None: + from sphinx.pycode import ModuleAnalyzer + analyzer = ModuleAnalyzer.for_file(fn, '') + tags = analyzer.find_tags() + if objectname not in tags: + return [state.document.reporter.warning( + 'Object named %r not found in include file %r' % + (objectname, arguments[0]), line=lineno)] + else: + fromline = tags[objectname][1] - 1 + toline = tags[objectname][2] - 1 + encoding = options.get('encoding', env.config.source_encoding) try: f = codecs.open(fn, 'r', encoding) - text = f.read() + lines = f.readlines() f.close() except (IOError, OSError): - retnode = state.document.reporter.warning( - 'Include file %r not found or reading it failed' % arguments[0], line=lineno) + return [state.document.reporter.warning( + 'Include file %r not found or reading it failed' % arguments[0], + line=lineno)] except UnicodeError: - retnode = state.document.reporter.warning( + return [state.document.reporter.warning( 'Encoding %r used for reading included file %r seems to ' 'be wrong, try giving an :encoding: option' % - (encoding, arguments[0])) - else: - retnode = nodes.literal_block(text, text, source=fn) - retnode.line = 1 - if options.get('language', ''): - retnode['language'] = options['language'] - if 'linenos' in options: - retnode['linenos'] = True - state.document.settings.env.note_dependency(rel_fn) + (encoding, arguments[0]))] + text = ''.join(lines[fromline:toline]) + retnode = nodes.literal_block(text, text, source=fn) + retnode.line = 1 + if options.get('language', ''): + retnode['language'] = options['language'] + if 'linenos' in options: + retnode['linenos'] = True + state.document.settings.env.note_dependency(rel_fn) return [retnode] literalinclude_directive.options = {'linenos': directives.flag, - 'language': directives.unchanged, - 'encoding': directives.encoding} + 'language': directives.unchanged_required, + 'encoding': directives.encoding, + 'object': directives.unchanged_required, + #'lines': directives.unchanged_required, + #'start-after': directives.unchanged_required, + #'end-before': directives.unchanged_required, + } literalinclude_directive.content = 0 literalinclude_directive.arguments = (1, 0, 0) directives.register_directive('literalinclude', literalinclude_directive) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index f456cfe6..a61208d5 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -220,7 +220,7 @@ class ModuleAnalyzer(object): dtype, fullname, startline, _ = stack.pop() endline = epos[0] namespace.pop() - result[dtype, fullname] = (startline, endline) + result[fullname] = (dtype, startline, endline) expect_indent = False if tok in ('def', 'class'): name = tokeniter.next()[1] @@ -239,7 +239,7 @@ class ModuleAnalyzer(object): dtype, fullname, startline, _ = stack.pop() endline = spos[0] namespace.pop() - result[dtype, fullname] = (startline, endline) + result[fullname] = (dtype, startline, endline) elif type == token.NEWLINE: # if this line contained a definition, expect an INDENT to start the # suite; if there is no such INDENT it's a one-line definition -- cgit v1.2.1 From c9d52ded703813ca16c75702bd18b9fcbd2e751d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 15:45:02 +0100 Subject: Rename "object" to "pyobject" and document it. --- doc/markup/code.rst | 12 ++++++++++++ sphinx/directives/code.py | 4 ++-- 2 files changed, 14 insertions(+), 2 deletions(-) diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 299ab0bc..2fd51c84 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -113,8 +113,20 @@ Includes .. literalinclude:: example.py :encoding: latin-1 + The directive also supports including only parts of the file. If it is a + Python module, you can select a class, function or method to include using + the ``pyobject`` option:: + + .. literalinclude:: example.py + :pyobject: Timer.start + + This would only include the code lines belonging to the ``start()`` method in + the ``Timer`` class within the file. + .. versionadded:: 0.4.3 The ``encoding`` option. + .. versionadded:: 0.6 + The ``pyobject`` option. .. rubric:: Footnotes diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 7ac9a1c3..cc74566d 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -69,7 +69,7 @@ def literalinclude_directive(name, arguments, options, content, lineno, fn = path.normpath(path.join(source_dir, rel_fn)) fromline = toline = None - objectname = options.get('object') + objectname = options.get('pyobject') if objectname is not None: from sphinx.pycode import ModuleAnalyzer analyzer = ModuleAnalyzer.for_file(fn, '') @@ -109,7 +109,7 @@ def literalinclude_directive(name, arguments, options, content, lineno, literalinclude_directive.options = {'linenos': directives.flag, 'language': directives.unchanged_required, 'encoding': directives.encoding, - 'object': directives.unchanged_required, + 'pyobject': directives.unchanged_required, #'lines': directives.unchanged_required, #'start-after': directives.unchanged_required, #'end-before': directives.unchanged_required, -- cgit v1.2.1 From c80f5f2c0969541faace962382011192dbf1fda2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 30 Dec 2008 23:02:47 +0100 Subject: Update Czech locale. --- sphinx/locale/cs/LC_MESSAGES/sphinx.js | 2 +- sphinx/locale/cs/LC_MESSAGES/sphinx.mo | Bin 7500 -> 9018 bytes sphinx/locale/cs/LC_MESSAGES/sphinx.po | 328 ++++++++++++++++----------------- 3 files changed, 161 insertions(+), 169 deletions(-) diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.js b/sphinx/locale/cs/LC_MESSAGES/sphinx.js index 4b814e4f..0684899d 100644 --- a/sphinx/locale/cs/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "cs", "plural_expr": "(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"module, in ": "modul", "Preparing search...": "", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "", "Search finished, found %s page(s) matching the search query.": "", ", in ": "", "Permalink to this headline": "Trval\u00fd odkaz na tento nadpis", "Searching": "hledej", "Permalink to this definition": "Trval\u00fd odkaz na tuto definici", "Hide Search Matches": "", "Search Results": "V\u00fdsledky hled\u00e1n\u00ed"}}); \ No newline at end of file +Documentation.addTranslations({"locale": "cs", "plural_expr": "(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"module, in ": "modul, v", "Preparing search...": "Připravuji hledání...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Nenalezli jsme žádný dokument. Ujistěte se prosím, že všechna slova jsou správně.", "Search finished, found %s page(s) matching the search query.": "Vyhledávání skončilo, nalezeno %s stran.", ", in ": ", v", "Permalink to this headline": "Trvalý odkaz na tento nadpis", "Searching": "Hledám", "Permalink to this definition": "Trvalý odkaz na tuto definici", "Hide Search Matches": "Skrýt výsledky hledání", "Search Results": "Výsledky hledání"}}); diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo index c50de3db..fd97a57e 100644 Binary files a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo and b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.po b/sphinx/locale/cs/LC_MESSAGES/sphinx.po index 758a4ff3..0d11dded 100644 --- a/sphinx/locale/cs/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.po @@ -7,41 +7,108 @@ msgid "" msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2008-08-10 11:43+0000\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"POT-Creation-Date: 2008-11-27 18:39+0100\n" +"PO-Revision-Date: 2008-12-25 05:59+0100\n" "Last-Translator: Pavel Kosina \n" "Language-Team: Pavel Kosina \n" -"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " -"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n" "MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=utf-8\n" +"Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" -"Generated-By: Babel 0.9.3\n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n" +"Generated-By: Babel 0.9.4\n" +"X-Poedit-Language: Czech\n" +"X-Poedit-Country: CZECH REPUBLIC\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/builder.py:408 +#, python-format +msgid "%b %d, %Y" +msgstr "%d.%m.%Y" + +#: sphinx/builder.py:427 +#: sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Rejstřík indexů" + +#: sphinx/builder.py:427 +msgid "index" +msgstr "index" + +#: sphinx/builder.py:429 +#: sphinx/htmlhelp.py:156 +#: sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 +#: sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Celkový rejstřík modulů" + +#: sphinx/builder.py:429 +msgid "modules" +msgstr "moduly" + +#: sphinx/builder.py:466 +msgid "next" +msgstr "další" + +#: sphinx/builder.py:473 +msgid "previous" +msgstr "předchozí" + +#: sphinx/builder.py:1054 +msgid " (in " +msgstr "(v" + +#: sphinx/builder.py:1129 +msgid "Builtins" +msgstr "Vestavěné funkce " + +#: sphinx/builder.py:1131 +msgid "Module level" +msgstr "Úroveň modulů" + +#: sphinx/environment.py:102 +#: sphinx/latexwriter.py:169 #, python-format msgid "%B %d, %Y" msgstr "%d.%m.%Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:291 +#: sphinx/latexwriter.py:175 +#: sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 -#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 -#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/genindex-split.html:5 +#: sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 +#: sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:130 msgid "Index" msgstr "Index" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 -#, fuzzy +#: sphinx/environment.py:292 +#: sphinx/latexwriter.py:174 msgid "Module Index" -msgstr "Rejstřík modulů" +msgstr "Rejstřík modulů " -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 -#, fuzzy +#: sphinx/environment.py:293 +#: sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Vyhledávací stránka" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/htmlwriter.py:79 +#: sphinx/static/doctools.js:145 +msgid "Permalink to this definition" +msgstr "Trvalý odkaz na tuto definici" + +#: sphinx/htmlwriter.py:399 +#: sphinx/static/doctools.js:139 +msgid "Permalink to this headline" +msgstr "Trvalý odkaz na tento nadpis" + +#: sphinx/latexwriter.py:172 +msgid "Release" +msgstr "Vydání" + +#: sphinx/roles.py:53 +#: sphinx/directives/desc.py:537 #, python-format msgid "environment variable; %s" msgstr "promměná prostředí, %s" @@ -51,55 +118,22 @@ msgstr "promměná prostředí, %s" msgid "Python Enhancement Proposals!PEP %s" msgstr "Python Enhancement Proposals!PEP %s" -#: sphinx/builders/changes.py:64 -msgid "Builtins" -msgstr "Vestavěné funkce" - -#: sphinx/builders/changes.py:66 -msgid "Module level" -msgstr "Úroveň modulů" - -#: sphinx/builders/html.py:115 +#: sphinx/textwriter.py:166 #, python-format -msgid "%b %d, %Y" -msgstr "%d.%m.%Y" - -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "Rejstřík indexů" - -#: sphinx/builders/html.py:134 -msgid "index" -msgstr "index" - -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 -#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "Rejstřík modulů" - -#: sphinx/builders/html.py:136 -msgid "modules" -msgstr "moduly" - -#: sphinx/builders/html.py:175 -msgid "next" -msgstr "další" - -#: sphinx/builders/html.py:182 -msgid "previous" -msgstr "předchozí" +msgid "Platform: %s" +msgstr "Platforma: %s" -#: sphinx/builders/latex.py:155 -msgid " (in " -msgstr "" +#: sphinx/textwriter.py:422 +msgid "[image]" +msgstr "[obrázek]" #: sphinx/directives/desc.py:25 #, python-format msgid "%s() (built-in function)" msgstr "%s() (vestavěná funkce)" -#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:26 +#: sphinx/directives/desc.py:42 #: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" @@ -110,15 +144,16 @@ msgstr "%s() (v modulu %s)" msgid "%s (built-in variable)" msgstr "%s() (vestavěná proměnná)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 +#: sphinx/directives/desc.py:66 #, python-format msgid "%s (in module %s)" msgstr "%s() (v modulu %s)" #: sphinx/directives/desc.py:33 -#, fuzzy, python-format +#, python-format msgid "%s (built-in class)" -msgstr "%s() (vestavěná proměnná)" +msgstr "%s () (vestavěná proměnná)" #: sphinx/directives/desc.py:34 #, python-format @@ -196,19 +231,14 @@ msgstr "Vrací" msgid "Return type" msgstr "Typ navrácené hodnoty" -#: sphinx/directives/desc.py:201 -#, fuzzy -msgid "Parameter" -msgstr "Parametry" - -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:143 msgid "Parameters" msgstr "Parametry" -#: sphinx/directives/desc.py:450 -#, fuzzy, python-format +#: sphinx/directives/desc.py:423 +#, python-format msgid "%scommand line option; %s" -msgstr "%sparametry příkazového řádku; %s" +msgstr "%s parametry příkazového řádku; %s" #: sphinx/directives/other.py:101 msgid "Platforms: " @@ -231,27 +261,22 @@ msgstr "Autor modulu: " msgid "Author: " msgstr "Autor: " -#: sphinx/directives/other.py:249 +#: sphinx/directives/other.py:246 msgid "See also" msgstr "Viz také" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 -#, python-format -msgid "alias of :class:`%s`" -msgstr "" - #: sphinx/ext/todo.py:31 msgid "Todo" -msgstr "" +msgstr "Todo" #: sphinx/ext/todo.py:75 #, python-format msgid "(The original entry is located in %s, line %d and can be found " -msgstr "" +msgstr "(Původní záznam je v %s, řádka %d a lze jej nalézt" #: sphinx/ext/todo.py:81 msgid "here" -msgstr "" +msgstr "zde" #: sphinx/locale/__init__.py:15 msgid "Attention" @@ -336,50 +361,39 @@ msgstr "příkaz" msgid "built-in function" msgstr "vestavěná funkce" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 -msgid "Permalink to this headline" -msgstr "Trvalý odkaz na tento nadpis" - -#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 -msgid "Permalink to this definition" -msgstr "Trvalý odkaz na tuto definici" - #: sphinx/static/doctools.js:174 msgid "Hide Search Matches" -msgstr "" +msgstr "Skrýt výsledky vyhledávání" #: sphinx/static/searchtools.js:274 -#, fuzzy msgid "Searching" -msgstr "hledej" +msgstr "Hledám" #: sphinx/static/searchtools.js:279 msgid "Preparing search..." -msgstr "" +msgstr "Připravuji vyhledávání...." #: sphinx/static/searchtools.js:338 -#, fuzzy msgid "module, in " -msgstr "modul" +msgstr "modul, v" #: sphinx/static/searchtools.js:347 msgid ", in " -msgstr "" +msgstr ", v" -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:447 +#: sphinx/templates/search.html:18 msgid "Search Results" msgstr "Výsledky hledání" -#: sphinx/static/searchtools.js:455 -msgid "" -"Your search did not match any documents. Please make sure that all words " -"are spelled correctly and that you've selected enough categories." -msgstr "" +#: sphinx/static/searchtools.js:449 +msgid "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." +msgstr "Nenalezli jsme žádný dokument. Ujistěte se prosím, že všechna slova jsou správně a že jste vybral dostatek kategorií." -#: sphinx/static/searchtools.js:457 +#: sphinx/static/searchtools.js:451 #, python-format msgid "Search finished, found %s page(s) matching the search query." -msgstr "" +msgstr "Vyhledávání skončilo, nalezeno %s stran." #: sphinx/templates/defindex.html:2 msgid "Overview" @@ -416,7 +430,8 @@ msgstr "Index – %(key)s" #: sphinx/templates/genindex-single.html:44 #: sphinx/templates/genindex-split.html:14 -#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +#: sphinx/templates/genindex-split.html:27 +#: sphinx/templates/genindex.html:54 msgid "Full index on one page" msgstr "Plný index na jedné stránce" @@ -452,70 +467,83 @@ msgstr "Další téma" msgid "next chapter" msgstr "další kapitola" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:55 msgid "This Page" msgstr "Tato stránka" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:59 +msgid "Suggest Change" +msgstr "Návrh změnu" + +#: sphinx/templates/layout.html:60 +#: sphinx/templates/layout.html:62 msgid "Show Source" msgstr "Ukázat zdroj" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Rychlé vyhledávání" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:71 +msgid "Keyword search" +msgstr "Hledání dle klíče" + +#: sphinx/templates/layout.html:73 msgid "Go" msgstr "hledej" -#: sphinx/templates/layout.html:73 -#, fuzzy -msgid "Enter search terms or a module, class or function name." +#: sphinx/templates/layout.html:78 +msgid "Enter a module, class or function name." msgstr "Zadej jméno modulu, třídy nebo funkce." -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:119 #, python-format msgid "Search within %(docstitle)s" msgstr "Hledání uvnitř %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:128 msgid "About these documents" msgstr "O těchto dokumentech" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:131 +#: sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Hledání" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:133 msgid "Copyright" msgstr "Veškerá práva vyhrazena" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:178 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:180 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:183 #, python-format msgid "Last updated on %(last_updated)s." -msgstr "Naposledy aktualizováno dne %(last_updated)s." +msgstr "Aktualizováno dne %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:186 #, python-format -msgid "" -"Created using Sphinx " -"%(sphinx_version)s." -msgstr "" -"Vytvořeno pomocí Sphinx " -"%(sphinx_version)s." +msgid "Created using Sphinx %(sphinx_version)s." +msgstr "Vytvořeno pomocí Sphinx %(sphinx_version)s." -#: sphinx/templates/modindex.html:36 +#: sphinx/templates/modindex.html:15 +msgid "Most popular modules:" +msgstr "Nejpopulárnější moduly:" + +#: sphinx/templates/modindex.html:24 +msgid "Show modules only available on these platforms" +msgstr "Zobrazit moduly dostupné na této platformě" + +#: sphinx/templates/modindex.html:56 msgid "Deprecated" msgstr "Zastaralé" @@ -524,18 +552,19 @@ msgstr "Zastaralé" msgid "Search %(docstitle)s" msgstr "Prohledat %(docstitle)s" +#: sphinx/templates/page.html:8 +msgid "Note: You requested an out-of-date URL from this server. We've tried to redirect you to the new location of this page, but it may not be the right one." +msgstr "Poznámka: Stránka, kterou hledáte, neexistuje.
    Snažili jsme se najít nové umístění této stránky, ale nepovedlo se." + #: sphinx/templates/search.html:7 -#, fuzzy msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" " containing fewer words won't appear in the result list." msgstr "" -"Toto je vyhledávací stránka. Zadejte klíčová slova do pole níže a " -"klikněte na \"hledej\". \n" -"Prohledávání funkcí hledá automaticky všechna slova. Stránky obsahující" -" slov méně, nebudou nalezeny." +"Toto je vyhledávací stránka. Zadejte klíčová slova a klikněte na \"hledej\". \n" +"Vyhledávání hledá automaticky všechna slova. Nebudou tedy nalezeny stránky, obsahující méně slov." #: sphinx/templates/search.html:14 msgid "search" @@ -573,40 +602,3 @@ msgstr "Změny API" msgid "Other changes" msgstr "Ostatní změny" -#: sphinx/writers/latex.py:173 -msgid "Release" -msgstr "Vydání" - -#: sphinx/writers/text.py:166 -#, python-format -msgid "Platform: %s" -msgstr "Platforma: %s" - -#: sphinx/writers/text.py:427 -msgid "[image]" -msgstr "[obrázek]" - -#~ msgid "Suggest Change" -#~ msgstr "Návrh změnu" - -#~ msgid "Keyword search" -#~ msgstr "Hledání dle klíče" - -#~ msgid "Most popular modules:" -#~ msgstr "Nejpopulárnější moduly:" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "Zobrazit moduly dostupné na této platformě" - -#~ msgid "" -#~ "Note: You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "Poznámka: Stránka, kterou hledáte," -#~ " neexistuje.
    Snažili jsme se najít nové" -#~ " umístění této stránky, ale nepovedlo " -#~ "se." - -- cgit v1.2.1 From 60a2cb5719f8d03d7ce425a696cb7cf1c49298ae Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 31 Dec 2008 00:21:19 +0100 Subject: Add WFront. --- EXAMPLES | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/EXAMPLES b/EXAMPLES index 6b61ec04..1fef388e 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -22,6 +22,7 @@ included, please mail to `the Google group * Matplotlib: http://matplotlib.sourceforge.net/ * Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi * Mixin.com: http://dev.mixin.com/ +* mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html * NetworkX: http://networkx.lanl.gov/ * NumPy: http://docs.scipy.org/doc/numpy/reference/ * ObjectListView: http://objectlistview.sourceforge.net/python @@ -40,6 +41,6 @@ included, please mail to `the Google group * SymPy: http://docs.sympy.org/ * tinyTiM: http://tinytim.sourceforge.net/docs/2.0/ * TurboGears: http://turbogears.org/2.0/docs/ +* WFront: http://discorporate.us/projects/WFront/ * Zope 3: e.g. http://docs.carduner.net/z3c-tutorial/ -* mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html * zc.async: http://packages.python.org/zc.async/1.5.0/ -- cgit v1.2.1 From d9f337266f7118d7bfd80a66ee6ae10fa251f866 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Thu, 1 Jan 2009 10:33:41 -0600 Subject: add a test for detecting python console sessions --- tests/test_highlighting.py | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/tests/test_highlighting.py b/tests/test_highlighting.py index 1d16b982..c54a7c2c 100644 --- a/tests/test_highlighting.py +++ b/tests/test_highlighting.py @@ -28,6 +28,11 @@ class MyLexer(RegexLexer): ], } +class ComplainOnUnhighlighted(PygmentsBridge): + + def unhighlighted(self, source): + raise AssertionError("should highlight %r" % source) + class MyFormatter(HtmlFormatter): def format(self, tokensource, outfile): outfile.write('test') @@ -41,6 +46,18 @@ def test_add_lexer(app): ret = bridge.highlight_block('ab', 'test') assert 'ab' in ret +def test_detect_interactive(): + bridge = ComplainOnUnhighlighted('html') + blocks = [ + """ + >>> testing() + True + """, + ] + for block in blocks: + ret = bridge.highlight_block(block.lstrip(), 'python') + assert ret.startswith("
    ") + def test_set_formatter(): PygmentsBridge.html_formatter = MyFormatter try: -- cgit v1.2.1 From 45c8e6b4f22e44208206b124a685ba273df284e2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 1 Jan 2009 23:48:10 +0100 Subject: Add Python license info, add parse.c source generated by Cython. --- LICENSE | 73 +- sphinx/pycode/__init__.py | 12 +- sphinx/pycode/nodes.py | 202 +++ sphinx/pycode/pgen2/parse.c | 3261 +++++++++++++++++++++++++++++++++++++++++ sphinx/pycode/pgen2/parse.pyx | 4 +- sphinx/pycode/pytree.py | 293 ---- 6 files changed, 3537 insertions(+), 308 deletions(-) create mode 100644 sphinx/pycode/nodes.py create mode 100644 sphinx/pycode/pgen2/parse.c delete mode 100644 sphinx/pycode/pytree.py diff --git a/LICENSE b/LICENSE index fd441170..34183cb5 100644 --- a/LICENSE +++ b/LICENSE @@ -1,17 +1,19 @@ -Copyright (c) 2007-2008 by the respective authors (see AUTHORS file). -All rights reserved. +Copyright (c) 2007-2008 by the Sphinx team (see AUTHORS file). All +rights reserved. + +License for Sphinx +================== Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: - * Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. +* Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. - * Redistributions in binary form must reproduce the above - copyright notice, this list of conditions and the following - disclaimer in the documentation and/or other materials provided - with the distribution. +* Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT @@ -24,3 +26,58 @@ DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + +Licenses for incorporated software +================================== + +The pgen2 package, included in this distribution under the name +sphinx.pycode.pgen2, is available in the Python 2.6 distribution under +the PSF license agreement for Python: + +1. This LICENSE AGREEMENT is between the Python Software Foundation + ("PSF"), and the Individual or Organization ("Licensee") accessing + and otherwise using Python 2.6 software in source or binary form + and its associated documentation. + +2. Subject to the terms and conditions of this License Agreement, PSF + hereby grants Licensee a nonexclusive, royalty-free, world-wide + license to reproduce, analyze, test, perform and/or display + publicly, prepare derivative works, distribute, and otherwise use + Python 2.6 alone or in any derivative version, provided, however, + that PSF's License Agreement and PSF's notice of copyright, i.e., + "Copyright © 2001-2008 Python Software Foundation; All Rights + Reserved" are retained in Python 2.6 alone or in any derivative + version prepared by Licensee. + +3. In the event Licensee prepares a derivative work that is based on + or incorporates Python 2.6 or any part thereof, and wants to make + the derivative work available to others as provided herein, then + Licensee hereby agrees to include in any such work a brief summary + of the changes made to Python 2.6. + +4. PSF is making Python 2.6 available to Licensee on an "AS IS" basis. + PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED. BY + WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND DISCLAIMS ANY + REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS FOR ANY + PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.6 WILL NOT INFRINGE + ANY THIRD PARTY RIGHTS. + +5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON + 2.6 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS + AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON + 2.6, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY + THEREOF. + +6. This License Agreement will automatically terminate upon a material + breach of its terms and conditions. + +7. Nothing in this License Agreement shall be deemed to create any + relationship of agency, partnership, or joint venture between PSF + and Licensee. This License Agreement does not grant permission to + use PSF trademarks or trade name in a trademark sense to endorse or + promote products or services of Licensee, or any third party. + +8. By copying, installing or otherwise using Python 2.6, Licensee + agrees to be bound by the terms and conditions of this License + Agreement. diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index a61208d5..d707db2d 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -5,7 +5,7 @@ Utilities parsing and analyzing Python code. - :copyright: 2008 by Georg Brandl. + :copyright: 2008-2009 by Georg Brandl. :license: BSD, see LICENSE for details. """ @@ -13,7 +13,7 @@ import sys from os import path from cStringIO import StringIO -from sphinx.pycode import pytree +from sphinx.pycode import nodes from sphinx.pycode.pgen2 import driver, token, tokenize, parse, literals from sphinx.util.docstrings import prepare_docstring, prepare_commentdoc @@ -21,7 +21,7 @@ from sphinx.util.docstrings import prepare_docstring, prepare_commentdoc # load the Python grammar _grammarfile = path.join(path.dirname(__file__), 'Grammar.txt') pygrammar = driver.load_grammar(_grammarfile) -pydriver = driver.Driver(pygrammar, convert=pytree.convert) +pydriver = driver.Driver(pygrammar, convert=nodes.convert) # an object with attributes corresponding to token and symbol names class sym: pass @@ -35,10 +35,10 @@ number2name = pygrammar.number2symbol.copy() number2name.update(token.tok_name) -_eq = pytree.Leaf(token.EQUAL, '=') +_eq = nodes.Leaf(token.EQUAL, '=') -class AttrDocVisitor(pytree.NodeVisitor): +class AttrDocVisitor(nodes.NodeVisitor): """ Visitor that collects docstrings for attribute assignments on toplevel and in classes. @@ -263,5 +263,5 @@ if __name__ == '__main__': # print '\n'.join(doc) pprint.pprint(ma.find_tags()) x3 = time.time() - #print pytree.nice_repr(ma.parsetree, number2name) + #print nodes.nice_repr(ma.parsetree, number2name) print "tokenizing %.4f, parsing %.4f, finding %.4f" % (x1-x0, x2-x1, x3-x2) diff --git a/sphinx/pycode/nodes.py b/sphinx/pycode/nodes.py new file mode 100644 index 00000000..d0fb522b --- /dev/null +++ b/sphinx/pycode/nodes.py @@ -0,0 +1,202 @@ +# -*- coding: utf-8 -*- +""" + sphinx.pycode.nodes + ~~~~~~~~~~~~~~~~~~~ + + Parse tree node implementations. + + :copyright: 2009 by Georg Brandl. + :license: BSD, see LICENSE for details. +""" + + +class BaseNode(object): + """ + Node superclass for both terminal and nonterminal nodes. + """ + + def _eq(self, other): + raise NotImplementedError + + def __eq__(self, other): + if self.__class__ is not other.__class__: + return NotImplemented + return self._eq(other) + + def __ne__(self, other): + if self.__class__ is not other.__class__: + return NotImplemented + return not self._eq(other) + + def get_prev_sibling(self): + """Return previous child in parent's children, or None.""" + if self.parent is None: + return None + for i, child in enumerate(self.parent.children): + if child is self: + if i == 0: + return None + return self.parent.children[i-1] + + def get_next_sibling(self): + """Return next child in parent's children, or None.""" + if self.parent is None: + return None + for i, child in enumerate(self.parent.children): + if child is self: + try: + return self.parent.children[i+1] + except IndexError: + return None + + def get_prev_leaf(self): + """Return the leaf node that precedes this node in the parse tree.""" + def last_child(node): + if isinstance(node, Leaf): + return node + elif not node.children: + return None + else: + return last_child(node.children[-1]) + if self.parent is None: + return None + prev = self.get_prev_sibling() + if isinstance(prev, Leaf): + return prev + elif prev is not None: + return last_child(prev) + return self.parent.get_prev_leaf() + + def get_next_leaf(self): + """Return self if leaf, otherwise the leaf node that succeeds this + node in the parse tree. + """ + node = self + while not isinstance(node, Leaf): + assert node.children + node = node.children[0] + return node + + def get_lineno(self): + """Return the line number which generated the invocant node.""" + return self.get_next_leaf().lineno + + def get_prefix(self): + """Return the prefix of the next leaf node.""" + # only leaves carry a prefix + return self.get_next_leaf().prefix + + +class Node(BaseNode): + """ + Node implementation for nonterminals. + """ + + def __init__(self, type, children, context=None): + # type of nonterminals is >= 256 + # assert type >= 256, type + self.type = type + self.children = list(children) + for ch in self.children: + # assert ch.parent is None, repr(ch) + ch.parent = self + + def __repr__(self): + return '%s(%s, %r)' % (self.__class__.__name__, self.type, self.children) + + def __str__(self): + """This reproduces the input source exactly.""" + return ''.join(map(str, self.children)) + + def _eq(self, other): + return (self.type, self.children) == (other.type, other.children) + + # support indexing the node directly instead of .children + + def __getitem__(self, index): + return self.children[index] + + def __iter__(self): + return iter(self.children) + + def __len__(self): + return len(self.children) + + +class Leaf(BaseNode): + """ + Node implementation for leaf nodes (terminals). + """ + prefix = '' # Whitespace and comments preceding this token in the input + lineno = 0 # Line where this token starts in the input + column = 0 # Column where this token tarts in the input + + def __init__(self, type, value, context=None): + # type of terminals is below 256 + # assert 0 <= type < 256, type + self.type = type + self.value = value + if context is not None: + self.prefix, (self.lineno, self.column) = context + + def __repr__(self): + return '%s(%r, %r, %r)' % (self.__class__.__name__, + self.type, self.value, self.prefix) + + def __str__(self): + """This reproduces the input source exactly.""" + return self.prefix + str(self.value) + + def _eq(self, other): + """Compares two nodes for equality.""" + return (self.type, self.value) == (other.type, other.value) + + +def convert(grammar, raw_node): + """Convert raw node to a Node or Leaf instance.""" + type, value, context, children = raw_node + if children or type in grammar.number2symbol: + # If there's exactly one child, return that child instead of + # creating a new node. + if len(children) == 1: + return children[0] + return Node(type, children, context=context) + else: + return Leaf(type, value, context=context) + + +def nice_repr(node, number2name, prefix=False): + def _repr(node): + if isinstance(node, Leaf): + return "%s(%r)" % (number2name[node.type], node.value) + else: + return "%s(%s)" % (number2name[node.type], + ', '.join(map(_repr, node.children))) + def _prepr(node): + if isinstance(node, Leaf): + return "%s(%r, %r)" % (number2name[node.type], node.prefix, node.value) + else: + return "%s(%s)" % (number2name[node.type], + ', '.join(map(_prepr, node.children))) + return (prefix and _prepr or _repr)(node) + + +class NodeVisitor(object): + def __init__(self, number2name, *args): + self.number2name = number2name + self.init(*args) + + def init(self, *args): + pass + + def visit(self, node): + """Visit a node.""" + method = 'visit_' + self.number2name[node.type] + visitor = getattr(self, method, self.generic_visit) + return visitor(node) + + def generic_visit(self, node): + """Called if no explicit visitor function exists for a node.""" + if isinstance(node, Node): + for child in node: + self.visit(child) diff --git a/sphinx/pycode/pgen2/parse.c b/sphinx/pycode/pgen2/parse.c new file mode 100644 index 00000000..fd0e9ff9 --- /dev/null +++ b/sphinx/pycode/pgen2/parse.c @@ -0,0 +1,3261 @@ +/* Generated by Cython 0.9.8.1 on Thu Jan 1 23:45:38 2009 */ + +#define PY_SSIZE_T_CLEAN +#include "Python.h" +#include "structmember.h" +#ifndef PY_LONG_LONG + #define PY_LONG_LONG LONG_LONG +#endif +#ifndef DL_EXPORT + #define DL_EXPORT(t) t +#endif +#if PY_VERSION_HEX < 0x02040000 + #define METH_COEXIST 0 +#endif +#if PY_VERSION_HEX < 0x02050000 + typedef int Py_ssize_t; + #define PY_SSIZE_T_MAX INT_MAX + #define PY_SSIZE_T_MIN INT_MIN + #define PyInt_FromSsize_t(z) PyInt_FromLong(z) + #define PyInt_AsSsize_t(o) PyInt_AsLong(o) + #define PyNumber_Index(o) PyNumber_Int(o) + #define PyIndex_Check(o) PyNumber_Check(o) +#endif +#if PY_VERSION_HEX < 0x02060000 + #define Py_REFCNT(ob) (((PyObject*)(ob))->ob_refcnt) + #define Py_TYPE(ob) (((PyObject*)(ob))->ob_type) + #define Py_SIZE(ob) (((PyVarObject*)(ob))->ob_size) + #define PyVarObject_HEAD_INIT(type, size) \ + PyObject_HEAD_INIT(type) size, + #define PyType_Modified(t) + + typedef struct { + void *buf; + Py_ssize_t len; + int readonly; + const char *format; + int ndim; + Py_ssize_t *shape; + Py_ssize_t *strides; + Py_ssize_t *suboffsets; + Py_ssize_t itemsize; + void *internal; + } Py_buffer; + + #define PyBUF_SIMPLE 0 + #define PyBUF_WRITABLE 0x0001 + #define PyBUF_LOCK 0x0002 + #define PyBUF_FORMAT 0x0004 + #define PyBUF_ND 0x0008 + #define PyBUF_STRIDES (0x0010 | PyBUF_ND) + #define PyBUF_C_CONTIGUOUS (0x0020 | PyBUF_STRIDES) + #define PyBUF_F_CONTIGUOUS (0x0040 | PyBUF_STRIDES) + #define PyBUF_ANY_CONTIGUOUS (0x0080 | PyBUF_STRIDES) + #define PyBUF_INDIRECT (0x0100 | PyBUF_STRIDES) + +#endif +#if PY_MAJOR_VERSION < 3 + #define __Pyx_BUILTIN_MODULE_NAME "__builtin__" +#else + #define __Pyx_BUILTIN_MODULE_NAME "builtins" +#endif +#if PY_MAJOR_VERSION >= 3 + #define Py_TPFLAGS_CHECKTYPES 0 + #define Py_TPFLAGS_HAVE_INDEX 0 +#endif +#if PY_MAJOR_VERSION >= 3 + #define PyBaseString_Type PyUnicode_Type + #define PyString_Type PyBytes_Type + #define PyInt_Type PyLong_Type + #define PyInt_Check(op) PyLong_Check(op) + #define PyInt_CheckExact(op) PyLong_CheckExact(op) + #define PyInt_FromString PyLong_FromString + #define PyInt_FromUnicode PyLong_FromUnicode + #define PyInt_FromLong PyLong_FromLong + #define PyInt_FromSize_t PyLong_FromSize_t + #define PyInt_FromSsize_t PyLong_FromSsize_t + #define PyInt_AsLong PyLong_AsLong + #define PyInt_AS_LONG PyLong_AS_LONG + #define PyInt_AsSsize_t PyLong_AsSsize_t + #define PyInt_AsUnsignedLongMask PyLong_AsUnsignedLongMask + #define PyInt_AsUnsignedLongLongMask PyLong_AsUnsignedLongLongMask + #define __Pyx_PyNumber_Divide(x,y) PyNumber_TrueDivide(x,y) +#else + #define __Pyx_PyNumber_Divide(x,y) PyNumber_Divide(x,y) + #define PyBytes_Type PyString_Type +#endif +#if PY_MAJOR_VERSION >= 3 + #define PyMethod_New(func, self, klass) PyInstanceMethod_New(func) +#endif +#if !defined(WIN32) && !defined(MS_WINDOWS) + #ifndef __stdcall + #define __stdcall + #endif + #ifndef __cdecl + #define __cdecl + #endif +#else + #define _USE_MATH_DEFINES +#endif +#ifdef __cplusplus +#define __PYX_EXTERN_C extern "C" +#else +#define __PYX_EXTERN_C extern +#endif +#include +#define __PYX_HAVE_API__sphinx__pycode__pgen2__parse + + +#ifdef __GNUC__ +#define INLINE __inline__ +#elif _WIN32 +#define INLINE __inline +#else +#define INLINE +#endif + +typedef struct {PyObject **p; char *s; long n; char is_unicode; char intern; char is_identifier;} __Pyx_StringTabEntry; /*proto*/ + + + +static int __pyx_skip_dispatch = 0; + + +/* Type Conversion Predeclarations */ + +#if PY_MAJOR_VERSION < 3 +#define __Pyx_PyBytes_FromString PyString_FromString +#define __Pyx_PyBytes_AsString PyString_AsString +#else +#define __Pyx_PyBytes_FromString PyBytes_FromString +#define __Pyx_PyBytes_AsString PyBytes_AsString +#endif + +#define __Pyx_PyBool_FromLong(b) ((b) ? (Py_INCREF(Py_True), Py_True) : (Py_INCREF(Py_False), Py_False)) +static INLINE int __Pyx_PyObject_IsTrue(PyObject* x); +static INLINE PY_LONG_LONG __pyx_PyInt_AsLongLong(PyObject* x); +static INLINE unsigned PY_LONG_LONG __pyx_PyInt_AsUnsignedLongLong(PyObject* x); +static INLINE Py_ssize_t __pyx_PyIndex_AsSsize_t(PyObject* b); + +#define __pyx_PyInt_AsLong(x) (PyInt_CheckExact(x) ? PyInt_AS_LONG(x) : PyInt_AsLong(x)) +#define __pyx_PyFloat_AsDouble(x) (PyFloat_CheckExact(x) ? PyFloat_AS_DOUBLE(x) : PyFloat_AsDouble(x)) + +static INLINE unsigned char __pyx_PyInt_unsigned_char(PyObject* x); +static INLINE unsigned short __pyx_PyInt_unsigned_short(PyObject* x); +static INLINE char __pyx_PyInt_char(PyObject* x); +static INLINE short __pyx_PyInt_short(PyObject* x); +static INLINE int __pyx_PyInt_int(PyObject* x); +static INLINE long __pyx_PyInt_long(PyObject* x); +static INLINE signed char __pyx_PyInt_signed_char(PyObject* x); +static INLINE signed short __pyx_PyInt_signed_short(PyObject* x); +static INLINE signed int __pyx_PyInt_signed_int(PyObject* x); +static INLINE signed long __pyx_PyInt_signed_long(PyObject* x); +static INLINE long double __pyx_PyInt_long_double(PyObject* x); +#ifdef __GNUC__ +/* Test for GCC > 2.95 */ +#if __GNUC__ > 2 || (__GNUC__ == 2 && (__GNUC_MINOR__ > 95)) +#define likely(x) __builtin_expect(!!(x), 1) +#define unlikely(x) __builtin_expect(!!(x), 0) +#else /* __GNUC__ > 2 ... */ +#define likely(x) (x) +#define unlikely(x) (x) +#endif /* __GNUC__ > 2 ... */ +#else /* __GNUC__ */ +#define likely(x) (x) +#define unlikely(x) (x) +#endif /* __GNUC__ */ + +static PyObject *__pyx_m; +static PyObject *__pyx_b; +static PyObject *__pyx_empty_tuple; +static int __pyx_lineno; +static int __pyx_clineno = 0; +static const char * __pyx_cfilenm= __FILE__; +static const char *__pyx_filename; +static const char **__pyx_f; + +static INLINE void __Pyx_RaiseArgtupleTooLong(Py_ssize_t num_expected, Py_ssize_t num_found); /*proto*/ + +static PyObject *__Pyx_Import(PyObject *name, PyObject *from_list); /*proto*/ + +static PyObject *__Pyx_GetName(PyObject *dict, PyObject *name); /*proto*/ + +static PyObject *__Pyx_CreateClass(PyObject *bases, PyObject *dict, PyObject *name, char *modname); /*proto*/ + +static INLINE PyObject *__Pyx_GetItemInt(PyObject *o, Py_ssize_t i, int is_unsigned) { + PyObject *r; + if (PyList_CheckExact(o) && 0 <= i && i < PyList_GET_SIZE(o)) { + r = PyList_GET_ITEM(o, i); + Py_INCREF(r); + } + else if (PyTuple_CheckExact(o) && 0 <= i && i < PyTuple_GET_SIZE(o)) { + r = PyTuple_GET_ITEM(o, i); + Py_INCREF(r); + } + else if (Py_TYPE(o)->tp_as_sequence && Py_TYPE(o)->tp_as_sequence->sq_item && (likely(i >= 0) || !is_unsigned)) + r = PySequence_GetItem(o, i); + else { + PyObject *j = (likely(i >= 0) || !is_unsigned) ? PyInt_FromLong(i) : PyLong_FromUnsignedLongLong((sizeof(unsigned long long) > sizeof(Py_ssize_t) ? (1ULL << (sizeof(Py_ssize_t)*8)) : 0) + i); + if (!j) + return 0; + r = PyObject_GetItem(o, j); + Py_DECREF(j); + } + return r; +} + +static PyObject *__Pyx_UnpackItem(PyObject *, Py_ssize_t index); /*proto*/ +static int __Pyx_EndUnpack(PyObject *); /*proto*/ + +static void __Pyx_Raise(PyObject *type, PyObject *value, PyObject *tb); /*proto*/ + +static INLINE PyObject* __Pyx_PyObject_Append(PyObject* L, PyObject* x) { + if (likely(PyList_CheckExact(L))) { + if (PyList_Append(L, x) < 0) return NULL; + Py_INCREF(Py_None); + return Py_None; // this is just to have an accurate signature + } + else { + return PyObject_CallMethod(L, "append", "(O)", x); + } +} + +static INLINE int __Pyx_SetItemInt(PyObject *o, Py_ssize_t i, PyObject *v, int is_unsigned) { + int r; + if (PyList_CheckExact(o) && 0 <= i && i < PyList_GET_SIZE(o)) { + Py_DECREF(PyList_GET_ITEM(o, i)); + Py_INCREF(v); + PyList_SET_ITEM(o, i, v); + return 1; + } + else if (Py_TYPE(o)->tp_as_sequence && Py_TYPE(o)->tp_as_sequence->sq_ass_item && (likely(i >= 0) || !is_unsigned)) + r = PySequence_SetItem(o, i, v); + else { + PyObject *j = (likely(i >= 0) || !is_unsigned) ? PyInt_FromLong(i) : PyLong_FromUnsignedLongLong((sizeof(unsigned long long) > sizeof(Py_ssize_t) ? (1ULL << (sizeof(Py_ssize_t)*8)) : 0) + i); + if (!j) + return -1; + r = PyObject_SetItem(o, j, v); + Py_DECREF(j); + } + return r; +} + +static void __Pyx_WriteUnraisable(const char *name); /*proto*/ + +static int __Pyx_SetVtable(PyObject *dict, void *vtable); /*proto*/ + +static void __Pyx_AddTraceback(const char *funcname); /*proto*/ + +static int __Pyx_InitStrings(__Pyx_StringTabEntry *t); /*proto*/ + +/* Type declarations */ + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":31 + * + * + * cdef class Parser: # <<<<<<<<<<<<<< + * cdef public grammar, stack, rootnode, used_names + * cdef _grammar_dfas, _grammar_labels, _grammar_keywords, _grammar_tokens + */ + +struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser { + PyObject_HEAD + struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_vtab; + PyObject *grammar; + PyObject *stack; + PyObject *rootnode; + PyObject *used_names; + PyObject *_grammar_dfas; + PyObject *_grammar_labels; + PyObject *_grammar_keywords; + PyObject *_grammar_tokens; + PyObject *_grammar_number2symbol; +}; + + +struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser { + int (*classify)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *, PyObject *, PyObject *, PyObject *); + void (*shift)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *, PyObject *, PyObject *, PyObject *, PyObject *); + void (*push)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *, PyObject *, PyObject *, PyObject *, PyObject *); + void (*pop)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *); + PyObject *(*convert)(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *, PyObject *); +}; +static struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_vtabptr_6sphinx_6pycode_5pgen2_5parse_Parser; +/* Module declarations from sphinx.pycode.pgen2.parse */ + +static PyTypeObject *__pyx_ptype_6sphinx_6pycode_5pgen2_5parse_Parser = 0; + + +/* Implementation of sphinx.pycode.pgen2.parse */ +static char __pyx_k_2[] = "Exception to signal the parser is stuck."; +static PyObject *__pyx_int_0; +static PyObject *__pyx_int_1; +static char __pyx_k___init__[] = "__init__"; +static PyObject *__pyx_kp___init__; +static char __pyx_k_setup[] = "setup"; +static PyObject *__pyx_kp_setup; +static char __pyx_k_addtoken[] = "addtoken"; +static PyObject *__pyx_kp_addtoken; +static char __pyx_k_1[] = "sphinx.pycode.nodes"; +static PyObject *__pyx_kp_1; +static char __pyx_k_Node[] = "Node"; +static PyObject *__pyx_kp_Node; +static char __pyx_k_Leaf[] = "Leaf"; +static PyObject *__pyx_kp_Leaf; +static char __pyx_k_ParseError[] = "ParseError"; +static PyObject *__pyx_kp_ParseError; +static char __pyx_k_Exception[] = "Exception"; +static PyObject *__pyx_kp_Exception; +static char __pyx_k_msg[] = "msg"; +static PyObject *__pyx_kp_msg; +static char __pyx_k_type[] = "type"; +static PyObject *__pyx_kp_type; +static char __pyx_k_value[] = "value"; +static PyObject *__pyx_kp_value; +static char __pyx_k_context[] = "context"; +static PyObject *__pyx_kp_context; +static char __pyx_k_dfas[] = "dfas"; +static PyObject *__pyx_kp_dfas; +static char __pyx_k_labels[] = "labels"; +static PyObject *__pyx_kp_labels; +static char __pyx_k_keywords[] = "keywords"; +static PyObject *__pyx_kp_keywords; +static char __pyx_k_tokens[] = "tokens"; +static PyObject *__pyx_kp_tokens; +static char __pyx_k_4[] = "number2symbol"; +static PyObject *__pyx_kp_4; +static char __pyx_k_start[] = "start"; +static PyObject *__pyx_kp_start; +static char __pyx_k_add[] = "add"; +static PyObject *__pyx_kp_add; +static char __pyx_k_get[] = "get"; +static PyObject *__pyx_kp_get; +static char __pyx_k_append[] = "append"; +static PyObject *__pyx_kp_append; +static char __pyx_k_pop[] = "pop"; +static PyObject *__pyx_kp_pop; +static char __pyx_k_used_names[] = "used_names"; +static PyObject *__pyx_kp_used_names; +static PyObject *__pyx_kp_2; +static PyObject *__pyx_builtin_Exception; +static PyObject *__pyx_kp_3; +static char __pyx_k_3[] = "%s: type=%r, value=%r, context=%r"; +static PyObject *__pyx_kp_5; +static PyObject *__pyx_kp_6; +static char __pyx_k_5[] = "too much input"; +static char __pyx_k_6[] = "bad input"; +static PyObject *__pyx_kp_7; +static char __pyx_k_7[] = "bad token"; + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":22 + * """Exception to signal the parser is stuck.""" + * + * def __init__(self, msg, type, value, context): # <<<<<<<<<<<<<< + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + * (msg, type, value, context)) + */ + +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__(PyObject *__pyx_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ +static PyMethodDef __pyx_mdef_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__ = {"__init__", (PyCFunction)__pyx_pf_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__, METH_VARARGS|METH_KEYWORDS, 0}; +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__(PyObject *__pyx_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { + PyObject *__pyx_v_self = 0; + PyObject *__pyx_v_msg = 0; + PyObject *__pyx_v_type = 0; + PyObject *__pyx_v_value = 0; + PyObject *__pyx_v_context = 0; + PyObject *__pyx_r; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + static char *__pyx_argnames[] = {"self","msg","type","value","context",0}; + __pyx_self = __pyx_self; + if (likely(!__pyx_kwds) && likely(PyTuple_GET_SIZE(__pyx_args) == 5)) { + __pyx_v_self = PyTuple_GET_ITEM(__pyx_args, 0); + __pyx_v_msg = PyTuple_GET_ITEM(__pyx_args, 1); + __pyx_v_type = PyTuple_GET_ITEM(__pyx_args, 2); + __pyx_v_value = PyTuple_GET_ITEM(__pyx_args, 3); + __pyx_v_context = PyTuple_GET_ITEM(__pyx_args, 4); + } + else { + if (unlikely(!PyArg_ParseTupleAndKeywords(__pyx_args, __pyx_kwds, "OOOOO", __pyx_argnames, &__pyx_v_self, &__pyx_v_msg, &__pyx_v_type, &__pyx_v_value, &__pyx_v_context))) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 22; __pyx_clineno = __LINE__; goto __pyx_L3_error;} + } + goto __pyx_L4; + __pyx_L3_error:; + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.ParseError.__init__"); + return NULL; + __pyx_L4:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":23 + * + * def __init__(self, msg, type, value, context): + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % # <<<<<<<<<<<<<< + * (msg, type, value, context)) + * self.msg = msg + */ + __pyx_1 = PyObject_GetAttr(__pyx_builtin_Exception, __pyx_kp___init__); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 23; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":24 + * def __init__(self, msg, type, value, context): + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + * (msg, type, value, context)) # <<<<<<<<<<<<<< + * self.msg = msg + * self.type = type + */ + __pyx_2 = PyTuple_New(4); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 24; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_msg); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_v_msg); + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_2, 2, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_2, 3, __pyx_v_context); + __pyx_3 = PyNumber_Remainder(__pyx_kp_3, ((PyObject *)__pyx_2)); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 23; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + __pyx_2 = PyTuple_New(2); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 23; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_self); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_v_self); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_3); + __pyx_3 = 0; + __pyx_3 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_2), NULL); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 23; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + Py_DECREF(__pyx_3); __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":25 + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + * (msg, type, value, context)) + * self.msg = msg # <<<<<<<<<<<<<< + * self.type = type + * self.value = value + */ + if (PyObject_SetAttr(__pyx_v_self, __pyx_kp_msg, __pyx_v_msg) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 25; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":26 + * (msg, type, value, context)) + * self.msg = msg + * self.type = type # <<<<<<<<<<<<<< + * self.value = value + * self.context = context + */ + if (PyObject_SetAttr(__pyx_v_self, __pyx_kp_type, __pyx_v_type) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 26; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":27 + * self.msg = msg + * self.type = type + * self.value = value # <<<<<<<<<<<<<< + * self.context = context + * + */ + if (PyObject_SetAttr(__pyx_v_self, __pyx_kp_value, __pyx_v_value) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 27; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":28 + * self.type = type + * self.value = value + * self.context = context # <<<<<<<<<<<<<< + * + * + */ + if (PyObject_SetAttr(__pyx_v_self, __pyx_kp_context, __pyx_v_context) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 28; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + __pyx_r = Py_None; Py_INCREF(Py_None); + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.ParseError.__init__"); + __pyx_r = NULL; + __pyx_L0:; + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":36 + * cdef _grammar_number2symbol + * + * def __init__(self, grammar, convert=None): # <<<<<<<<<<<<<< + * self.grammar = grammar + * #self.convert = convert or noconvert + */ + +static int __pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser___init__(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ +static int __pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser___init__(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { + PyObject *__pyx_v_grammar = 0; + PyObject *__pyx_v_convert = 0; + int __pyx_r; + PyObject *__pyx_1 = 0; + static char *__pyx_argnames[] = {"grammar","convert",0}; + __pyx_v_convert = Py_None; + if (likely(!__pyx_kwds) && likely(1 <= PyTuple_GET_SIZE(__pyx_args)) && likely(PyTuple_GET_SIZE(__pyx_args) <= 2)) { + __pyx_v_grammar = PyTuple_GET_ITEM(__pyx_args, 0); + if (PyTuple_GET_SIZE(__pyx_args) > 1) { + __pyx_v_convert = PyTuple_GET_ITEM(__pyx_args, 1); + } + } + else { + if (unlikely(!PyArg_ParseTupleAndKeywords(__pyx_args, __pyx_kwds, "O|O", __pyx_argnames, &__pyx_v_grammar, &__pyx_v_convert))) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 36; __pyx_clineno = __LINE__; goto __pyx_L3_error;} + } + goto __pyx_L4; + __pyx_L3_error:; + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.__init__"); + return -1; + __pyx_L4:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":37 + * + * def __init__(self, grammar, convert=None): + * self.grammar = grammar # <<<<<<<<<<<<<< + * #self.convert = convert or noconvert + * + */ + Py_INCREF(__pyx_v_grammar); + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->grammar); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->grammar = __pyx_v_grammar; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":40 + * #self.convert = convert or noconvert + * + * self._grammar_dfas = grammar.dfas # <<<<<<<<<<<<<< + * self._grammar_labels = grammar.labels + * self._grammar_keywords = grammar.keywords + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_dfas); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 40; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_dfas); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_dfas = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":41 + * + * self._grammar_dfas = grammar.dfas + * self._grammar_labels = grammar.labels # <<<<<<<<<<<<<< + * self._grammar_keywords = grammar.keywords + * self._grammar_tokens = grammar.tokens + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_labels); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 41; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_labels); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_labels = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":42 + * self._grammar_dfas = grammar.dfas + * self._grammar_labels = grammar.labels + * self._grammar_keywords = grammar.keywords # <<<<<<<<<<<<<< + * self._grammar_tokens = grammar.tokens + * self._grammar_number2symbol = grammar.number2symbol + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_keywords); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 42; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_keywords); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_keywords = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":43 + * self._grammar_labels = grammar.labels + * self._grammar_keywords = grammar.keywords + * self._grammar_tokens = grammar.tokens # <<<<<<<<<<<<<< + * self._grammar_number2symbol = grammar.number2symbol + * + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_tokens); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 43; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_tokens); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_tokens = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":44 + * self._grammar_keywords = grammar.keywords + * self._grammar_tokens = grammar.tokens + * self._grammar_number2symbol = grammar.number2symbol # <<<<<<<<<<<<<< + * + * def setup(self, start=None): + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_grammar, __pyx_kp_4); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 44; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_number2symbol); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_number2symbol = __pyx_1; + __pyx_1 = 0; + + __pyx_r = 0; + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.__init__"); + __pyx_r = -1; + __pyx_L0:; + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":46 + * self._grammar_number2symbol = grammar.number2symbol + * + * def setup(self, start=None): # <<<<<<<<<<<<<< + * if start is None: + * start = self.grammar.start + */ + +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_setup(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_setup(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { + PyObject *__pyx_v_start = 0; + PyObject *__pyx_v_newnode; + PyObject *__pyx_v_stackentry; + PyObject *__pyx_r; + int __pyx_1; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + static char *__pyx_argnames[] = {"start",0}; + __pyx_v_start = Py_None; + if (likely(!__pyx_kwds) && likely(0 <= PyTuple_GET_SIZE(__pyx_args)) && likely(PyTuple_GET_SIZE(__pyx_args) <= 1)) { + if (PyTuple_GET_SIZE(__pyx_args) > 0) { + __pyx_v_start = PyTuple_GET_ITEM(__pyx_args, 0); + } + } + else { + if (unlikely(!PyArg_ParseTupleAndKeywords(__pyx_args, __pyx_kwds, "|O", __pyx_argnames, &__pyx_v_start))) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 46; __pyx_clineno = __LINE__; goto __pyx_L3_error;} + } + goto __pyx_L4; + __pyx_L3_error:; + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.setup"); + return NULL; + __pyx_L4:; + Py_INCREF(__pyx_v_start); + __pyx_v_newnode = Py_None; Py_INCREF(Py_None); + __pyx_v_stackentry = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":47 + * + * def setup(self, start=None): + * if start is None: # <<<<<<<<<<<<<< + * start = self.grammar.start + * # Each stack entry is a tuple: (dfa, state, node). + */ + __pyx_1 = (__pyx_v_start == Py_None); + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":48 + * def setup(self, start=None): + * if start is None: + * start = self.grammar.start # <<<<<<<<<<<<<< + * # Each stack entry is a tuple: (dfa, state, node). + * # A node is a tuple: (type, value, context, children), + */ + __pyx_2 = PyObject_GetAttr(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->grammar, __pyx_kp_start); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 48; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_start); + __pyx_v_start = __pyx_2; + __pyx_2 = 0; + goto __pyx_L5; + } + __pyx_L5:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":52 + * # A node is a tuple: (type, value, context, children), + * # where children is a list of nodes or None, and context may be None. + * newnode = (start, None, None, []) # <<<<<<<<<<<<<< + * stackentry = (self._grammar_dfas[start], 0, newnode) + * self.stack = [stackentry] + */ + __pyx_2 = PyList_New(0); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 52; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(4); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 52; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_start); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_start); + Py_INCREF(Py_None); + PyTuple_SET_ITEM(__pyx_3, 1, Py_None); + Py_INCREF(Py_None); + PyTuple_SET_ITEM(__pyx_3, 2, Py_None); + PyTuple_SET_ITEM(__pyx_3, 3, ((PyObject *)__pyx_2)); + __pyx_2 = 0; + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = ((PyObject *)__pyx_3); + __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":53 + * # where children is a list of nodes or None, and context may be None. + * newnode = (start, None, None, []) + * stackentry = (self._grammar_dfas[start], 0, newnode) # <<<<<<<<<<<<<< + * self.stack = [stackentry] + * self.rootnode = None + */ + __pyx_2 = PyObject_GetItem(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_dfas, __pyx_v_start); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 53; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(3); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 53; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_2); + Py_INCREF(__pyx_int_0); + PyTuple_SET_ITEM(__pyx_3, 1, __pyx_int_0); + Py_INCREF(__pyx_v_newnode); + PyTuple_SET_ITEM(__pyx_3, 2, __pyx_v_newnode); + __pyx_2 = 0; + Py_DECREF(__pyx_v_stackentry); + __pyx_v_stackentry = ((PyObject *)__pyx_3); + __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":54 + * newnode = (start, None, None, []) + * stackentry = (self._grammar_dfas[start], 0, newnode) + * self.stack = [stackentry] # <<<<<<<<<<<<<< + * self.rootnode = None + * self.used_names = set() # Aliased to self.rootnode.used_names in pop() + */ + __pyx_2 = PyList_New(1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 54; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_stackentry); + PyList_SET_ITEM(__pyx_2, 0, __pyx_v_stackentry); + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack = ((PyObject *)__pyx_2); + __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":55 + * stackentry = (self._grammar_dfas[start], 0, newnode) + * self.stack = [stackentry] + * self.rootnode = None # <<<<<<<<<<<<<< + * self.used_names = set() # Aliased to self.rootnode.used_names in pop() + * + */ + Py_INCREF(Py_None); + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->rootnode); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->rootnode = Py_None; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":56 + * self.stack = [stackentry] + * self.rootnode = None + * self.used_names = set() # Aliased to self.rootnode.used_names in pop() # <<<<<<<<<<<<<< + * + * def addtoken(self, type, value, context): + */ + __pyx_3 = PyObject_Call(((PyObject*)&PySet_Type), ((PyObject *)__pyx_empty_tuple), NULL); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 56; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->used_names); + ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->used_names = __pyx_3; + __pyx_3 = 0; + + __pyx_r = Py_None; Py_INCREF(Py_None); + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.setup"); + __pyx_r = NULL; + __pyx_L0:; + Py_DECREF(__pyx_v_newnode); + Py_DECREF(__pyx_v_stackentry); + Py_DECREF(__pyx_v_start); + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":58 + * self.used_names = set() # Aliased to self.rootnode.used_names in pop() + * + * def addtoken(self, type, value, context): # <<<<<<<<<<<<<< + * """Add a token; return True iff this is the end of the program.""" + * cdef int ilabel, i, t, state, newstate + */ + +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds); /*proto*/ +static char __pyx_doc_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken[] = "Add a token; return True iff this is the end of the program."; +static PyObject *__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken(PyObject *__pyx_v_self, PyObject *__pyx_args, PyObject *__pyx_kwds) { + PyObject *__pyx_v_type = 0; + PyObject *__pyx_v_value = 0; + PyObject *__pyx_v_context = 0; + int __pyx_v_ilabel; + int __pyx_v_i; + int __pyx_v_t; + int __pyx_v_state; + int __pyx_v_newstate; + PyObject *__pyx_v_dfa; + PyObject *__pyx_v_node; + PyObject *__pyx_v_states; + PyObject *__pyx_v_first; + PyObject *__pyx_v_arcs; + PyObject *__pyx_v_v; + PyObject *__pyx_v_itsdfa; + PyObject *__pyx_v_itsstates; + PyObject *__pyx_v_itsfirst; + PyObject *__pyx_r; + int __pyx_1; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + PyObject *__pyx_4 = 0; + int __pyx_5; + Py_ssize_t __pyx_6 = 0; + PyObject *__pyx_7 = 0; + int __pyx_8; + static char *__pyx_argnames[] = {"type","value","context",0}; + if (likely(!__pyx_kwds) && likely(PyTuple_GET_SIZE(__pyx_args) == 3)) { + __pyx_v_type = PyTuple_GET_ITEM(__pyx_args, 0); + __pyx_v_value = PyTuple_GET_ITEM(__pyx_args, 1); + __pyx_v_context = PyTuple_GET_ITEM(__pyx_args, 2); + } + else { + if (unlikely(!PyArg_ParseTupleAndKeywords(__pyx_args, __pyx_kwds, "OOO", __pyx_argnames, &__pyx_v_type, &__pyx_v_value, &__pyx_v_context))) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 58; __pyx_clineno = __LINE__; goto __pyx_L3_error;} + } + goto __pyx_L4; + __pyx_L3_error:; + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.addtoken"); + return NULL; + __pyx_L4:; + __pyx_v_dfa = Py_None; Py_INCREF(Py_None); + __pyx_v_node = Py_None; Py_INCREF(Py_None); + __pyx_v_states = Py_None; Py_INCREF(Py_None); + __pyx_v_first = Py_None; Py_INCREF(Py_None); + __pyx_v_arcs = Py_None; Py_INCREF(Py_None); + __pyx_v_v = Py_None; Py_INCREF(Py_None); + __pyx_v_itsdfa = Py_None; Py_INCREF(Py_None); + __pyx_v_itsstates = Py_None; Py_INCREF(Py_None); + __pyx_v_itsfirst = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":62 + * cdef int ilabel, i, t, state, newstate + * # Map from token to label + * ilabel = self.classify(type, value, context) # <<<<<<<<<<<<<< + * # Loop until the token is shifted; may raise exceptions + * while True: + */ + __pyx_v_ilabel = ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->classify(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self), __pyx_v_type, __pyx_v_value, __pyx_v_context); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":64 + * ilabel = self.classify(type, value, context) + * # Loop until the token is shifted; may raise exceptions + * while True: # <<<<<<<<<<<<<< + * dfa, state, node = self.stack[-1] + * states, first = dfa + */ + while (1) { + __pyx_1 = 1; + if (!__pyx_1) break; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":65 + * # Loop until the token is shifted; may raise exceptions + * while True: + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * states, first = dfa + * arcs = states[state] + */ + __pyx_2 = __Pyx_GetItemInt(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack, -1, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_2) && PyTuple_GET_SIZE(__pyx_2) == 3) { + PyObject* tuple = __pyx_2; + __pyx_4 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_4); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_4; + __pyx_4 = 0; + __pyx_4 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_4); + __pyx_5 = __pyx_PyInt_int(__pyx_4); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + __pyx_v_state = __pyx_5; + __pyx_4 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_4); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_4; + __pyx_4 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + else { + __pyx_3 = PyObject_GetIter(__pyx_2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_4 = __Pyx_UnpackItem(__pyx_3, 0); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_4; + __pyx_4 = 0; + __pyx_4 = __Pyx_UnpackItem(__pyx_3, 1); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_4); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + __pyx_v_state = __pyx_5; + __pyx_4 = __Pyx_UnpackItem(__pyx_3, 2); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_4; + __pyx_4 = 0; + if (__Pyx_EndUnpack(__pyx_3) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 65; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_3); __pyx_3 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":66 + * while True: + * dfa, state, node = self.stack[-1] + * states, first = dfa # <<<<<<<<<<<<<< + * arcs = states[state] + * # Look for a state with this label + */ + if (PyTuple_CheckExact(__pyx_v_dfa) && PyTuple_GET_SIZE(__pyx_v_dfa) == 2) { + PyObject* tuple = __pyx_v_dfa; + __pyx_2 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_states); + __pyx_v_states = __pyx_2; + __pyx_2 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_first); + __pyx_v_first = __pyx_3; + __pyx_3 = 0; + } + else { + __pyx_4 = PyObject_GetIter(__pyx_v_dfa); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 66; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_UnpackItem(__pyx_4, 0); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 66; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_states); + __pyx_v_states = __pyx_2; + __pyx_2 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_4, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 66; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_first); + __pyx_v_first = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_4) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 66; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":67 + * dfa, state, node = self.stack[-1] + * states, first = dfa + * arcs = states[state] # <<<<<<<<<<<<<< + * # Look for a state with this label + * for i, newstate in arcs: + */ + __pyx_2 = __Pyx_GetItemInt(__pyx_v_states, __pyx_v_state, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 67; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_arcs); + __pyx_v_arcs = __pyx_2; + __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":69 + * arcs = states[state] + * # Look for a state with this label + * for i, newstate in arcs: # <<<<<<<<<<<<<< + * t, v = self._grammar_labels[i] + * if ilabel == i: + */ + if (PyList_CheckExact(__pyx_v_arcs) || PyTuple_CheckExact(__pyx_v_arcs)) { + __pyx_6 = 0; __pyx_3 = __pyx_v_arcs; Py_INCREF(__pyx_3); + } else { + __pyx_6 = -1; __pyx_3 = PyObject_GetIter(__pyx_v_arcs); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + } + for (;;) { + if (likely(PyList_CheckExact(__pyx_3))) { + if (__pyx_6 >= PyList_GET_SIZE(__pyx_3)) break; + __pyx_4 = PyList_GET_ITEM(__pyx_3, __pyx_6); Py_INCREF(__pyx_4); __pyx_6++; + } else if (likely(PyTuple_CheckExact(__pyx_3))) { + if (__pyx_6 >= PyTuple_GET_SIZE(__pyx_3)) break; + __pyx_4 = PyTuple_GET_ITEM(__pyx_3, __pyx_6); Py_INCREF(__pyx_4); __pyx_6++; + } else { + __pyx_4 = PyIter_Next(__pyx_3); + if (!__pyx_4) { + if (unlikely(PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + break; + } + } + if (PyTuple_CheckExact(__pyx_4) && PyTuple_GET_SIZE(__pyx_4) == 2) { + PyObject* tuple = __pyx_4; + __pyx_7 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_7); + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_i = __pyx_5; + __pyx_7 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_7); + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_newstate = __pyx_5; + Py_DECREF(__pyx_4); __pyx_4 = 0; + } + else { + __pyx_2 = PyObject_GetIter(__pyx_4); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 0); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_i = __pyx_5; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 1); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_newstate = __pyx_5; + if (__Pyx_EndUnpack(__pyx_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 69; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":70 + * # Look for a state with this label + * for i, newstate in arcs: + * t, v = self._grammar_labels[i] # <<<<<<<<<<<<<< + * if ilabel == i: + * # Look it up in the list of labels + */ + __pyx_7 = __Pyx_GetItemInt(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_labels, __pyx_v_i, 0); if (!__pyx_7) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_7) && PyTuple_GET_SIZE(__pyx_7) == 2) { + PyObject* tuple = __pyx_7; + __pyx_2 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_2); + __pyx_5 = __pyx_PyInt_int(__pyx_2); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_v_t = __pyx_5; + __pyx_2 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_v); + __pyx_v_v = __pyx_2; + __pyx_2 = 0; + Py_DECREF(__pyx_7); __pyx_7 = 0; + } + else { + __pyx_4 = PyObject_GetIter(__pyx_7); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_4, 0); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_2); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_v_t = __pyx_5; + __pyx_2 = __Pyx_UnpackItem(__pyx_4, 1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_v); + __pyx_v_v = __pyx_2; + __pyx_2 = 0; + if (__Pyx_EndUnpack(__pyx_4) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 70; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":71 + * for i, newstate in arcs: + * t, v = self._grammar_labels[i] + * if ilabel == i: # <<<<<<<<<<<<<< + * # Look it up in the list of labels + * ## assert t < 256 + */ + __pyx_1 = (__pyx_v_ilabel == __pyx_v_i); + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":75 + * ## assert t < 256 + * # Shift a token; we're done with it + * self.shift(type, value, newstate, context) # <<<<<<<<<<<<<< + * # Pop while we are in an accept-only state + * state = newstate + */ + __pyx_2 = PyInt_FromLong(__pyx_v_newstate); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 75; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->shift(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self), __pyx_v_type, __pyx_v_value, __pyx_2, __pyx_v_context); + Py_DECREF(__pyx_2); __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":77 + * self.shift(type, value, newstate, context) + * # Pop while we are in an accept-only state + * state = newstate # <<<<<<<<<<<<<< + * while states[state] == [(0, state)]: + * self.pop() + */ + __pyx_v_state = __pyx_v_newstate; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":78 + * # Pop while we are in an accept-only state + * state = newstate + * while states[state] == [(0, state)]: # <<<<<<<<<<<<<< + * self.pop() + * if not self.stack: + */ + while (1) { + __pyx_7 = __Pyx_GetItemInt(__pyx_v_states, __pyx_v_state, 0); if (!__pyx_7) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = PyInt_FromLong(__pyx_v_state); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = PyTuple_New(2); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_int_0); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_int_0); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_4); + __pyx_4 = 0; + __pyx_4 = PyList_New(1); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + PyList_SET_ITEM(__pyx_4, 0, ((PyObject *)__pyx_2)); + __pyx_2 = 0; + __pyx_2 = PyObject_RichCompare(__pyx_7, ((PyObject *)__pyx_4), Py_EQ); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + Py_DECREF(((PyObject *)__pyx_4)); __pyx_4 = 0; + __pyx_1 = __Pyx_PyObject_IsTrue(__pyx_2); if (unlikely(__pyx_1 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 78; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + if (!__pyx_1) break; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":79 + * state = newstate + * while states[state] == [(0, state)]: + * self.pop() # <<<<<<<<<<<<<< + * if not self.stack: + * # Done parsing! + */ + ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->pop(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":80 + * while states[state] == [(0, state)]: + * self.pop() + * if not self.stack: # <<<<<<<<<<<<<< + * # Done parsing! + * return True + */ + __pyx_1 = __Pyx_PyObject_IsTrue(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack); if (unlikely(__pyx_1 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 80; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_8 = (!__pyx_1); + if (__pyx_8) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":82 + * if not self.stack: + * # Done parsing! + * return True # <<<<<<<<<<<<<< + * dfa, state, node = self.stack[-1] + * states, first = dfa + */ + __pyx_7 = __Pyx_PyBool_FromLong(1); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 82; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_7; + __pyx_7 = 0; + Py_DECREF(__pyx_3); __pyx_3 = 0; + goto __pyx_L0; + goto __pyx_L12; + } + __pyx_L12:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":83 + * # Done parsing! + * return True + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * states, first = dfa + * # Done with this token + */ + __pyx_4 = __Pyx_GetItemInt(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack, -1, 0); if (!__pyx_4) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_4) && PyTuple_GET_SIZE(__pyx_4) == 3) { + PyObject* tuple = __pyx_4; + __pyx_7 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_7); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_7; + __pyx_7 = 0; + __pyx_7 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_7); + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_state = __pyx_5; + __pyx_7 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_7); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_7; + __pyx_7 = 0; + Py_DECREF(__pyx_4); __pyx_4 = 0; + } + else { + __pyx_2 = PyObject_GetIter(__pyx_4); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 0); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_7; + __pyx_7 = 0; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 1); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_5 = __pyx_PyInt_int(__pyx_7); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + __pyx_v_state = __pyx_5; + __pyx_7 = __Pyx_UnpackItem(__pyx_2, 2); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_7; + __pyx_7 = 0; + if (__Pyx_EndUnpack(__pyx_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 83; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":84 + * return True + * dfa, state, node = self.stack[-1] + * states, first = dfa # <<<<<<<<<<<<<< + * # Done with this token + * return False + */ + if (PyTuple_CheckExact(__pyx_v_dfa) && PyTuple_GET_SIZE(__pyx_v_dfa) == 2) { + PyObject* tuple = __pyx_v_dfa; + __pyx_4 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_4); + Py_DECREF(__pyx_v_states); + __pyx_v_states = __pyx_4; + __pyx_4 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_first); + __pyx_v_first = __pyx_2; + __pyx_2 = 0; + } + else { + __pyx_7 = PyObject_GetIter(__pyx_v_dfa); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 84; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = __Pyx_UnpackItem(__pyx_7, 0); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 84; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_states); + __pyx_v_states = __pyx_4; + __pyx_4 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_7, 1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 84; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_first); + __pyx_v_first = __pyx_2; + __pyx_2 = 0; + if (__Pyx_EndUnpack(__pyx_7) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 84; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + } + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":86 + * states, first = dfa + * # Done with this token + * return False # <<<<<<<<<<<<<< + * elif t >= 256: + * # See if it's a symbol and if we're in its first set + */ + __pyx_4 = __Pyx_PyBool_FromLong(0); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 86; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_4; + __pyx_4 = 0; + Py_DECREF(__pyx_3); __pyx_3 = 0; + goto __pyx_L0; + goto __pyx_L9; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":87 + * # Done with this token + * return False + * elif t >= 256: # <<<<<<<<<<<<<< + * # See if it's a symbol and if we're in its first set + * itsdfa = self._grammar_dfas[t] + */ + __pyx_1 = (__pyx_v_t >= 256); + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":89 + * elif t >= 256: + * # See if it's a symbol and if we're in its first set + * itsdfa = self._grammar_dfas[t] # <<<<<<<<<<<<<< + * itsstates, itsfirst = itsdfa + * if ilabel in itsfirst: + */ + __pyx_2 = __Pyx_GetItemInt(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->_grammar_dfas, __pyx_v_t, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 89; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_itsdfa); + __pyx_v_itsdfa = __pyx_2; + __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":90 + * # See if it's a symbol and if we're in its first set + * itsdfa = self._grammar_dfas[t] + * itsstates, itsfirst = itsdfa # <<<<<<<<<<<<<< + * if ilabel in itsfirst: + * # Push a symbol + */ + if (PyTuple_CheckExact(__pyx_v_itsdfa) && PyTuple_GET_SIZE(__pyx_v_itsdfa) == 2) { + PyObject* tuple = __pyx_v_itsdfa; + __pyx_4 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_4); + Py_DECREF(__pyx_v_itsstates); + __pyx_v_itsstates = __pyx_4; + __pyx_4 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_itsfirst); + __pyx_v_itsfirst = __pyx_2; + __pyx_2 = 0; + } + else { + __pyx_7 = PyObject_GetIter(__pyx_v_itsdfa); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 90; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = __Pyx_UnpackItem(__pyx_7, 0); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 90; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_itsstates); + __pyx_v_itsstates = __pyx_4; + __pyx_4 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_7, 1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 90; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_itsfirst); + __pyx_v_itsfirst = __pyx_2; + __pyx_2 = 0; + if (__Pyx_EndUnpack(__pyx_7) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 90; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":91 + * itsdfa = self._grammar_dfas[t] + * itsstates, itsfirst = itsdfa + * if ilabel in itsfirst: # <<<<<<<<<<<<<< + * # Push a symbol + * self.push(t, itsdfa, newstate, context) + */ + __pyx_4 = PyInt_FromLong(__pyx_v_ilabel); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 91; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_8 = (PySequence_Contains(__pyx_v_itsfirst, __pyx_4)); if (unlikely(__pyx_8 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 91; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + if (__pyx_8) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":93 + * if ilabel in itsfirst: + * # Push a symbol + * self.push(t, itsdfa, newstate, context) # <<<<<<<<<<<<<< + * break # To continue the outer while loop + * else: + */ + __pyx_2 = PyInt_FromLong(__pyx_v_t); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 93; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_7 = PyInt_FromLong(__pyx_v_newstate); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 93; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->push(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self), __pyx_2, __pyx_v_itsdfa, __pyx_7, __pyx_v_context); + Py_DECREF(__pyx_2); __pyx_2 = 0; + Py_DECREF(__pyx_7); __pyx_7 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":94 + * # Push a symbol + * self.push(t, itsdfa, newstate, context) + * break # To continue the outer while loop # <<<<<<<<<<<<<< + * else: + * if (0, state) in arcs: + */ + goto __pyx_L8; + goto __pyx_L13; + } + __pyx_L13:; + goto __pyx_L9; + } + __pyx_L9:; + } + /*else*/ { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":96 + * break # To continue the outer while loop + * else: + * if (0, state) in arcs: # <<<<<<<<<<<<<< + * # An accepting state, pop it and try something else + * self.pop() + */ + __pyx_4 = PyInt_FromLong(__pyx_v_state); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 96; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = PyTuple_New(2); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 96; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_int_0); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_int_0); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_4); + __pyx_4 = 0; + __pyx_1 = (PySequence_Contains(__pyx_v_arcs, ((PyObject *)__pyx_2))); if (unlikely(__pyx_1 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 96; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":98 + * if (0, state) in arcs: + * # An accepting state, pop it and try something else + * self.pop() # <<<<<<<<<<<<<< + * if not self.stack: + * # Done parsing, but another token is input + */ + ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->__pyx_vtab)->pop(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":99 + * # An accepting state, pop it and try something else + * self.pop() + * if not self.stack: # <<<<<<<<<<<<<< + * # Done parsing, but another token is input + * raise ParseError("too much input", + */ + __pyx_8 = __Pyx_PyObject_IsTrue(((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self)->stack); if (unlikely(__pyx_8 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 99; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = (!__pyx_8); + if (__pyx_1) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":101 + * if not self.stack: + * # Done parsing, but another token is input + * raise ParseError("too much input", # <<<<<<<<<<<<<< + * type, value, context) + * else: + */ + __pyx_7 = __Pyx_GetName(__pyx_m, __pyx_kp_ParseError); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 101; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":102 + * # Done parsing, but another token is input + * raise ParseError("too much input", + * type, value, context) # <<<<<<<<<<<<<< + * else: + * # No success finding a transition + */ + __pyx_4 = PyTuple_New(4); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 101; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_kp_5); + PyTuple_SET_ITEM(__pyx_4, 0, __pyx_kp_5); + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_4, 1, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_4, 2, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_4, 3, __pyx_v_context); + __pyx_2 = PyObject_Call(__pyx_7, ((PyObject *)__pyx_4), NULL); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 101; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + Py_DECREF(((PyObject *)__pyx_4)); __pyx_4 = 0; + __Pyx_Raise(__pyx_2, 0, 0); + Py_DECREF(__pyx_2); __pyx_2 = 0; + {__pyx_filename = __pyx_f[0]; __pyx_lineno = 101; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + goto __pyx_L15; + } + __pyx_L15:; + goto __pyx_L14; + } + /*else*/ { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":105 + * else: + * # No success finding a transition + * raise ParseError("bad input", type, value, context) # <<<<<<<<<<<<<< + * + * cdef int classify(self, type, value, context): + */ + __pyx_7 = __Pyx_GetName(__pyx_m, __pyx_kp_ParseError); if (unlikely(!__pyx_7)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 105; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = PyTuple_New(4); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 105; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_kp_6); + PyTuple_SET_ITEM(__pyx_4, 0, __pyx_kp_6); + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_4, 1, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_4, 2, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_4, 3, __pyx_v_context); + __pyx_2 = PyObject_Call(__pyx_7, ((PyObject *)__pyx_4), NULL); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 105; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_7); __pyx_7 = 0; + Py_DECREF(((PyObject *)__pyx_4)); __pyx_4 = 0; + __Pyx_Raise(__pyx_2, 0, 0); + Py_DECREF(__pyx_2); __pyx_2 = 0; + {__pyx_filename = __pyx_f[0]; __pyx_lineno = 105; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + } + __pyx_L14:; + } + __pyx_L8:; + Py_DECREF(__pyx_3); __pyx_3 = 0; + } + + __pyx_r = Py_None; Py_INCREF(Py_None); + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + Py_XDECREF(__pyx_4); + Py_XDECREF(__pyx_7); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.addtoken"); + __pyx_r = NULL; + __pyx_L0:; + Py_DECREF(__pyx_v_dfa); + Py_DECREF(__pyx_v_node); + Py_DECREF(__pyx_v_states); + Py_DECREF(__pyx_v_first); + Py_DECREF(__pyx_v_arcs); + Py_DECREF(__pyx_v_v); + Py_DECREF(__pyx_v_itsdfa); + Py_DECREF(__pyx_v_itsstates); + Py_DECREF(__pyx_v_itsfirst); + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":107 + * raise ParseError("bad input", type, value, context) + * + * cdef int classify(self, type, value, context): # <<<<<<<<<<<<<< + * """Turn a token into a label. (Internal)""" + * if type == NAME: + */ + +static int __pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_classify(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self, PyObject *__pyx_v_type, PyObject *__pyx_v_value, PyObject *__pyx_v_context) { + PyObject *__pyx_v_ilabel; + int __pyx_r; + PyObject *__pyx_1 = 0; + int __pyx_2; + PyObject *__pyx_3 = 0; + PyObject *__pyx_4 = 0; + int __pyx_5; + __pyx_v_ilabel = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":109 + * cdef int classify(self, type, value, context): + * """Turn a token into a label. (Internal)""" + * if type == NAME: # <<<<<<<<<<<<<< + * # Keep a listing of all used names + * self.used_names.add(value) + */ + __pyx_1 = PyObject_RichCompare(__pyx_v_type, __pyx_int_1, Py_EQ); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 109; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_PyObject_IsTrue(__pyx_1); if (unlikely(__pyx_2 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 109; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + if (__pyx_2) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":111 + * if type == NAME: + * # Keep a listing of all used names + * self.used_names.add(value) # <<<<<<<<<<<<<< + * # Check for reserved words + * ilabel = self._grammar_keywords.get(value) + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_self->used_names, __pyx_kp_add); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 111; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 111; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_value); + __pyx_4 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_3), NULL); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 111; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + Py_DECREF(__pyx_4); __pyx_4 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":113 + * self.used_names.add(value) + * # Check for reserved words + * ilabel = self._grammar_keywords.get(value) # <<<<<<<<<<<<<< + * if ilabel is not None: + * return ilabel + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_self->_grammar_keywords, __pyx_kp_get); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 113; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 113; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_value); + __pyx_4 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_3), NULL); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 113; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + Py_DECREF(__pyx_v_ilabel); + __pyx_v_ilabel = __pyx_4; + __pyx_4 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":114 + * # Check for reserved words + * ilabel = self._grammar_keywords.get(value) + * if ilabel is not None: # <<<<<<<<<<<<<< + * return ilabel + * ilabel = self._grammar_tokens.get(type) + */ + __pyx_2 = (__pyx_v_ilabel != Py_None); + if (__pyx_2) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":115 + * ilabel = self._grammar_keywords.get(value) + * if ilabel is not None: + * return ilabel # <<<<<<<<<<<<<< + * ilabel = self._grammar_tokens.get(type) + * if ilabel is None: + */ + __pyx_5 = __pyx_PyInt_int(__pyx_v_ilabel); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 115; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_5; + goto __pyx_L0; + goto __pyx_L4; + } + __pyx_L4:; + goto __pyx_L3; + } + __pyx_L3:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":116 + * if ilabel is not None: + * return ilabel + * ilabel = self._grammar_tokens.get(type) # <<<<<<<<<<<<<< + * if ilabel is None: + * raise ParseError("bad token", type, value, context) + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_self->_grammar_tokens, __pyx_kp_get); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 116; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 116; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_type); + __pyx_4 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_3), NULL); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 116; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + Py_DECREF(__pyx_v_ilabel); + __pyx_v_ilabel = __pyx_4; + __pyx_4 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":117 + * return ilabel + * ilabel = self._grammar_tokens.get(type) + * if ilabel is None: # <<<<<<<<<<<<<< + * raise ParseError("bad token", type, value, context) + * return ilabel + */ + __pyx_2 = (__pyx_v_ilabel == Py_None); + if (__pyx_2) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":118 + * ilabel = self._grammar_tokens.get(type) + * if ilabel is None: + * raise ParseError("bad token", type, value, context) # <<<<<<<<<<<<<< + * return ilabel + * + */ + __pyx_1 = __Pyx_GetName(__pyx_m, __pyx_kp_ParseError); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 118; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = PyTuple_New(4); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 118; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_kp_7); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_kp_7); + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_3, 1, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_3, 2, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_3, 3, __pyx_v_context); + __pyx_4 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_3), NULL); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 118; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + __Pyx_Raise(__pyx_4, 0, 0); + Py_DECREF(__pyx_4); __pyx_4 = 0; + {__pyx_filename = __pyx_f[0]; __pyx_lineno = 118; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + goto __pyx_L5; + } + __pyx_L5:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":119 + * if ilabel is None: + * raise ParseError("bad token", type, value, context) + * return ilabel # <<<<<<<<<<<<<< + * + * cdef void shift(self, type, value, newstate, context): + */ + __pyx_5 = __pyx_PyInt_int(__pyx_v_ilabel); if (unlikely((__pyx_5 == (int)-1) && PyErr_Occurred())) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 119; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_5; + goto __pyx_L0; + + __pyx_r = 0; + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_3); + Py_XDECREF(__pyx_4); + __Pyx_WriteUnraisable("sphinx.pycode.pgen2.parse.Parser.classify"); + __pyx_r = 0; + __pyx_L0:; + Py_DECREF(__pyx_v_ilabel); + return __pyx_r; +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":121 + * return ilabel + * + * cdef void shift(self, type, value, newstate, context): # <<<<<<<<<<<<<< + * """Shift a token. (Internal)""" + * dfa, state, node = self.stack[-1] + */ + +static void __pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_shift(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self, PyObject *__pyx_v_type, PyObject *__pyx_v_value, PyObject *__pyx_v_newstate, PyObject *__pyx_v_context) { + PyObject *__pyx_v_dfa; + PyObject *__pyx_v_state; + PyObject *__pyx_v_node; + PyObject *__pyx_v_newnode; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + int __pyx_4; + __pyx_v_dfa = Py_None; Py_INCREF(Py_None); + __pyx_v_state = Py_None; Py_INCREF(Py_None); + __pyx_v_node = Py_None; Py_INCREF(Py_None); + __pyx_v_newnode = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":123 + * cdef void shift(self, type, value, newstate, context): + * """Shift a token. (Internal)""" + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * newnode = (type, value, context, None) + * newnode = self.convert(newnode) + */ + __pyx_1 = __Pyx_GetItemInt(__pyx_v_self->stack, -1, 0); if (!__pyx_1) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_1) && PyTuple_GET_SIZE(__pyx_1) == 3) { + PyObject* tuple = __pyx_1; + __pyx_3 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + else { + __pyx_2 = PyObject_GetIter(__pyx_1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 123; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":124 + * """Shift a token. (Internal)""" + * dfa, state, node = self.stack[-1] + * newnode = (type, value, context, None) # <<<<<<<<<<<<<< + * newnode = self.convert(newnode) + * if newnode is not None: + */ + __pyx_3 = PyTuple_New(4); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 124; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_3, 1, __pyx_v_value); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_3, 2, __pyx_v_context); + Py_INCREF(Py_None); + PyTuple_SET_ITEM(__pyx_3, 3, Py_None); + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = ((PyObject *)__pyx_3); + __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":125 + * dfa, state, node = self.stack[-1] + * newnode = (type, value, context, None) + * newnode = self.convert(newnode) # <<<<<<<<<<<<<< + * if newnode is not None: + * node[-1].append(newnode) + */ + __pyx_1 = ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self->__pyx_vtab)->convert(__pyx_v_self, __pyx_v_newnode); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 125; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = __pyx_1; + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":126 + * newnode = (type, value, context, None) + * newnode = self.convert(newnode) + * if newnode is not None: # <<<<<<<<<<<<<< + * node[-1].append(newnode) + * self.stack[-1] = (dfa, newstate, node) + */ + __pyx_4 = (__pyx_v_newnode != Py_None); + if (__pyx_4) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":127 + * newnode = self.convert(newnode) + * if newnode is not None: + * node[-1].append(newnode) # <<<<<<<<<<<<<< + * self.stack[-1] = (dfa, newstate, node) + * + */ + __pyx_2 = __Pyx_GetItemInt(__pyx_v_node, -1, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 127; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = __Pyx_PyObject_Append(__pyx_2, __pyx_v_newnode); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 127; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + Py_DECREF(__pyx_3); __pyx_3 = 0; + goto __pyx_L3; + } + __pyx_L3:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":128 + * if newnode is not None: + * node[-1].append(newnode) + * self.stack[-1] = (dfa, newstate, node) # <<<<<<<<<<<<<< + * + * cdef void push(self, type, newdfa, newstate, context): + */ + __pyx_1 = PyTuple_New(3); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 128; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_dfa); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_v_dfa); + Py_INCREF(__pyx_v_newstate); + PyTuple_SET_ITEM(__pyx_1, 1, __pyx_v_newstate); + Py_INCREF(__pyx_v_node); + PyTuple_SET_ITEM(__pyx_1, 2, __pyx_v_node); + if (__Pyx_SetItemInt(__pyx_v_self->stack, -1, ((PyObject *)__pyx_1), 0) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 128; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_WriteUnraisable("sphinx.pycode.pgen2.parse.Parser.shift"); + __pyx_L0:; + Py_DECREF(__pyx_v_dfa); + Py_DECREF(__pyx_v_state); + Py_DECREF(__pyx_v_node); + Py_DECREF(__pyx_v_newnode); +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":130 + * self.stack[-1] = (dfa, newstate, node) + * + * cdef void push(self, type, newdfa, newstate, context): # <<<<<<<<<<<<<< + * """Push a nonterminal. (Internal)""" + * dfa, state, node = self.stack[-1] + */ + +static void __pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_push(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self, PyObject *__pyx_v_type, PyObject *__pyx_v_newdfa, PyObject *__pyx_v_newstate, PyObject *__pyx_v_context) { + PyObject *__pyx_v_dfa; + PyObject *__pyx_v_state; + PyObject *__pyx_v_node; + PyObject *__pyx_v_newnode; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + __pyx_v_dfa = Py_None; Py_INCREF(Py_None); + __pyx_v_state = Py_None; Py_INCREF(Py_None); + __pyx_v_node = Py_None; Py_INCREF(Py_None); + __pyx_v_newnode = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":132 + * cdef void push(self, type, newdfa, newstate, context): + * """Push a nonterminal. (Internal)""" + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * newnode = (type, None, context, []) + * self.stack[-1] = (dfa, newstate, node) + */ + __pyx_1 = __Pyx_GetItemInt(__pyx_v_self->stack, -1, 0); if (!__pyx_1) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_1) && PyTuple_GET_SIZE(__pyx_1) == 3) { + PyObject* tuple = __pyx_1; + __pyx_3 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + else { + __pyx_2 = PyObject_GetIter(__pyx_1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_2, 2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 132; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":133 + * """Push a nonterminal. (Internal)""" + * dfa, state, node = self.stack[-1] + * newnode = (type, None, context, []) # <<<<<<<<<<<<<< + * self.stack[-1] = (dfa, newstate, node) + * self.stack.append((newdfa, 0, newnode)) + */ + __pyx_3 = PyList_New(0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 133; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = PyTuple_New(4); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 133; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_v_type); + Py_INCREF(Py_None); + PyTuple_SET_ITEM(__pyx_1, 1, Py_None); + Py_INCREF(__pyx_v_context); + PyTuple_SET_ITEM(__pyx_1, 2, __pyx_v_context); + PyTuple_SET_ITEM(__pyx_1, 3, ((PyObject *)__pyx_3)); + __pyx_3 = 0; + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = ((PyObject *)__pyx_1); + __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":134 + * dfa, state, node = self.stack[-1] + * newnode = (type, None, context, []) + * self.stack[-1] = (dfa, newstate, node) # <<<<<<<<<<<<<< + * self.stack.append((newdfa, 0, newnode)) + * + */ + __pyx_2 = PyTuple_New(3); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 134; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_dfa); + PyTuple_SET_ITEM(__pyx_2, 0, __pyx_v_dfa); + Py_INCREF(__pyx_v_newstate); + PyTuple_SET_ITEM(__pyx_2, 1, __pyx_v_newstate); + Py_INCREF(__pyx_v_node); + PyTuple_SET_ITEM(__pyx_2, 2, __pyx_v_node); + if (__Pyx_SetItemInt(__pyx_v_self->stack, -1, ((PyObject *)__pyx_2), 0) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 134; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":135 + * newnode = (type, None, context, []) + * self.stack[-1] = (dfa, newstate, node) + * self.stack.append((newdfa, 0, newnode)) # <<<<<<<<<<<<<< + * + * cdef void pop(self): + */ + __pyx_3 = PyTuple_New(3); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 135; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_newdfa); + PyTuple_SET_ITEM(__pyx_3, 0, __pyx_v_newdfa); + Py_INCREF(__pyx_int_0); + PyTuple_SET_ITEM(__pyx_3, 1, __pyx_int_0); + Py_INCREF(__pyx_v_newnode); + PyTuple_SET_ITEM(__pyx_3, 2, __pyx_v_newnode); + __pyx_1 = __Pyx_PyObject_Append(__pyx_v_self->stack, ((PyObject *)__pyx_3)); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 135; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_3)); __pyx_3 = 0; + Py_DECREF(__pyx_1); __pyx_1 = 0; + + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_WriteUnraisable("sphinx.pycode.pgen2.parse.Parser.push"); + __pyx_L0:; + Py_DECREF(__pyx_v_dfa); + Py_DECREF(__pyx_v_state); + Py_DECREF(__pyx_v_node); + Py_DECREF(__pyx_v_newnode); +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":137 + * self.stack.append((newdfa, 0, newnode)) + * + * cdef void pop(self): # <<<<<<<<<<<<<< + * """Pop a nonterminal. (Internal)""" + * popdfa, popstate, popnode = self.stack.pop() + */ + +static void __pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_pop(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self) { + PyObject *__pyx_v_popdfa; + PyObject *__pyx_v_popstate; + PyObject *__pyx_v_popnode; + PyObject *__pyx_v_newnode; + PyObject *__pyx_v_dfa; + PyObject *__pyx_v_state; + PyObject *__pyx_v_node; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + int __pyx_4; + __pyx_v_popdfa = Py_None; Py_INCREF(Py_None); + __pyx_v_popstate = Py_None; Py_INCREF(Py_None); + __pyx_v_popnode = Py_None; Py_INCREF(Py_None); + __pyx_v_newnode = Py_None; Py_INCREF(Py_None); + __pyx_v_dfa = Py_None; Py_INCREF(Py_None); + __pyx_v_state = Py_None; Py_INCREF(Py_None); + __pyx_v_node = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":139 + * cdef void pop(self): + * """Pop a nonterminal. (Internal)""" + * popdfa, popstate, popnode = self.stack.pop() # <<<<<<<<<<<<<< + * newnode = self.convert(popnode) + * if newnode is not None: + */ + __pyx_1 = PyObject_GetAttr(__pyx_v_self->stack, __pyx_kp_pop); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = PyObject_Call(__pyx_1, ((PyObject *)__pyx_empty_tuple), NULL); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + if (PyTuple_CheckExact(__pyx_2) && PyTuple_GET_SIZE(__pyx_2) == 3) { + PyObject* tuple = __pyx_2; + __pyx_3 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_popdfa); + __pyx_v_popdfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_popstate); + __pyx_v_popstate = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_popnode); + __pyx_v_popnode = __pyx_3; + __pyx_3 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + else { + __pyx_1 = PyObject_GetIter(__pyx_2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_popdfa); + __pyx_v_popdfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_popstate); + __pyx_v_popstate = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_popnode); + __pyx_v_popnode = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 139; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":140 + * """Pop a nonterminal. (Internal)""" + * popdfa, popstate, popnode = self.stack.pop() + * newnode = self.convert(popnode) # <<<<<<<<<<<<<< + * if newnode is not None: + * if self.stack: + */ + __pyx_3 = ((struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser *)__pyx_v_self->__pyx_vtab)->convert(__pyx_v_self, __pyx_v_popnode); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 140; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_newnode); + __pyx_v_newnode = __pyx_3; + __pyx_3 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":141 + * popdfa, popstate, popnode = self.stack.pop() + * newnode = self.convert(popnode) + * if newnode is not None: # <<<<<<<<<<<<<< + * if self.stack: + * dfa, state, node = self.stack[-1] + */ + __pyx_4 = (__pyx_v_newnode != Py_None); + if (__pyx_4) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":142 + * newnode = self.convert(popnode) + * if newnode is not None: + * if self.stack: # <<<<<<<<<<<<<< + * dfa, state, node = self.stack[-1] + * node[-1].append(newnode) + */ + __pyx_4 = __Pyx_PyObject_IsTrue(__pyx_v_self->stack); if (unlikely(__pyx_4 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 142; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (__pyx_4) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":143 + * if newnode is not None: + * if self.stack: + * dfa, state, node = self.stack[-1] # <<<<<<<<<<<<<< + * node[-1].append(newnode) + * else: + */ + __pyx_2 = __Pyx_GetItemInt(__pyx_v_self->stack, -1, 0); if (!__pyx_2) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyTuple_CheckExact(__pyx_2) && PyTuple_GET_SIZE(__pyx_2) == 3) { + PyObject* tuple = __pyx_2; + __pyx_3 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_3); + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + } + else { + __pyx_1 = PyObject_GetIter(__pyx_2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 0); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_dfa); + __pyx_v_dfa = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 1); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_state); + __pyx_v_state = __pyx_3; + __pyx_3 = 0; + __pyx_3 = __Pyx_UnpackItem(__pyx_1, 2); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_node); + __pyx_v_node = __pyx_3; + __pyx_3 = 0; + if (__Pyx_EndUnpack(__pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 143; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":144 + * if self.stack: + * dfa, state, node = self.stack[-1] + * node[-1].append(newnode) # <<<<<<<<<<<<<< + * else: + * self.rootnode = newnode + */ + __pyx_3 = __Pyx_GetItemInt(__pyx_v_node, -1, 0); if (!__pyx_3) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 144; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_PyObject_Append(__pyx_3, __pyx_v_newnode); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 144; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_3); __pyx_3 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + goto __pyx_L4; + } + /*else*/ { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":146 + * node[-1].append(newnode) + * else: + * self.rootnode = newnode # <<<<<<<<<<<<<< + * self.rootnode.used_names = self.used_names + * + */ + Py_INCREF(__pyx_v_newnode); + Py_DECREF(__pyx_v_self->rootnode); + __pyx_v_self->rootnode = __pyx_v_newnode; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":147 + * else: + * self.rootnode = newnode + * self.rootnode.used_names = self.used_names # <<<<<<<<<<<<<< + * + * cdef convert(self, raw_node): + */ + if (PyObject_SetAttr(__pyx_v_self->rootnode, __pyx_kp_used_names, __pyx_v_self->used_names) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 147; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + } + __pyx_L4:; + goto __pyx_L3; + } + __pyx_L3:; + + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + __Pyx_WriteUnraisable("sphinx.pycode.pgen2.parse.Parser.pop"); + __pyx_L0:; + Py_DECREF(__pyx_v_popdfa); + Py_DECREF(__pyx_v_popstate); + Py_DECREF(__pyx_v_popnode); + Py_DECREF(__pyx_v_newnode); + Py_DECREF(__pyx_v_dfa); + Py_DECREF(__pyx_v_state); + Py_DECREF(__pyx_v_node); +} + +/* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":149 + * self.rootnode.used_names = self.used_names + * + * cdef convert(self, raw_node): # <<<<<<<<<<<<<< + * type, value, context, children = raw_node + * if children or type in self._grammar_number2symbol: + */ + +static PyObject *__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_convert(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *__pyx_v_self, PyObject *__pyx_v_raw_node) { + PyObject *__pyx_v_type; + PyObject *__pyx_v_value; + PyObject *__pyx_v_context; + PyObject *__pyx_v_children; + PyObject *__pyx_r; + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + int __pyx_3; + Py_ssize_t __pyx_4 = 0; + PyObject *__pyx_5 = 0; + PyObject *__pyx_6 = 0; + __pyx_v_type = Py_None; Py_INCREF(Py_None); + __pyx_v_value = Py_None; Py_INCREF(Py_None); + __pyx_v_context = Py_None; Py_INCREF(Py_None); + __pyx_v_children = Py_None; Py_INCREF(Py_None); + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":150 + * + * cdef convert(self, raw_node): + * type, value, context, children = raw_node # <<<<<<<<<<<<<< + * if children or type in self._grammar_number2symbol: + * # If there's exactly one child, return that child instead of + */ + if (PyTuple_CheckExact(__pyx_v_raw_node) && PyTuple_GET_SIZE(__pyx_v_raw_node) == 4) { + PyObject* tuple = __pyx_v_raw_node; + __pyx_2 = PyTuple_GET_ITEM(tuple, 0); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_type); + __pyx_v_type = __pyx_2; + __pyx_2 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 1); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_value); + __pyx_v_value = __pyx_2; + __pyx_2 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 2); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_context); + __pyx_v_context = __pyx_2; + __pyx_2 = 0; + __pyx_2 = PyTuple_GET_ITEM(tuple, 3); + Py_INCREF(__pyx_2); + Py_DECREF(__pyx_v_children); + __pyx_v_children = __pyx_2; + __pyx_2 = 0; + } + else { + __pyx_1 = PyObject_GetIter(__pyx_v_raw_node); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_UnpackItem(__pyx_1, 0); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_type); + __pyx_v_type = __pyx_2; + __pyx_2 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_1, 1); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_value); + __pyx_v_value = __pyx_2; + __pyx_2 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_1, 2); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_context); + __pyx_v_context = __pyx_2; + __pyx_2 = 0; + __pyx_2 = __Pyx_UnpackItem(__pyx_1, 3); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_v_children); + __pyx_v_children = __pyx_2; + __pyx_2 = 0; + if (__Pyx_EndUnpack(__pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 150; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + } + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":151 + * cdef convert(self, raw_node): + * type, value, context, children = raw_node + * if children or type in self._grammar_number2symbol: # <<<<<<<<<<<<<< + * # If there's exactly one child, return that child instead of + * # creating a new node. + */ + __pyx_2 = __pyx_v_children; + Py_INCREF(__pyx_2); + __pyx_3 = __Pyx_PyObject_IsTrue(__pyx_2); if (unlikely(__pyx_3 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 151; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (!__pyx_3) { + Py_DECREF(__pyx_2); __pyx_2 = 0; + __pyx_3 = (PySequence_Contains(__pyx_v_self->_grammar_number2symbol, __pyx_v_type)); if (unlikely(__pyx_3 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 151; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_2 = __Pyx_PyBool_FromLong(__pyx_3); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 151; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + } + __pyx_3 = __Pyx_PyObject_IsTrue(__pyx_2); if (unlikely(__pyx_3 < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 151; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + if (__pyx_3) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":154 + * # If there's exactly one child, return that child instead of + * # creating a new node. + * if len(children) == 1: # <<<<<<<<<<<<<< + * return children[0] + * return Node(type, children, context=context) + */ + __pyx_4 = PyObject_Length(__pyx_v_children); if (unlikely(__pyx_4 == -1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 154; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = (__pyx_4 == 1); + if (__pyx_3) { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":155 + * # creating a new node. + * if len(children) == 1: + * return children[0] # <<<<<<<<<<<<<< + * return Node(type, children, context=context) + * else: + */ + __pyx_1 = __Pyx_GetItemInt(__pyx_v_children, 0, 0); if (!__pyx_1) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 155; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_r = __pyx_1; + __pyx_1 = 0; + goto __pyx_L0; + goto __pyx_L4; + } + __pyx_L4:; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":156 + * if len(children) == 1: + * return children[0] + * return Node(type, children, context=context) # <<<<<<<<<<<<<< + * else: + * return Leaf(type, value, context=context) + */ + __pyx_2 = __Pyx_GetName(__pyx_m, __pyx_kp_Node); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = PyTuple_New(2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_v_type); + Py_INCREF(__pyx_v_children); + PyTuple_SET_ITEM(__pyx_1, 1, __pyx_v_children); + __pyx_5 = PyDict_New(); if (unlikely(!__pyx_5)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyDict_SetItem(__pyx_5, __pyx_kp_context, __pyx_v_context) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_6 = PyEval_CallObjectWithKeywords(__pyx_2, ((PyObject *)__pyx_1), ((PyObject *)__pyx_5)); if (unlikely(!__pyx_6)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 156; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_5)); __pyx_5 = 0; + __pyx_r = __pyx_6; + __pyx_6 = 0; + goto __pyx_L0; + goto __pyx_L3; + } + /*else*/ { + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":158 + * return Node(type, children, context=context) + * else: + * return Leaf(type, value, context=context) # <<<<<<<<<<<<<< + */ + __pyx_2 = __Pyx_GetName(__pyx_m, __pyx_kp_Leaf); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = PyTuple_New(2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_v_type); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_v_type); + Py_INCREF(__pyx_v_value); + PyTuple_SET_ITEM(__pyx_1, 1, __pyx_v_value); + __pyx_5 = PyDict_New(); if (unlikely(!__pyx_5)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyDict_SetItem(__pyx_5, __pyx_kp_context, __pyx_v_context) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_6 = PyEval_CallObjectWithKeywords(__pyx_2, ((PyObject *)__pyx_1), ((PyObject *)__pyx_5)); if (unlikely(!__pyx_6)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 158; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_2); __pyx_2 = 0; + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + Py_DECREF(((PyObject *)__pyx_5)); __pyx_5 = 0; + __pyx_r = __pyx_6; + __pyx_6 = 0; + goto __pyx_L0; + } + __pyx_L3:; + + __pyx_r = Py_None; Py_INCREF(Py_None); + goto __pyx_L0; + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_5); + Py_XDECREF(__pyx_6); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse.Parser.convert"); + __pyx_r = 0; + __pyx_L0:; + Py_DECREF(__pyx_v_type); + Py_DECREF(__pyx_v_value); + Py_DECREF(__pyx_v_context); + Py_DECREF(__pyx_v_children); + return __pyx_r; +} +static struct __pyx_vtabstruct_6sphinx_6pycode_5pgen2_5parse_Parser __pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser; + +static PyObject *__pyx_tp_new_6sphinx_6pycode_5pgen2_5parse_Parser(PyTypeObject *t, PyObject *a, PyObject *k) { + struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *p; + PyObject *o = (*t->tp_alloc)(t, 0); + if (!o) return 0; + p = ((struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)o); + p->__pyx_vtab = __pyx_vtabptr_6sphinx_6pycode_5pgen2_5parse_Parser; + p->grammar = Py_None; Py_INCREF(Py_None); + p->stack = Py_None; Py_INCREF(Py_None); + p->rootnode = Py_None; Py_INCREF(Py_None); + p->used_names = Py_None; Py_INCREF(Py_None); + p->_grammar_dfas = Py_None; Py_INCREF(Py_None); + p->_grammar_labels = Py_None; Py_INCREF(Py_None); + p->_grammar_keywords = Py_None; Py_INCREF(Py_None); + p->_grammar_tokens = Py_None; Py_INCREF(Py_None); + p->_grammar_number2symbol = Py_None; Py_INCREF(Py_None); + return o; +} + +static void __pyx_tp_dealloc_6sphinx_6pycode_5pgen2_5parse_Parser(PyObject *o) { + struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *p = (struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)o; + Py_XDECREF(p->grammar); + Py_XDECREF(p->stack); + Py_XDECREF(p->rootnode); + Py_XDECREF(p->used_names); + Py_XDECREF(p->_grammar_dfas); + Py_XDECREF(p->_grammar_labels); + Py_XDECREF(p->_grammar_keywords); + Py_XDECREF(p->_grammar_tokens); + Py_XDECREF(p->_grammar_number2symbol); + (*Py_TYPE(o)->tp_free)(o); +} + +static int __pyx_tp_traverse_6sphinx_6pycode_5pgen2_5parse_Parser(PyObject *o, visitproc v, void *a) { + int e; + struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *p = (struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)o; + if (p->grammar) { + e = (*v)(p->grammar, a); if (e) return e; + } + if (p->stack) { + e = (*v)(p->stack, a); if (e) return e; + } + if (p->rootnode) { + e = (*v)(p->rootnode, a); if (e) return e; + } + if (p->used_names) { + e = (*v)(p->used_names, a); if (e) return e; + } + if (p->_grammar_dfas) { + e = (*v)(p->_grammar_dfas, a); if (e) return e; + } + if (p->_grammar_labels) { + e = (*v)(p->_grammar_labels, a); if (e) return e; + } + if (p->_grammar_keywords) { + e = (*v)(p->_grammar_keywords, a); if (e) return e; + } + if (p->_grammar_tokens) { + e = (*v)(p->_grammar_tokens, a); if (e) return e; + } + if (p->_grammar_number2symbol) { + e = (*v)(p->_grammar_number2symbol, a); if (e) return e; + } + return 0; +} + +static int __pyx_tp_clear_6sphinx_6pycode_5pgen2_5parse_Parser(PyObject *o) { + struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *p = (struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser *)o; + PyObject* tmp; + tmp = ((PyObject*)p->grammar); + p->grammar = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->stack); + p->stack = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->rootnode); + p->rootnode = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->used_names); + p->used_names = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_dfas); + p->_grammar_dfas = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_labels); + p->_grammar_labels = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_keywords); + p->_grammar_keywords = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_tokens); + p->_grammar_tokens = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + tmp = ((PyObject*)p->_grammar_number2symbol); + p->_grammar_number2symbol = Py_None; Py_INCREF(Py_None); + Py_XDECREF(tmp); + return 0; +} + +static struct PyMethodDef __pyx_methods_6sphinx_6pycode_5pgen2_5parse_Parser[] = { + {"setup", (PyCFunction)__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_setup, METH_VARARGS|METH_KEYWORDS, 0}, + {"addtoken", (PyCFunction)__pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken, METH_VARARGS|METH_KEYWORDS, __pyx_doc_6sphinx_6pycode_5pgen2_5parse_6Parser_addtoken}, + {0, 0, 0, 0} +}; + +static struct PyMemberDef __pyx_members_6sphinx_6pycode_5pgen2_5parse_Parser[] = { + {"grammar", T_OBJECT, offsetof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser, grammar), 0, 0}, + {"stack", T_OBJECT, offsetof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser, stack), 0, 0}, + {"rootnode", T_OBJECT, offsetof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser, rootnode), 0, 0}, + {"used_names", T_OBJECT, offsetof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser, used_names), 0, 0}, + {0, 0, 0, 0, 0} +}; + +static PyNumberMethods __pyx_tp_as_number_Parser = { + 0, /*nb_add*/ + 0, /*nb_subtract*/ + 0, /*nb_multiply*/ + #if PY_MAJOR_VERSION < 3 + 0, /*nb_divide*/ + #endif + 0, /*nb_remainder*/ + 0, /*nb_divmod*/ + 0, /*nb_power*/ + 0, /*nb_negative*/ + 0, /*nb_positive*/ + 0, /*nb_absolute*/ + 0, /*nb_nonzero*/ + 0, /*nb_invert*/ + 0, /*nb_lshift*/ + 0, /*nb_rshift*/ + 0, /*nb_and*/ + 0, /*nb_xor*/ + 0, /*nb_or*/ + #if PY_MAJOR_VERSION < 3 + 0, /*nb_coerce*/ + #endif + 0, /*nb_int*/ + 0, /*nb_long*/ + 0, /*nb_float*/ + #if PY_MAJOR_VERSION < 3 + 0, /*nb_oct*/ + #endif + #if PY_MAJOR_VERSION < 3 + 0, /*nb_hex*/ + #endif + 0, /*nb_inplace_add*/ + 0, /*nb_inplace_subtract*/ + 0, /*nb_inplace_multiply*/ + #if PY_MAJOR_VERSION < 3 + 0, /*nb_inplace_divide*/ + #endif + 0, /*nb_inplace_remainder*/ + 0, /*nb_inplace_power*/ + 0, /*nb_inplace_lshift*/ + 0, /*nb_inplace_rshift*/ + 0, /*nb_inplace_and*/ + 0, /*nb_inplace_xor*/ + 0, /*nb_inplace_or*/ + 0, /*nb_floor_divide*/ + 0, /*nb_true_divide*/ + 0, /*nb_inplace_floor_divide*/ + 0, /*nb_inplace_true_divide*/ + #if (PY_MAJOR_VERSION >= 3) || (Py_TPFLAGS_DEFAULT & Py_TPFLAGS_HAVE_INDEX) + 0, /*nb_index*/ + #endif +}; + +static PySequenceMethods __pyx_tp_as_sequence_Parser = { + 0, /*sq_length*/ + 0, /*sq_concat*/ + 0, /*sq_repeat*/ + 0, /*sq_item*/ + 0, /*sq_slice*/ + 0, /*sq_ass_item*/ + 0, /*sq_ass_slice*/ + 0, /*sq_contains*/ + 0, /*sq_inplace_concat*/ + 0, /*sq_inplace_repeat*/ +}; + +static PyMappingMethods __pyx_tp_as_mapping_Parser = { + 0, /*mp_length*/ + 0, /*mp_subscript*/ + 0, /*mp_ass_subscript*/ +}; + +static PyBufferProcs __pyx_tp_as_buffer_Parser = { + #if PY_MAJOR_VERSION < 3 + 0, /*bf_getreadbuffer*/ + #endif + #if PY_MAJOR_VERSION < 3 + 0, /*bf_getwritebuffer*/ + #endif + #if PY_MAJOR_VERSION < 3 + 0, /*bf_getsegcount*/ + #endif + #if PY_MAJOR_VERSION < 3 + 0, /*bf_getcharbuffer*/ + #endif + #if (PY_MAJOR_VERSION >= 3) || (Py_TPFLAGS_DEFAULT & Py_TPFLAGS_HAVE_NEWBUFFER) + 0, /*bf_getbuffer*/ + #endif + #if (PY_MAJOR_VERSION >= 3) || (Py_TPFLAGS_DEFAULT & Py_TPFLAGS_HAVE_NEWBUFFER) + 0, /*bf_releasebuffer*/ + #endif +}; + +PyTypeObject __pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser = { + PyVarObject_HEAD_INIT(0, 0) + "sphinx.pycode.pgen2.parse.Parser", /*tp_name*/ + sizeof(struct __pyx_obj_6sphinx_6pycode_5pgen2_5parse_Parser), /*tp_basicsize*/ + 0, /*tp_itemsize*/ + __pyx_tp_dealloc_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_dealloc*/ + 0, /*tp_print*/ + 0, /*tp_getattr*/ + 0, /*tp_setattr*/ + 0, /*tp_compare*/ + 0, /*tp_repr*/ + &__pyx_tp_as_number_Parser, /*tp_as_number*/ + &__pyx_tp_as_sequence_Parser, /*tp_as_sequence*/ + &__pyx_tp_as_mapping_Parser, /*tp_as_mapping*/ + 0, /*tp_hash*/ + 0, /*tp_call*/ + 0, /*tp_str*/ + 0, /*tp_getattro*/ + 0, /*tp_setattro*/ + &__pyx_tp_as_buffer_Parser, /*tp_as_buffer*/ + Py_TPFLAGS_DEFAULT|Py_TPFLAGS_CHECKTYPES|Py_TPFLAGS_BASETYPE|Py_TPFLAGS_HAVE_GC, /*tp_flags*/ + 0, /*tp_doc*/ + __pyx_tp_traverse_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_traverse*/ + __pyx_tp_clear_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_clear*/ + 0, /*tp_richcompare*/ + 0, /*tp_weaklistoffset*/ + 0, /*tp_iter*/ + 0, /*tp_iternext*/ + __pyx_methods_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_methods*/ + __pyx_members_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_members*/ + 0, /*tp_getset*/ + 0, /*tp_base*/ + 0, /*tp_dict*/ + 0, /*tp_descr_get*/ + 0, /*tp_descr_set*/ + 0, /*tp_dictoffset*/ + __pyx_pf_6sphinx_6pycode_5pgen2_5parse_6Parser___init__, /*tp_init*/ + 0, /*tp_alloc*/ + __pyx_tp_new_6sphinx_6pycode_5pgen2_5parse_Parser, /*tp_new*/ + 0, /*tp_free*/ + 0, /*tp_is_gc*/ + 0, /*tp_bases*/ + 0, /*tp_mro*/ + 0, /*tp_cache*/ + 0, /*tp_subclasses*/ + 0, /*tp_weaklist*/ +}; + +static struct PyMethodDef __pyx_methods[] = { + {0, 0, 0, 0} +}; + +static void __pyx_init_filenames(void); /*proto*/ + +#if PY_MAJOR_VERSION >= 3 +static struct PyModuleDef __pyx_moduledef = { + PyModuleDef_HEAD_INIT, + "parse", + 0, /* m_doc */ + -1, /* m_size */ + __pyx_methods /* m_methods */, + NULL, /* m_reload */ + NULL, /* m_traverse */ + NULL, /* m_clear */ + NULL /* m_free */ +}; +#endif + +static __Pyx_StringTabEntry __pyx_string_tab[] = { + {&__pyx_kp___init__, __pyx_k___init__, sizeof(__pyx_k___init__), 0, 1, 1}, + {&__pyx_kp_setup, __pyx_k_setup, sizeof(__pyx_k_setup), 0, 1, 1}, + {&__pyx_kp_addtoken, __pyx_k_addtoken, sizeof(__pyx_k_addtoken), 0, 1, 1}, + {&__pyx_kp_1, __pyx_k_1, sizeof(__pyx_k_1), 1, 1, 1}, + {&__pyx_kp_Node, __pyx_k_Node, sizeof(__pyx_k_Node), 1, 1, 1}, + {&__pyx_kp_Leaf, __pyx_k_Leaf, sizeof(__pyx_k_Leaf), 1, 1, 1}, + {&__pyx_kp_ParseError, __pyx_k_ParseError, sizeof(__pyx_k_ParseError), 0, 1, 1}, + {&__pyx_kp_Exception, __pyx_k_Exception, sizeof(__pyx_k_Exception), 1, 1, 1}, + {&__pyx_kp_msg, __pyx_k_msg, sizeof(__pyx_k_msg), 1, 1, 1}, + {&__pyx_kp_type, __pyx_k_type, sizeof(__pyx_k_type), 1, 1, 1}, + {&__pyx_kp_value, __pyx_k_value, sizeof(__pyx_k_value), 1, 1, 1}, + {&__pyx_kp_context, __pyx_k_context, sizeof(__pyx_k_context), 1, 1, 1}, + {&__pyx_kp_dfas, __pyx_k_dfas, sizeof(__pyx_k_dfas), 1, 1, 1}, + {&__pyx_kp_labels, __pyx_k_labels, sizeof(__pyx_k_labels), 1, 1, 1}, + {&__pyx_kp_keywords, __pyx_k_keywords, sizeof(__pyx_k_keywords), 1, 1, 1}, + {&__pyx_kp_tokens, __pyx_k_tokens, sizeof(__pyx_k_tokens), 1, 1, 1}, + {&__pyx_kp_4, __pyx_k_4, sizeof(__pyx_k_4), 1, 1, 1}, + {&__pyx_kp_start, __pyx_k_start, sizeof(__pyx_k_start), 1, 1, 1}, + {&__pyx_kp_add, __pyx_k_add, sizeof(__pyx_k_add), 1, 1, 1}, + {&__pyx_kp_get, __pyx_k_get, sizeof(__pyx_k_get), 1, 1, 1}, + {&__pyx_kp_append, __pyx_k_append, sizeof(__pyx_k_append), 1, 1, 1}, + {&__pyx_kp_pop, __pyx_k_pop, sizeof(__pyx_k_pop), 1, 1, 1}, + {&__pyx_kp_used_names, __pyx_k_used_names, sizeof(__pyx_k_used_names), 1, 1, 1}, + {&__pyx_kp_2, __pyx_k_2, sizeof(__pyx_k_2), 0, 0, 0}, + {&__pyx_kp_3, __pyx_k_3, sizeof(__pyx_k_3), 0, 0, 0}, + {&__pyx_kp_5, __pyx_k_5, sizeof(__pyx_k_5), 0, 0, 0}, + {&__pyx_kp_6, __pyx_k_6, sizeof(__pyx_k_6), 0, 0, 0}, + {&__pyx_kp_7, __pyx_k_7, sizeof(__pyx_k_7), 0, 0, 0}, + {0, 0, 0, 0, 0, 0} +}; +static int __Pyx_InitCachedBuiltins(void) { + __pyx_builtin_Exception = __Pyx_GetName(__pyx_b, __pyx_kp_Exception); if (!__pyx_builtin_Exception) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + return 0; + __pyx_L1_error:; + return -1; +} + +static int __Pyx_InitGlobals(void) { + __pyx_int_0 = PyInt_FromLong(0); if (unlikely(!__pyx_int_0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + __pyx_int_1 = PyInt_FromLong(1); if (unlikely(!__pyx_int_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + if (__Pyx_InitStrings(__pyx_string_tab) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + return 0; + __pyx_L1_error:; + return -1; +} + +#if PY_MAJOR_VERSION < 3 +PyMODINIT_FUNC initparse(void); /*proto*/ +PyMODINIT_FUNC initparse(void) +#else +PyMODINIT_FUNC PyInit_parse(void); /*proto*/ +PyMODINIT_FUNC PyInit_parse(void) +#endif +{ + PyObject *__pyx_1 = 0; + PyObject *__pyx_2 = 0; + PyObject *__pyx_3 = 0; + PyObject *__pyx_4 = 0; + __pyx_empty_tuple = PyTuple_New(0); if (unlikely(!__pyx_empty_tuple)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + /*--- Libary function declarations ---*/ + __pyx_init_filenames(); + /*--- Initialize various global constants etc. ---*/ + if (unlikely(__Pyx_InitGlobals() < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + /*--- Module creation code ---*/ + #if PY_MAJOR_VERSION < 3 + __pyx_m = Py_InitModule4("parse", __pyx_methods, 0, 0, PYTHON_API_VERSION); + #else + __pyx_m = PyModule_Create(&__pyx_moduledef); + #endif + if (!__pyx_m) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + #if PY_MAJOR_VERSION < 3 + Py_INCREF(__pyx_m); + #endif + __pyx_b = PyImport_AddModule(__Pyx_BUILTIN_MODULE_NAME); + if (!__pyx_b) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + if (PyObject_SetAttrString(__pyx_m, "__builtins__", __pyx_b) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;}; + /*--- Builtin init code ---*/ + if (unlikely(__Pyx_InitCachedBuiltins() < 0)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 1; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_skip_dispatch = 0; + /*--- Global init code ---*/ + /*--- Function export code ---*/ + /*--- Type init code ---*/ + __pyx_vtabptr_6sphinx_6pycode_5pgen2_5parse_Parser = &__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.classify = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_classify; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.shift = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_shift; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.push = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_push; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.pop = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_pop; + *(void(**)(void))&__pyx_vtable_6sphinx_6pycode_5pgen2_5parse_Parser.convert = (void(*)(void))__pyx_f_6sphinx_6pycode_5pgen2_5parse_6Parser_convert; + if (PyType_Ready(&__pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 31; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (__Pyx_SetVtable(__pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser.tp_dict, __pyx_vtabptr_6sphinx_6pycode_5pgen2_5parse_Parser) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 31; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyObject_SetAttrString(__pyx_m, "Parser", (PyObject *)&__pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 31; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_ptype_6sphinx_6pycode_5pgen2_5parse_Parser = &__pyx_type_6sphinx_6pycode_5pgen2_5parse_Parser; + /*--- Type import code ---*/ + /*--- Function import code ---*/ + /*--- Execution code ---*/ + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":15 + * """ + * + * from sphinx.pycode.nodes import Node, Leaf # <<<<<<<<<<<<<< + * + * DEF NAME = 1 + */ + __pyx_1 = PyList_New(2); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_kp_Node); + PyList_SET_ITEM(__pyx_1, 0, __pyx_kp_Node); + Py_INCREF(__pyx_kp_Leaf); + PyList_SET_ITEM(__pyx_1, 1, __pyx_kp_Leaf); + __pyx_2 = __Pyx_Import(__pyx_kp_1, ((PyObject *)__pyx_1)); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + __pyx_1 = PyObject_GetAttr(__pyx_2, __pyx_kp_Node); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyObject_SetAttr(__pyx_m, __pyx_kp_Node, __pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + __pyx_1 = PyObject_GetAttr(__pyx_2, __pyx_kp_Leaf); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + if (PyObject_SetAttr(__pyx_m, __pyx_kp_Leaf, __pyx_1) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 15; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + Py_DECREF(__pyx_2); __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":19 + * DEF NAME = 1 + * + * class ParseError(Exception): # <<<<<<<<<<<<<< + * """Exception to signal the parser is stuck.""" + * + */ + __pyx_2 = PyDict_New(); if (unlikely(!__pyx_2)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_1 = PyTuple_New(1); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_INCREF(__pyx_builtin_Exception); + PyTuple_SET_ITEM(__pyx_1, 0, __pyx_builtin_Exception); + if (PyDict_SetItemString(((PyObject *)__pyx_2), "__doc__", __pyx_kp_2) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_3 = __Pyx_CreateClass(((PyObject *)__pyx_1), ((PyObject *)__pyx_2), __pyx_kp_ParseError, "sphinx.pycode.pgen2.parse"); if (unlikely(!__pyx_3)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(((PyObject *)__pyx_1)); __pyx_1 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":22 + * """Exception to signal the parser is stuck.""" + * + * def __init__(self, msg, type, value, context): # <<<<<<<<<<<<<< + * Exception.__init__(self, "%s: type=%r, value=%r, context=%r" % + * (msg, type, value, context)) + */ + __pyx_1 = PyCFunction_New(&__pyx_mdef_6sphinx_6pycode_5pgen2_5parse_10ParseError___init__, 0); if (unlikely(!__pyx_1)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 22; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + __pyx_4 = PyMethod_New(__pyx_1, 0, __pyx_3); if (unlikely(!__pyx_4)) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 22; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_1); __pyx_1 = 0; + if (PyObject_SetAttr(__pyx_3, __pyx_kp___init__, __pyx_4) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 22; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_4); __pyx_4 = 0; + if (PyObject_SetAttr(__pyx_m, __pyx_kp_ParseError, __pyx_3) < 0) {__pyx_filename = __pyx_f[0]; __pyx_lineno = 19; __pyx_clineno = __LINE__; goto __pyx_L1_error;} + Py_DECREF(__pyx_3); __pyx_3 = 0; + Py_DECREF(((PyObject *)__pyx_2)); __pyx_2 = 0; + + /* "/home/gbr/devel/sphinx/sphinx/pycode/pgen2/parse.pyx":149 + * self.rootnode.used_names = self.used_names + * + * cdef convert(self, raw_node): # <<<<<<<<<<<<<< + * type, value, context, children = raw_node + * if children or type in self._grammar_number2symbol: + */ + #if PY_MAJOR_VERSION < 3 + return; + #else + return __pyx_m; + #endif + __pyx_L1_error:; + Py_XDECREF(__pyx_1); + Py_XDECREF(__pyx_2); + Py_XDECREF(__pyx_3); + Py_XDECREF(__pyx_4); + __Pyx_AddTraceback("sphinx.pycode.pgen2.parse"); + #if PY_MAJOR_VERSION >= 3 + return NULL; + #endif +} + +static const char *__pyx_filenames[] = { + "parse.pyx", +}; + +/* Runtime support code */ + +static void __pyx_init_filenames(void) { + __pyx_f = __pyx_filenames; +} + +static INLINE void __Pyx_RaiseArgtupleTooLong( + Py_ssize_t num_expected, + Py_ssize_t num_found) +{ + const char* error_message = + #if PY_VERSION_HEX < 0x02050000 + "function takes at most %d positional arguments (%d given)"; + #else + "function takes at most %zd positional arguments (%zd given)"; + #endif + PyErr_Format(PyExc_TypeError, error_message, num_expected, num_found); +} + +static PyObject *__Pyx_Import(PyObject *name, PyObject *from_list) { + PyObject *__import__ = 0; + PyObject *empty_list = 0; + PyObject *module = 0; + PyObject *global_dict = 0; + PyObject *empty_dict = 0; + PyObject *list; + __import__ = PyObject_GetAttrString(__pyx_b, "__import__"); + if (!__import__) + goto bad; + if (from_list) + list = from_list; + else { + empty_list = PyList_New(0); + if (!empty_list) + goto bad; + list = empty_list; + } + global_dict = PyModule_GetDict(__pyx_m); + if (!global_dict) + goto bad; + empty_dict = PyDict_New(); + if (!empty_dict) + goto bad; + module = PyObject_CallFunction(__import__, "OOOO", + name, global_dict, empty_dict, list); +bad: + Py_XDECREF(empty_list); + Py_XDECREF(__import__); + Py_XDECREF(empty_dict); + return module; +} + +static PyObject *__Pyx_GetName(PyObject *dict, PyObject *name) { + PyObject *result; + result = PyObject_GetAttr(dict, name); + if (!result) + PyErr_SetObject(PyExc_NameError, name); + return result; +} + +static PyObject *__Pyx_CreateClass( + PyObject *bases, PyObject *dict, PyObject *name, char *modname) +{ + PyObject *py_modname; + PyObject *result = 0; + + #if PY_MAJOR_VERSION < 3 + py_modname = PyString_FromString(modname); + #else + py_modname = PyUnicode_FromString(modname); + #endif + if (!py_modname) + goto bad; + if (PyDict_SetItemString(dict, "__module__", py_modname) < 0) + goto bad; + #if PY_MAJOR_VERSION < 3 + result = PyClass_New(bases, dict, name); + #else + result = PyObject_CallFunctionObjArgs((PyObject *)&PyType_Type, name, bases, dict, NULL); + #endif +bad: + Py_XDECREF(py_modname); + return result; +} + + +static PyObject *__Pyx_UnpackItem(PyObject *iter, Py_ssize_t index) { + PyObject *item; + if (!(item = PyIter_Next(iter))) { + if (!PyErr_Occurred()) { + PyErr_Format(PyExc_ValueError, + #if PY_VERSION_HEX < 0x02050000 + "need more than %d values to unpack", (int)index); + #else + "need more than %zd values to unpack", index); + #endif + } + } + return item; +} + +static int __Pyx_EndUnpack(PyObject *iter) { + PyObject *item; + if ((item = PyIter_Next(iter))) { + Py_DECREF(item); + PyErr_SetString(PyExc_ValueError, "too many values to unpack"); + return -1; + } + else if (!PyErr_Occurred()) + return 0; + else + return -1; +} + +static void __Pyx_Raise(PyObject *type, PyObject *value, PyObject *tb) { + Py_XINCREF(type); + Py_XINCREF(value); + Py_XINCREF(tb); + /* First, check the traceback argument, replacing None with NULL. */ + if (tb == Py_None) { + Py_DECREF(tb); + tb = 0; + } + else if (tb != NULL && !PyTraceBack_Check(tb)) { + PyErr_SetString(PyExc_TypeError, + "raise: arg 3 must be a traceback or None"); + goto raise_error; + } + /* Next, replace a missing value with None */ + if (value == NULL) { + value = Py_None; + Py_INCREF(value); + } + #if PY_VERSION_HEX < 0x02050000 + if (!PyClass_Check(type)) + #else + if (!PyType_Check(type)) + #endif + { + /* Raising an instance. The value should be a dummy. */ + if (value != Py_None) { + PyErr_SetString(PyExc_TypeError, + "instance exception may not have a separate value"); + goto raise_error; + } + /* Normalize to raise , */ + Py_DECREF(value); + value = type; + #if PY_VERSION_HEX < 0x02050000 + if (PyInstance_Check(type)) { + type = (PyObject*) ((PyInstanceObject*)type)->in_class; + Py_INCREF(type); + } + else { + type = 0; + PyErr_SetString(PyExc_TypeError, + "raise: exception must be an old-style class or instance"); + goto raise_error; + } + #else + type = (PyObject*) Py_TYPE(type); + Py_INCREF(type); + if (!PyType_IsSubtype((PyTypeObject *)type, (PyTypeObject *)PyExc_BaseException)) { + PyErr_SetString(PyExc_TypeError, + "raise: exception class must be a subclass of BaseException"); + goto raise_error; + } + #endif + } + PyErr_Restore(type, value, tb); + return; +raise_error: + Py_XDECREF(value); + Py_XDECREF(type); + Py_XDECREF(tb); + return; +} + + +static void __Pyx_WriteUnraisable(const char *name) { + PyObject *old_exc, *old_val, *old_tb; + PyObject *ctx; + PyErr_Fetch(&old_exc, &old_val, &old_tb); + #if PY_MAJOR_VERSION < 3 + ctx = PyString_FromString(name); + #else + ctx = PyUnicode_FromString(name); + #endif + PyErr_Restore(old_exc, old_val, old_tb); + if (!ctx) + ctx = Py_None; + PyErr_WriteUnraisable(ctx); +} + +static int __Pyx_SetVtable(PyObject *dict, void *vtable) { + PyObject *pycobj = 0; + int result; + + pycobj = PyCObject_FromVoidPtr(vtable, 0); + if (!pycobj) + goto bad; + if (PyDict_SetItemString(dict, "__pyx_vtable__", pycobj) < 0) + goto bad; + result = 0; + goto done; + +bad: + result = -1; +done: + Py_XDECREF(pycobj); + return result; +} + +#include "compile.h" +#include "frameobject.h" +#include "traceback.h" + +static void __Pyx_AddTraceback(const char *funcname) { + PyObject *py_srcfile = 0; + PyObject *py_funcname = 0; + PyObject *py_globals = 0; + PyObject *empty_string = 0; + PyCodeObject *py_code = 0; + PyFrameObject *py_frame = 0; + + #if PY_MAJOR_VERSION < 3 + py_srcfile = PyString_FromString(__pyx_filename); + #else + py_srcfile = PyUnicode_FromString(__pyx_filename); + #endif + if (!py_srcfile) goto bad; + if (__pyx_clineno) { + #if PY_MAJOR_VERSION < 3 + py_funcname = PyString_FromFormat( "%s (%s:%d)", funcname, __pyx_cfilenm, __pyx_clineno); + #else + py_funcname = PyUnicode_FromFormat( "%s (%s:%d)", funcname, __pyx_cfilenm, __pyx_clineno); + #endif + } + else { + #if PY_MAJOR_VERSION < 3 + py_funcname = PyString_FromString(funcname); + #else + py_funcname = PyUnicode_FromString(funcname); + #endif + } + if (!py_funcname) goto bad; + py_globals = PyModule_GetDict(__pyx_m); + if (!py_globals) goto bad; + #if PY_MAJOR_VERSION < 3 + empty_string = PyString_FromStringAndSize("", 0); + #else + empty_string = PyBytes_FromStringAndSize("", 0); + #endif + if (!empty_string) goto bad; + py_code = PyCode_New( + 0, /*int argcount,*/ + #if PY_MAJOR_VERSION >= 3 + 0, /*int kwonlyargcount,*/ + #endif + 0, /*int nlocals,*/ + 0, /*int stacksize,*/ + 0, /*int flags,*/ + empty_string, /*PyObject *code,*/ + __pyx_empty_tuple, /*PyObject *consts,*/ + __pyx_empty_tuple, /*PyObject *names,*/ + __pyx_empty_tuple, /*PyObject *varnames,*/ + __pyx_empty_tuple, /*PyObject *freevars,*/ + __pyx_empty_tuple, /*PyObject *cellvars,*/ + py_srcfile, /*PyObject *filename,*/ + py_funcname, /*PyObject *name,*/ + __pyx_lineno, /*int firstlineno,*/ + empty_string /*PyObject *lnotab*/ + ); + if (!py_code) goto bad; + py_frame = PyFrame_New( + PyThreadState_Get(), /*PyThreadState *tstate,*/ + py_code, /*PyCodeObject *code,*/ + py_globals, /*PyObject *globals,*/ + 0 /*PyObject *locals*/ + ); + if (!py_frame) goto bad; + py_frame->f_lineno = __pyx_lineno; + PyTraceBack_Here(py_frame); +bad: + Py_XDECREF(py_srcfile); + Py_XDECREF(py_funcname); + Py_XDECREF(empty_string); + Py_XDECREF(py_code); + Py_XDECREF(py_frame); +} + +static int __Pyx_InitStrings(__Pyx_StringTabEntry *t) { + while (t->p) { + #if PY_MAJOR_VERSION < 3 + if (t->is_unicode && (!t->is_identifier)) { + *t->p = PyUnicode_DecodeUTF8(t->s, t->n - 1, NULL); + } else if (t->intern) { + *t->p = PyString_InternFromString(t->s); + } else { + *t->p = PyString_FromStringAndSize(t->s, t->n - 1); + } + #else /* Python 3+ has unicode identifiers */ + if (t->is_identifier || (t->is_unicode && t->intern)) { + *t->p = PyUnicode_InternFromString(t->s); + } else if (t->is_unicode) { + *t->p = PyUnicode_FromStringAndSize(t->s, t->n - 1); + } else { + *t->p = PyBytes_FromStringAndSize(t->s, t->n - 1); + } + #endif + if (!*t->p) + return -1; + ++t; + } + return 0; +} + +/* Type Conversion Functions */ + +static INLINE Py_ssize_t __pyx_PyIndex_AsSsize_t(PyObject* b) { + Py_ssize_t ival; + PyObject* x = PyNumber_Index(b); + if (!x) return -1; + ival = PyInt_AsSsize_t(x); + Py_DECREF(x); + return ival; +} + +static INLINE int __Pyx_PyObject_IsTrue(PyObject* x) { + if (x == Py_True) return 1; + else if (x == Py_False) return 0; + else return PyObject_IsTrue(x); +} + +static INLINE PY_LONG_LONG __pyx_PyInt_AsLongLong(PyObject* x) { + if (PyInt_CheckExact(x)) { + return PyInt_AS_LONG(x); + } + else if (PyLong_CheckExact(x)) { + return PyLong_AsLongLong(x); + } + else { + PY_LONG_LONG val; + PyObject* tmp = PyNumber_Int(x); if (!tmp) return (PY_LONG_LONG)-1; + val = __pyx_PyInt_AsLongLong(tmp); + Py_DECREF(tmp); + return val; + } +} + +static INLINE unsigned PY_LONG_LONG __pyx_PyInt_AsUnsignedLongLong(PyObject* x) { + if (PyInt_CheckExact(x)) { + long val = PyInt_AS_LONG(x); + if (unlikely(val < 0)) { + PyErr_SetString(PyExc_TypeError, "Negative assignment to unsigned type."); + return (unsigned PY_LONG_LONG)-1; + } + return val; + } + else if (PyLong_CheckExact(x)) { + return PyLong_AsUnsignedLongLong(x); + } + else { + PY_LONG_LONG val; + PyObject* tmp = PyNumber_Int(x); if (!tmp) return (PY_LONG_LONG)-1; + val = __pyx_PyInt_AsUnsignedLongLong(tmp); + Py_DECREF(tmp); + return val; + } +} + + +static INLINE unsigned char __pyx_PyInt_unsigned_char(PyObject* x) { + if (sizeof(unsigned char) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + unsigned char val = (unsigned char)long_val; + if (unlikely((val != long_val) || (long_val < 0))) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to unsigned char"); + return (unsigned char)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE unsigned short __pyx_PyInt_unsigned_short(PyObject* x) { + if (sizeof(unsigned short) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + unsigned short val = (unsigned short)long_val; + if (unlikely((val != long_val) || (long_val < 0))) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to unsigned short"); + return (unsigned short)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE char __pyx_PyInt_char(PyObject* x) { + if (sizeof(char) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + char val = (char)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to char"); + return (char)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE short __pyx_PyInt_short(PyObject* x) { + if (sizeof(short) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + short val = (short)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to short"); + return (short)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE int __pyx_PyInt_int(PyObject* x) { + if (sizeof(int) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + int val = (int)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to int"); + return (int)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE long __pyx_PyInt_long(PyObject* x) { + if (sizeof(long) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + long val = (long)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to long"); + return (long)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE signed char __pyx_PyInt_signed_char(PyObject* x) { + if (sizeof(signed char) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + signed char val = (signed char)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to signed char"); + return (signed char)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE signed short __pyx_PyInt_signed_short(PyObject* x) { + if (sizeof(signed short) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + signed short val = (signed short)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to signed short"); + return (signed short)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE signed int __pyx_PyInt_signed_int(PyObject* x) { + if (sizeof(signed int) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + signed int val = (signed int)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to signed int"); + return (signed int)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE signed long __pyx_PyInt_signed_long(PyObject* x) { + if (sizeof(signed long) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + signed long val = (signed long)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to signed long"); + return (signed long)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + +static INLINE long double __pyx_PyInt_long_double(PyObject* x) { + if (sizeof(long double) < sizeof(long)) { + long long_val = __pyx_PyInt_AsLong(x); + long double val = (long double)long_val; + if (unlikely((val != long_val) )) { + PyErr_SetString(PyExc_OverflowError, "value too large to convert to long double"); + return (long double)-1; + } + return val; + } + else { + return __pyx_PyInt_AsLong(x); + } +} + diff --git a/sphinx/pycode/pgen2/parse.pyx b/sphinx/pycode/pgen2/parse.pyx index 6a11ee6b..537d7393 100644 --- a/sphinx/pycode/pgen2/parse.pyx +++ b/sphinx/pycode/pgen2/parse.pyx @@ -1,6 +1,8 @@ # Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. # Licensed to PSF under a Contributor Agreement. +# Adapted from parse.py to be compiled with Cython by Georg Brandl. + """Parser engine for the grammar tables generated by pgen. The grammar table must be loaded first. @@ -10,7 +12,7 @@ how this parsing engine works. """ -from sphinx.pycode.pytree import Node, Leaf +from sphinx.pycode.nodes import Node, Leaf DEF NAME = 1 diff --git a/sphinx/pycode/pytree.py b/sphinx/pycode/pytree.py deleted file mode 100644 index 063e39ec..00000000 --- a/sphinx/pycode/pytree.py +++ /dev/null @@ -1,293 +0,0 @@ -# Copyright 2006 Google, Inc. All Rights Reserved. -# Licensed to PSF under a Contributor Agreement. - -"""Python parse tree definitions. - -This is a very concrete parse tree; we need to keep every token and -even the comments and whitespace between tokens. - -Adapted for read-only nodes from pytree.py in Python's 2to3 tool, and -added a few bits. -""" - -__author__ = "Guido van Rossum " - - -class Base(object): - - """Abstract base class for Node and Leaf. - - This provides some default functionality and boilerplate using the - template pattern. - - A node may be a subnode of at most one parent. - """ - - # Default values for instance variables - type = None # int: token number (< 256) or symbol number (>= 256) - parent = None # Parent node pointer, or None - children = () # Tuple of subnodes - was_changed = False - - def __eq__(self, other): - """Compares two nodes for equality. - - This calls the method _eq(). - """ - if self.__class__ is not other.__class__: - return NotImplemented - return self._eq(other) - - def __ne__(self, other): - """Compares two nodes for inequality. - - This calls the method _eq(). - """ - if self.__class__ is not other.__class__: - return NotImplemented - return not self._eq(other) - - def _eq(self, other): - """Compares two nodes for equality. - - This is called by __eq__ and __ne__. It is only called if the - two nodes have the same type. This must be implemented by the - concrete subclass. Nodes should be considered equal if they - have the same structure, ignoring the prefix string and other - context information. - """ - raise NotImplementedError - - def get_lineno(self): - """Returns the line number which generated the invocant node.""" - node = self - while not isinstance(node, Leaf): - if not node.children: - return - node = node.children[0] - return node.lineno - - def get_next_sibling(self): - """Return the node immediately following the invocant in their - parent's children list. If the invocant does not have a next - sibling, return None.""" - if self.parent is None: - return None - - # Can't use index(); we need to test by identity - for i, child in enumerate(self.parent.children): - if child is self: - try: - return self.parent.children[i+1] - except IndexError: - return None - - def get_prev_sibling(self): - """Return the node immediately preceding the invocant in their - parent's children list. If the invocant does not have a previous - sibling, return None.""" - if self.parent is None: - return None - - # Can't use index(); we need to test by identity - for i, child in enumerate(self.parent.children): - if child is self: - if i == 0: - return None - return self.parent.children[i-1] - - def get_prev_leaf(self): - """Return the leaf node that precedes this node in the parse tree.""" - def last_child(node): - if isinstance(node, Leaf): - return node - elif not node.children: - return None - else: - return last_child(node.children[-1]) - if self.parent is None: - return None - prev = self.get_prev_sibling() - if isinstance(prev, Leaf): - return prev - elif prev is not None: - return last_child(prev) - return self.parent.get_prev_leaf() - - def get_suffix(self): - """Return the string immediately following the invocant node. This - is effectively equivalent to node.get_next_sibling().get_prefix()""" - next_sib = self.get_next_sibling() - if next_sib is None: - return "" - return next_sib.get_prefix() - - -class Node(Base): - - """Concrete implementation for interior nodes.""" - - def __init__(self, type, children, context=None): - """Initializer. - - Takes a type constant (a symbol number >= 256), a sequence of - child nodes, and an optional context keyword argument. - - As a side effect, the parent pointers of the children are updated. - """ - # assert type >= 256, type - self.type = type - self.children = list(children) - for ch in self.children: - # assert ch.parent is None, repr(ch) - ch.parent = self - # if prefix is not None: - # self.set_prefix(prefix) - - def __repr__(self): - return "%s(%s, %r)" % (self.__class__.__name__, - self.type, self.children) - - def __str__(self): - """This reproduces the input source exactly.""" - return "".join(map(str, self.children)) - - def compact(self): - return ''.join(child.compact() for child in self.children) - - def __getitem__(self, index): - return self.children[index] - - def __iter__(self): - return iter(self.children) - - def __len__(self): - return len(self.children) - - def _eq(self, other): - """Compares two nodes for equality.""" - return (self.type, self.children) == (other.type, other.children) - - def post_order(self): - """Returns a post-order iterator for the tree.""" - for child in self.children: - for node in child.post_order(): - yield node - yield self - - def pre_order(self): - """Returns a pre-order iterator for the tree.""" - yield self - for child in self.children: - for node in child.post_order(): - yield node - - def get_prefix(self): - """Returns the prefix for the node. - - This passes the call on to the first child. - """ - if not self.children: - return "" - return self.children[0].get_prefix() - - -class Leaf(Base): - - """Concrete implementation for leaf nodes.""" - - # Default values for instance variables - prefix = "" # Whitespace and comments preceding this token in the input - lineno = 0 # Line where this token starts in the input - column = 0 # Column where this token tarts in the input - - def __init__(self, type, value, context=None): - """Initializer. - - Takes a type constant (a token number < 256), a string value, - and an optional context keyword argument. - """ - # assert 0 <= type < 256, type - if context is not None: - self.prefix, (self.lineno, self.column) = context - self.type = type - self.value = value - # if prefix is not None: - # self.prefix = prefix - - def __repr__(self): - return "%s(%r, %r, %r)" % (self.__class__.__name__, - self.type, self.value, self.prefix) - - def __str__(self): - """This reproduces the input source exactly.""" - return self.prefix + str(self.value) - - def compact(self): - return str(self.value) - - def _eq(self, other): - """Compares two nodes for equality.""" - return (self.type, self.value) == (other.type, other.value) - - def post_order(self): - """Returns a post-order iterator for the tree.""" - yield self - - def pre_order(self): - """Returns a pre-order iterator for the tree.""" - yield self - - def get_prefix(self): - """Returns the prefix for the node.""" - return self.prefix - - -def convert(grammar, raw_node): - """Convert raw node to a Node or Leaf instance.""" - type, value, context, children = raw_node - if children or type in grammar.number2symbol: - # If there's exactly one child, return that child instead of - # creating a new node. - if len(children) == 1: - return children[0] - return Node(type, children, context=context) - else: - return Leaf(type, value, context=context) - - -def nice_repr(node, number2name, prefix=False): - def _repr(node): - if isinstance(node, Leaf): - return "%s(%r)" % (number2name[node.type], node.value) - else: - return "%s(%s)" % (number2name[node.type], - ', '.join(map(_repr, node.children))) - def _prepr(node): - if isinstance(node, Leaf): - return "%s(%r, %r)" % (number2name[node.type], node.prefix, node.value) - else: - return "%s(%s)" % (number2name[node.type], - ', '.join(map(_prepr, node.children))) - return (prefix and _prepr or _repr)(node) - - -class NodeVisitor(object): - def __init__(self, number2name, *args): - self.number2name = number2name - self.init(*args) - - def init(self, *args): - pass - - def visit(self, node): - """Visit a node.""" - method = 'visit_' + self.number2name[node.type] - visitor = getattr(self, method, self.generic_visit) - return visitor(node) - - def generic_visit(self, node): - """Called if no explicit visitor function exists for a node.""" - if isinstance(node, Node): - for child in node: - self.visit(child) -- cgit v1.2.1 From 57ad5365be590f8e65ac4a85fef5cb685fa08b55 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 1 Jan 2009 23:49:32 +0100 Subject: Fix long line. --- sphinx/pycode/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index d707db2d..03481233 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -233,8 +233,8 @@ class ModuleAnalyzer(object): indent += 1 elif type == token.DEDENT: indent -= 1 - # if the stacklevel is the same as it was before the last def/class block, - # this dedent closes that block + # if the stacklevel is the same as it was before the last + # def/class block, this dedent closes that block if stack and indent == stack[-1][3]: dtype, fullname, startline, _ = stack.pop() endline = spos[0] -- cgit v1.2.1 From 5d006c40aabdf9aad10f7871a55db4416d80d98a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 2 Jan 2009 00:25:29 +0100 Subject: Add lines and start-after/end-before options to literalinclude. --- sphinx/directives/code.py | 63 +++++++++++++++++++++++++++++++++-------------- sphinx/util/__init__.py | 25 ++++++++++++++++++- 2 files changed, 69 insertions(+), 19 deletions(-) diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index cc74566d..07fceaae 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -3,7 +3,7 @@ sphinx.directives.code ~~~~~~~~~~~~~~~~~~~~~~ - :copyright: 2007-2008 by Georg Brandl. + :copyright: 2007-2009 by Georg Brandl. :license: BSD, see LICENSE for details. """ @@ -15,6 +15,7 @@ from docutils import nodes from docutils.parsers.rst import directives from sphinx import addnodes +from sphinx.util import parselinenos # ------ highlight directive -------------------------------------------------------- @@ -68,19 +69,9 @@ def literalinclude_directive(name, arguments, options, content, lineno, lineno - state_machine.input_offset - 1))) fn = path.normpath(path.join(source_dir, rel_fn)) - fromline = toline = None - objectname = options.get('pyobject') - if objectname is not None: - from sphinx.pycode import ModuleAnalyzer - analyzer = ModuleAnalyzer.for_file(fn, '') - tags = analyzer.find_tags() - if objectname not in tags: - return [state.document.reporter.warning( - 'Object named %r not found in include file %r' % - (objectname, arguments[0]), line=lineno)] - else: - fromline = tags[objectname][1] - 1 - toline = tags[objectname][2] - 1 + if 'pyobject' in options and 'lines' in options: + return [state.document.reporter.warning( + 'Cannot use both "pyobject" and "lines" options', line=lineno)] encoding = options.get('encoding', env.config.source_encoding) try: @@ -96,7 +87,43 @@ def literalinclude_directive(name, arguments, options, content, lineno, 'Encoding %r used for reading included file %r seems to ' 'be wrong, try giving an :encoding: option' % (encoding, arguments[0]))] - text = ''.join(lines[fromline:toline]) + + objectname = options.get('pyobject') + if objectname is not None: + from sphinx.pycode import ModuleAnalyzer + analyzer = ModuleAnalyzer.for_file(fn, '') + tags = analyzer.find_tags() + if objectname not in tags: + return [state.document.reporter.warning( + 'Object named %r not found in include file %r' % + (objectname, arguments[0]), line=lineno)] + else: + lines = lines[tags[objectname][1] - 1 : tags[objectname][2]] + + linespec = options.get('lines') + if linespec is not None: + try: + linelist = parselinenos(linespec, len(lines)) + except ValueError, err: + return [state.document.reporter.warning(str(err), line=lineno)] + lines = [lines[i] for i in linelist] + + startafter = options.get('start-after') + endbefore = options.get('end-before') + if startafter is not None or endbefore is not None: + use = not startafter + res = [] + for line in lines: + if not use and startafter in line: + use = True + elif use and endbefore in line: + use = False + break + elif use: + res.append(line) + lines = res + + text = ''.join(lines) retnode = nodes.literal_block(text, text, source=fn) retnode.line = 1 if options.get('language', ''): @@ -110,9 +137,9 @@ literalinclude_directive.options = {'linenos': directives.flag, 'language': directives.unchanged_required, 'encoding': directives.encoding, 'pyobject': directives.unchanged_required, - #'lines': directives.unchanged_required, - #'start-after': directives.unchanged_required, - #'end-before': directives.unchanged_required, + 'lines': directives.unchanged_required, + 'start-after': directives.unchanged_required, + 'end-before': directives.unchanged_required, } literalinclude_directive.content = 0 literalinclude_directive.arguments = (1, 0, 0) diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index e25bc5a1..fbd7d243 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -5,7 +5,7 @@ Utility functions for Sphinx. - :copyright: 2007-2008 by Georg Brandl. + :copyright: 2007-2009 by Georg Brandl. :license: BSD, see LICENSE for details. """ @@ -324,3 +324,26 @@ class FilenameUniqDict(dict): def __setstate__(self, state): self._existing = state + + +def parselinenos(spec, total): + """ + Parse a line number spec (such as "1,2,4-6") and return a list of + wanted line numbers. + """ + items = list() + parts = spec.split(',') + for part in parts: + try: + begend = part.strip().split('-') + if len(begend) > 2: + raise ValueError + if len(begend) == 1: + items.append(int(begend[0])-1) + else: + start = (begend[0] == '') and 0 or int(begend[0])-1 + end = (begend[1] == '') and total or int(begend[1]) + items.extend(xrange(start, end)) + except Exception, err: + raise ValueError('invalid line number spec: %r' % spec) + return items -- cgit v1.2.1 From 8429841e5c11fa1e3ce5c56dd7070c1bd21a51ec Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 2 Jan 2009 00:32:02 +0100 Subject: Document new literalinclude options. --- doc/markup/code.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 2fd51c84..0bf8343b 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -123,10 +123,25 @@ Includes This would only include the code lines belonging to the ``start()`` method in the ``Timer`` class within the file. + Alternately, you can specify exactly which lines to include by giving a + ``lines`` option:: + + .. literalinclude:: example.py + :lines: 1,3,5-10,20- + + This includes the lines 1, 3, 5 to 10 and lines 20 to the last line. + + Another way to control which part of the file is included is to use the + ``start-after`` and ``end-before`` options (or only one of them). If + ``start-after`` is given as a string option, only lines that follow the first + line containing that string are included. If ``end-before`` is given as a + string option, only lines that precede the first lines containing that string + are included. + .. versionadded:: 0.4.3 The ``encoding`` option. .. versionadded:: 0.6 - The ``pyobject`` option. + The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options. .. rubric:: Footnotes -- cgit v1.2.1 From 531600d1bb35018f59774a7ff89a433a84aeb81e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 12:29:42 +0100 Subject: Add tests for new literalinclude options, and fix an off-by-one bug. --- sphinx/directives/code.py | 2 +- tests/root/includes.txt | 22 ++++++++++++++++++++++ tests/root/literal.inc | 9 +++++++++ tests/test_build.py | 36 +++++++++++++++++++++++++----------- tests/test_markup.py | 2 ++ 5 files changed, 59 insertions(+), 12 deletions(-) diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 07fceaae..80836689 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -98,7 +98,7 @@ def literalinclude_directive(name, arguments, options, content, lineno, 'Object named %r not found in include file %r' % (objectname, arguments[0]), line=lineno)] else: - lines = lines[tags[objectname][1] - 1 : tags[objectname][2]] + lines = lines[tags[objectname][1] - 1 : tags[objectname][2] - 1] linespec = options.get('lines') if linespec is not None: diff --git a/tests/root/includes.txt b/tests/root/includes.txt index d2964d3f..44e33af0 100644 --- a/tests/root/includes.txt +++ b/tests/root/includes.txt @@ -15,6 +15,28 @@ Test file and literal inclusion .. include:: wrongenc.inc :encoding: latin-1 +Literalinclude options +====================== + +.. highlight:: text + +.. cssclass:: inc-pyobj1 +.. literalinclude:: literal.inc + :pyobject: Foo + +.. cssclass:: inc-pyobj2 +.. literalinclude:: literal.inc + :pyobject: Bar.baz + +.. cssclass:: inc-lines +.. literalinclude:: literal.inc + :lines: 6-7,9 + +.. cssclass:: inc-startend +.. literalinclude:: literal.inc + :start-after: coding: utf-8 + :end-before: class Foo + Testing downloadable files ========================== diff --git a/tests/root/literal.inc b/tests/root/literal.inc index a4ce93d2..d5b9890c 100644 --- a/tests/root/literal.inc +++ b/tests/root/literal.inc @@ -2,3 +2,12 @@ # -*- coding: utf-8 -*- foo = u"Including Unicode characters: üöä" + +class Foo: + pass + +class Bar: + def baz(): + pass + +def bar(): pass diff --git a/tests/test_build.py b/tests/test_build.py index 91506dad..0ac5380e 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -10,6 +10,7 @@ """ import os +import re import sys import difflib import htmlentitydefs @@ -32,7 +33,7 @@ WARNING: %(root)s/images.txt:9: Image file not readable: foo.png WARNING: %(root)s/images.txt:23: Nonlocal image URI found: http://www.python.org/logo.png WARNING: %(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading included \ file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option -WARNING: %(root)s/includes.txt:34: Download file not readable: nonexisting.png +WARNING: %(root)s/includes.txt:56: Download file not readable: nonexisting.png """ HTML_WARNINGS = ENV_WARNINGS + """\ @@ -61,11 +62,19 @@ HTML_XPATH = { ".//pre": u'Max Strauß', ".//a[@href='_downloads/img.png']": '', ".//a[@href='_downloads/img1.png']": '', + ".//div[@class='inc-pyobj1 highlight-text']/div/pre": + r'^class Foo:\n pass\n\s*$', + ".//div[@class='inc-pyobj2 highlight-text']/div/pre": + r'^ def baz\(\):\n pass\n\s*$', + ".//div[@class='inc-lines highlight-text']/div/pre": + r'^class Foo:\n pass\nclass Bar:\n$', + ".//div[@class='inc-startend highlight-text']/div/pre": + ur'^foo = u"Including Unicode characters: üöä"\n$', }, 'autodoc.html': { ".//dt[@id='test_autodoc.Class']": '', - ".//dt[@id='test_autodoc.function']/em": '**kwds', - ".//dd": 'Return spam.', + ".//dt[@id='test_autodoc.function']/em": r'\*\*kwds', + ".//dd": r'Return spam\.', }, 'markup.html': { ".//meta[@name='author'][@content='Me']": '', @@ -81,7 +90,7 @@ HTML_XPATH = { }, 'contents.html': { ".//meta[@name='hc'][@content='hcval']": '', - ".//td[@class='label']": '[Ref1]', + ".//td[@class='label']": r'\[Ref1\]', ".//li[@class='toctree-l1']/a": 'Testing various markup', ".//li[@class='toctree-l2']/a": 'Admonitions', ".//title": 'Sphinx ', @@ -117,18 +126,23 @@ def test_html(app): parser = NslessParser() parser.entity.update(htmlentitydefs.entitydefs) etree = ET.parse(os.path.join(app.outdir, fname), parser) - for path, text in paths.iteritems(): + for path, check in paths.iteritems(): nodes = list(etree.findall(path)) assert nodes != [] - if not text: + if callable(check): + check(nodes) + elif not check: # only check for node presence continue - for node in nodes: - if node.text and text in node.text: - break else: - assert False, ('%r not found in any node matching ' - 'path %s in %s' % (text, path, fname)) + rex = re.compile(check) + for node in nodes: + if node.text and rex.search(node.text): + break + else: + assert False, ('%r not found in any node matching ' + 'path %s in %s: %r' % (check, path, fname, + [node.text for node in nodes])) @with_app(buildername='latex', warning=latex_warnfile) diff --git a/tests/test_markup.py b/tests/test_markup.py index 86889a2a..29583866 100644 --- a/tests/test_markup.py +++ b/tests/test_markup.py @@ -17,11 +17,13 @@ from docutils import frontend, utils, nodes from docutils.parsers import rst from sphinx import addnodes +from sphinx.util import texescape from sphinx.writers.html import HTMLWriter, SmartyPantsHTMLTranslator from sphinx.writers.latex import LaTeXWriter, LaTeXTranslator def setup_module(): global app, settings, parser + texescape.init() # otherwise done by the latex builder app = TestApp(cleanenv=True) optparser = frontend.OptionParser(components=(rst.Parser, HTMLWriter, LaTeXWriter)) settings = optparser.get_default_values() -- cgit v1.2.1 From 01ca953cbeae8082d8d28c0e3ee2d856eef8a865 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 13:29:26 +0100 Subject: Add OpenLayers. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 1fef388e..d3ac299c 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -26,6 +26,7 @@ included, please mail to `the Google group * NetworkX: http://networkx.lanl.gov/ * NumPy: http://docs.scipy.org/doc/numpy/reference/ * ObjectListView: http://objectlistview.sourceforge.net/python +* OpenLayers: http://docs.openlayers.org/ * Paste: http://pythonpaste.org/script/ * Paver: http://www.blueskyonmars.com/projects/paver/ * Py on Windows: http://timgolden.me.uk/python-on-windows/ -- cgit v1.2.1 From 9b7a7f6c10dd58776179bd405c3eed7b3d81dc29 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 21:18:28 +0100 Subject: Fix bad node value for makevar. --- sphinx/roles.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/roles.py b/sphinx/roles.py index 2bbdab94..d2e9558e 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -24,7 +24,7 @@ generic_docroles = { 'guilabel' : nodes.strong, 'kbd' : nodes.literal, 'mailheader' : addnodes.literal_emphasis, - 'makevar' : nodes.Text, + 'makevar' : nodes.strong, 'manpage' : addnodes.literal_emphasis, 'mimetype' : addnodes.literal_emphasis, 'newsgroup' : addnodes.literal_emphasis, -- cgit v1.2.1 From 615da933a90527588029a1164894c6a8f56ecfce Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 14:39:36 +0100 Subject: Fix a few remaining copyrights and add 2009 to license. --- LICENSE | 2 +- doc/conf.py | 2 +- sphinx/builders/__init__.py | 2 +- sphinx/environment.py | 4 ---- sphinx/jinja2glue.py | 2 +- sphinx/pycode/__init__.py | 2 +- sphinx/pycode/nodes.py | 2 +- sphinx/util/docstrings.py | 2 +- sphinx/util/jsdump.py | 2 +- 9 files changed, 8 insertions(+), 12 deletions(-) diff --git a/LICENSE b/LICENSE index 8b1ad263..faac79f0 100644 --- a/LICENSE +++ b/LICENSE @@ -1,4 +1,4 @@ -Copyright (c) 2007-2008 by the Sphinx team (see AUTHORS file). +Copyright (c) 2007-2009 by the Sphinx team (see AUTHORS file). All rights reserved. License for Sphinx diff --git a/doc/conf.py b/doc/conf.py index 89247821..709d6f75 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -36,7 +36,7 @@ master_doc = 'contents' # General substitutions. project = 'Sphinx' -copyright = '2008, Georg Brandl' +copyright = '2007-2009, Georg Brandl' # The default replacements for |version| and |release|, also used in various # other places throughout the built documents. diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 52b4b0ac..8847b6dc 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -5,7 +5,7 @@ Builder superclass for all builders. - :copyright: 2007-2008 by Georg Brandl, Sebastian Wiesner, Horst Gutmann. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ diff --git a/sphinx/environment.py b/sphinx/environment.py index 0562ce66..b70bd250 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -5,11 +5,7 @@ Global creation environment. -<<<<<<< local - :copyright: 2007-2009 by Georg Brandl. -======= :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. ->>>>>>> other :license: BSD, see LICENSE for details. """ diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index 996df70b..0c7c5d72 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -5,7 +5,7 @@ Glue code for the jinja2 templating engine. - :copyright: 2008 by Sebastian Wiesner. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index 03481233..a61a051a 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -5,7 +5,7 @@ Utilities parsing and analyzing Python code. - :copyright: 2008-2009 by Georg Brandl. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ diff --git a/sphinx/pycode/nodes.py b/sphinx/pycode/nodes.py index d0fb522b..4d27fc66 100644 --- a/sphinx/pycode/nodes.py +++ b/sphinx/pycode/nodes.py @@ -5,7 +5,7 @@ Parse tree node implementations. - :copyright: 2009 by Georg Brandl. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ diff --git a/sphinx/util/docstrings.py b/sphinx/util/docstrings.py index d7e20e4c..1b0a599a 100644 --- a/sphinx/util/docstrings.py +++ b/sphinx/util/docstrings.py @@ -5,7 +5,7 @@ Utilities for docstring processing. - :copyright: 2008 by Georg Brandl. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ diff --git a/sphinx/util/jsdump.py b/sphinx/util/jsdump.py index 2eb4619e..8c760b68 100644 --- a/sphinx/util/jsdump.py +++ b/sphinx/util/jsdump.py @@ -6,7 +6,7 @@ This module implements a simple JavaScript serializer. Uses the basestring encode function from simplejson by Bob Ippolito. - :copyright: Copyright 2008 by the Sphinx team, see AUTHORS. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ -- cgit v1.2.1 From 939e3f37d96e29c260244476caf60ee33c2761ed Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 19:16:52 +0100 Subject: Cache tags and attribute docs in the analyzer. --- sphinx/pycode/__init__.py | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index a61a051a..0141ede4 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -176,6 +176,10 @@ class ModuleAnalyzer(object): self.tokens = None # will be filled by parse() self.parsetree = None + # will be filled by find_attr_docs() + self.attr_docs = None + # will be filled by find_tags() + self.tags = None def tokenize(self): """Generate tokens from the source.""" @@ -193,13 +197,18 @@ class ModuleAnalyzer(object): def find_attr_docs(self, scope=''): """Find class and module-level attributes and their documentation.""" + if self.attr_docs is not None: + return self.attr_docs self.parse() attr_visitor = AttrDocVisitor(number2name, scope) attr_visitor.visit(self.parsetree) + self.attr_docs = attr_visitor.collected return attr_visitor.collected def find_tags(self): """Find class, function and method definitions and their location.""" + if self.tags is not None: + return self.tags self.tokenize() result = {} namespace = [] @@ -246,6 +255,7 @@ class ModuleAnalyzer(object): if defline: defline = False expect_indent = True + self.tags = result return result -- cgit v1.2.1 From 686c154eea969fe7eecc4aec27d922d301be46fc Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 19:35:03 +0100 Subject: Support all types of string literals in literals.py. --- sphinx/pycode/pgen2/literals.py | 54 +++++++++++++++++++++++++++++++++-------- 1 file changed, 44 insertions(+), 10 deletions(-) diff --git a/sphinx/pycode/pgen2/literals.py b/sphinx/pycode/pgen2/literals.py index 0b3948a5..78667df0 100644 --- a/sphinx/pycode/pgen2/literals.py +++ b/sphinx/pycode/pgen2/literals.py @@ -1,6 +1,8 @@ # Copyright 2004-2005 Elemental Security, Inc. All Rights Reserved. # Licensed to PSF under a Contributor Agreement. +# Extended to handle raw and unicode literals by Georg Brandl. + """Safely evaluate Python string literals without using eval().""" import re @@ -16,28 +18,60 @@ simple_escapes = {"a": "\a", '"': '"', "\\": "\\"} +def convert_hex(x, n): + if len(x) < n+1: + raise ValueError("invalid hex string escape ('\\%s')" % x) + try: + return int(x[1:], 16) + except ValueError: + raise ValueError("invalid hex string escape ('\\%s')" % x) + def escape(m): all, tail = m.group(0, 1) assert all.startswith("\\") esc = simple_escapes.get(tail) if esc is not None: return esc - if tail.startswith("x"): - hexes = tail[1:] - if len(hexes) < 2: - raise ValueError("invalid hex string escape ('\\%s')" % tail) + elif tail.startswith("x"): + return chr(convert_hex(tail, 2)) + elif tail.startswith('u'): + return unichr(convert_hex(tail, 4)) + elif tail.startswith('U'): + return unichr(convert_hex(tail, 8)) + elif tail.startswith('N'): + import unicodedata try: - i = int(hexes, 16) - except ValueError: - raise ValueError("invalid hex string escape ('\\%s')" % tail) + return unicodedata.lookup(tail[1:-1]) + except KeyError: + raise ValueError("undefined character name %r" % tail[1:-1]) else: try: - i = int(tail, 8) + return chr(int(tail, 8)) except ValueError: raise ValueError("invalid octal string escape ('\\%s')" % tail) - return chr(i) + +def escaperaw(m): + all, tail = m.group(0, 1) + if tail.startswith('u'): + return unichr(convert_hex(tail, 4)) + elif tail.startswith('U'): + return unichr(convert_hex(tail, 8)) + else: + return all + +escape_re = re.compile(r"\\(\'|\"|\\|[abfnrtv]|x.{0,2}|[0-7]{1,3})") +uni_escape_re = re.compile(r"\\(\'|\"|\\|[abfnrtv]|x.{0,2}|[0-7]{1,3}|" + r"u[0-9a-fA-F]{0,4}|U[0-9a-fA-F]{0,8}|N\{.+?\})") def evalString(s): + regex = escape_re + repl = escape + if s.startswith('u') or s.startswith('U'): + regex = uni_escape_re + s = s[1:] + if s.startswith('r') or s.startswith('R'): + repl = escaperaw + s = s[1:] assert s.startswith("'") or s.startswith('"'), repr(s[:1]) q = s[0] if s[:3] == q*3: @@ -45,7 +79,7 @@ def evalString(s): assert s.endswith(q), repr(s[-len(q):]) assert len(s) >= 2*len(q) s = s[len(q):-len(q)] - return re.sub(r"\\(\'|\"|\\|[abfnrtv]|x.{0,2}|[0-7]{1,3})", escape, s) + return regex.sub(repl, s) def test(): for i in range(256): -- cgit v1.2.1 From 93c8edb25dbab5c219258662ab750aa346aeb0e9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 20:02:24 +0100 Subject: Add support for decoding strings and comments to the analyzer. --- sphinx/pycode/__init__.py | 86 +++++++++++++++++++++++++++-------------- sphinx/pycode/pgen2/literals.py | 4 +- 2 files changed, 59 insertions(+), 31 deletions(-) diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index 0141ede4..17dc6afb 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -9,6 +9,7 @@ :license: BSD, see LICENSE for details. """ +import re import sys from os import path from cStringIO import StringIO @@ -35,6 +36,9 @@ number2name = pygrammar.number2symbol.copy() number2name.update(token.tok_name) +# a regex to recognize coding cookies +_coding_re = re.compile(r'coding[:=]\s*([-\w.]+)') + _eq = nodes.Leaf(token.EQUAL, '=') @@ -46,8 +50,9 @@ class AttrDocVisitor(nodes.NodeVisitor): The docstrings can either be in special '#:' comments before the assignment or in a docstring after it. """ - def init(self, scope): + def init(self, scope, encoding): self.scope = scope + self.encoding = encoding self.namespace = [] self.collected = {} @@ -71,6 +76,7 @@ class AttrDocVisitor(nodes.NodeVisitor): if not pnode or pnode.type not in (token.INDENT, token.DEDENT): break prefix = pnode.get_prefix() + prefix = prefix.decode(self.encoding) docstring = prepare_commentdoc(prefix) if docstring: self.add_docstring(node, docstring) @@ -86,7 +92,8 @@ class AttrDocVisitor(nodes.NodeVisitor): if prev.type == sym.simple_stmt and \ prev[0].type == sym.expr_stmt and _eq in prev[0].children: # need to "eval" the string because it's returned in its original form - docstring = prepare_docstring(literals.evalString(node[0].value)) + docstring = literals.evalString(node[0].value, self.encoding) + docstring = prepare_docstring(docstring) self.add_docstring(prev[0], docstring) def visit_funcdef(self, node): @@ -136,38 +143,48 @@ class ModuleAnalyzer(object): @classmethod def for_module(cls, modname): if ('module', modname) in cls.cache: - return cls.cache['module', modname] - if modname not in sys.modules: - try: - __import__(modname) - except ImportError, err: - raise PycodeError('error importing %r' % modname, err) - mod = sys.modules[modname] - if hasattr(mod, '__loader__'): - try: - source = mod.__loader__.get_source(modname) - except Exception, err: - raise PycodeError('error getting source for %r' % modname, err) - obj = cls.for_string(source, modname) - cls.cache['module', modname] = obj - return obj - filename = getattr(mod, '__file__', None) - if filename is None: - raise PycodeError('no source found for module %r' % modname) - filename = path.normpath(filename) - lfilename = filename.lower() - if lfilename.endswith('.pyo') or lfilename.endswith('.pyc'): - filename = filename[:-1] - elif not lfilename.endswith('.py'): - raise PycodeError('source is not a .py file: %r' % filename) - if not path.isfile(filename): - raise PycodeError('source file is not present: %r' % filename) - obj = cls.for_file(filename, modname) + entry = cls.cache['module', modname] + if isinstance(entry, PycodeError): + raise entry + return entry + + try: + if modname not in sys.modules: + try: + __import__(modname) + except ImportError, err: + raise PycodeError('error importing %r' % modname, err) + mod = sys.modules[modname] + if hasattr(mod, '__loader__'): + try: + source = mod.__loader__.get_source(modname) + except Exception, err: + raise PycodeError('error getting source for %r' % modname, err) + obj = cls.for_string(source, modname) + cls.cache['module', modname] = obj + return obj + filename = getattr(mod, '__file__', None) + if filename is None: + raise PycodeError('no source found for module %r' % modname) + filename = path.normpath(filename) + lfilename = filename.lower() + if lfilename.endswith('.pyo') or lfilename.endswith('.pyc'): + filename = filename[:-1] + elif not lfilename.endswith('.py'): + raise PycodeError('source is not a .py file: %r' % filename) + if not path.isfile(filename): + raise PycodeError('source file is not present: %r' % filename) + obj = cls.for_file(filename, modname) + except PycodeError, err: + cls.cache['module', modname] = err + raise cls.cache['module', modname] = obj return obj def __init__(self, source, modname, srcname): + # name of the module self.modname = modname + # name of the source file self.srcname = srcname # file-like object yielding source lines self.source = source @@ -194,13 +211,22 @@ class ModuleAnalyzer(object): return self.tokenize() self.parsetree = pydriver.parse_tokens(self.tokens) + # find the source code encoding + encoding = sys.getdefaultencoding() + comments = self.parsetree.get_prefix() + for line in comments.splitlines()[:2]: + match = _coding_re.search(line) + if match is not None: + encoding = match.group(1) + break + self.encoding = encoding def find_attr_docs(self, scope=''): """Find class and module-level attributes and their documentation.""" if self.attr_docs is not None: return self.attr_docs self.parse() - attr_visitor = AttrDocVisitor(number2name, scope) + attr_visitor = AttrDocVisitor(number2name, scope, self.encoding) attr_visitor.visit(self.parsetree) self.attr_docs = attr_visitor.collected return attr_visitor.collected diff --git a/sphinx/pycode/pgen2/literals.py b/sphinx/pycode/pgen2/literals.py index 78667df0..31900291 100644 --- a/sphinx/pycode/pgen2/literals.py +++ b/sphinx/pycode/pgen2/literals.py @@ -63,9 +63,11 @@ escape_re = re.compile(r"\\(\'|\"|\\|[abfnrtv]|x.{0,2}|[0-7]{1,3})") uni_escape_re = re.compile(r"\\(\'|\"|\\|[abfnrtv]|x.{0,2}|[0-7]{1,3}|" r"u[0-9a-fA-F]{0,4}|U[0-9a-fA-F]{0,8}|N\{.+?\})") -def evalString(s): +def evalString(s, encoding=None): regex = escape_re repl = escape + if encoding: + s = s.decode(encoding) if s.startswith('u') or s.startswith('U'): regex = uni_escape_re s = s[1:] -- cgit v1.2.1 From 7570f70ab99020eeacc640aa69ff03da58341901 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 20:27:37 +0100 Subject: Add new tests for the attribute feature and fix existing tests. --- sphinx/ext/autodoc.py | 108 +++++++++++++++++++----------------------------- sphinx/util/__init__.py | 14 +++++++ tests/test_autodoc.py | 65 ++++++++++++++++++++--------- 3 files changed, 102 insertions(+), 85 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index c8faa0da..60ebd5b5 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -21,7 +21,7 @@ from docutils import nodes from docutils.parsers.rst import directives from docutils.statemachine import ViewList -from sphinx.util import rpartition, nested_parse_with_titles +from sphinx.util import rpartition, nested_parse_with_titles, force_decode from sphinx.pycode import ModuleAnalyzer, PycodeError from sphinx.util.docstrings import prepare_docstring @@ -31,8 +31,6 @@ try: except NameError: base_exception = Exception -_charset_re = re.compile(r'coding[:=]\s*([-\w.]+)') -_module_charsets = {} py_ext_sig_re = re.compile( r'''^ ([\w.]+::)? # explicit module name @@ -173,27 +171,6 @@ def isdescriptor(x): return False -def get_module_charset(module): - """Return the charset of the given module (cached in _module_charsets).""" - if module in _module_charsets: - return _module_charsets[module] - try: - filename = __import__(module, None, None, ['foo']).__file__ - except (ImportError, AttributeError): - return None - if filename[-4:].lower() in ('.pyc', '.pyo'): - filename = filename[:-1] - for line in [linecache.getline(filename, x) for x in (1, 2)]: - match = _charset_re.search(line) - if match is not None: - charset = match.group(1) - break - else: - charset = 'ascii' - _module_charsets[module] = charset - return charset - - class RstGenerator(object): def __init__(self, options, document, lineno): self.options = options @@ -207,15 +184,19 @@ class RstGenerator(object): def warn(self, msg): self.warnings.append(self.reporter.warning(msg, line=self.lineno)) - def get_doc(self, what, name, obj): - """Format and yield lines of the docstring(s) for the object.""" + def get_doc(self, what, obj, encoding=None): + """Decode and return lines of the docstring(s) for the object.""" docstrings = [] + + # add the regular docstring if present if getattr(obj, '__doc__', None): docstrings.append(obj.__doc__) - # skip some lines in module docstrings if configured + + # skip some lines in module docstrings if configured (deprecated!) if what == 'module' and self.env.config.automodule_skip_lines and docstrings: docstrings[0] = '\n'.join(docstrings[0].splitlines() [self.env.config.automodule_skip_lines:]) + # for classes, what the "docstring" is can be controlled via an option if what in ('class', 'exception'): content = self.env.config.autoclass_content @@ -231,24 +212,12 @@ class RstGenerator(object): docstrings.append(initdocstring) # the default is only the class docstring - # decode the docstrings using the module's source encoding - charset = None - module = getattr(obj, '__module__', None) - if module is not None: - charset = get_module_charset(module) + # make sure we get Unicode docstrings + return [force_decode(docstring, encoding) for docstring in docstrings] - for docstring in docstrings: - if isinstance(docstring, str): - if charset: - docstring = docstring.decode(charset) - else: - try: - # try decoding with utf-8, should only work for real UTF-8 - docstring = docstring.decode('utf-8') - except UnicodeError: - # last resort -- can't fail - docstring = docstring.decode('latin1') - docstringlines = prepare_docstring(docstring) + def process_doc(self, docstrings, what, name, obj): + """Let the user process the docstrings.""" + for docstringlines in docstrings: if self.env.app: # let extensions preprocess docstrings self.env.app.emit('autodoc-process-docstring', @@ -397,24 +366,25 @@ class RstGenerator(object): # now, import the module and get object to document try: - todoc = module = __import__(mod, None, None, ['foo']) - if hasattr(module, '__file__') and module.__file__: - modfile = module.__file__ - if modfile[-4:].lower() in ('.pyc', '.pyo'): - modfile = modfile[:-1] - self.filename_set.add(modfile) - else: - modfile = None # e.g. for builtin and C modules + __import__(mod) + todoc = module = sys.modules[mod] for part in objpath: todoc = getattr(todoc, part) - # also get a source code analyzer for attribute docs - analyzer = ModuleAnalyzer.for_module(mod) except (ImportError, AttributeError, PycodeError), err: self.warn('autodoc can\'t import/find %s %r, it reported error: "%s", ' 'please check your spelling and sys.path' % (what, str(fullname), err)) return + # try to also get a source code analyzer for attribute docs + try: + analyzer = ModuleAnalyzer.for_module(mod) + except PycodeError, err: + # no source file -- e.g. for builtin and C modules + analyzer = None + else: + self.filename_set.add(analyzer.srcname) + # check __module__ of object if wanted (for members not given explicitly) if check_module: if hasattr(todoc, '__module__'): @@ -473,23 +443,29 @@ class RstGenerator(object): if what != 'module': indent += u' ' - if modfile: - sourcename = '%s:docstring of %s' % (modfile, fullname) + # add content from attribute documentation + if analyzer: + sourcename = '%s:docstring of %s' % (analyzer.srcname, fullname) + attr_docs = analyzer.find_attr_docs() + if what in ('data', 'attribute'): + key = ('.'.join(objpath[:-1]), objpath[-1]) + if key in attr_docs: + no_docstring = True + docstrings = [attr_docs[key]] + for i, line in enumerate(self.process_doc(docstrings, what, + fullname, todoc)): + self.result.append(indent + line, sourcename, i) else: sourcename = 'docstring of %s' % fullname - - # add content from attribute documentation - attr_docs = analyzer.find_attr_docs() - if what in ('data', 'attribute'): - key = ('.'.join(objpath[:-1]), objpath[-1]) - if key in attr_docs: - no_docstring = True - for i, line in enumerate(attr_docs[key]): - self.result.append(indent + line, sourcename, i) + attr_docs = {} # add content from docstrings if not no_docstring: - for i, line in enumerate(self.get_doc(what, fullname, todoc)): + encoding = analyzer and analyzer.encoding + docstrings = map(prepare_docstring, + self.get_doc(what, todoc, encoding)) + for i, line in enumerate(self.process_doc(docstrings, what, + fullname, todoc)): self.result.append(indent + line, sourcename, i) # add source content, if present diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index b851e484..4aacf67b 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -347,3 +347,17 @@ def parselinenos(spec, total): except Exception, err: raise ValueError('invalid line number spec: %r' % spec) return items + + +def force_decode(string, encoding): + if isinstance(string, str): + if encoding: + string = string.decode(encoding) + else: + try: + # try decoding with utf-8, should only work for real UTF-8 + string = string.decode('utf-8') + except UnicodeError: + # last resort -- can't fail + string = string.decode('latin1') + return string diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 837b5695..dd9934f5 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -15,6 +15,7 @@ from util import * from docutils.statemachine import ViewList from sphinx.ext.autodoc import RstGenerator, cut_lines, between +from sphinx.util.docstrings import prepare_docstring def setup_module(): @@ -173,13 +174,14 @@ def test_format_signature(): def test_get_doc(): def getdocl(*args): - # strip the empty line at the end - return list(gen.get_doc(*args))[:-1] + ds = map(prepare_docstring, gen.get_doc(*args)) + # for testing purposes, concat them and strip the empty line at the end + return sum(ds, [])[:-1] # objects without docstring def f(): pass - assert getdocl('function', 'f', f) == [] + assert getdocl('function', f) == [] # standard function, diverse docstring styles... def f(): @@ -189,7 +191,7 @@ def test_get_doc(): Docstring """ for func in (f, g): - assert getdocl('function', 'f', func) == ['Docstring'] + assert getdocl('function', func) == ['Docstring'] # first line vs. other lines indentation def f(): @@ -198,17 +200,17 @@ def test_get_doc(): Other lines """ - assert getdocl('function', 'f', f) == ['First line', '', 'Other', ' lines'] + assert getdocl('function', f) == ['First line', '', 'Other', ' lines'] # charset guessing (this module is encoded in utf-8) def f(): """Döcstring""" - assert getdocl('function', 'f', f) == [u'Döcstring'] + assert getdocl('function', f) == [u'Döcstring'] # already-unicode docstrings must be taken literally def f(): u"""Döcstring""" - assert getdocl('function', 'f', f) == [u'Döcstring'] + assert getdocl('function', f) == [u'Döcstring'] # class docstring: depends on config value which one is taken class C: @@ -216,11 +218,11 @@ def test_get_doc(): def __init__(self): """Init docstring""" gen.env.config.autoclass_content = 'class' - assert getdocl('class', 'C', C) == ['Class docstring'] + assert getdocl('class', C) == ['Class docstring'] gen.env.config.autoclass_content = 'init' - assert getdocl('class', 'C', C) == ['Init docstring'] + assert getdocl('class', C) == ['Init docstring'] gen.env.config.autoclass_content = 'both' - assert getdocl('class', 'C', C) == ['Class docstring', '', 'Init docstring'] + assert getdocl('class', C) == ['Class docstring', '', 'Init docstring'] class D: """Class docstring""" @@ -232,18 +234,22 @@ def test_get_doc(): """ # Indentation is normalized for 'both' - assert getdocl('class', 'D', D) == ['Class docstring', '', 'Init docstring', - '', 'Other', ' lines'] + assert getdocl('class', D) == ['Class docstring', '', 'Init docstring', + '', 'Other', ' lines'] + + +def test_docstring_processing(): + def process(what, name, obj): + return list(gen.process_doc(map(prepare_docstring, gen.get_doc(what, obj)), + what, name, obj)) class E: def __init__(self): """Init docstring""" # docstring processing by event handler - assert getdocl('class', 'bar', E) == ['Init docstring', '', '42'] + assert process('class', 'bar', E) == ['Init docstring', '', '42', ''] - -def test_docstring_processing_functions(): lid = app.connect('autodoc-process-docstring', cut_lines(1, 1, ['function'])) def f(): """ @@ -251,7 +257,7 @@ def test_docstring_processing_functions(): second line third line """ - assert list(gen.get_doc('function', 'f', f)) == ['second line', ''] + assert process('function', 'f', f) == ['second line', ''] app.disconnect(lid) lid = app.connect('autodoc-process-docstring', between('---', ['function'])) @@ -263,7 +269,7 @@ def test_docstring_processing_functions(): --- third line """ - assert list(gen.get_doc('function', 'f', f)) == ['second line', ''] + assert process('function', 'f', f) == ['second line', ''] app.disconnect(lid) @@ -289,7 +295,7 @@ def test_generate(): def assert_result_contains(item, *args): gen.generate(*args) - print '\n'.join(gen.result) + #print '\n'.join(gen.result) assert len(gen.warnings) == 0, gen.warnings assert item in gen.result del gen.result[:] @@ -325,7 +331,10 @@ def test_generate(): assert_processes(should, 'class', 'Class', [], None) should.extend([('method', 'test_autodoc.Class.meth')]) assert_processes(should, 'class', 'Class', ['meth'], None) - should.extend([('attribute', 'test_autodoc.Class.prop')]) + should.extend([('attribute', 'test_autodoc.Class.prop'), + ('attribute', 'test_autodoc.Class.attr'), + ('attribute', 'test_autodoc.Class.docattr'), + ('attribute', 'test_autodoc.Class.udocattr')]) assert_processes(should, 'class', 'Class', ['__all__'], None) options.undoc_members = True should.append(('method', 'test_autodoc.Class.undocmeth')) @@ -369,6 +378,11 @@ def test_generate(): ('method', 'test_autodoc.Outer.Inner.meth')], 'class', 'Outer', ['__all__'], None) + # test generation for C modules (which have no source file) + gen.env.currmodule = 'time' + assert_processes([('function', 'time.asctime')], 'function', 'asctime', [], None) + assert_processes([('function', 'time.asctime')], 'function', 'asctime', [], None) + # --- generate fodder ------------ @@ -398,10 +412,22 @@ class Class(Base): """Method that should be skipped.""" pass + # should not be documented + skipattr = 'foo' + + #: should be documented -- süß + attr = 'bar' + @property def prop(self): """Property.""" + docattr = 'baz' + """should likewise be documented -- süß""" + + udocattr = 'quux' + u"""should be documented as well - süß""" + class CustomDict(dict): """Docstring.""" @@ -421,4 +447,5 @@ class Outer(object): def meth(self): """Foo""" + # should be documented as an alias factory = dict -- cgit v1.2.1 From 34c771ec24fc8ac1e8aa6bf82471962692eef20b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 20:43:15 +0100 Subject: Small API change. --- sphinx/ext/autodoc.py | 8 ++++---- tests/test_autodoc.py | 6 ++---- 2 files changed, 6 insertions(+), 8 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 60ebd5b5..35d96bda 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -212,8 +212,9 @@ class RstGenerator(object): docstrings.append(initdocstring) # the default is only the class docstring - # make sure we get Unicode docstrings - return [force_decode(docstring, encoding) for docstring in docstrings] + # make sure we have Unicode docstrings, then sanitize and split into lines + return [prepare_docstring(force_decode(docstring, encoding)) + for docstring in docstrings] def process_doc(self, docstrings, what, name, obj): """Let the user process the docstrings.""" @@ -462,8 +463,7 @@ class RstGenerator(object): # add content from docstrings if not no_docstring: encoding = analyzer and analyzer.encoding - docstrings = map(prepare_docstring, - self.get_doc(what, todoc, encoding)) + docstrings = self.get_doc(what, todoc, encoding) for i, line in enumerate(self.process_doc(docstrings, what, fullname, todoc)): self.result.append(indent + line, sourcename, i) diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index dd9934f5..67220180 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -15,7 +15,6 @@ from util import * from docutils.statemachine import ViewList from sphinx.ext.autodoc import RstGenerator, cut_lines, between -from sphinx.util.docstrings import prepare_docstring def setup_module(): @@ -174,7 +173,7 @@ def test_format_signature(): def test_get_doc(): def getdocl(*args): - ds = map(prepare_docstring, gen.get_doc(*args)) + ds = gen.get_doc(*args) # for testing purposes, concat them and strip the empty line at the end return sum(ds, [])[:-1] @@ -240,8 +239,7 @@ def test_get_doc(): def test_docstring_processing(): def process(what, name, obj): - return list(gen.process_doc(map(prepare_docstring, gen.get_doc(what, obj)), - what, name, obj)) + return list(gen.process_doc(gen.get_doc(what, obj), what, name, obj)) class E: def __init__(self): -- cgit v1.2.1 From 78a34be10800b6ce834212c83a7dfa000778e351 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 20:52:35 +0100 Subject: A few more fixes in autodoc. --- sphinx/ext/autodoc.py | 27 +++++++++++++++------------ 1 file changed, 15 insertions(+), 12 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 35d96bda..be3e3f0f 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -371,7 +371,7 @@ class RstGenerator(object): todoc = module = sys.modules[mod] for part in objpath: todoc = getattr(todoc, part) - except (ImportError, AttributeError, PycodeError), err: + except (ImportError, AttributeError), err: self.warn('autodoc can\'t import/find %s %r, it reported error: "%s", ' 'please check your spelling and sys.path' % (what, str(fullname), err)) @@ -392,6 +392,11 @@ class RstGenerator(object): if todoc.__module__ != mod: return + # make sure that the result starts with an empty line. This is + # necessary for some situations where another directive preprocesses + # reST and no starting newline is present + self.result.append(u'', '') + # format the object's signature, if any try: sig = self.format_signature(what, fullname, todoc, args, retann) @@ -400,11 +405,6 @@ class RstGenerator(object): (fullname, err)) sig = '' - # make sure that the result starts with an empty line. This is - # necessary for some situations where another directive preprocesses - # reST and no starting newline is present - self.result.append(u'', '') - # now, create the directive header if what == 'method': directive = get_method_type(todoc) @@ -430,13 +430,14 @@ class RstGenerator(object): self.result.append(indent + u' :noindex:', '') self.result.append(u'', '') + # add inheritance info, if wanted if self.options.show_inheritance and what in ('class', 'exception'): if len(todoc.__bases__): bases = [b.__module__ == '__builtin__' and u':class:`%s`' % b.__name__ or u':class:`%s.%s`' % (b.__module__, b.__name__) for b in todoc.__bases__] - self.result.append(indent + u' Bases: %s' % ', '.join(bases), + self.result.append(indent + _(u' Bases: %s') % ', '.join(bases), '') self.result.append(u'', '') @@ -468,7 +469,7 @@ class RstGenerator(object): fullname, todoc)): self.result.append(indent + line, sourcename, i) - # add source content, if present + # add additional content (e.g. from document), if present if add_content: for line, src in zip(add_content.data, add_content.items): self.result.append(indent + line, src[0], src[1]) @@ -483,10 +484,10 @@ class RstGenerator(object): if objpath: self.env.autodoc_current_class = objpath[0] - # add members, if possible - all_members = members == ['__all__'] + # look for members to include + want_all_members = members == ['__all__'] members_check_module = False - if all_members: + if want_all_members: # unqualified :members: given if what == 'module': if hasattr(todoc, '__all__'): @@ -524,7 +525,7 @@ class RstGenerator(object): # if content is not None, no extra content from docstrings will be added content = None - if all_members and membername.startswith('_'): + if want_all_members and membername.startswith('_'): # ignore members whose name starts with _ by default skip = True else: @@ -547,6 +548,7 @@ class RstGenerator(object): if skip: continue + # determine member type if what == 'module': if isinstance(member, (FunctionType, BuiltinFunctionType)): memberwhat = 'function' @@ -581,6 +583,7 @@ class RstGenerator(object): memberwhat = 'attribute' else: continue + # give explicitly separated module name, so that members of inner classes # can be documented full_membername = mod + '::' + '.'.join(objpath + [membername]) -- cgit v1.2.1 From 15a06e44095f77c1fdbe3485f837480c2309988b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 21:07:25 +0100 Subject: Add changelog entries for news in pycode branch. --- CHANGES | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGES b/CHANGES index d43a044c..f5b53f9f 100644 --- a/CHANGES +++ b/CHANGES @@ -29,6 +29,9 @@ New features added - #4: Added a ``:download:`` role that marks a non-document file for inclusion into the HTML output and links to it. + - The ``literalinclude`` directive now supports several more + options, to include only parts of a file. + - The ``toctree`` directive now supports a ``:hidden:`` flag, which will prevent links from being generated in place of the directive -- this allows you to define your document @@ -68,6 +71,8 @@ New features added * Extensions and API: + - Autodoc now handles documented attributes. + - Autodoc now handles inner classes and their methods. - There is now a ``Sphinx.add_lexer()`` method to be able to use -- cgit v1.2.1 From afaacbd66760f8ce11ec8d7ea2cdd3d7b22fe3e8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 21:20:51 +0100 Subject: Close #33: add manpages for command-line tools. --- doc/sphinx-build.1 | 96 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/sphinx-quickstart.1 | 17 +++++++++ 2 files changed, 113 insertions(+) create mode 100644 doc/sphinx-build.1 create mode 100644 doc/sphinx-quickstart.1 diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1 new file mode 100644 index 00000000..16f8bd34 --- /dev/null +++ b/doc/sphinx-build.1 @@ -0,0 +1,96 @@ +.TH sphinx-build 1 "Jan 2009" "Sphinx 0.6" "User Commands" +.SH NAME +sphinx-build \- Sphinx documentation generator tool +.SH SYNOPSIS +.B sphinx-build +[\fIoptions\fR] <\fIsourcedir\fR> <\fIoutdir\fR> [\fIfilenames\fR...] +.SH DESCRIPTION +sphinx-build generates documentation from the files in and places it +in the . + +sphinx-build looks for /conf.py for the configuration settings. +.B sphinx-quickstart(1) +may be used to generate template files, including conf.py. + +sphinx-build can create documentation in different formats. A format is +selected by specifying the builder name on the command line; it defaults to +HTML. Builders can also perform other tasks related to documentation +processing. + +By default, everything that is outdated is built. Output only for selected +files can be built by specifying individual filenames. + +List of available builders: +.TP +\fBhtml\fR +HTML files generation. This is default builder. +.TP +\fBhtmlhelp\fR +Generates files for CHM generation. +.TP +\fBqthelp\fR +Generates files for Qt help collection generation. +.TP +\fBlatex\fR +Generates a LaTeX version of the documentation. +.TP +\fBtext\fR +Generates a plain-text version of the documentation. +.TP +\fBchanges\fR +Generates HTML files listing changed/added/deprecated items for the +current version. +.TP +\fBlinkcheck\fR +Checks the integrity of all external links in the documentation. +.TP +\fBpickle / json\fR +Generates serialized HTML files in the selected format. + +.SH OPTIONS +.TP +\fB-b\fR +Builder to use; defaults to html. See the full list of builders above. +.TP +\fB-a\fR +Generates output for all files; without this option only output for +new and changed files is generated. +.TP +\fB-E\fR +Ignores cached files, forces to re-read all source files from disk. +.TP +\fB-c\fR +Locates the conf.py file in the specified path instead of . +.TP +\fB-C\fR +Specifies that no conf.py file at all is to be used. Configuration can +only be set with the -D option. +.TP +\fB-D\fR = +Overrides a setting from the configuration file. +.TP +\fB-d\fR +Path to cached files; defaults to /.doctrees. +.TP +\fB-A\fR = +Passes a value into the HTML templates (only for html builders). +.TP +\fB-N\fR +Prevents colored output. +.TP +\fB-q\fR +Quiet operation, just prints warnings and errors on stderr. +.TP +\fB-Q\fR +Very quiet operation, doesn't print anything except for errors. +.TP +\fB-P\fR +Runs Pdb on exception. +.SH "SEE ALSO" +.BR sphinx-quickstart(1) +.SH AUTHOR +Georg Brandl , Armin Ronacher et +al. +.PP +This manual page was initially written by Mikhail Gusarov +, for the Debian project. diff --git a/doc/sphinx-quickstart.1 b/doc/sphinx-quickstart.1 new file mode 100644 index 00000000..93b0a4a5 --- /dev/null +++ b/doc/sphinx-quickstart.1 @@ -0,0 +1,17 @@ +.TH sphinx-quickstart 1 "Jan 2009" "Sphinx 0.6" "User Commands" +.SH NAME +sphinx-quickstart \- Sphinx documentation template generator +.SH SYNOPSIS +.B sphinx-quickstart +.SH DESCRIPTION +sphinx-quickstart is an interactive tool that asks some questions about your +project and then generates a complete documentation directory and sample +Makefile to be used with \fBsphinx-build(1)\fR. +.SH "SEE ALSO" +.BR sphinx-build(1) +.SH AUTHOR +Georg Brandl , Armin Ronacher et +al. +.PP +This manual page was initially written by Mikhail Gusarov + for the Debian project. -- cgit v1.2.1 From afc0d3fbc313eaca17aee86cbb0993d4f92d55c9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 22:00:40 +0100 Subject: Close #52: There is now a ``hlist`` directive, creating a compact list by placing distributing items into multiple columns. --- CHANGES | 3 +++ doc/markup/para.rst | 21 +++++++++++++++++++++ sphinx/addnodes.py | 6 +++++- sphinx/directives/other.py | 28 ++++++++++++++++++++++++++++ sphinx/writers/html.py | 10 ++++++++++ sphinx/writers/latex.py | 22 ++++++++++++++++++++-- sphinx/writers/text.py | 10 ++++++++++ tests/root/markup.txt | 10 ++++++++++ 8 files changed, 107 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index f5b53f9f..0d2ffbbb 100644 --- a/CHANGES +++ b/CHANGES @@ -37,6 +37,9 @@ New features added the directive -- this allows you to define your document structure, but place the links yourself. + - #52: There is now a ``hlist`` directive, creating a compact + list by placing distributing items into multiple columns. + - #77: If a description environment with info field list only contains one ``:param:`` entry, no bullet list is generated. diff --git a/doc/markup/para.rst b/doc/markup/para.rst index c60eb258..b071e46c 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -100,6 +100,27 @@ units as well as normal text: .. centered:: LICENSE AGREEMENT +.. directive:: hlist + + This directive must contain a bullet list. It will transform it into a more + compact list by either distributing more than one item horizontally, or + reducing spacing between items, depending on the builder. + + For builders that support the horizontal distribution, there is a ``columns`` + option that specifies the number of columns; it defaults to 2. Example:: + + .. hlist:: + :columns: 3 + + * A list of + * short items + * that should be + * displayed + * horizontally + + .. versionadded:: 0.6 + + Table-of-contents markup ------------------------ diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index b267913b..a4af584c 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -74,6 +74,10 @@ class download_reference(nodes.reference): pass # for the ACKS list class acks(nodes.Element): pass +# for horizontal lists +class hlist(nodes.Element): pass +class hlistcol(nodes.Element): pass + # sets the highlighting language for literal blocks class highlightlang(nodes.Element): pass @@ -99,7 +103,7 @@ class meta(nodes.Special, nodes.PreBibliographic, nodes.Element): pass # will choke at some point if these are not added nodes._add_node_class_names("""index desc desc_content desc_signature desc_type desc_returns desc_addname desc_name desc_parameterlist - desc_parameter desc_optional download_reference + desc_parameter desc_optional download_reference hlist hlistcol centered versionmodified seealso productionlist production toctree pending_xref compact_paragraph highlightlang literal_emphasis glossary acks module start_of_file tabular_col_spec meta""".split()) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index f19c4f9b..cbf548be 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -383,6 +383,34 @@ acks_directive.arguments = (0, 0, 0) directives.register_directive('acks', acks_directive) +def hlist_directive(name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + ncolumns = options.get('columns', 2) + node = nodes.paragraph() + state.nested_parse(content, content_offset, node) + if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): + return [state.document.reporter.warning('.. hlist content is not a list', + line=lineno)] + fulllist = node.children[0] + # create a hlist node where the items are distributed + npercol, nmore = divmod(len(fulllist), ncolumns) + index = 0 + newnode = addnodes.hlist() + for column in range(ncolumns): + endindex = index + (column < nmore and (npercol+1) or npercol) + col = addnodes.hlistcol() + col += nodes.bullet_list() + col[0] += fulllist.children[index:endindex] + index = endindex + newnode += col + return [newnode] + +hlist_directive.content = 1 +hlist_directive.arguments = (0, 0, 0) +hlist_directive.options = {'columns': int} +directives.register_directive('hlist', hlist_directive) + + def tabularcolumns_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): # support giving explicit tabulary column definition to latex diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index e34b8fa9..8c1a87ba 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -321,6 +321,16 @@ class HTMLTranslator(BaseTranslator): def depart_module(self, node): pass + def visit_hlist(self, node): + self.body.append('') + def depart_hlist(self, node): + self.body.append('
    \n') + + def visit_hlistcol(self, node): + self.body.append('') + def depart_hlistcol(self, node): + self.body.append('') + def bulk_text_processor(self, text): return text diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index c16a4271..885cac44 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -223,6 +223,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.this_is_the_title = 1 self.literal_whitespace = 0 self.no_contractions = 0 + self.compact_list = 0 def astext(self): return (HEADER % self.elements + self.highlighter.get_stylesheet() + @@ -652,9 +653,11 @@ class LaTeXTranslator(nodes.NodeVisitor): raise nodes.SkipNode def visit_bullet_list(self, node): - self.body.append('\\begin{itemize}\n' ) + if not self.compact_list: + self.body.append('\\begin{itemize}\n' ) def depart_bullet_list(self, node): - self.body.append('\\end{itemize}\n' ) + if not self.compact_list: + self.body.append('\\end{itemize}\n' ) def visit_enumerated_list(self, node): self.body.append('\\begin{enumerate}\n' ) @@ -723,6 +726,21 @@ class LaTeXTranslator(nodes.NodeVisitor): def depart_centered(self, node): self.body.append('\n\\end{centering}') + def visit_hlist(self, node): + # for now, we don't support a more compact list format + # don't add individual itemize environments, but one for all columns + self.compact_list += 1 + self.body.append('\\begin{itemize}\\setlength{\\itemsep}{0pt}' + '\\setlength{\\parskip}{0pt}\n') + def depart_hlist(self, node): + self.compact_list -= 1 + self.body.append('\\end{itemize}\n') + + def visit_hlistcol(self, node): + pass + def depart_hlistcol(self, node): + pass + def visit_module(self, node): modname = node['modname'] self.body.append('\n\\declaremodule[%s]{}{%s}' % (modname.replace('_', ''), diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py index 5c8500fb..4718d41d 100644 --- a/sphinx/writers/text.py +++ b/sphinx/writers/text.py @@ -516,6 +516,16 @@ class TextTranslator(nodes.NodeVisitor): def depart_centered(self, node): pass + def visit_hlist(self, node): + pass + def depart_hlist(self, node): + pass + + def visit_hlistcol(self, node): + pass + def depart_hlistcol(self, node): + pass + def visit_admonition(self, node): self.new_state(0) def depart_admonition(self, node): diff --git a/tests/root/markup.txt b/tests/root/markup.txt index 454762e3..777fbd2f 100644 --- a/tests/root/markup.txt +++ b/tests/root/markup.txt @@ -104,6 +104,16 @@ Reference lookup: [Ref1]_ (defined in another file). `Google `_ For everything. +.. hlist:: + :columns: 4 + + * This + * is + * a horizontal + * list + * with several + * items + .. rubric:: Side note This is a side note. -- cgit v1.2.1 From c663958f6064cc325e271ca5416167716aa65e49 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 22:34:00 +0100 Subject: Add changelog entry for #32. --- CHANGES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGES b/CHANGES index 0d2ffbbb..47cfa672 100644 --- a/CHANGES +++ b/CHANGES @@ -91,6 +91,8 @@ New features added - Source links in HTML are now generated with ``rel="nofollow"``. + - Quickstart can now generate a Windows ``make.bat`` file. + Release 0.5.2 (in development) ============================== -- cgit v1.2.1 From 0d6fd15228d6192dcd4beb763dcdc9ac4652b185 Mon Sep 17 00:00:00 2001 From: Benoit Boissinot Date: Sun, 4 Jan 2009 23:15:38 +0100 Subject: fix #30: disable the search box when javascript isn't available --- sphinx/templates/layout.html | 21 +++++++++++++-------- sphinx/templates/search.html | 6 ++++++ 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index e011f643..29ddf014 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -63,14 +63,19 @@ {% include customsidebar %} {%- endif %} {%- block sidebarsearch %} - {%- if pagename != "search" %} -

    {{ _('Quick search') }}

    -
    - - - -
    -

    {{ _('Enter search terms or a module, class or function name.') }}

    + {%- if pagename != "search" %} + + {%- endif %} {%- endblock %}
    diff --git a/sphinx/templates/search.html b/sphinx/templates/search.html index 545a459b..363f641f 100644 --- a/sphinx/templates/search.html +++ b/sphinx/templates/search.html @@ -3,6 +3,12 @@ {% set script_files = script_files + ['_static/searchtools.js'] %} {% block body %}

    {{ _('Search') }}

    +
    + +

    + {% trans %}Please activate Javascript to enable the search functionality.{% endtrans %} +

    +

    {% trans %}From here you can search these documents. Enter your search words into the box below and click "search". Note that the search -- cgit v1.2.1 From b94c9985e98ca0dca829942c3aac099685296349 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 4 Jan 2009 23:23:54 +0100 Subject: Simplify script snippet, break long lines. --- sphinx/templates/layout.html | 16 +++++++++------- sphinx/templates/search.html | 5 +++-- 2 files changed, 12 insertions(+), 9 deletions(-) diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html index 29ddf014..fb0df9e0 100644 --- a/sphinx/templates/layout.html +++ b/sphinx/templates/layout.html @@ -44,18 +44,21 @@ {%- block sidebarrel %} {%- if prev %}

    {{ _('Previous topic') }}

    -

    {{ prev.title }}

    +

    {{ prev.title }}

    {%- endif %} {%- if next %}

    {{ _('Next topic') }}

    -

    {{ next.title }}

    +

    {{ next.title }}

    {%- endif %} {%- endblock %} {%- block sidebarsourcelink %} {%- if show_source and has_source and sourcename %}

    {{ _('This Page') }}

    {%- endif %} {%- endblock %} @@ -67,15 +70,14 @@ - + {%- endif %} {%- endblock %} diff --git a/sphinx/templates/search.html b/sphinx/templates/search.html index 363f641f..224d87b8 100644 --- a/sphinx/templates/search.html +++ b/sphinx/templates/search.html @@ -3,10 +3,11 @@ {% set script_files = script_files + ['_static/searchtools.js'] %} {% block body %}

    {{ _('Search') }}

    -
    +

    - {% trans %}Please activate Javascript to enable the search functionality.{% endtrans %} + {% trans %}Please activate JavaScript to enable the search + functionality.{% endtrans %}

    -- cgit v1.2.1 From a104927be918b503769e298df9c4ba43a7e1a3e9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 5 Jan 2009 00:04:53 +0100 Subject: Add JQuery license; add PSF copyright statement. --- LICENSE | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/LICENSE b/LICENSE index faac79f0..fb2049a8 100644 --- a/LICENSE +++ b/LICENSE @@ -1,9 +1,9 @@ -Copyright (c) 2007-2009 by the Sphinx team (see AUTHORS file). -All rights reserved. - License for Sphinx ================== +Copyright (c) 2007-2009 by the Sphinx team (see AUTHORS file). +All rights reserved. + Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: @@ -36,6 +36,11 @@ sphinx.pycode.pgen2, is available in the Python 2.6 distribution under the PSF license agreement for Python: ---------------------------------------------------------------------- +Copyright © 2001-2008 Python Software Foundation; All Rights Reserved. + +PYTHON SOFTWARE FOUNDATION LICENSE VERSION 2 +-------------------------------------------- + 1. This LICENSE AGREEMENT is between the Python Software Foundation ("PSF"), and the Individual or Organization ("Licensee") accessing and otherwise using Python 2.6 software in source or binary form @@ -186,3 +191,29 @@ WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. ---------------------------------------------------------------------- + +The included JQuery JavaScript library is available under the MIT +license: + +---------------------------------------------------------------------- +Copyright (c) 2008 John Resig, http://jquery.com/ + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be +included in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +---------------------------------------------------------------------- -- cgit v1.2.1 From 5c28c0bd44c42ddd7e01150d363a0ca0bdcf6b83 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 5 Jan 2009 19:11:52 +0100 Subject: Remove old Jinja 1 bridge. --- sphinx/_jinja.py | 114 ------------------------------------------------------- 1 file changed, 114 deletions(-) delete mode 100644 sphinx/_jinja.py diff --git a/sphinx/_jinja.py b/sphinx/_jinja.py deleted file mode 100644 index fba432c4..00000000 --- a/sphinx/_jinja.py +++ /dev/null @@ -1,114 +0,0 @@ -# -*- coding: utf-8 -*- -""" - sphinx._jinja - ~~~~~~~~~~~~~ - - Jinja glue. - - :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. - :license: BSD, see LICENSE for details. -""" - -import codecs -from os import path - -from sphinx import package_dir -from sphinx.util import mtimes_of_files -from sphinx.application import TemplateBridge - -from jinja import Environment -from jinja.loaders import BaseLoader -from jinja.exceptions import TemplateNotFound - - -def babel_extract(fileobj, keywords, comment_tags, options): - """ - Simple extractor to get some basic Babel support. - """ - env = Environment() - for lineno, sg, pl in env.get_translations_for_string(fileobj.read()): - yield lineno, None, (sg, pl), '' - - -class SphinxFileSystemLoader(BaseLoader): - """ - A loader that loads templates either relative to one of a list of given - paths, or from an absolute path. - """ - - def __init__(self, basepath, extpaths): - self.basepath = path.abspath(basepath) - self.extpaths = map(path.abspath, extpaths) - self.searchpaths = self.extpaths + [self.basepath] - - def get_source(self, environment, name, parent): - name = name.replace('/', path.sep) - if name.startswith('!'): - name = name[1:] - if not path.exists(path.join(self.basepath, name)): - raise TemplateNotFound(name) - filename = path.join(self.basepath, name) - elif path.isabs(name): - if not path.exists(name): - raise TemplateNotFound(name) - filename = name - else: - for searchpath in self.searchpaths: - if path.exists(path.join(searchpath, name)): - filename = path.join(searchpath, name) - break - else: - raise TemplateNotFound(name) - f = codecs.open(filename, 'r', environment.template_charset) - try: - return f.read() - finally: - f.close() - - -class TranslatorEnvironment(Environment): - class _Translator(object): - def __init__(self, translator): - self.trans = translator - - def gettext(self, string): - return self.trans.ugettext(string) - - def ngettext(self, singular, plural, n): - return self.trans.ungettext(singular, plural, n) - - def __init__(self, *args, **kwargs): - self.translator = kwargs['translator'] - del kwargs['translator'] - super(TranslatorEnvironment, self).__init__(*args, **kwargs) - - def get_translator(self, context): - return TranslatorEnvironment._Translator(self.translator) - - -class BuiltinTemplates(TemplateBridge): - def init(self, builder): - self.templates = {} - base_templates_path = path.join(package_dir, 'templates') - ext_templates_path = [path.join(builder.confdir, dir) - for dir in builder.config.templates_path] - self.templates_path = [base_templates_path] + ext_templates_path - loader = SphinxFileSystemLoader(base_templates_path, ext_templates_path) - if builder.translator is not None: - self.jinja_env = TranslatorEnvironment(loader=loader, - friendly_traceback=False, translator=builder.translator) - else: - self.jinja_env = Environment(loader=loader, - # disable traceback, more likely that something - # in the application is broken than in the templates - friendly_traceback=False) - - def newest_template_mtime(self): - return max(mtimes_of_files(self.templates_path, '.html')) - - def render(self, template, context): - if template in self.templates: - return self.templates[template].render(context) - templateobj = self.templates[template] = \ - self.jinja_env.get_template(template) - return templateobj.render(context) -- cgit v1.2.1 From 9d7be98a2d69b979d8c1be5b408ba15c657b37b6 Mon Sep 17 00:00:00 2001 From: gbrandl Date: Mon, 5 Jan 2009 19:19:28 +0100 Subject: Create themes/ subdirectory and move stuff from templates/ and static/ there. --- sphinx/static/contents.png | Bin 202 -> 0 bytes sphinx/static/default.css | 657 --------------------- sphinx/static/doctools.js | 232 -------- sphinx/static/file.png | Bin 392 -> 0 bytes sphinx/static/jquery.js | 32 -- sphinx/static/minus.png | Bin 199 -> 0 bytes sphinx/static/navigation.png | Bin 218 -> 0 bytes sphinx/static/plus.png | Bin 199 -> 0 bytes sphinx/static/rightsidebar.css | 16 - sphinx/static/searchtools.js | 467 --------------- sphinx/static/sphinxdoc.css | 557 ------------------ sphinx/static/stickysidebar.css | 19 - sphinx/static/traditional.css | 700 ----------------------- sphinx/templates/changes/frameset.html | 11 - sphinx/templates/changes/rstsource.html | 15 - sphinx/templates/changes/versionchanges.html | 33 -- sphinx/templates/defindex.html | 26 - sphinx/templates/genindex-single.html | 46 -- sphinx/templates/genindex-split.html | 30 - sphinx/templates/genindex.html | 57 -- sphinx/templates/layout.html | 187 ------ sphinx/templates/modindex.html | 42 -- sphinx/templates/opensearch.xml | 10 - sphinx/templates/page.html | 4 - sphinx/templates/search.html | 45 -- sphinx/themes/basic/changes/frameset.html | 11 + sphinx/themes/basic/changes/rstsource.html | 15 + sphinx/themes/basic/changes/versionchanges.html | 33 ++ sphinx/themes/basic/defindex.html | 26 + sphinx/themes/basic/genindex-single.html | 46 ++ sphinx/themes/basic/genindex-split.html | 30 + sphinx/themes/basic/genindex.html | 57 ++ sphinx/themes/basic/layout.html | 187 ++++++ sphinx/themes/basic/modindex.html | 42 ++ sphinx/themes/basic/opensearch.xml | 10 + sphinx/themes/basic/page.html | 4 + sphinx/themes/basic/search.html | 45 ++ sphinx/themes/basic/static/basic.css | 657 +++++++++++++++++++++ sphinx/themes/basic/static/doctools.js | 232 ++++++++ sphinx/themes/basic/static/file.png | Bin 0 -> 392 bytes sphinx/themes/basic/static/jquery.js | 32 ++ sphinx/themes/basic/static/minus.png | Bin 0 -> 199 bytes sphinx/themes/basic/static/plus.png | Bin 0 -> 199 bytes sphinx/themes/basic/static/searchtools.js | 467 +++++++++++++++ sphinx/themes/default/static/default.css | 657 +++++++++++++++++++++ sphinx/themes/default/static/rightsidebar.css | 16 + sphinx/themes/default/static/stickysidebar.css | 19 + sphinx/themes/sphinxdoc/static/contents.png | Bin 0 -> 202 bytes sphinx/themes/sphinxdoc/static/navigation.png | Bin 0 -> 218 bytes sphinx/themes/sphinxdoc/static/sphinxdoc.css | 557 ++++++++++++++++++ sphinx/themes/traditional/static/traditional.css | 700 +++++++++++++++++++++++ 51 files changed, 3843 insertions(+), 3186 deletions(-) delete mode 100644 sphinx/static/contents.png delete mode 100644 sphinx/static/default.css delete mode 100644 sphinx/static/doctools.js delete mode 100644 sphinx/static/file.png delete mode 100644 sphinx/static/jquery.js delete mode 100644 sphinx/static/minus.png delete mode 100644 sphinx/static/navigation.png delete mode 100644 sphinx/static/plus.png delete mode 100644 sphinx/static/rightsidebar.css delete mode 100644 sphinx/static/searchtools.js delete mode 100644 sphinx/static/sphinxdoc.css delete mode 100644 sphinx/static/stickysidebar.css delete mode 100644 sphinx/static/traditional.css delete mode 100644 sphinx/templates/changes/frameset.html delete mode 100644 sphinx/templates/changes/rstsource.html delete mode 100644 sphinx/templates/changes/versionchanges.html delete mode 100644 sphinx/templates/defindex.html delete mode 100644 sphinx/templates/genindex-single.html delete mode 100644 sphinx/templates/genindex-split.html delete mode 100644 sphinx/templates/genindex.html delete mode 100644 sphinx/templates/layout.html delete mode 100644 sphinx/templates/modindex.html delete mode 100644 sphinx/templates/opensearch.xml delete mode 100644 sphinx/templates/page.html delete mode 100644 sphinx/templates/search.html create mode 100644 sphinx/themes/basic/changes/frameset.html create mode 100644 sphinx/themes/basic/changes/rstsource.html create mode 100644 sphinx/themes/basic/changes/versionchanges.html create mode 100644 sphinx/themes/basic/defindex.html create mode 100644 sphinx/themes/basic/genindex-single.html create mode 100644 sphinx/themes/basic/genindex-split.html create mode 100644 sphinx/themes/basic/genindex.html create mode 100644 sphinx/themes/basic/layout.html create mode 100644 sphinx/themes/basic/modindex.html create mode 100644 sphinx/themes/basic/opensearch.xml create mode 100644 sphinx/themes/basic/page.html create mode 100644 sphinx/themes/basic/search.html create mode 100644 sphinx/themes/basic/static/basic.css create mode 100644 sphinx/themes/basic/static/doctools.js create mode 100644 sphinx/themes/basic/static/file.png create mode 100644 sphinx/themes/basic/static/jquery.js create mode 100644 sphinx/themes/basic/static/minus.png create mode 100644 sphinx/themes/basic/static/plus.png create mode 100644 sphinx/themes/basic/static/searchtools.js create mode 100644 sphinx/themes/default/static/default.css create mode 100644 sphinx/themes/default/static/rightsidebar.css create mode 100644 sphinx/themes/default/static/stickysidebar.css create mode 100644 sphinx/themes/sphinxdoc/static/contents.png create mode 100644 sphinx/themes/sphinxdoc/static/navigation.png create mode 100644 sphinx/themes/sphinxdoc/static/sphinxdoc.css create mode 100644 sphinx/themes/traditional/static/traditional.css diff --git a/sphinx/static/contents.png b/sphinx/static/contents.png deleted file mode 100644 index 7fb82154..00000000 Binary files a/sphinx/static/contents.png and /dev/null differ diff --git a/sphinx/static/default.css b/sphinx/static/default.css deleted file mode 100644 index 005caa1f..00000000 --- a/sphinx/static/default.css +++ /dev/null @@ -1,657 +0,0 @@ -/** - * Sphinx Doc Design - */ - -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -/* :::: LAYOUT :::: */ - -div.document { - background-color: #1c4e63; -} - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 230px; -} - -div.body { - background-color: white; - padding: 0 20px 30px 20px; -} - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - -div.clearer { - clear: both; -} - -div.footer { - color: #fff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #fff; - text-decoration: underline; -} - -div.related { - background-color: #133f52; - color: #fff; - width: 100%; - line-height: 30px; - font-size: 90%; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; -} - -div.related li.right { - float: right; - margin-right: 5px; -} - -div.related a { - color: white; -} - -/* ::: TOC :::: */ -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: white; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: white; -} - -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: white; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: white; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - padding: 0; - list-style: none; - color: white; -} - -div.sphinxsidebar ul ul, -div.sphinxsidebar ul.want-points { - margin-left: 20px; - list-style: square; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -div.sphinxsidebar a { - color: #98dbcc; -} - -div.sphinxsidebar form { - margin-top: 10px; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -/* :::: MODULE CLOUD :::: */ -div.modulecloud { - margin: -5px 10px 5px 10px; - padding: 10px; - line-height: 160%; - border: 1px solid #cbe7e5; - background-color: #f2fbfd; -} - -div.modulecloud a { - padding: 0 5px 0 5px; -} - -/* :::: SEARCH :::: */ -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* :::: COMMON FORM STYLES :::: */ - -div.actions { - padding: 5px 10px 5px 10px; - border-top: 1px solid #cbe7e5; - border-bottom: 1px solid #cbe7e5; - background-color: #e0f6f4; -} - -form dl { - color: #333; -} - -form dt { - clear: both; - float: left; - min-width: 110px; - margin-right: 10px; - padding-top: 2px; -} - -input#homepage { - display: none; -} - -div.error { - margin: 5px 20px 0 0; - padding: 5px; - border: 1px solid #d00; - font-weight: bold; -} - -/* :::: INDEX PAGE :::: */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* :::: INDEX STYLES :::: */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -form.pfform { - margin: 10px 0 20px 0; -} - -/* :::: GLOBAL STYLES :::: */ - -.docwarning { - background-color: #ffe4e4; - padding: 10px; - margin: 0 -20px 0 -20px; - border-bottom: 1px solid #f66; -} - -p.subhead { - font-weight: bold; - margin-top: 20px; -} - -a { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: justify; - line-height: 130%; -} - -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -ul.fakelist { - list-style: none; - margin: 10px 0 10px 20px; - padding: 0; -} - -.field-list ul { - padding-left: 1em; -} - -.first { - margin-top: 0 !important; -} - -/* "Footnotes" heading */ -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* Sidebars */ - -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -p.sidebar-title { - font-weight: bold; -} - -/* "Topics" */ - -div.topic { - background-color: #eee; - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* Admonitions */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -div.admonition p.admonition-title + p { - display: inline; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -table.docutils { - border: 0; -} - -table.docutils td, table.docutils th { - padding: 1px 8px 1px 0; - border-top: 0; - border-left: 0; - border-right: 0; - border-bottom: 1px solid #aaa; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -dl { - margin-bottom: 15px; - clear: both; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -.refcount { - color: #060; -} - -dt:target, -.highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -th { - text-align: left; - padding-right: 5px; -} - -pre { - padding: 5px; - background-color: #efc; - color: #333; - border: 1px solid #ac9; - border-left: none; - border-right: none; - overflow: auto; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -.footnote:target { background-color: #ffa } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -form.comment { - margin: 0; - padding: 10px 30px 10px 30px; - background-color: #eee; -} - -form.comment h3 { - background-color: #326591; - color: white; - margin: -10px -30px 10px -30px; - padding: 5px; - font-size: 1.4em; -} - -form.comment input, -form.comment textarea { - border: 1px solid #ccc; - padding: 2px; - font-family: sans-serif; - font-size: 100%; -} - -form.comment input[type="text"] { - width: 240px; -} - -form.comment textarea { - width: 100%; - height: 200px; - margin-bottom: 10px; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -img.math { - vertical-align: middle; -} - -div.math p { - text-align: center; -} - -span.eqno { - float: right; -} - -img.logo { - border: 0; -} - -/* :::: PRINT :::: */ -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0; - width : 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - div#comments div.new-comment-box, - #top-link { - display: none; - } -} diff --git a/sphinx/static/doctools.js b/sphinx/static/doctools.js deleted file mode 100644 index be4bdc88..00000000 --- a/sphinx/static/doctools.js +++ /dev/null @@ -1,232 +0,0 @@ -/// XXX: make it cross browser - -/** - * make the code below compatible with browsers without - * an installed firebug like debugger - */ -if (!window.console || !console.firebug) { - var names = ["log", "debug", "info", "warn", "error", "assert", "dir", "dirxml", - "group", "groupEnd", "time", "timeEnd", "count", "trace", "profile", "profileEnd"]; - window.console = {}; - for (var i = 0; i < names.length; ++i) - window.console[names[i]] = function() {} -} - -/** - * small helper function to urldecode strings - */ -jQuery.urldecode = function(x) { - return decodeURIComponent(x).replace(/\+/g, ' '); -} - -/** - * small helper function to urlencode strings - */ -jQuery.urlencode = encodeURIComponent; - -/** - * This function returns the parsed url parameters of the - * current request. Multiple values per key are supported, - * it will always return arrays of strings for the value parts. - */ -jQuery.getQueryParameters = function(s) { - if (typeof s == 'undefined') - s = document.location.search; - var parts = s.substr(s.indexOf('?') + 1).split('&'); - var result = {}; - for (var i = 0; i < parts.length; i++) { - var tmp = parts[i].split('=', 2); - var key = jQuery.urldecode(tmp[0]); - var value = jQuery.urldecode(tmp[1]); - if (key in result) - result[key].push(value); - else - result[key] = [value]; - } - return result; -} - -/** - * small function to check if an array contains - * a given item. - */ -jQuery.contains = function(arr, item) { - for (var i = 0; i < arr.length; i++) { - if (arr[i] == item) - return true; - } - return false; -} - -/** - * highlight a given string on a jquery object by wrapping it in - * span elements with the given class name. - */ -jQuery.fn.highlightText = function(text, className) { - function highlight(node) { - if (node.nodeType == 3) { - var val = node.nodeValue; - var pos = val.toLowerCase().indexOf(text); - if (pos >= 0 && !jQuery.className.has(node.parentNode, className)) { - var span = document.createElement("span"); - span.className = className; - span.appendChild(document.createTextNode(val.substr(pos, text.length))); - node.parentNode.insertBefore(span, node.parentNode.insertBefore( - document.createTextNode(val.substr(pos + text.length)), - node.nextSibling)); - node.nodeValue = val.substr(0, pos); - } - } - else if (!jQuery(node).is("button, select, textarea")) { - jQuery.each(node.childNodes, function() { - highlight(this) - }); - } - } - return this.each(function() { - highlight(this); - }); -} - -/** - * Small JavaScript module for the documentation. - */ -var Documentation = { - - init : function() { - this.fixFirefoxAnchorBug(); - this.highlightSearchWords(); - this.initModIndex(); - }, - - /** - * i18n support - */ - TRANSLATIONS : {}, - PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, - LOCALE : 'unknown', - - // gettext and ngettext don't access this so that the functions - // can savely bound to a different name (_ = Documentation.gettext) - gettext : function(string) { - var translated = Documentation.TRANSLATIONS[string]; - if (typeof translated == 'undefined') - return string; - return (typeof translated == 'string') ? translated : translated[0]; - }, - - ngettext : function(singular, plural, n) { - var translated = Documentation.TRANSLATIONS[singular]; - if (typeof translated == 'undefined') - return (n == 1) ? singular : plural; - return translated[Documentation.PLURALEXPR(n)]; - }, - - addTranslations : function(catalog) { - for (var key in catalog.messages) - this.TRANSLATIONS[key] = catalog.messages[key]; - this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); - this.LOCALE = catalog.locale; - }, - - /** - * add context elements like header anchor links - */ - addContextElements : function() { - $('div[@id] > :header:first').each(function() { - $('\u00B6'). - attr('href', '#' + this.id). - attr('title', _('Permalink to this headline')). - appendTo(this); - }); - $('dt[@id]').each(function() { - $('\u00B6'). - attr('href', '#' + this.id). - attr('title', _('Permalink to this definition')). - appendTo(this); - }); - }, - - /** - * workaround a firefox stupidity - */ - fixFirefoxAnchorBug : function() { - if (document.location.hash && $.browser.mozilla) - window.setTimeout(function() { - document.location.href += ''; - }, 10); - }, - - /** - * highlight the search words provided in the url in the text - */ - highlightSearchWords : function() { - var params = $.getQueryParameters(); - var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; - if (terms.length) { - var body = $('div.body'); - window.setTimeout(function() { - $.each(terms, function() { - body.highlightText(this.toLowerCase(), 'highlight'); - }); - }, 10); - $('

  • ' + _('Hide Search Matches') + '
    • ') - .appendTo($('.sidebar .this-page-menu')); - } - }, - - /** - * init the modindex toggle buttons - */ - initModIndex : function() { - var togglers = $('img.toggler').click(function() { - var src = $(this).attr('src'); - var idnum = $(this).attr('id').substr(7); - console.log($('tr.cg-' + idnum).toggle()); - if (src.substr(-9) == 'minus.png') - $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); - else - $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); - }).css('display', ''); - if (DOCUMENTATION_OPTIONS.COLLAPSE_MODINDEX) { - togglers.click(); - } - }, - - /** - * helper function to hide the search marks again - */ - hideSearchWords : function() { - $('.sidebar .this-page-menu li.highlight-link').fadeOut(300); - $('span.highlight').removeClass('highlight'); - }, - - /** - * make the url absolute - */ - makeURL : function(relativeURL) { - return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; - }, - - /** - * get the current relative url - */ - getCurrentURL : function() { - var path = document.location.pathname; - var parts = path.split(/\//); - $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { - if (this == '..') - parts.pop(); - }); - var url = parts.join('/'); - return path.substring(url.lastIndexOf('/') + 1, path.length - 1); - } -}; - -// quick alias for translations -_ = Documentation.gettext; - -$(document).ready(function() { - Documentation.init(); -}); diff --git a/sphinx/static/file.png b/sphinx/static/file.png deleted file mode 100644 index d18082e3..00000000 Binary files a/sphinx/static/file.png and /dev/null differ diff --git a/sphinx/static/jquery.js b/sphinx/static/jquery.js deleted file mode 100644 index 82b98e1d..00000000 --- a/sphinx/static/jquery.js +++ /dev/null @@ -1,32 +0,0 @@ -/* - * jQuery 1.2.6 - New Wave Javascript - * - * Copyright (c) 2008 John Resig (jquery.com) - * Dual licensed under the MIT (MIT-LICENSE.txt) - * and GPL (GPL-LICENSE.txt) licenses. - * - * $Date: 2008-05-24 14:22:17 -0400 (Sat, 24 May 2008) $ - * $Rev: 5685 $ - */ -(function(){var _jQuery=window.jQuery,_$=window.$;var jQuery=window.jQuery=window.$=function(selector,context){return new jQuery.fn.init(selector,context);};var quickExpr=/^[^<]*(<(.|\s)+>)[^>]*$|^#(\w+)$/,isSimple=/^.[^:#\[\.]*$/,undefined;jQuery.fn=jQuery.prototype={init:function(selector,context){selector=selector||document;if(selector.nodeType){this[0]=selector;this.length=1;return this;}if(typeof selector=="string"){var match=quickExpr.exec(selector);if(match&&(match[1]||!context)){if(match[1])selector=jQuery.clean([match[1]],context);else{var elem=document.getElementById(match[3]);if(elem){if(elem.id!=match[3])return jQuery().find(selector);return jQuery(elem);}selector=[];}}else -return jQuery(context).find(selector);}else if(jQuery.isFunction(selector))return jQuery(document)[jQuery.fn.ready?"ready":"load"](selector);return this.setArray(jQuery.makeArray(selector));},jquery:"1.2.6",size:function(){return this.length;},length:0,get:function(num){return num==undefined?jQuery.makeArray(this):this[num];},pushStack:function(elems){var ret=jQuery(elems);ret.prevObject=this;return ret;},setArray:function(elems){this.length=0;Array.prototype.push.apply(this,elems);return this;},each:function(callback,args){return jQuery.each(this,callback,args);},index:function(elem){var ret=-1;return jQuery.inArray(elem&&elem.jquery?elem[0]:elem,this);},attr:function(name,value,type){var options=name;if(name.constructor==String)if(value===undefined)return this[0]&&jQuery[type||"attr"](this[0],name);else{options={};options[name]=value;}return this.each(function(i){for(name in options)jQuery.attr(type?this.style:this,name,jQuery.prop(this,options[name],type,i,name));});},css:function(key,value){if((key=='width'||key=='height')&&parseFloat(value)<0)value=undefined;return this.attr(key,value,"curCSS");},text:function(text){if(typeof text!="object"&&text!=null)return this.empty().append((this[0]&&this[0].ownerDocument||document).createTextNode(text));var ret="";jQuery.each(text||this,function(){jQuery.each(this.childNodes,function(){if(this.nodeType!=8)ret+=this.nodeType!=1?this.nodeValue:jQuery.fn.text([this]);});});return ret;},wrapAll:function(html){if(this[0])jQuery(html,this[0].ownerDocument).clone().insertBefore(this[0]).map(function(){var elem=this;while(elem.firstChild)elem=elem.firstChild;return elem;}).append(this);return this;},wrapInner:function(html){return this.each(function(){jQuery(this).contents().wrapAll(html);});},wrap:function(html){return this.each(function(){jQuery(this).wrapAll(html);});},append:function(){return this.domManip(arguments,true,false,function(elem){if(this.nodeType==1)this.appendChild(elem);});},prepend:function(){return this.domManip(arguments,true,true,function(elem){if(this.nodeType==1)this.insertBefore(elem,this.firstChild);});},before:function(){return this.domManip(arguments,false,false,function(elem){this.parentNode.insertBefore(elem,this);});},after:function(){return this.domManip(arguments,false,true,function(elem){this.parentNode.insertBefore(elem,this.nextSibling);});},end:function(){return this.prevObject||jQuery([]);},find:function(selector){var elems=jQuery.map(this,function(elem){return jQuery.find(selector,elem);});return this.pushStack(/[^+>] [^+>]/.test(selector)||selector.indexOf("..")>-1?jQuery.unique(elems):elems);},clone:function(events){var ret=this.map(function(){if(jQuery.browser.msie&&!jQuery.isXMLDoc(this)){var clone=this.cloneNode(true),container=document.createElement("div");container.appendChild(clone);return jQuery.clean([container.innerHTML])[0];}else -return this.cloneNode(true);});var clone=ret.find("*").andSelf().each(function(){if(this[expando]!=undefined)this[expando]=null;});if(events===true)this.find("*").andSelf().each(function(i){if(this.nodeType==3)return;var events=jQuery.data(this,"events");for(var type in events)for(var handler in events[type])jQuery.event.add(clone[i],type,events[type][handler],events[type][handler].data);});return ret;},filter:function(selector){return this.pushStack(jQuery.isFunction(selector)&&jQuery.grep(this,function(elem,i){return selector.call(elem,i);})||jQuery.multiFilter(selector,this));},not:function(selector){if(selector.constructor==String)if(isSimple.test(selector))return this.pushStack(jQuery.multiFilter(selector,this,true));else -selector=jQuery.multiFilter(selector,this);var isArrayLike=selector.length&&selector[selector.length-1]!==undefined&&!selector.nodeType;return this.filter(function(){return isArrayLike?jQuery.inArray(this,selector)<0:this!=selector;});},add:function(selector){return this.pushStack(jQuery.unique(jQuery.merge(this.get(),typeof selector=='string'?jQuery(selector):jQuery.makeArray(selector))));},is:function(selector){return!!selector&&jQuery.multiFilter(selector,this).length>0;},hasClass:function(selector){return this.is("."+selector);},val:function(value){if(value==undefined){if(this.length){var elem=this[0];if(jQuery.nodeName(elem,"select")){var index=elem.selectedIndex,values=[],options=elem.options,one=elem.type=="select-one";if(index<0)return null;for(var i=one?index:0,max=one?index+1:options.length;i=0||jQuery.inArray(this.name,value)>=0);else if(jQuery.nodeName(this,"select")){var values=jQuery.makeArray(value);jQuery("option",this).each(function(){this.selected=(jQuery.inArray(this.value,values)>=0||jQuery.inArray(this.text,values)>=0);});if(!values.length)this.selectedIndex=-1;}else -this.value=value;});},html:function(value){return value==undefined?(this[0]?this[0].innerHTML:null):this.empty().append(value);},replaceWith:function(value){return this.after(value).remove();},eq:function(i){return this.slice(i,i+1);},slice:function(){return this.pushStack(Array.prototype.slice.apply(this,arguments));},map:function(callback){return this.pushStack(jQuery.map(this,function(elem,i){return callback.call(elem,i,elem);}));},andSelf:function(){return this.add(this.prevObject);},data:function(key,value){var parts=key.split(".");parts[1]=parts[1]?"."+parts[1]:"";if(value===undefined){var data=this.triggerHandler("getData"+parts[1]+"!",[parts[0]]);if(data===undefined&&this.length)data=jQuery.data(this[0],key);return data===undefined&&parts[1]?this.data(parts[0]):data;}else -return this.trigger("setData"+parts[1]+"!",[parts[0],value]).each(function(){jQuery.data(this,key,value);});},removeData:function(key){return this.each(function(){jQuery.removeData(this,key);});},domManip:function(args,table,reverse,callback){var clone=this.length>1,elems;return this.each(function(){if(!elems){elems=jQuery.clean(args,this.ownerDocument);if(reverse)elems.reverse();}var obj=this;if(table&&jQuery.nodeName(this,"table")&&jQuery.nodeName(elems[0],"tr"))obj=this.getElementsByTagName("tbody")[0]||this.appendChild(this.ownerDocument.createElement("tbody"));var scripts=jQuery([]);jQuery.each(elems,function(){var elem=clone?jQuery(this).clone(true)[0]:this;if(jQuery.nodeName(elem,"script"))scripts=scripts.add(elem);else{if(elem.nodeType==1)scripts=scripts.add(jQuery("script",elem).remove());callback.call(obj,elem);}});scripts.each(evalScript);});}};jQuery.fn.init.prototype=jQuery.fn;function evalScript(i,elem){if(elem.src)jQuery.ajax({url:elem.src,async:false,dataType:"script"});else -jQuery.globalEval(elem.text||elem.textContent||elem.innerHTML||"");if(elem.parentNode)elem.parentNode.removeChild(elem);}function now(){return+new Date;}jQuery.extend=jQuery.fn.extend=function(){var target=arguments[0]||{},i=1,length=arguments.length,deep=false,options;if(target.constructor==Boolean){deep=target;target=arguments[1]||{};i=2;}if(typeof target!="object"&&typeof target!="function")target={};if(length==i){target=this;--i;}for(;i-1;}},swap:function(elem,options,callback){var old={};for(var name in options){old[name]=elem.style[name];elem.style[name]=options[name];}callback.call(elem);for(var name in options)elem.style[name]=old[name];},css:function(elem,name,force){if(name=="width"||name=="height"){var val,props={position:"absolute",visibility:"hidden",display:"block"},which=name=="width"?["Left","Right"]:["Top","Bottom"];function getWH(){val=name=="width"?elem.offsetWidth:elem.offsetHeight;var padding=0,border=0;jQuery.each(which,function(){padding+=parseFloat(jQuery.curCSS(elem,"padding"+this,true))||0;border+=parseFloat(jQuery.curCSS(elem,"border"+this+"Width",true))||0;});val-=Math.round(padding+border);}if(jQuery(elem).is(":visible"))getWH();else -jQuery.swap(elem,props,getWH);return Math.max(0,val);}return jQuery.curCSS(elem,name,force);},curCSS:function(elem,name,force){var ret,style=elem.style;function color(elem){if(!jQuery.browser.safari)return false;var ret=defaultView.getComputedStyle(elem,null);return!ret||ret.getPropertyValue("color")=="";}if(name=="opacity"&&jQuery.browser.msie){ret=jQuery.attr(style,"opacity");return ret==""?"1":ret;}if(jQuery.browser.opera&&name=="display"){var save=style.outline;style.outline="0 solid black";style.outline=save;}if(name.match(/float/i))name=styleFloat;if(!force&&style&&style[name])ret=style[name];else if(defaultView.getComputedStyle){if(name.match(/float/i))name="float";name=name.replace(/([A-Z])/g,"-$1").toLowerCase();var computedStyle=defaultView.getComputedStyle(elem,null);if(computedStyle&&!color(elem))ret=computedStyle.getPropertyValue(name);else{var swap=[],stack=[],a=elem,i=0;for(;a&&color(a);a=a.parentNode)stack.unshift(a);for(;i]*?)\/>/g,function(all,front,tag){return tag.match(/^(abbr|br|col|img|input|link|meta|param|hr|area|embed)$/i)?all:front+">";});var tags=jQuery.trim(elem).toLowerCase(),div=context.createElement("div");var wrap=!tags.indexOf("",""]||!tags.indexOf("",""]||tags.match(/^<(thead|tbody|tfoot|colg|cap)/)&&[1,"","
    "]||!tags.indexOf("",""]||(!tags.indexOf("",""]||!tags.indexOf("",""]||jQuery.browser.msie&&[1,"div
    ","
    "]||[0,"",""];div.innerHTML=wrap[1]+elem+wrap[2];while(wrap[0]--)div=div.lastChild;if(jQuery.browser.msie){var tbody=!tags.indexOf(""&&tags.indexOf("=0;--j)if(jQuery.nodeName(tbody[j],"tbody")&&!tbody[j].childNodes.length)tbody[j].parentNode.removeChild(tbody[j]);if(/^\s/.test(elem))div.insertBefore(context.createTextNode(elem.match(/^\s*/)[0]),div.firstChild);}elem=jQuery.makeArray(div.childNodes);}if(elem.length===0&&(!jQuery.nodeName(elem,"form")&&!jQuery.nodeName(elem,"select")))return;if(elem[0]==undefined||jQuery.nodeName(elem,"form")||elem.options)ret.push(elem);else -ret=jQuery.merge(ret,elem);});return ret;},attr:function(elem,name,value){if(!elem||elem.nodeType==3||elem.nodeType==8)return undefined;var notxml=!jQuery.isXMLDoc(elem),set=value!==undefined,msie=jQuery.browser.msie;name=notxml&&jQuery.props[name]||name;if(elem.tagName){var special=/href|src|style/.test(name);if(name=="selected"&&jQuery.browser.safari)elem.parentNode.selectedIndex;if(name in elem&¬xml&&!special){if(set){if(name=="type"&&jQuery.nodeName(elem,"input")&&elem.parentNode)throw"type property can't be changed";elem[name]=value;}if(jQuery.nodeName(elem,"form")&&elem.getAttributeNode(name))return elem.getAttributeNode(name).nodeValue;return elem[name];}if(msie&¬xml&&name=="style")return jQuery.attr(elem.style,"cssText",value);if(set)elem.setAttribute(name,""+value);var attr=msie&¬xml&&special?elem.getAttribute(name,2):elem.getAttribute(name);return attr===null?undefined:attr;}if(msie&&name=="opacity"){if(set){elem.zoom=1;elem.filter=(elem.filter||"").replace(/alpha\([^)]*\)/,"")+(parseInt(value)+''=="NaN"?"":"alpha(opacity="+value*100+")");}return elem.filter&&elem.filter.indexOf("opacity=")>=0?(parseFloat(elem.filter.match(/opacity=([^)]*)/)[1])/100)+'':"";}name=name.replace(/-([a-z])/ig,function(all,letter){return letter.toUpperCase();});if(set)elem[name]=value;return elem[name];},trim:function(text){return(text||"").replace(/^\s+|\s+$/g,"");},makeArray:function(array){var ret=[];if(array!=null){var i=array.length;if(i==null||array.split||array.setInterval||array.call)ret[0]=array;else -while(i)ret[--i]=array[i];}return ret;},inArray:function(elem,array){for(var i=0,length=array.length;i*",this).remove();while(this.firstChild)this.removeChild(this.firstChild);}},function(name,fn){jQuery.fn[name]=function(){return this.each(fn,arguments);};});jQuery.each(["Height","Width"],function(i,name){var type=name.toLowerCase();jQuery.fn[type]=function(size){return this[0]==window?jQuery.browser.opera&&document.body["client"+name]||jQuery.browser.safari&&window["inner"+name]||document.compatMode=="CSS1Compat"&&document.documentElement["client"+name]||document.body["client"+name]:this[0]==document?Math.max(Math.max(document.body["scroll"+name],document.documentElement["scroll"+name]),Math.max(document.body["offset"+name],document.documentElement["offset"+name])):size==undefined?(this.length?jQuery.css(this[0],type):null):this.css(type,size.constructor==String?size:size+"px");};});function num(elem,prop){return elem[0]&&parseInt(jQuery.curCSS(elem[0],prop,true),10)||0;}var chars=jQuery.browser.safari&&parseInt(jQuery.browser.version)<417?"(?:[\\w*_-]|\\\\.)":"(?:[\\w\u0128-\uFFFF*_-]|\\\\.)",quickChild=new RegExp("^>\\s*("+chars+"+)"),quickID=new RegExp("^("+chars+"+)(#)("+chars+"+)"),quickClass=new RegExp("^([#.]?)("+chars+"*)");jQuery.extend({expr:{"":function(a,i,m){return m[2]=="*"||jQuery.nodeName(a,m[2]);},"#":function(a,i,m){return a.getAttribute("id")==m[2];},":":{lt:function(a,i,m){return im[3]-0;},nth:function(a,i,m){return m[3]-0==i;},eq:function(a,i,m){return m[3]-0==i;},first:function(a,i){return i==0;},last:function(a,i,m,r){return i==r.length-1;},even:function(a,i){return i%2==0;},odd:function(a,i){return i%2;},"first-child":function(a){return a.parentNode.getElementsByTagName("*")[0]==a;},"last-child":function(a){return jQuery.nth(a.parentNode.lastChild,1,"previousSibling")==a;},"only-child":function(a){return!jQuery.nth(a.parentNode.lastChild,2,"previousSibling");},parent:function(a){return a.firstChild;},empty:function(a){return!a.firstChild;},contains:function(a,i,m){return(a.textContent||a.innerText||jQuery(a).text()||"").indexOf(m[3])>=0;},visible:function(a){return"hidden"!=a.type&&jQuery.css(a,"display")!="none"&&jQuery.css(a,"visibility")!="hidden";},hidden:function(a){return"hidden"==a.type||jQuery.css(a,"display")=="none"||jQuery.css(a,"visibility")=="hidden";},enabled:function(a){return!a.disabled;},disabled:function(a){return a.disabled;},checked:function(a){return a.checked;},selected:function(a){return a.selected||jQuery.attr(a,"selected");},text:function(a){return"text"==a.type;},radio:function(a){return"radio"==a.type;},checkbox:function(a){return"checkbox"==a.type;},file:function(a){return"file"==a.type;},password:function(a){return"password"==a.type;},submit:function(a){return"submit"==a.type;},image:function(a){return"image"==a.type;},reset:function(a){return"reset"==a.type;},button:function(a){return"button"==a.type||jQuery.nodeName(a,"button");},input:function(a){return/input|select|textarea|button/i.test(a.nodeName);},has:function(a,i,m){return jQuery.find(m[3],a).length;},header:function(a){return/h\d/i.test(a.nodeName);},animated:function(a){return jQuery.grep(jQuery.timers,function(fn){return a==fn.elem;}).length;}}},parse:[/^(\[) *@?([\w-]+) *([!*$^~=]*) *('?"?)(.*?)\4 *\]/,/^(:)([\w-]+)\("?'?(.*?(\(.*?\))?[^(]*?)"?'?\)/,new RegExp("^([:.#]*)("+chars+"+)")],multiFilter:function(expr,elems,not){var old,cur=[];while(expr&&expr!=old){old=expr;var f=jQuery.filter(expr,elems,not);expr=f.t.replace(/^\s*,\s*/,"");cur=not?elems=f.r:jQuery.merge(cur,f.r);}return cur;},find:function(t,context){if(typeof t!="string")return[t];if(context&&context.nodeType!=1&&context.nodeType!=9)return[];context=context||document;var ret=[context],done=[],last,nodeName;while(t&&last!=t){var r=[];last=t;t=jQuery.trim(t);var foundToken=false,re=quickChild,m=re.exec(t);if(m){nodeName=m[1].toUpperCase();for(var i=0;ret[i];i++)for(var c=ret[i].firstChild;c;c=c.nextSibling)if(c.nodeType==1&&(nodeName=="*"||c.nodeName.toUpperCase()==nodeName))r.push(c);ret=r;t=t.replace(re,"");if(t.indexOf(" ")==0)continue;foundToken=true;}else{re=/^([>+~])\s*(\w*)/i;if((m=re.exec(t))!=null){r=[];var merge={};nodeName=m[2].toUpperCase();m=m[1];for(var j=0,rl=ret.length;j=0;if(!not&&pass||not&&!pass)tmp.push(r[i]);}return tmp;},filter:function(t,r,not){var last;while(t&&t!=last){last=t;var p=jQuery.parse,m;for(var i=0;p[i];i++){m=p[i].exec(t);if(m){t=t.substring(m[0].length);m[2]=m[2].replace(/\\/g,"");break;}}if(!m)break;if(m[1]==":"&&m[2]=="not")r=isSimple.test(m[3])?jQuery.filter(m[3],r,true).r:jQuery(r).not(m[3]);else if(m[1]==".")r=jQuery.classFilter(r,m[2],not);else if(m[1]=="["){var tmp=[],type=m[3];for(var i=0,rl=r.length;i=0)^not)tmp.push(a);}r=tmp;}else if(m[1]==":"&&m[2]=="nth-child"){var merge={},tmp=[],test=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(m[3]=="even"&&"2n"||m[3]=="odd"&&"2n+1"||!/\D/.test(m[3])&&"0n+"+m[3]||m[3]),first=(test[1]+(test[2]||1))-0,last=test[3]-0;for(var i=0,rl=r.length;i=0)add=true;if(add^not)tmp.push(node);}r=tmp;}else{var fn=jQuery.expr[m[1]];if(typeof fn=="object")fn=fn[m[2]];if(typeof fn=="string")fn=eval("false||function(a,i){return "+fn+";}");r=jQuery.grep(r,function(elem,i){return fn(elem,i,m,r);},not);}}return{r:r,t:t};},dir:function(elem,dir){var matched=[],cur=elem[dir];while(cur&&cur!=document){if(cur.nodeType==1)matched.push(cur);cur=cur[dir];}return matched;},nth:function(cur,result,dir,elem){result=result||1;var num=0;for(;cur;cur=cur[dir])if(cur.nodeType==1&&++num==result)break;return cur;},sibling:function(n,elem){var r=[];for(;n;n=n.nextSibling){if(n.nodeType==1&&n!=elem)r.push(n);}return r;}});jQuery.event={add:function(elem,types,handler,data){if(elem.nodeType==3||elem.nodeType==8)return;if(jQuery.browser.msie&&elem.setInterval)elem=window;if(!handler.guid)handler.guid=this.guid++;if(data!=undefined){var fn=handler;handler=this.proxy(fn,function(){return fn.apply(this,arguments);});handler.data=data;}var events=jQuery.data(elem,"events")||jQuery.data(elem,"events",{}),handle=jQuery.data(elem,"handle")||jQuery.data(elem,"handle",function(){if(typeof jQuery!="undefined"&&!jQuery.event.triggered)return jQuery.event.handle.apply(arguments.callee.elem,arguments);});handle.elem=elem;jQuery.each(types.split(/\s+/),function(index,type){var parts=type.split(".");type=parts[0];handler.type=parts[1];var handlers=events[type];if(!handlers){handlers=events[type]={};if(!jQuery.event.special[type]||jQuery.event.special[type].setup.call(elem)===false){if(elem.addEventListener)elem.addEventListener(type,handle,false);else if(elem.attachEvent)elem.attachEvent("on"+type,handle);}}handlers[handler.guid]=handler;jQuery.event.global[type]=true;});elem=null;},guid:1,global:{},remove:function(elem,types,handler){if(elem.nodeType==3||elem.nodeType==8)return;var events=jQuery.data(elem,"events"),ret,index;if(events){if(types==undefined||(typeof types=="string"&&types.charAt(0)=="."))for(var type in events)this.remove(elem,type+(types||""));else{if(types.type){handler=types.handler;types=types.type;}jQuery.each(types.split(/\s+/),function(index,type){var parts=type.split(".");type=parts[0];if(events[type]){if(handler)delete events[type][handler.guid];else -for(handler in events[type])if(!parts[1]||events[type][handler].type==parts[1])delete events[type][handler];for(ret in events[type])break;if(!ret){if(!jQuery.event.special[type]||jQuery.event.special[type].teardown.call(elem)===false){if(elem.removeEventListener)elem.removeEventListener(type,jQuery.data(elem,"handle"),false);else if(elem.detachEvent)elem.detachEvent("on"+type,jQuery.data(elem,"handle"));}ret=null;delete events[type];}}});}for(ret in events)break;if(!ret){var handle=jQuery.data(elem,"handle");if(handle)handle.elem=null;jQuery.removeData(elem,"events");jQuery.removeData(elem,"handle");}}},trigger:function(type,data,elem,donative,extra){data=jQuery.makeArray(data);if(type.indexOf("!")>=0){type=type.slice(0,-1);var exclusive=true;}if(!elem){if(this.global[type])jQuery("*").add([window,document]).trigger(type,data);}else{if(elem.nodeType==3||elem.nodeType==8)return undefined;var val,ret,fn=jQuery.isFunction(elem[type]||null),event=!data[0]||!data[0].preventDefault;if(event){data.unshift({type:type,target:elem,preventDefault:function(){},stopPropagation:function(){},timeStamp:now()});data[0][expando]=true;}data[0].type=type;if(exclusive)data[0].exclusive=true;var handle=jQuery.data(elem,"handle");if(handle)val=handle.apply(elem,data);if((!fn||(jQuery.nodeName(elem,'a')&&type=="click"))&&elem["on"+type]&&elem["on"+type].apply(elem,data)===false)val=false;if(event)data.shift();if(extra&&jQuery.isFunction(extra)){ret=extra.apply(elem,val==null?data:data.concat(val));if(ret!==undefined)val=ret;}if(fn&&donative!==false&&val!==false&&!(jQuery.nodeName(elem,'a')&&type=="click")){this.triggered=true;try{elem[type]();}catch(e){}}this.triggered=false;}return val;},handle:function(event){var val,ret,namespace,all,handlers;event=arguments[0]=jQuery.event.fix(event||window.event);namespace=event.type.split(".");event.type=namespace[0];namespace=namespace[1];all=!namespace&&!event.exclusive;handlers=(jQuery.data(this,"events")||{})[event.type];for(var j in handlers){var handler=handlers[j];if(all||handler.type==namespace){event.handler=handler;event.data=handler.data;ret=handler.apply(this,arguments);if(val!==false)val=ret;if(ret===false){event.preventDefault();event.stopPropagation();}}}return val;},fix:function(event){if(event[expando]==true)return event;var originalEvent=event;event={originalEvent:originalEvent};var props="altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode metaKey newValue originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target timeStamp toElement type view wheelDelta which".split(" ");for(var i=props.length;i;i--)event[props[i]]=originalEvent[props[i]];event[expando]=true;event.preventDefault=function(){if(originalEvent.preventDefault)originalEvent.preventDefault();originalEvent.returnValue=false;};event.stopPropagation=function(){if(originalEvent.stopPropagation)originalEvent.stopPropagation();originalEvent.cancelBubble=true;};event.timeStamp=event.timeStamp||now();if(!event.target)event.target=event.srcElement||document;if(event.target.nodeType==3)event.target=event.target.parentNode;if(!event.relatedTarget&&event.fromElement)event.relatedTarget=event.fromElement==event.target?event.toElement:event.fromElement;if(event.pageX==null&&event.clientX!=null){var doc=document.documentElement,body=document.body;event.pageX=event.clientX+(doc&&doc.scrollLeft||body&&body.scrollLeft||0)-(doc.clientLeft||0);event.pageY=event.clientY+(doc&&doc.scrollTop||body&&body.scrollTop||0)-(doc.clientTop||0);}if(!event.which&&((event.charCode||event.charCode===0)?event.charCode:event.keyCode))event.which=event.charCode||event.keyCode;if(!event.metaKey&&event.ctrlKey)event.metaKey=event.ctrlKey;if(!event.which&&event.button)event.which=(event.button&1?1:(event.button&2?3:(event.button&4?2:0)));return event;},proxy:function(fn,proxy){proxy.guid=fn.guid=fn.guid||proxy.guid||this.guid++;return proxy;},special:{ready:{setup:function(){bindReady();return;},teardown:function(){return;}},mouseenter:{setup:function(){if(jQuery.browser.msie)return false;jQuery(this).bind("mouseover",jQuery.event.special.mouseenter.handler);return true;},teardown:function(){if(jQuery.browser.msie)return false;jQuery(this).unbind("mouseover",jQuery.event.special.mouseenter.handler);return true;},handler:function(event){if(withinElement(event,this))return true;event.type="mouseenter";return jQuery.event.handle.apply(this,arguments);}},mouseleave:{setup:function(){if(jQuery.browser.msie)return false;jQuery(this).bind("mouseout",jQuery.event.special.mouseleave.handler);return true;},teardown:function(){if(jQuery.browser.msie)return false;jQuery(this).unbind("mouseout",jQuery.event.special.mouseleave.handler);return true;},handler:function(event){if(withinElement(event,this))return true;event.type="mouseleave";return jQuery.event.handle.apply(this,arguments);}}}};jQuery.fn.extend({bind:function(type,data,fn){return type=="unload"?this.one(type,data,fn):this.each(function(){jQuery.event.add(this,type,fn||data,fn&&data);});},one:function(type,data,fn){var one=jQuery.event.proxy(fn||data,function(event){jQuery(this).unbind(event,one);return(fn||data).apply(this,arguments);});return this.each(function(){jQuery.event.add(this,type,one,fn&&data);});},unbind:function(type,fn){return this.each(function(){jQuery.event.remove(this,type,fn);});},trigger:function(type,data,fn){return this.each(function(){jQuery.event.trigger(type,data,this,true,fn);});},triggerHandler:function(type,data,fn){return this[0]&&jQuery.event.trigger(type,data,this[0],false,fn);},toggle:function(fn){var args=arguments,i=1;while(i=0){var selector=url.slice(off,url.length);url=url.slice(0,off);}callback=callback||function(){};var type="GET";if(params)if(jQuery.isFunction(params)){callback=params;params=null;}else{params=jQuery.param(params);type="POST";}var self=this;jQuery.ajax({url:url,type:type,dataType:"html",data:params,complete:function(res,status){if(status=="success"||status=="notmodified")self.html(selector?jQuery("
    ").append(res.responseText.replace(//g,"")).find(selector):res.responseText);self.each(callback,[res.responseText,status,res]);}});return this;},serialize:function(){return jQuery.param(this.serializeArray());},serializeArray:function(){return this.map(function(){return jQuery.nodeName(this,"form")?jQuery.makeArray(this.elements):this;}).filter(function(){return this.name&&!this.disabled&&(this.checked||/select|textarea/i.test(this.nodeName)||/text|hidden|password/i.test(this.type));}).map(function(i,elem){var val=jQuery(this).val();return val==null?null:val.constructor==Array?jQuery.map(val,function(val,i){return{name:elem.name,value:val};}):{name:elem.name,value:val};}).get();}});jQuery.each("ajaxStart,ajaxStop,ajaxComplete,ajaxError,ajaxSuccess,ajaxSend".split(","),function(i,o){jQuery.fn[o]=function(f){return this.bind(o,f);};});var jsc=now();jQuery.extend({get:function(url,data,callback,type){if(jQuery.isFunction(data)){callback=data;data=null;}return jQuery.ajax({type:"GET",url:url,data:data,success:callback,dataType:type});},getScript:function(url,callback){return jQuery.get(url,null,callback,"script");},getJSON:function(url,data,callback){return jQuery.get(url,data,callback,"json");},post:function(url,data,callback,type){if(jQuery.isFunction(data)){callback=data;data={};}return jQuery.ajax({type:"POST",url:url,data:data,success:callback,dataType:type});},ajaxSetup:function(settings){jQuery.extend(jQuery.ajaxSettings,settings);},ajaxSettings:{url:location.href,global:true,type:"GET",timeout:0,contentType:"application/x-www-form-urlencoded",processData:true,async:true,data:null,username:null,password:null,accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},ajax:function(s){s=jQuery.extend(true,s,jQuery.extend(true,{},jQuery.ajaxSettings,s));var jsonp,jsre=/=\?(&|$)/g,status,data,type=s.type.toUpperCase();if(s.data&&s.processData&&typeof s.data!="string")s.data=jQuery.param(s.data);if(s.dataType=="jsonp"){if(type=="GET"){if(!s.url.match(jsre))s.url+=(s.url.match(/\?/)?"&":"?")+(s.jsonp||"callback")+"=?";}else if(!s.data||!s.data.match(jsre))s.data=(s.data?s.data+"&":"")+(s.jsonp||"callback")+"=?";s.dataType="json";}if(s.dataType=="json"&&(s.data&&s.data.match(jsre)||s.url.match(jsre))){jsonp="jsonp"+jsc++;if(s.data)s.data=(s.data+"").replace(jsre,"="+jsonp+"$1");s.url=s.url.replace(jsre,"="+jsonp+"$1");s.dataType="script";window[jsonp]=function(tmp){data=tmp;success();complete();window[jsonp]=undefined;try{delete window[jsonp];}catch(e){}if(head)head.removeChild(script);};}if(s.dataType=="script"&&s.cache==null)s.cache=false;if(s.cache===false&&type=="GET"){var ts=now();var ret=s.url.replace(/(\?|&)_=.*?(&|$)/,"$1_="+ts+"$2");s.url=ret+((ret==s.url)?(s.url.match(/\?/)?"&":"?")+"_="+ts:"");}if(s.data&&type=="GET"){s.url+=(s.url.match(/\?/)?"&":"?")+s.data;s.data=null;}if(s.global&&!jQuery.active++)jQuery.event.trigger("ajaxStart");var remote=/^(?:\w+:)?\/\/([^\/?#]+)/;if(s.dataType=="script"&&type=="GET"&&remote.test(s.url)&&remote.exec(s.url)[1]!=location.host){var head=document.getElementsByTagName("head")[0];var script=document.createElement("script");script.src=s.url;if(s.scriptCharset)script.charset=s.scriptCharset;if(!jsonp){var done=false;script.onload=script.onreadystatechange=function(){if(!done&&(!this.readyState||this.readyState=="loaded"||this.readyState=="complete")){done=true;success();complete();head.removeChild(script);}};}head.appendChild(script);return undefined;}var requestDone=false;var xhr=window.ActiveXObject?new ActiveXObject("Microsoft.XMLHTTP"):new XMLHttpRequest();if(s.username)xhr.open(type,s.url,s.async,s.username,s.password);else -xhr.open(type,s.url,s.async);try{if(s.data)xhr.setRequestHeader("Content-Type",s.contentType);if(s.ifModified)xhr.setRequestHeader("If-Modified-Since",jQuery.lastModified[s.url]||"Thu, 01 Jan 1970 00:00:00 GMT");xhr.setRequestHeader("X-Requested-With","XMLHttpRequest");xhr.setRequestHeader("Accept",s.dataType&&s.accepts[s.dataType]?s.accepts[s.dataType]+", */*":s.accepts._default);}catch(e){}if(s.beforeSend&&s.beforeSend(xhr,s)===false){s.global&&jQuery.active--;xhr.abort();return false;}if(s.global)jQuery.event.trigger("ajaxSend",[xhr,s]);var onreadystatechange=function(isTimeout){if(!requestDone&&xhr&&(xhr.readyState==4||isTimeout=="timeout")){requestDone=true;if(ival){clearInterval(ival);ival=null;}status=isTimeout=="timeout"&&"timeout"||!jQuery.httpSuccess(xhr)&&"error"||s.ifModified&&jQuery.httpNotModified(xhr,s.url)&&"notmodified"||"success";if(status=="success"){try{data=jQuery.httpData(xhr,s.dataType,s.dataFilter);}catch(e){status="parsererror";}}if(status=="success"){var modRes;try{modRes=xhr.getResponseHeader("Last-Modified");}catch(e){}if(s.ifModified&&modRes)jQuery.lastModified[s.url]=modRes;if(!jsonp)success();}else -jQuery.handleError(s,xhr,status);complete();if(s.async)xhr=null;}};if(s.async){var ival=setInterval(onreadystatechange,13);if(s.timeout>0)setTimeout(function(){if(xhr){xhr.abort();if(!requestDone)onreadystatechange("timeout");}},s.timeout);}try{xhr.send(s.data);}catch(e){jQuery.handleError(s,xhr,null,e);}if(!s.async)onreadystatechange();function success(){if(s.success)s.success(data,status);if(s.global)jQuery.event.trigger("ajaxSuccess",[xhr,s]);}function complete(){if(s.complete)s.complete(xhr,status);if(s.global)jQuery.event.trigger("ajaxComplete",[xhr,s]);if(s.global&&!--jQuery.active)jQuery.event.trigger("ajaxStop");}return xhr;},handleError:function(s,xhr,status,e){if(s.error)s.error(xhr,status,e);if(s.global)jQuery.event.trigger("ajaxError",[xhr,s,e]);},active:0,httpSuccess:function(xhr){try{return!xhr.status&&location.protocol=="file:"||(xhr.status>=200&&xhr.status<300)||xhr.status==304||xhr.status==1223||jQuery.browser.safari&&xhr.status==undefined;}catch(e){}return false;},httpNotModified:function(xhr,url){try{var xhrRes=xhr.getResponseHeader("Last-Modified");return xhr.status==304||xhrRes==jQuery.lastModified[url]||jQuery.browser.safari&&xhr.status==undefined;}catch(e){}return false;},httpData:function(xhr,type,filter){var ct=xhr.getResponseHeader("content-type"),xml=type=="xml"||!type&&ct&&ct.indexOf("xml")>=0,data=xml?xhr.responseXML:xhr.responseText;if(xml&&data.documentElement.tagName=="parsererror")throw"parsererror";if(filter)data=filter(data,type);if(type=="script")jQuery.globalEval(data);if(type=="json")data=eval("("+data+")");return data;},param:function(a){var s=[];if(a.constructor==Array||a.jquery)jQuery.each(a,function(){s.push(encodeURIComponent(this.name)+"="+encodeURIComponent(this.value));});else -for(var j in a)if(a[j]&&a[j].constructor==Array)jQuery.each(a[j],function(){s.push(encodeURIComponent(j)+"="+encodeURIComponent(this));});else -s.push(encodeURIComponent(j)+"="+encodeURIComponent(jQuery.isFunction(a[j])?a[j]():a[j]));return s.join("&").replace(/%20/g,"+");}});jQuery.fn.extend({show:function(speed,callback){return speed?this.animate({height:"show",width:"show",opacity:"show"},speed,callback):this.filter(":hidden").each(function(){this.style.display=this.oldblock||"";if(jQuery.css(this,"display")=="none"){var elem=jQuery("<"+this.tagName+" />").appendTo("body");this.style.display=elem.css("display");if(this.style.display=="none")this.style.display="block";elem.remove();}}).end();},hide:function(speed,callback){return speed?this.animate({height:"hide",width:"hide",opacity:"hide"},speed,callback):this.filter(":visible").each(function(){this.oldblock=this.oldblock||jQuery.css(this,"display");this.style.display="none";}).end();},_toggle:jQuery.fn.toggle,toggle:function(fn,fn2){return jQuery.isFunction(fn)&&jQuery.isFunction(fn2)?this._toggle.apply(this,arguments):fn?this.animate({height:"toggle",width:"toggle",opacity:"toggle"},fn,fn2):this.each(function(){jQuery(this)[jQuery(this).is(":hidden")?"show":"hide"]();});},slideDown:function(speed,callback){return this.animate({height:"show"},speed,callback);},slideUp:function(speed,callback){return this.animate({height:"hide"},speed,callback);},slideToggle:function(speed,callback){return this.animate({height:"toggle"},speed,callback);},fadeIn:function(speed,callback){return this.animate({opacity:"show"},speed,callback);},fadeOut:function(speed,callback){return this.animate({opacity:"hide"},speed,callback);},fadeTo:function(speed,to,callback){return this.animate({opacity:to},speed,callback);},animate:function(prop,speed,easing,callback){var optall=jQuery.speed(speed,easing,callback);return this[optall.queue===false?"each":"queue"](function(){if(this.nodeType!=1)return false;var opt=jQuery.extend({},optall),p,hidden=jQuery(this).is(":hidden"),self=this;for(p in prop){if(prop[p]=="hide"&&hidden||prop[p]=="show"&&!hidden)return opt.complete.call(this);if(p=="height"||p=="width"){opt.display=jQuery.css(this,"display");opt.overflow=this.style.overflow;}}if(opt.overflow!=null)this.style.overflow="hidden";opt.curAnim=jQuery.extend({},prop);jQuery.each(prop,function(name,val){var e=new jQuery.fx(self,opt,name);if(/toggle|show|hide/.test(val))e[val=="toggle"?hidden?"show":"hide":val](prop);else{var parts=val.toString().match(/^([+-]=)?([\d+-.]+)(.*)$/),start=e.cur(true)||0;if(parts){var end=parseFloat(parts[2]),unit=parts[3]||"px";if(unit!="px"){self.style[name]=(end||1)+unit;start=((end||1)/e.cur(true))*start;self.style[name]=start+unit;}if(parts[1])end=((parts[1]=="-="?-1:1)*end)+start;e.custom(start,end,unit);}else -e.custom(start,val,"");}});return true;});},queue:function(type,fn){if(jQuery.isFunction(type)||(type&&type.constructor==Array)){fn=type;type="fx";}if(!type||(typeof type=="string"&&!fn))return queue(this[0],type);return this.each(function(){if(fn.constructor==Array)queue(this,type,fn);else{queue(this,type).push(fn);if(queue(this,type).length==1)fn.call(this);}});},stop:function(clearQueue,gotoEnd){var timers=jQuery.timers;if(clearQueue)this.queue([]);this.each(function(){for(var i=timers.length-1;i>=0;i--)if(timers[i].elem==this){if(gotoEnd)timers[i](true);timers.splice(i,1);}});if(!gotoEnd)this.dequeue();return this;}});var queue=function(elem,type,array){if(elem){type=type||"fx";var q=jQuery.data(elem,type+"queue");if(!q||array)q=jQuery.data(elem,type+"queue",jQuery.makeArray(array));}return q;};jQuery.fn.dequeue=function(type){type=type||"fx";return this.each(function(){var q=queue(this,type);q.shift();if(q.length)q[0].call(this);});};jQuery.extend({speed:function(speed,easing,fn){var opt=speed&&speed.constructor==Object?speed:{complete:fn||!fn&&easing||jQuery.isFunction(speed)&&speed,duration:speed,easing:fn&&easing||easing&&easing.constructor!=Function&&easing};opt.duration=(opt.duration&&opt.duration.constructor==Number?opt.duration:jQuery.fx.speeds[opt.duration])||jQuery.fx.speeds.def;opt.old=opt.complete;opt.complete=function(){if(opt.queue!==false)jQuery(this).dequeue();if(jQuery.isFunction(opt.old))opt.old.call(this);};return opt;},easing:{linear:function(p,n,firstNum,diff){return firstNum+diff*p;},swing:function(p,n,firstNum,diff){return((-Math.cos(p*Math.PI)/2)+0.5)*diff+firstNum;}},timers:[],timerId:null,fx:function(elem,options,prop){this.options=options;this.elem=elem;this.prop=prop;if(!options.orig)options.orig={};}});jQuery.fx.prototype={update:function(){if(this.options.step)this.options.step.call(this.elem,this.now,this);(jQuery.fx.step[this.prop]||jQuery.fx.step._default)(this);if(this.prop=="height"||this.prop=="width")this.elem.style.display="block";},cur:function(force){if(this.elem[this.prop]!=null&&this.elem.style[this.prop]==null)return this.elem[this.prop];var r=parseFloat(jQuery.css(this.elem,this.prop,force));return r&&r>-10000?r:parseFloat(jQuery.curCSS(this.elem,this.prop))||0;},custom:function(from,to,unit){this.startTime=now();this.start=from;this.end=to;this.unit=unit||this.unit||"px";this.now=this.start;this.pos=this.state=0;this.update();var self=this;function t(gotoEnd){return self.step(gotoEnd);}t.elem=this.elem;jQuery.timers.push(t);if(jQuery.timerId==null){jQuery.timerId=setInterval(function(){var timers=jQuery.timers;for(var i=0;ithis.options.duration+this.startTime){this.now=this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;var done=true;for(var i in this.options.curAnim)if(this.options.curAnim[i]!==true)done=false;if(done){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;this.elem.style.display=this.options.display;if(jQuery.css(this.elem,"display")=="none")this.elem.style.display="block";}if(this.options.hide)this.elem.style.display="none";if(this.options.hide||this.options.show)for(var p in this.options.curAnim)jQuery.attr(this.elem.style,p,this.options.orig[p]);}if(done)this.options.complete.call(this.elem);return false;}else{var n=t-this.startTime;this.state=n/this.options.duration;this.pos=jQuery.easing[this.options.easing||(jQuery.easing.swing?"swing":"linear")](this.state,n,0,1,this.options.duration);this.now=this.start+((this.end-this.start)*this.pos);this.update();}return true;}};jQuery.extend(jQuery.fx,{speeds:{slow:600,fast:200,def:400},step:{scrollLeft:function(fx){fx.elem.scrollLeft=fx.now;},scrollTop:function(fx){fx.elem.scrollTop=fx.now;},opacity:function(fx){jQuery.attr(fx.elem.style,"opacity",fx.now);},_default:function(fx){fx.elem.style[fx.prop]=fx.now+fx.unit;}}});jQuery.fn.offset=function(){var left=0,top=0,elem=this[0],results;if(elem)with(jQuery.browser){var parent=elem.parentNode,offsetChild=elem,offsetParent=elem.offsetParent,doc=elem.ownerDocument,safari2=safari&&parseInt(version)<522&&!/adobeair/i.test(userAgent),css=jQuery.curCSS,fixed=css(elem,"position")=="fixed";if(elem.getBoundingClientRect){var box=elem.getBoundingClientRect();add(box.left+Math.max(doc.documentElement.scrollLeft,doc.body.scrollLeft),box.top+Math.max(doc.documentElement.scrollTop,doc.body.scrollTop));add(-doc.documentElement.clientLeft,-doc.documentElement.clientTop);}else{add(elem.offsetLeft,elem.offsetTop);while(offsetParent){add(offsetParent.offsetLeft,offsetParent.offsetTop);if(mozilla&&!/^t(able|d|h)$/i.test(offsetParent.tagName)||safari&&!safari2)border(offsetParent);if(!fixed&&css(offsetParent,"position")=="fixed")fixed=true;offsetChild=/^body$/i.test(offsetParent.tagName)?offsetChild:offsetParent;offsetParent=offsetParent.offsetParent;}while(parent&&parent.tagName&&!/^body|html$/i.test(parent.tagName)){if(!/^inline|table.*$/i.test(css(parent,"display")))add(-parent.scrollLeft,-parent.scrollTop);if(mozilla&&css(parent,"overflow")!="visible")border(parent);parent=parent.parentNode;}if((safari2&&(fixed||css(offsetChild,"position")=="absolute"))||(mozilla&&css(offsetChild,"position")!="absolute"))add(-doc.body.offsetLeft,-doc.body.offsetTop);if(fixed)add(Math.max(doc.documentElement.scrollLeft,doc.body.scrollLeft),Math.max(doc.documentElement.scrollTop,doc.body.scrollTop));}results={top:top,left:left};}function border(elem){add(jQuery.curCSS(elem,"borderLeftWidth",true),jQuery.curCSS(elem,"borderTopWidth",true));}function add(l,t){left+=parseInt(l,10)||0;top+=parseInt(t,10)||0;}return results;};jQuery.fn.extend({position:function(){var left=0,top=0,results;if(this[0]){var offsetParent=this.offsetParent(),offset=this.offset(),parentOffset=/^body|html$/i.test(offsetParent[0].tagName)?{top:0,left:0}:offsetParent.offset();offset.top-=num(this,'marginTop');offset.left-=num(this,'marginLeft');parentOffset.top+=num(offsetParent,'borderTopWidth');parentOffset.left+=num(offsetParent,'borderLeftWidth');results={top:offset.top-parentOffset.top,left:offset.left-parentOffset.left};}return results;},offsetParent:function(){var offsetParent=this[0].offsetParent;while(offsetParent&&(!/^body|html$/i.test(offsetParent.tagName)&&jQuery.css(offsetParent,'position')=='static'))offsetParent=offsetParent.offsetParent;return jQuery(offsetParent);}});jQuery.each(['Left','Top'],function(i,name){var method='scroll'+name;jQuery.fn[method]=function(val){if(!this[0])return;return val!=undefined?this.each(function(){this==window||this==document?window.scrollTo(!i?val:jQuery(window).scrollLeft(),i?val:jQuery(window).scrollTop()):this[method]=val;}):this[0]==window||this[0]==document?self[i?'pageYOffset':'pageXOffset']||jQuery.boxModel&&document.documentElement[method]||document.body[method]:this[0][method];};});jQuery.each(["Height","Width"],function(i,name){var tl=i?"Left":"Top",br=i?"Right":"Bottom";jQuery.fn["inner"+name]=function(){return this[name.toLowerCase()]()+num(this,"padding"+tl)+num(this,"padding"+br);};jQuery.fn["outer"+name]=function(margin){return this["inner"+name]()+num(this,"border"+tl+"Width")+num(this,"border"+br+"Width")+(margin?num(this,"margin"+tl)+num(this,"margin"+br):0);};});})(); \ No newline at end of file diff --git a/sphinx/static/minus.png b/sphinx/static/minus.png deleted file mode 100644 index da1c5620..00000000 Binary files a/sphinx/static/minus.png and /dev/null differ diff --git a/sphinx/static/navigation.png b/sphinx/static/navigation.png deleted file mode 100644 index 1081dc14..00000000 Binary files a/sphinx/static/navigation.png and /dev/null differ diff --git a/sphinx/static/plus.png b/sphinx/static/plus.png deleted file mode 100644 index b3cb3742..00000000 Binary files a/sphinx/static/plus.png and /dev/null differ diff --git a/sphinx/static/rightsidebar.css b/sphinx/static/rightsidebar.css deleted file mode 100644 index bc604a89..00000000 --- a/sphinx/static/rightsidebar.css +++ /dev/null @@ -1,16 +0,0 @@ -/** - * Sphinx Doc Design -- Right Side Bar Overrides - */ - - -div.sphinxsidebar { - float: right; -} - -div.bodywrapper { - margin: 0 230px 0 0; -} - -div.inlinecomments { - right: 250px; -} diff --git a/sphinx/static/searchtools.js b/sphinx/static/searchtools.js deleted file mode 100644 index f9d9b6c3..00000000 --- a/sphinx/static/searchtools.js +++ /dev/null @@ -1,467 +0,0 @@ -/** - * helper function to return a node containing the - * search summary for a given text. keywords is a list - * of stemmed words, hlwords is the list of normal, unstemmed - * words. the first one is used to find the occurance, the - * latter for highlighting it. - */ - -jQuery.makeSearchSummary = function(text, keywords, hlwords) { - var textLower = text.toLowerCase(); - var start = 0; - $.each(keywords, function() { - var i = textLower.indexOf(this.toLowerCase()); - if (i > -1) - start = i; - }); - start = Math.max(start - 120, 0); - var excerpt = ((start > 0) ? '...' : '') + - $.trim(text.substr(start, 240)) + - ((start + 240 - text.length) ? '...' : ''); - var rv = $('
    ').text(excerpt); - $.each(hlwords, function() { - rv = rv.highlightText(this, 'highlight'); - }); - return rv; -} - -/** - * Porter Stemmer - */ -var PorterStemmer = function() { - - var step2list = { - ational: 'ate', - tional: 'tion', - enci: 'ence', - anci: 'ance', - izer: 'ize', - bli: 'ble', - alli: 'al', - entli: 'ent', - eli: 'e', - ousli: 'ous', - ization: 'ize', - ation: 'ate', - ator: 'ate', - alism: 'al', - iveness: 'ive', - fulness: 'ful', - ousness: 'ous', - aliti: 'al', - iviti: 'ive', - biliti: 'ble', - logi: 'log' - }; - - var step3list = { - icate: 'ic', - ative: '', - alize: 'al', - iciti: 'ic', - ical: 'ic', - ful: '', - ness: '' - }; - - var c = "[^aeiou]"; // consonant - var v = "[aeiouy]"; // vowel - var C = c + "[^aeiouy]*"; // consonant sequence - var V = v + "[aeiou]*"; // vowel sequence - - var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 - var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 - var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 - var s_v = "^(" + C + ")?" + v; // vowel in stem - - this.stemWord = function (w) { - var stem; - var suffix; - var firstch; - var origword = w; - - if (w.length < 3) - return w; - - var re; - var re2; - var re3; - var re4; - - firstch = w.substr(0,1); - if (firstch == "y") - w = firstch.toUpperCase() + w.substr(1); - - // Step 1a - re = /^(.+?)(ss|i)es$/; - re2 = /^(.+?)([^s])s$/; - - if (re.test(w)) - w = w.replace(re,"$1$2"); - else if (re2.test(w)) - w = w.replace(re2,"$1$2"); - - // Step 1b - re = /^(.+?)eed$/; - re2 = /^(.+?)(ed|ing)$/; - if (re.test(w)) { - var fp = re.exec(w); - re = new RegExp(mgr0); - if (re.test(fp[1])) { - re = /.$/; - w = w.replace(re,""); - } - } - else if (re2.test(w)) { - var fp = re2.exec(w); - stem = fp[1]; - re2 = new RegExp(s_v); - if (re2.test(stem)) { - w = stem; - re2 = /(at|bl|iz)$/; - re3 = new RegExp("([^aeiouylsz])\\1$"); - re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); - if (re2.test(w)) - w = w + "e"; - else if (re3.test(w)) { - re = /.$/; - w = w.replace(re,""); - } - else if (re4.test(w)) - w = w + "e"; - } - } - - // Step 1c - re = /^(.+?)y$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(s_v); - if (re.test(stem)) - w = stem + "i"; - } - - // Step 2 - re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - suffix = fp[2]; - re = new RegExp(mgr0); - if (re.test(stem)) - w = stem + step2list[suffix]; - } - - // Step 3 - re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - suffix = fp[2]; - re = new RegExp(mgr0); - if (re.test(stem)) - w = stem + step3list[suffix]; - } - - // Step 4 - re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; - re2 = /^(.+?)(s|t)(ion)$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(mgr1); - if (re.test(stem)) - w = stem; - } - else if (re2.test(w)) { - var fp = re2.exec(w); - stem = fp[1] + fp[2]; - re2 = new RegExp(mgr1); - if (re2.test(stem)) - w = stem; - } - - // Step 5 - re = /^(.+?)e$/; - if (re.test(w)) { - var fp = re.exec(w); - stem = fp[1]; - re = new RegExp(mgr1); - re2 = new RegExp(meq1); - re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); - if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) - w = stem; - } - re = /ll$/; - re2 = new RegExp(mgr1); - if (re.test(w) && re2.test(w)) { - re = /.$/; - w = w.replace(re,""); - } - - // and turn initial Y back to y - if (firstch == "y") - w = firstch.toLowerCase() + w.substr(1); - return w; - } -} - - -/** - * Search Module - */ -var Search = { - - _index : null, - _queued_query : null, - _pulse_status : -1, - - init : function() { - var params = $.getQueryParameters(); - if (params.q) { - var query = params.q[0]; - $('input[@name="q"]')[0].value = query; - this.performSearch(query); - } - }, - - /** - * Sets the index - */ - setIndex : function(index) { - var q; - this._index = index; - if ((q = this._queued_query) !== null) { - this._queued_query = null; - Search.query(q); - } - }, - - hasIndex : function() { - return this._index !== null; - }, - - deferQuery : function(query) { - this._queued_query = query; - }, - - stopPulse : function() { - this._pulse_status = 0; - }, - - startPulse : function() { - if (this._pulse_status >= 0) - return; - function pulse() { - Search._pulse_status = (Search._pulse_status + 1) % 4; - var dotString = ''; - for (var i = 0; i < Search._pulse_status; i++) - dotString += '.'; - Search.dots.text(dotString); - if (Search._pulse_status > -1) - window.setTimeout(pulse, 500); - }; - pulse(); - }, - - /** - * perform a search for something - */ - performSearch : function(query) { - // create the required interface elements - this.out = $('#search-results'); - this.title = $('

    ' + _('Searching') + '

    ').appendTo(this.out); - this.dots = $('').appendTo(this.title); - this.status = $('

    ').appendTo(this.out); - this.output = $('
      ').appendTo(this.out); - - $('#search-progress').text(_('Preparing search...')); - this.startPulse(); - - // index already loaded, the browser was quick! - if (this.hasIndex()) - this.query(query); - else - this.setQuery(query); - }, - - query : function(query) { - // stem the searchterms and add them to the - // correct list - var stemmer = new PorterStemmer(); - var searchterms = []; - var excluded = []; - var hlterms = []; - var tmp = query.split(/\s+/); - var object = (tmp.length == 1) ? tmp[0].toLowerCase() : null; - for (var i = 0; i < tmp.length; i++) { - // stem the word - var word = stemmer.stemWord(tmp[i]).toLowerCase(); - // select the correct list - if (word[0] == '-') { - var toAppend = excluded; - word = word.substr(1); - } - else { - var toAppend = searchterms; - hlterms.push(tmp[i].toLowerCase()); - } - // only add if not already in the list - if (!$.contains(toAppend, word)) - toAppend.push(word); - }; - var highlightstring = '?highlight=' + $.urlencode(hlterms.join(" ")); - - console.debug('SEARCH: searching for:'); - console.info('required: ', searchterms); - console.info('excluded: ', excluded); - - // prepare search - var filenames = this._index.filenames; - var titles = this._index.titles; - var terms = this._index.terms; - var descrefs = this._index.descrefs; - var modules = this._index.modules; - var desctypes = this._index.desctypes; - var fileMap = {}; - var files = null; - var objectResults = []; - var regularResults = []; - $('#search-progress').empty(); - - // lookup as object - if (object != null) { - for (var module in modules) { - if (module.indexOf(object) > -1) { - fn = modules[module]; - descr = _('module, in ') + titles[fn]; - objectResults.push([filenames[fn], module, '#module-'+module, descr]); - } - } - for (var prefix in descrefs) { - for (var name in descrefs[prefix]) { - if (name.toLowerCase().indexOf(object) > -1) { - match = descrefs[prefix][name]; - fullname = (prefix ? prefix + '.' : '') + name; - descr = desctypes[match[1]] + _(', in ') + titles[match[0]]; - objectResults.push([filenames[match[0]], fullname, '#'+fullname, descr]); - } - } - } - } - - // sort results descending - objectResults.sort(function(a, b) { - return (a[1] > b[1]) ? -1 : ((a[1] < b[1]) ? 1 : 0); - }); - - - // perform the search on the required terms - for (var i = 0; i < searchterms.length; i++) { - var word = searchterms[i]; - // no match but word was a required one - if ((files = terms[word]) == null) - break; - if (files.length == undefined) { - files = [files]; - } - // create the mapping - for (var j = 0; j < files.length; j++) { - var file = files[j]; - if (file in fileMap) - fileMap[file].push(word); - else - fileMap[file] = [word]; - } - } - - // now check if the files don't contain excluded terms - for (var file in fileMap) { - var valid = true; - - // check if all requirements are matched - if (fileMap[file].length != searchterms.length) - continue; - - // ensure that none of the excluded terms is in the - // search result. - for (var i = 0; i < excluded.length; i++) { - if (terms[excluded[i]] == file || - $.contains(terms[excluded[i]] || [], file)) { - valid = false; - break; - } - } - - // if we have still a valid result we can add it - // to the result list - if (valid) - regularResults.push([filenames[file], titles[file], '', null]); - } - - // delete unused variables in order to not waste - // memory until list is retrieved completely - delete filenames, titles, terms; - - // now sort the regular results descending by title - regularResults.sort(function(a, b) { - var left = a[1].toLowerCase(); - var right = b[1].toLowerCase(); - return (left > right) ? -1 : ((left < right) ? 1 : 0); - }); - - // combine both - var results = regularResults.concat(objectResults); - - // print the results - var resultCount = results.length; - function displayNextItem() { - // results left, load the summary and display it - if (results.length) { - var item = results.pop(); - var listItem = $('
    • '); - listItem.append($('').attr( - 'href', - item[0] + DOCUMENTATION_OPTIONS.FILE_SUFFIX + - highlightstring + item[2]).html(item[1])); - if (item[3]) { - listItem.append($(' (' + item[3] + ')')); - Search.output.append(listItem); - listItem.slideDown(5, function() { - displayNextItem(); - }); - } else if (DOCUMENTATION_OPTIONS.HAS_SOURCE) { - $.get('_sources/' + item[0] + '.txt', function(data) { - listItem.append($.makeSearchSummary(data, searchterms, hlterms)); - Search.output.append(listItem); - listItem.slideDown(5, function() { - displayNextItem(); - }); - }); - } else { - // no source available, just display title - Search.output.append(listItem); - listItem.slideDown(5, function() { - displayNextItem(); - }); - } - } - // search finished, update title and status message - else { - Search.stopPulse(); - Search.title.text(_('Search Results')); - if (!resultCount) - Search.status.text(_('Your search did not match any documents. Please make sure that all words are spelled correctly and that you\'ve selected enough categories.')); - else - Search.status.text(_('Search finished, found %s page(s) matching the search query.').replace('%s', resultCount)); - Search.status.fadeIn(500); - } - } - displayNextItem(); - } -} - -$(document).ready(function() { - Search.init(); -}); diff --git a/sphinx/static/sphinxdoc.css b/sphinx/static/sphinxdoc.css deleted file mode 100644 index 999bf48c..00000000 --- a/sphinx/static/sphinxdoc.css +++ /dev/null @@ -1,557 +0,0 @@ -/** - * Alternate Sphinx design - * Originally created by Armin Ronacher for Werkzeug, adapted by Georg Brandl. - */ - -body { - font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', 'Verdana', sans-serif; - font-size: 14px; - letter-spacing: -0.01em; - line-height: 150%; - text-align: center; - /*background-color: #AFC1C4; */ - background-color: #BFD1D4; - color: black; - padding: 0; - border: 1px solid #aaa; - - margin: 0px 80px 0px 80px; - min-width: 740px; -} - -a { - color: #CA7900; - text-decoration: none; -} - -a:hover { - color: #2491CF; -} - -pre { - font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.015em; - padding: 0.5em; - border: 1px solid #ccc; - background-color: #f8f8f8; -} - -td.linenos pre { - padding: 0.5em 0; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -cite, code, tt { - font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.01em; -} - -hr { - border: 1px solid #abc; - margin: 2em; -} - -tt { - background-color: #f2f2f2; - border-bottom: 1px solid #ddd; - color: #333; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; - border: 0; -} - -tt.descclassname { - background-color: transparent; - border: 0; -} - -tt.xref { - background-color: transparent; - font-weight: bold; - border: 0; -} - -a tt { - background-color: transparent; - font-weight: bold; - border: 0; - color: #CA7900; -} - -a tt:hover { - color: #2491CF; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -.refcount { - color: #060; -} - -dt:target, -.highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -pre { - line-height: 120%; -} - -pre a { - color: inherit; - text-decoration: underline; -} - -.first { - margin-top: 0 !important; -} - -div.document { - background-color: white; - text-align: left; - background-image: url(contents.png); - background-repeat: repeat-x; -} - -/* -div.documentwrapper { - width: 100%; -} -*/ - -div.clearer { - clear: both; -} - -div.related h3 { - display: none; -} - -div.related ul { - background-image: url(navigation.png); - height: 2em; - list-style: none; - border-top: 1px solid #ddd; - border-bottom: 1px solid #ddd; - margin: 0; - padding-left: 10px; -} - -div.related ul li { - margin: 0; - padding: 0; - height: 2em; - float: left; -} - -div.related ul li.right { - float: right; - margin-right: 5px; -} - -div.related ul li a { - margin: 0; - padding: 0 5px 0 5px; - line-height: 1.75em; - color: #EE9816; -} - -div.related ul li a:hover { - color: #3CA8E7; -} - -div.body { - margin: 0; - padding: 0.5em 20px 20px 20px; -} - -div.bodywrapper { - margin: 0 240px 0 0; - border-right: 1px solid #ccc; -} - -div.body a { - text-decoration: underline; -} - -div.sphinxsidebar { - margin: 0; - padding: 0.5em 15px 15px 0; - width: 210px; - float: right; - text-align: left; -/* margin-left: -100%; */ -} - -div.sphinxsidebar h4, div.sphinxsidebar h3 { - margin: 1em 0 0.5em 0; - font-size: 0.9em; - padding: 0.1em 0 0.1em 0.5em; - color: white; - border: 1px solid #86989B; - background-color: #AFC1C4; -} - -div.sphinxsidebar h3 a { - color: white; -} - -div.sphinxsidebar ul { - padding-left: 1.5em; - margin-top: 7px; - list-style: none; - padding: 0; - line-height: 130%; -} - -div.sphinxsidebar ul ul { - list-style: square; - margin-left: 20px; -} - -p { - margin: 0.8em 0 0.5em 0; -} - -p.rubric { - font-weight: bold; -} - -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -div.quotebar { - background-color: #f8f8f8; - max-width: 250px; - float: right; - padding: 2px 7px; - border: 1px solid #ccc; -} - -p.sidebar-title { - font-weight: bold; -} - -div.topic { - background-color: #f8f8f8; - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; -} - -h1 { - margin: 0; - padding: 0.7em 0 0.3em 0; - font-size: 1.5em; - color: #11557C; -} - -h2 { - margin: 1.3em 0 0.2em 0; - font-size: 1.35em; - padding: 0; -} - -h3 { - margin: 1em 0 -0.3em 0; - font-size: 1.2em; -} - -div.body h1 a, div.body h2 a, div.body h3 a, div.body h4 a, div.body h5 a, div.body h6 a { - color: black!important; -} - -h1 a.anchor, h2 a.anchor, h3 a.anchor, h4 a.anchor, h5 a.anchor, h6 a.anchor { - display: none; - margin: 0 0 0 0.3em; - padding: 0 0.2em 0 0.2em; - color: #aaa!important; -} - -h1:hover a.anchor, h2:hover a.anchor, h3:hover a.anchor, h4:hover a.anchor, -h5:hover a.anchor, h6:hover a.anchor { - display: inline; -} - -h1 a.anchor:hover, h2 a.anchor:hover, h3 a.anchor:hover, h4 a.anchor:hover, -h5 a.anchor:hover, h6 a.anchor:hover { - color: #777; - background-color: #eee; -} - -table { - border-collapse: collapse; - margin: 0 -0.5em 0 -0.5em; -} - -table td, table th { - padding: 0.2em 0.5em 0.2em 0.5em; -} - -div.footer { - background-color: #E3EFF1; - color: #86989B; - padding: 3px 8px 3px 0; - clear: both; - font-size: 0.8em; - text-align: right; -} - -div.footer a { - color: #86989B; - text-decoration: underline; -} - -div.pagination { - margin-top: 2em; - padding-top: 0.5em; - border-top: 1px solid black; - text-align: center; -} - -div.sphinxsidebar ul.toc { - margin: 1em 0 1em 0; - padding: 0 0 0 0.5em; - list-style: none; -} - -div.sphinxsidebar ul.toc li { - margin: 0.5em 0 0.5em 0; - font-size: 0.9em; - line-height: 130%; -} - -div.sphinxsidebar ul.toc li p { - margin: 0; - padding: 0; -} - -div.sphinxsidebar ul.toc ul { - margin: 0.2em 0 0.2em 0; - padding: 0 0 0 1.8em; -} - -div.sphinxsidebar ul.toc ul li { - padding: 0; -} - -div.admonition, div.warning { - font-size: 0.9em; - margin: 1em 0 0 0; - border: 1px solid #86989B; - background-color: #f7f7f7; -} - -div.admonition p, div.warning p { - margin: 0.5em 1em 0.5em 1em; - padding: 0; -} - -div.admonition pre, div.warning pre { - margin: 0.4em 1em 0.4em 1em; -} - -div.admonition p.admonition-title, -div.warning p.admonition-title { - margin: 0; - padding: 0.1em 0 0.1em 0.5em; - color: white; - border-bottom: 1px solid #86989B; - font-weight: bold; - background-color: #AFC1C4; -} - -div.warning { - border: 1px solid #940000; -} - -div.warning p.admonition-title { - background-color: #CF0000; - border-bottom-color: #940000; -} - -div.admonition ul, div.admonition ol, -div.warning ul, div.warning ol { - margin: 0.1em 0.5em 0.5em 3em; - padding: 0; -} - -div.versioninfo { - margin: 1em 0 0 0; - border: 1px solid #ccc; - background-color: #DDEAF0; - padding: 8px; - line-height: 1.3em; - font-size: 0.9em; -} - - -a.headerlink { - color: #c60f0f!important; - font-size: 1em; - margin-left: 6px; - padding: 0 4px 0 4px; - text-decoration: none!important; - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -a.headerlink:hover { - background-color: #ccc; - color: white!important; -} - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -form.pfform { - margin: 10px 0 20px 0; -} - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -img.math { - vertical-align: center; -} - -div.math { - text-align: center; -} - -span.eqno { - float: right; -} - -img.logo { - border: 0; -} diff --git a/sphinx/static/stickysidebar.css b/sphinx/static/stickysidebar.css deleted file mode 100644 index dfc99c77..00000000 --- a/sphinx/static/stickysidebar.css +++ /dev/null @@ -1,19 +0,0 @@ -/** - * Sphinx Doc Design -- Sticky sidebar Overrides - */ - -div.sphinxsidebar { - top: 30px; - left: 0px; - position: fixed; - margin: 0; - float: none; -} - -div.related { - position: fixed; -} - -div.documentwrapper { - margin-top: 30px; -} diff --git a/sphinx/static/traditional.css b/sphinx/static/traditional.css deleted file mode 100644 index 8c224c07..00000000 --- a/sphinx/static/traditional.css +++ /dev/null @@ -1,700 +0,0 @@ -/** - * Sphinx Doc Design -- traditional python.org style - */ - -body { - color: #000; - margin: 0; - padding: 0; -} - -/* :::: LAYOUT :::: */ - -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 230px 0 0; -} - -div.body { - background-color: white; - padding: 0 20px 30px 20px; -} - -div.sphinxsidebarwrapper { - border: 1px solid #99ccff; - padding: 10px; - margin: 10px 15px 10px 0; -} - -div.sphinxsidebar { - float: right; - margin-left: -100%; - width: 230px; -} - -div.clearer { - clear: both; -} - -div.footer { - clear: both; - width: 100%; - background-color: #99ccff; - padding: 9px 0 9px 0; - text-align: center; -} - -div.related { - background-color: #99ccff; - color: #333; - width: 100%; - height: 30px; - line-height: 30px; - border-bottom: 5px solid white; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; - font-weight: bold; -} - -div.related li.right { - float: right; - margin-right: 5px; -} - -/* ::: SIDEBAR :::: */ -div.sphinxsidebar h3 { - margin: 0; -} - -div.sphinxsidebar h4 { - margin: 5px 0 0 0; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - margin-left: 15px; - padding: 0; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - -div.sphinxsidebar form { - margin-top: 10px; -} - - -/* :::: SEARCH :::: */ -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* :::: COMMON FORM STYLES :::: */ - -div.actions { - border-top: 1px solid #aaa; - background-color: #ddd; - margin: 10px 0 0 -20px; - padding: 5px 0 5px 20px; -} - -form dl { - color: #333; -} - -form dt { - clear: both; - float: left; - min-width: 110px; - margin-right: 10px; - padding-top: 2px; -} - -input#homepage { - display: none; -} - -div.error { - margin: 5px 20px 0 0; - padding: 5px; - border: 1px solid #d00; - /*border: 2px solid #05171e; - background-color: #092835; - color: white;*/ - font-weight: bold; -} - -/* :::: INLINE COMMENTS :::: */ - -div.inlinecommentswrapper { - float: right; - max-width: 40%; -} - -div.commentmarker { - float: right; - background-image: url(style/comment.png); - background-repeat: no-repeat; - width: 25px; - height: 25px; - text-align: center; - padding-top: 3px; -} - -div.nocommentmarker { - float: right; - background-image: url(style/nocomment.png); - background-repeat: no-repeat; - width: 25px; - height: 25px; -} - -div.inlinecomments { - margin-left: 10px; - margin-bottom: 5px; - background-color: #eee; - border: 1px solid #ccc; - padding: 5px; -} - -div.inlinecomment { - border-top: 1px solid #ccc; - padding-top: 5px; - margin-top: 5px; -} - -.inlinecomments p { - margin: 5px 0 5px 0; -} - -.inlinecomments .head { - font-weight: bold; -} - -.inlinecomments .meta { - font-style: italic; -} - - -/* :::: COMMENTS :::: */ - -div#comments h3 { - border-top: 1px solid #aaa; - padding: 5px 20px 5px 20px; - margin: 20px -20px 20px -20px; - background-color: #ddd; -} - -/* -div#comments { - background-color: #ccc; - margin: 40px -20px -30px -20px; - padding: 0 0 1px 0; -} - -div#comments h4 { - margin: 30px 0 20px 0; - background-color: #aaa; - border-bottom: 1px solid #09232e; - color: #333; -} - -div#comments form { - display: block; - margin: 0 0 0 20px; -} - -div#comments textarea { - width: 98%; - height: 160px; -} - -div#comments div.help { - margin: 20px 20px 10px 0; - background-color: #ccc; - color: #333; -} - -div#comments div.help p { - margin: 0; - padding: 0 0 10px 0; -} - -div#comments input, div#comments textarea { - font-family: 'Bitstream Vera Sans', 'Arial', sans-serif; - font-size: 13px; - color: black; - background-color: #aaa; - border: 1px solid #092835; -} - -div#comments input[type="reset"], -div#comments input[type="submit"] { - cursor: pointer; - font-weight: bold; - padding: 2px; - margin: 5px 5px 5px 0; - background-color: #666; - color: white; -} - -div#comments div.comment { - margin: 10px 10px 10px 20px; - padding: 10px; - border: 1px solid #0f3646; - background-color: #aaa; - color: #333; -} - -div#comments div.comment p { - margin: 5px 0 5px 0; -} - -div#comments div.comment p.meta { - font-style: italic; - color: #444; - text-align: right; - margin: -5px 0 -5px 0; -} - -div#comments div.comment h4 { - margin: -10px -10px 5px -10px; - padding: 3px; - font-size: 15px; - background-color: #888; - color: white; - border: 0; -} - -div#comments div.comment pre, -div#comments div.comment tt { - background-color: #ddd; - color: #111; - border: none; -} - -div#comments div.comment a { - color: #fff; - text-decoration: underline; -} - -div#comments div.comment blockquote { - margin: 10px; - padding: 10px; - border-left: 1px solid #0f3646; - /*border: 1px solid #0f3646; - background-color: #071c25;*/ -} - -div#comments em.important { - color: #d00; - font-weight: bold; - font-style: normal; -}*/ - -/* :::: SUGGEST CHANGES :::: */ -div#suggest-changes-box input, div#suggest-changes-box textarea { - border: 1px solid #ccc; - background-color: white; - color: black; -} - -div#suggest-changes-box textarea { - width: 99%; - height: 400px; -} - - -/* :::: PREVIEW :::: */ -div.preview { - background-image: url(style/preview.png); - padding: 0 20px 20px 20px; - margin-bottom: 30px; -} - - -/* :::: INDEX PAGE :::: */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.5em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; -} - -/* :::: GENINDEX STYLES :::: */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -/* :::: GLOBAL STYLES :::: */ - -p.subhead { - font-weight: bold; - margin-top: 20px; -} - -a:link:active { color: #ff0000; } -a:link:hover { background-color: #bbeeff; } -a:visited:hover { background-color: #bbeeff; } -a:visited { color: #551a8b; } -a:link { color: #0000bb; } - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: avantgarde, sans-serif; - font-weight: bold; -} - -div.body h1 { font-size: 180%; } -div.body h2 { font-size: 150%; } -div.body h3 { font-size: 120%; } -div.body h4 { font-size: 120%; } - -a.headerlink, -a.headerlink, -a.headerlink, -a.headerlink, -a.headerlink, -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; - visibility: hidden; -} - -*:hover > a.headerlink, -*:hover > a.headerlink, -*:hover > a.headerlink, -*:hover > a.headerlink, -*:hover > a.headerlink, -*:hover > a.headerlink { - visibility: visible; -} - -a.headerlink:hover, -a.headerlink:hover, -a.headerlink:hover, -a.headerlink:hover, -a.headerlink:hover, -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: justify; -} - -div.body td { - text-align: left; -} - -ul.fakelist { - list-style: none; - margin: 10px 0 10px 20px; - padding: 0; -} - -/* "Footnotes" heading */ -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* "Topics" */ - -div.topic { - background-color: #eee; - border: 1px solid #ccc; - padding: 0 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* Admonitions */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dd { - margin-bottom: 10px; -} - -div.admonition dl { - margin-bottom: 0; -} - -div.admonition p { - display: inline; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -table.docutils { - border: 0; -} - -table.docutils td, table.docutils th { - padding: 0 8px 2px 0; - border-top: 0; - border-left: 0; - border-right: 0; - border-bottom: 1px solid #aaa; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -dl { - margin-bottom: 15px; - clear: both; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -.refcount { - color: #060; -} - -th { - text-align: left; - padding-right: 5px; -} - -pre { - font-family: monospace; - padding: 5px; - color: #00008b; - border-left: none; - border-right: none; -} - -tt { - font-family: monospace; - background-color: #ecf0f3; - padding: 0 1px 0 1px; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -.footnote:target { background-color: #ffa } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -form.comment { - margin: 0; - padding: 10px 30px 10px 30px; - background-color: #eee; -} - -form.comment h3 { - background-color: #326591; - color: white; - margin: -10px -30px 10px -30px; - padding: 5px; - font-size: 1.4em; -} - -form.comment input, -form.comment textarea { - border: 1px solid #ccc; - padding: 2px; - font-family: sans-serif; - font-size: 13px; -} - -form.comment input[type="text"] { - width: 240px; -} - -form.comment textarea { - width: 100%; - height: 200px; - margin-bottom: 10px; -} - -/* :::: PRINT :::: */ -@media print { - div.documentwrapper { - width: 100%; - } - - div.body { - margin: 0; - } - - div.sphinxsidebar, - div.related, - div.footer, - div#comments div.new-comment-box, - #top-link { - display: none; - } -} diff --git a/sphinx/templates/changes/frameset.html b/sphinx/templates/changes/frameset.html deleted file mode 100644 index 9d9af9eb..00000000 --- a/sphinx/templates/changes/frameset.html +++ /dev/null @@ -1,11 +0,0 @@ - - - - {% trans version=version|e, docstitle=docstitle|e %}Changes in Version {{ version }} — {{ docstitle }}{% endtrans %} - - - - - - diff --git a/sphinx/templates/changes/rstsource.html b/sphinx/templates/changes/rstsource.html deleted file mode 100644 index abd12c1d..00000000 --- a/sphinx/templates/changes/rstsource.html +++ /dev/null @@ -1,15 +0,0 @@ - - - - {% trans filename=filename, docstitle=docstitle|e %}{{ filename }} — {{ docstitle }}{% endtrans %} - - - - 
      -      {{ text }}
-
      - - diff --git a/sphinx/templates/changes/versionchanges.html b/sphinx/templates/changes/versionchanges.html deleted file mode 100644 index 09651bf1..00000000 --- a/sphinx/templates/changes/versionchanges.html +++ /dev/null @@ -1,33 +0,0 @@ -{% macro entries(changes) %} -       -{% endmacro -%} - - - - - - {% trans version=version|e, docstitle=docstitle|e %}Changes in Version {{ version }} — {{ docstitle }}{% endtrans %} - - -
      -
      -

      {% trans version=version|e %}Automatically generated list of changes in version {{ version }}{% endtrans %}

      -

      {{ _('Library changes') }}

      - {% for modname, changes in libchanges %} -

      {{ modname }}

      - {{ entries(changes) }} - {% endfor %} -

      {{ _('C API changes') }}

      - {{ entries(apichanges) }} -

      {{ _('Other changes') }}

      - {% for (fn, title), changes in otherchanges %} -

      {{ title }} ({{ fn }})

      - {{ entries(changes) }} - {% endfor %} -
      -
      - - diff --git a/sphinx/templates/defindex.html b/sphinx/templates/defindex.html deleted file mode 100644 index 40f4f4c9..00000000 --- a/sphinx/templates/defindex.html +++ /dev/null @@ -1,26 +0,0 @@ -{% extends "layout.html" %} -{% set title = _('Overview') %} -{% block body %} -

      {{ docstitle|e }}

      -

      - Welcome! This is - {% block description %}the documentation for {{ project|e }} - {{ release|e }}{% if last_updated %}, last updated {{ last_updated|e }}{% endif %}{% endblock %}. -

      - {% block tables %} -

      {{ _('Indices and tables:') }}

      - - -
      -

      {{ _('Complete Table of Contents') }}
      - {{ _('lists all sections and subsections') }}

      -

      {{ _('Search Page') }}
      - {{ _('search this documentation') }}

      -       		-

      {{ _('Global Module Index') }}
      - {{ _('quick access to all modules') }}

      -

      {{ _('General Index') }}
      - {{ _('all functions, classes, terms') }}

      -
      - {% endblock %} -{% endblock %} diff --git a/sphinx/templates/genindex-single.html b/sphinx/templates/genindex-single.html deleted file mode 100644 index 9aaaeb0c..00000000 --- a/sphinx/templates/genindex-single.html +++ /dev/null @@ -1,46 +0,0 @@ -{% extends "layout.html" %} -{% set title = _('Index') %} -{% block body %} - -

      {% trans key=key %}Index – {{ key }}{% endtrans %}

      - -
      -
      -{%- set breakat = count // 2 %} -{%- set numcols = 1 %} -{%- set numitems = 0 %} -{% for entryname, (links, subitems) in entries %} -
      {%- if links -%}{{ entryname|e }} - {%- for link in links[1:] %}, [{{ loop.index }}]{% endfor -%} - {%- else -%} -{{ entryname|e }} - {%- endif -%}
      - {%- if subitems %} -
      - {%- for subentryname, subentrylinks in subitems %} -
      {{ subentryname|e }} - {%- for link in subentrylinks[1:] %}, [{{ loop.index }}]{% endfor -%} -
      - {%- endfor %} -
      - {%- endif -%} -{%- set numitems = numitems + 1 + (subitems|length) -%} -{%- if numcols < 2 and numitems > breakat -%} -{%- set numcols = numcols+1 -%} -
      -{%- endif -%} -{%- endfor %} -
      - -{% endblock %} - -{% block sidebarrel %} -

      Index

      -

      {% for key, dummy in genindexentries -%} - {{ key }} - {% if not loop.last %}| {% endif %} - {%- endfor %}

      - -

      {{ _('Full index on one page') }}

      - {{ super() }} -{% endblock %} diff --git a/sphinx/templates/genindex-split.html b/sphinx/templates/genindex-split.html deleted file mode 100644 index ab099e5b..00000000 --- a/sphinx/templates/genindex-split.html +++ /dev/null @@ -1,30 +0,0 @@ -{% extends "layout.html" %} -{% set title = _('Index') %} -{% block body %} - -

      {{ _('Index') }}

      - -

      {{ _('Index pages by letter') }}:

      - -

      {% for key, dummy in genindexentries -%} - {{ key }} - {% if not loop.last %}| {% endif %} - {%- endfor %}

      - -

      {{ _('Full index on one page') }} - ({{ _('can be huge') }})

      - -{% endblock %} - -{% block sidebarrel %} -{% if split_index %} -

      Index

      -

      {% for key, dummy in genindexentries -%} - {{ key }} - {% if not loop.last %}| {% endif %} - {%- endfor %}

      - -

      {{ _('Full index on one page') }}

      -{% endif %} - {{ super() }} -{% endblock %} diff --git a/sphinx/templates/genindex.html b/sphinx/templates/genindex.html deleted file mode 100644 index a19aa80f..00000000 --- a/sphinx/templates/genindex.html +++ /dev/null @@ -1,57 +0,0 @@ -{% extends "layout.html" %} -{% set title = _('Index') %} -{% block body %} - -

      {{ _('Index') }}

      - - {% for key, dummy in genindexentries -%} - {{ key }} {% if not loop.last %}| {% endif %} - {%- endfor %} - -
      - - {% for key, entries in genindexentries %} -

      {{ key }}

      -
      -
      -{%- set breakat = genindexcounts[loop.index0] // 2 %} -{%- set numcols = 1 %} -{%- set numitems = 0 %} -{% for entryname, (links, subitems) in entries %} -
      {%- if links -%}{{ entryname|e }} - {%- for link in links[1:] %}, [{{ loop.index }}]{% endfor -%} - {%- else -%} -{{ entryname|e }} - {%- endif -%}
      - {%- if subitems %} -
      - {%- for subentryname, subentrylinks in subitems %} -
      {{ subentryname|e }} - {%- for link in subentrylinks[1:] %}, [{{ loop.index }}]{% endfor -%} -
      - {%- endfor %} -
      - {%- endif -%} -{%- set numitems = numitems + 1 + (subitems|length) -%} -{%- if numcols < 2 and numitems > breakat -%} -{%- set numcols = numcols+1 -%} -
      -{%- endif -%} -{%- endfor %} -
      -{% endfor %} - -{% endblock %} - -{% block sidebarrel %} -{% if split_index %} -

      {{ _('Index') }}

      -

      {% for key, dummy in genindexentries -%} - {{ key }} - {% if not loop.last %}| {% endif %} - {%- endfor %}

      - -

      {{ _('Full index on one page') }}

      -{% endif %} - {{ super() }} -{% endblock %} diff --git a/sphinx/templates/layout.html b/sphinx/templates/layout.html deleted file mode 100644 index fb0df9e0..00000000 --- a/sphinx/templates/layout.html +++ /dev/null @@ -1,187 +0,0 @@ -{%- block doctype -%} - -{%- endblock %} -{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} -{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} -{%- macro relbar() %} -
      -

      {{ _('Navigation') }}

      -
        - {%- for rellink in rellinks %} -
      • - {{ rellink[3] }} - {%- if not loop.first %}{{ reldelim2 }}{% endif %}
        • - {%- endfor %} - {%- block rootrellink %} -
      • {{ shorttitle|e }}{{ reldelim1 }}
        • - {%- endblock %} - {%- for parent in parents %} -
      • {{ parent.title }}{{ reldelim1 }}
        • - {%- endfor %} - {%- block relbaritems %} {% endblock %} -
      -
      -{%- endmacro %} -{%- macro sidebar() %} - {%- if not embedded %} -
      -
      - {%- block sidebarlogo %} - {%- if logo %} - - {%- endif %} - {%- endblock %} - {%- block sidebartoc %} - {%- if display_toc %} -

      {{ _('Table Of Contents') }}

      - {{ toc }} - {%- endif %} - {%- endblock %} - {%- block sidebarrel %} - {%- if prev %} -

      {{ _('Previous topic') }}

      -

      {{ prev.title }}

      - {%- endif %} - {%- if next %} -

      {{ _('Next topic') }}

      -

      {{ next.title }}

      - {%- endif %} - {%- endblock %} - {%- block sidebarsourcelink %} - {%- if show_source and has_source and sourcename %} -

      {{ _('This Page') }}

      - - {%- endif %} - {%- endblock %} - {%- if customsidebar %} - {% include customsidebar %} - {%- endif %} - {%- block sidebarsearch %} - {%- if pagename != "search" %} - - - {%- endif %} - {%- endblock %} -
      -
      - {%- endif %} -{%- endmacro %} - - - - - {{ metatags }} - {%- if not embedded %} - {%- set titlesuffix = " — "|safe + docstitle|e %} - {%- else %} - {%- set titlesuffix = "" %} - {%- endif %} - {{ title|striptags }}{{ titlesuffix }} - - - {%- if not embedded %} - - {%- for scriptfile in script_files %} - - {%- endfor %} - {%- if use_opensearch %} - - {%- endif %} - {%- if favicon %} - - {%- endif %} - {%- endif %} -{%- block linktags %} - {%- if hasdoc('about') %} - - {%- endif %} - - - {%- if hasdoc('copyright') %} - - {%- endif %} - - {%- if parents %} - - {%- endif %} - {%- if next %} - - {%- endif %} - {%- if prev %} - - {%- endif %} -{%- endblock %} -{%- block extrahead %} {% endblock %} - - - -{%- block relbar1 %}{{ relbar() }}{% endblock %} - -{%- block sidebar1 %} {# possible location for sidebar #} {% endblock %} - -{%- block document %} -
      -
      - {%- if not embedded %} -
      - {%- endif %} -
      - {% block body %} {% endblock %} -
      - {%- if not embedded %} -
      - {%- endif %} -
      -{%- endblock %} - -{%- block sidebar2 %}{{ sidebar() }}{% endblock %} -
      -
      - -{%- block relbar2 %}{{ relbar() }}{% endblock %} - -{%- block footer %} -
      - {%- if hasdoc('copyright') %} - {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} - {%- else %} - {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} - {%- endif %} - {%- if last_updated %} - {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} - {%- endif %} - {%- if show_sphinx %} - {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} - {%- endif %} -
      -{%- endblock %} - - diff --git a/sphinx/templates/modindex.html b/sphinx/templates/modindex.html deleted file mode 100644 index 6e33e55c..00000000 --- a/sphinx/templates/modindex.html +++ /dev/null @@ -1,42 +0,0 @@ -{% extends "layout.html" %} -{% set title = _('Global Module Index') %} -{% block extrahead %} -{{ super() }} -{% if not embedded and collapse_modindex %} - -{% endif %} -{% endblock %} -{% block body %} - -

      {{ _('Global Module Index') }}

      - - {%- for letter in letters %} - {{ letter }} {% if not loop.last %}| {% endif %} - {%- endfor %} -
      - - - {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep in modindexentries %} - {%- if not modname -%} - - - {%- else -%} - - - - {%- endif -%} - {% endfor %} -
       
      {{ fname }}
      {% if collapse -%} - - {%- endif %}{% if indent %}   {% endif %} - {% if fname %}{% endif -%} - {{ modname|e }} - {%- if fname %}{% endif %} - {%- if pform and pform[0] %} ({{ pform|join(', ') }}){% endif -%} - {% if dep %}{{ _('Deprecated')}}:{% endif %} - {{ synops|e }}
      - -{% endblock %} diff --git a/sphinx/templates/opensearch.xml b/sphinx/templates/opensearch.xml deleted file mode 100644 index 03875be4..00000000 --- a/sphinx/templates/opensearch.xml +++ /dev/null @@ -1,10 +0,0 @@ - - - {{ project|e }} - {% trans docstitle=docstitle|e %}Search {{ docstitle }}{% endtrans %} - utf-8 - - {{ docstitle|e }} -{% block extra %} {# Put e.g. an element here. #} {% endblock %} - diff --git a/sphinx/templates/page.html b/sphinx/templates/page.html deleted file mode 100644 index 17a93016..00000000 --- a/sphinx/templates/page.html +++ /dev/null @@ -1,4 +0,0 @@ -{% extends "layout.html" %} -{% block body %} - {{ body }} -{% endblock %} diff --git a/sphinx/templates/search.html b/sphinx/templates/search.html deleted file mode 100644 index 224d87b8..00000000 --- a/sphinx/templates/search.html +++ /dev/null @@ -1,45 +0,0 @@ -{% extends "layout.html" %} -{% set title = _('Search') %} -{% set script_files = script_files + ['_static/searchtools.js'] %} -{% block body %} -

      {{ _('Search') }}

      -
      - -

      - {% trans %}Please activate JavaScript to enable the search - functionality.{% endtrans %} -

      -
      -

      - {% trans %}From here you can search these documents. Enter your search - words into the box below and click "search". Note that the search - function will automatically search for all of the words. Pages - containing fewer words won't appear in the result list.{% endtrans %} -

      -
      - - - -
      - {% if search_performed %} -

      {{ _('Search Results') }}

      - {% if not search_results %} -

      {{ _('Your search did not match any results.') }}

      - {% endif %} - {% endif %} -
      - {% if search_results %} -
        - {% for href, caption, context in search_results %} -
      • {{ caption }} -
        {{ context|e }}
        -
        • - {% endfor %} -
      - {% endif %} -
      -{% endblock %} -{% block footer %} - {{ super() }} - -{% endblock %} diff --git a/sphinx/themes/basic/changes/frameset.html b/sphinx/themes/basic/changes/frameset.html new file mode 100644 index 00000000..9d9af9eb --- /dev/null +++ b/sphinx/themes/basic/changes/frameset.html @@ -0,0 +1,11 @@ + + + + {% trans version=version|e, docstitle=docstitle|e %}Changes in Version {{ version }} — {{ docstitle }}{% endtrans %} + + + + + + diff --git a/sphinx/themes/basic/changes/rstsource.html b/sphinx/themes/basic/changes/rstsource.html new file mode 100644 index 00000000..abd12c1d --- /dev/null +++ b/sphinx/themes/basic/changes/rstsource.html @@ -0,0 +1,15 @@ + + + + {% trans filename=filename, docstitle=docstitle|e %}{{ filename }} — {{ docstitle }}{% endtrans %} + + + + 
      +      {{ text }}
+
      + + diff --git a/sphinx/themes/basic/changes/versionchanges.html b/sphinx/themes/basic/changes/versionchanges.html new file mode 100644 index 00000000..09651bf1 --- /dev/null +++ b/sphinx/themes/basic/changes/versionchanges.html @@ -0,0 +1,33 @@ +{% macro entries(changes) %} +
        {% for entry, docname, lineno in changes %} +
      • {{ entry }}
        • +{% endfor %}
      +{% endmacro -%} + + + + + + {% trans version=version|e, docstitle=docstitle|e %}Changes in Version {{ version }} — {{ docstitle }}{% endtrans %} + + +
      +
      +

      {% trans version=version|e %}Automatically generated list of changes in version {{ version }}{% endtrans %}

      +

      {{ _('Library changes') }}

      + {% for modname, changes in libchanges %} +

      {{ modname }}

      + {{ entries(changes) }} + {% endfor %} +

      {{ _('C API changes') }}

      + {{ entries(apichanges) }} +

      {{ _('Other changes') }}

      + {% for (fn, title), changes in otherchanges %} +

      {{ title }} ({{ fn }})

      + {{ entries(changes) }} + {% endfor %} +
      +
      + + diff --git a/sphinx/themes/basic/defindex.html b/sphinx/themes/basic/defindex.html new file mode 100644 index 00000000..40f4f4c9 --- /dev/null +++ b/sphinx/themes/basic/defindex.html @@ -0,0 +1,26 @@ +{% extends "layout.html" %} +{% set title = _('Overview') %} +{% block body %} +

      {{ docstitle|e }}

      +

      + Welcome! This is + {% block description %}the documentation for {{ project|e }} + {{ release|e }}{% if last_updated %}, last updated {{ last_updated|e }}{% endif %}{% endblock %}. +

      + {% block tables %} +

      {{ _('Indices and tables:') }}

      + + +
      +

      {{ _('Complete Table of Contents') }}
      + {{ _('lists all sections and subsections') }}

      +

      {{ _('Search Page') }}
      + {{ _('search this documentation') }}

      +       		+

      {{ _('Global Module Index') }}
      + {{ _('quick access to all modules') }}

      +

      {{ _('General Index') }}
      + {{ _('all functions, classes, terms') }}

      +
      + {% endblock %} +{% endblock %} diff --git a/sphinx/themes/basic/genindex-single.html b/sphinx/themes/basic/genindex-single.html new file mode 100644 index 00000000..9aaaeb0c --- /dev/null +++ b/sphinx/themes/basic/genindex-single.html @@ -0,0 +1,46 @@ +{% extends "layout.html" %} +{% set title = _('Index') %} +{% block body %} + +

      {% trans key=key %}Index – {{ key }}{% endtrans %}

      + +
      +
      +{%- set breakat = count // 2 %} +{%- set numcols = 1 %} +{%- set numitems = 0 %} +{% for entryname, (links, subitems) in entries %} +
      {%- if links -%}{{ entryname|e }} + {%- for link in links[1:] %}, [{{ loop.index }}]{% endfor -%} + {%- else -%} +{{ entryname|e }} + {%- endif -%}
      + {%- if subitems %} +
      + {%- for subentryname, subentrylinks in subitems %} +
      {{ subentryname|e }} + {%- for link in subentrylinks[1:] %}, [{{ loop.index }}]{% endfor -%} +
      + {%- endfor %} +
      + {%- endif -%} +{%- set numitems = numitems + 1 + (subitems|length) -%} +{%- if numcols < 2 and numitems > breakat -%} +{%- set numcols = numcols+1 -%} +
      +{%- endif -%} +{%- endfor %} +
      + +{% endblock %} + +{% block sidebarrel %} +

      Index

      +

      {% for key, dummy in genindexentries -%} + {{ key }} + {% if not loop.last %}| {% endif %} + {%- endfor %}

      + +

      {{ _('Full index on one page') }}

      + {{ super() }} +{% endblock %} diff --git a/sphinx/themes/basic/genindex-split.html b/sphinx/themes/basic/genindex-split.html new file mode 100644 index 00000000..ab099e5b --- /dev/null +++ b/sphinx/themes/basic/genindex-split.html @@ -0,0 +1,30 @@ +{% extends "layout.html" %} +{% set title = _('Index') %} +{% block body %} + +

      {{ _('Index') }}

      + +

      {{ _('Index pages by letter') }}:

      + +

      {% for key, dummy in genindexentries -%} + {{ key }} + {% if not loop.last %}| {% endif %} + {%- endfor %}

      + +

      {{ _('Full index on one page') }} + ({{ _('can be huge') }})

      + +{% endblock %} + +{% block sidebarrel %} +{% if split_index %} +

      Index

      +

      {% for key, dummy in genindexentries -%} + {{ key }} + {% if not loop.last %}| {% endif %} + {%- endfor %}

      + +

      {{ _('Full index on one page') }}

      +{% endif %} + {{ super() }} +{% endblock %} diff --git a/sphinx/themes/basic/genindex.html b/sphinx/themes/basic/genindex.html new file mode 100644 index 00000000..a19aa80f --- /dev/null +++ b/sphinx/themes/basic/genindex.html @@ -0,0 +1,57 @@ +{% extends "layout.html" %} +{% set title = _('Index') %} +{% block body %} + +

      {{ _('Index') }}

      + + {% for key, dummy in genindexentries -%} + {{ key }} {% if not loop.last %}| {% endif %} + {%- endfor %} + +
      + + {% for key, entries in genindexentries %} +

      {{ key }}

      +
      +
      +{%- set breakat = genindexcounts[loop.index0] // 2 %} +{%- set numcols = 1 %} +{%- set numitems = 0 %} +{% for entryname, (links, subitems) in entries %} +
      {%- if links -%}{{ entryname|e }} + {%- for link in links[1:] %}, [{{ loop.index }}]{% endfor -%} + {%- else -%} +{{ entryname|e }} + {%- endif -%}
      + {%- if subitems %} +
      + {%- for subentryname, subentrylinks in subitems %} +
      {{ subentryname|e }} + {%- for link in subentrylinks[1:] %}, [{{ loop.index }}]{% endfor -%} +
      + {%- endfor %} +
      + {%- endif -%} +{%- set numitems = numitems + 1 + (subitems|length) -%} +{%- if numcols < 2 and numitems > breakat -%} +{%- set numcols = numcols+1 -%} +
      +{%- endif -%} +{%- endfor %} +
      +{% endfor %} + +{% endblock %} + +{% block sidebarrel %} +{% if split_index %} +

      {{ _('Index') }}

      +

      {% for key, dummy in genindexentries -%} + {{ key }} + {% if not loop.last %}| {% endif %} + {%- endfor %}

      + +

      {{ _('Full index on one page') }}

      +{% endif %} + {{ super() }} +{% endblock %} diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html new file mode 100644 index 00000000..fb0df9e0 --- /dev/null +++ b/sphinx/themes/basic/layout.html @@ -0,0 +1,187 @@ +{%- block doctype -%} + +{%- endblock %} +{%- set reldelim1 = reldelim1 is not defined and ' »' or reldelim1 %} +{%- set reldelim2 = reldelim2 is not defined and ' |' or reldelim2 %} +{%- macro relbar() %} +
      +

      {{ _('Navigation') }}

      +
        + {%- for rellink in rellinks %} +
      • + {{ rellink[3] }} + {%- if not loop.first %}{{ reldelim2 }}{% endif %}
        • + {%- endfor %} + {%- block rootrellink %} +
      • {{ shorttitle|e }}{{ reldelim1 }}
        • + {%- endblock %} + {%- for parent in parents %} +
      • {{ parent.title }}{{ reldelim1 }}
        • + {%- endfor %} + {%- block relbaritems %} {% endblock %} +
      +
      +{%- endmacro %} +{%- macro sidebar() %} + {%- if not embedded %} +
      +
      + {%- block sidebarlogo %} + {%- if logo %} + + {%- endif %} + {%- endblock %} + {%- block sidebartoc %} + {%- if display_toc %} +

      {{ _('Table Of Contents') }}

      + {{ toc }} + {%- endif %} + {%- endblock %} + {%- block sidebarrel %} + {%- if prev %} +

      {{ _('Previous topic') }}

      +

      {{ prev.title }}

      + {%- endif %} + {%- if next %} +

      {{ _('Next topic') }}

      +

      {{ next.title }}

      + {%- endif %} + {%- endblock %} + {%- block sidebarsourcelink %} + {%- if show_source and has_source and sourcename %} +

      {{ _('This Page') }}

      + + {%- endif %} + {%- endblock %} + {%- if customsidebar %} + {% include customsidebar %} + {%- endif %} + {%- block sidebarsearch %} + {%- if pagename != "search" %} + + + {%- endif %} + {%- endblock %} +
      +
      + {%- endif %} +{%- endmacro %} + + + + + {{ metatags }} + {%- if not embedded %} + {%- set titlesuffix = " — "|safe + docstitle|e %} + {%- else %} + {%- set titlesuffix = "" %} + {%- endif %} + {{ title|striptags }}{{ titlesuffix }} + + + {%- if not embedded %} + + {%- for scriptfile in script_files %} + + {%- endfor %} + {%- if use_opensearch %} + + {%- endif %} + {%- if favicon %} + + {%- endif %} + {%- endif %} +{%- block linktags %} + {%- if hasdoc('about') %} + + {%- endif %} + + + {%- if hasdoc('copyright') %} + + {%- endif %} + + {%- if parents %} + + {%- endif %} + {%- if next %} + + {%- endif %} + {%- if prev %} + + {%- endif %} +{%- endblock %} +{%- block extrahead %} {% endblock %} + + + +{%- block relbar1 %}{{ relbar() }}{% endblock %} + +{%- block sidebar1 %} {# possible location for sidebar #} {% endblock %} + +{%- block document %} +
      +
      + {%- if not embedded %} +
      + {%- endif %} +
      + {% block body %} {% endblock %} +
      + {%- if not embedded %} +
      + {%- endif %} +
      +{%- endblock %} + +{%- block sidebar2 %}{{ sidebar() }}{% endblock %} +
      +
      + +{%- block relbar2 %}{{ relbar() }}{% endblock %} + +{%- block footer %} +
      + {%- if hasdoc('copyright') %} + {% trans path=pathto('copyright'), copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- else %} + {% trans copyright=copyright|e %}© Copyright {{ copyright }}.{% endtrans %} + {%- endif %} + {%- if last_updated %} + {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %} + {%- endif %} + {%- if show_sphinx %} + {% trans sphinx_version=sphinx_version|e %}Created using Sphinx {{ sphinx_version }}.{% endtrans %} + {%- endif %} +
      +{%- endblock %} + + diff --git a/sphinx/themes/basic/modindex.html b/sphinx/themes/basic/modindex.html new file mode 100644 index 00000000..6e33e55c --- /dev/null +++ b/sphinx/themes/basic/modindex.html @@ -0,0 +1,42 @@ +{% extends "layout.html" %} +{% set title = _('Global Module Index') %} +{% block extrahead %} +{{ super() }} +{% if not embedded and collapse_modindex %} + +{% endif %} +{% endblock %} +{% block body %} + +

      {{ _('Global Module Index') }}

      + + {%- for letter in letters %} + {{ letter }} {% if not loop.last %}| {% endif %} + {%- endfor %} +
      + + + {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep in modindexentries %} + {%- if not modname -%} + + + {%- else -%} + + + + {%- endif -%} + {% endfor %} +
       
      {{ fname }}
      {% if collapse -%} + + {%- endif %}{% if indent %}   {% endif %} + {% if fname %}{% endif -%} + {{ modname|e }} + {%- if fname %}{% endif %} + {%- if pform and pform[0] %} ({{ pform|join(', ') }}){% endif -%} + {% if dep %}{{ _('Deprecated')}}:{% endif %} + {{ synops|e }}
      + +{% endblock %} diff --git a/sphinx/themes/basic/opensearch.xml b/sphinx/themes/basic/opensearch.xml new file mode 100644 index 00000000..03875be4 --- /dev/null +++ b/sphinx/themes/basic/opensearch.xml @@ -0,0 +1,10 @@ + + + {{ project|e }} + {% trans docstitle=docstitle|e %}Search {{ docstitle }}{% endtrans %} + utf-8 + + {{ docstitle|e }} +{% block extra %} {# Put e.g. an element here. #} {% endblock %} + diff --git a/sphinx/themes/basic/page.html b/sphinx/themes/basic/page.html new file mode 100644 index 00000000..17a93016 --- /dev/null +++ b/sphinx/themes/basic/page.html @@ -0,0 +1,4 @@ +{% extends "layout.html" %} +{% block body %} + {{ body }} +{% endblock %} diff --git a/sphinx/themes/basic/search.html b/sphinx/themes/basic/search.html new file mode 100644 index 00000000..224d87b8 --- /dev/null +++ b/sphinx/themes/basic/search.html @@ -0,0 +1,45 @@ +{% extends "layout.html" %} +{% set title = _('Search') %} +{% set script_files = script_files + ['_static/searchtools.js'] %} +{% block body %} +

      {{ _('Search') }}

      +
      + +

      + {% trans %}Please activate JavaScript to enable the search + functionality.{% endtrans %} +

      +
      +

      + {% trans %}From here you can search these documents. Enter your search + words into the box below and click "search". Note that the search + function will automatically search for all of the words. Pages + containing fewer words won't appear in the result list.{% endtrans %} +

      +
      + + + +
      + {% if search_performed %} +

      {{ _('Search Results') }}

      + {% if not search_results %} +

      {{ _('Your search did not match any results.') }}

      + {% endif %} + {% endif %} +
      + {% if search_results %} +
        + {% for href, caption, context in search_results %} +
      • {{ caption }} +
        {{ context|e }}
        +
        • + {% endfor %} +
      + {% endif %} +
      +{% endblock %} +{% block footer %} + {{ super() }} + +{% endblock %} diff --git a/sphinx/themes/basic/static/basic.css b/sphinx/themes/basic/static/basic.css new file mode 100644 index 00000000..005caa1f --- /dev/null +++ b/sphinx/themes/basic/static/basic.css @@ -0,0 +1,657 @@ +/** + * Sphinx Doc Design + */ + +body { + font-family: sans-serif; + font-size: 100%; + background-color: #11303d; + color: #000; + margin: 0; + padding: 0; +} + +/* :::: LAYOUT :::: */ + +div.document { + background-color: #1c4e63; +} + +div.documentwrapper { + float: left; + width: 100%; +} + +div.bodywrapper { + margin: 0 0 0 230px; +} + +div.body { + background-color: white; + padding: 0 20px 30px 20px; +} + +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; +} + +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; +} + +div.clearer { + clear: both; +} + +div.footer { + color: #fff; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: #fff; + text-decoration: underline; +} + +div.related { + background-color: #133f52; + color: #fff; + width: 100%; + line-height: 30px; + font-size: 90%; +} + +div.related h3 { + display: none; +} + +div.related ul { + margin: 0; + padding: 0 0 0 10px; + list-style: none; +} + +div.related li { + display: inline; +} + +div.related li.right { + float: right; + margin-right: 5px; +} + +div.related a { + color: white; +} + +/* ::: TOC :::: */ +div.sphinxsidebar h3 { + font-family: 'Trebuchet MS', sans-serif; + color: white; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: white; +} + +div.sphinxsidebar h4 { + font-family: 'Trebuchet MS', sans-serif; + color: white; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: white; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + list-style: none; + color: white; +} + +div.sphinxsidebar ul ul, +div.sphinxsidebar ul.want-points { + margin-left: 20px; + list-style: square; +} + +div.sphinxsidebar ul ul { + margin-top: 0; + margin-bottom: 0; +} + +div.sphinxsidebar a { + color: #98dbcc; +} + +div.sphinxsidebar form { + margin-top: 10px; +} + +div.sphinxsidebar input { + border: 1px solid #98dbcc; + font-family: sans-serif; + font-size: 1em; +} + +/* :::: MODULE CLOUD :::: */ +div.modulecloud { + margin: -5px 10px 5px 10px; + padding: 10px; + line-height: 160%; + border: 1px solid #cbe7e5; + background-color: #f2fbfd; +} + +div.modulecloud a { + padding: 0 5px 0 5px; +} + +/* :::: SEARCH :::: */ +ul.search { + margin: 10px 0 0 20px; + padding: 0; +} + +ul.search li { + padding: 5px 0 5px 20px; + background-image: url(file.png); + background-repeat: no-repeat; + background-position: 0 7px; +} + +ul.search li a { + font-weight: bold; +} + +ul.search li div.context { + color: #888; + margin: 2px 0 0 30px; + text-align: left; +} + +ul.keywordmatches li.goodmatch a { + font-weight: bold; +} + +/* :::: COMMON FORM STYLES :::: */ + +div.actions { + padding: 5px 10px 5px 10px; + border-top: 1px solid #cbe7e5; + border-bottom: 1px solid #cbe7e5; + background-color: #e0f6f4; +} + +form dl { + color: #333; +} + +form dt { + clear: both; + float: left; + min-width: 110px; + margin-right: 10px; + padding-top: 2px; +} + +input#homepage { + display: none; +} + +div.error { + margin: 5px 20px 0 0; + padding: 5px; + border: 1px solid #d00; + font-weight: bold; +} + +/* :::: INDEX PAGE :::: */ + +table.contentstable { + width: 90%; +} + +table.contentstable p.biglink { + line-height: 150%; +} + +a.biglink { + font-size: 1.3em; +} + +span.linkdescr { + font-style: italic; + padding-top: 5px; + font-size: 90%; +} + +/* :::: INDEX STYLES :::: */ + +table.indextable td { + text-align: left; + vertical-align: top; +} + +table.indextable dl, table.indextable dd { + margin-top: 0; + margin-bottom: 0; +} + +table.indextable tr.pcap { + height: 10px; +} + +table.indextable tr.cap { + margin-top: 10px; + background-color: #f2f2f2; +} + +img.toggler { + margin-right: 3px; + margin-top: 3px; + cursor: pointer; +} + +form.pfform { + margin: 10px 0 20px 0; +} + +/* :::: GLOBAL STYLES :::: */ + +.docwarning { + background-color: #ffe4e4; + padding: 10px; + margin: 0 -20px 0 -20px; + border-bottom: 1px solid #f66; +} + +p.subhead { + font-weight: bold; + margin-top: 20px; +} + +a { + color: #355f7c; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: 'Trebuchet MS', sans-serif; + background-color: #f2f2f2; + font-weight: normal; + color: #20435c; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; + visibility: hidden; +} + +h1:hover > a.headerlink, +h2:hover > a.headerlink, +h3:hover > a.headerlink, +h4:hover > a.headerlink, +h5:hover > a.headerlink, +h6:hover > a.headerlink, +dt:hover > a.headerlink { + visibility: visible; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.body p.caption { + text-align: inherit; +} + +div.body td { + text-align: left; +} + +ul.fakelist { + list-style: none; + margin: 10px 0 10px 20px; + padding: 0; +} + +.field-list ul { + padding-left: 1em; +} + +.first { + margin-top: 0 !important; +} + +/* "Footnotes" heading */ +p.rubric { + margin-top: 30px; + font-weight: bold; +} + +/* Sidebars */ + +div.sidebar { + margin: 0 0 0.5em 1em; + border: 1px solid #ddb; + padding: 7px 7px 0 7px; + background-color: #ffe; + width: 40%; + float: right; +} + +p.sidebar-title { + font-weight: bold; +} + +/* "Topics" */ + +div.topic { + background-color: #eee; + border: 1px solid #ccc; + padding: 7px 7px 0 7px; + margin: 10px 0 10px 0; +} + +p.topic-title { + font-size: 1.1em; + font-weight: bold; + margin-top: 10px; +} + +/* Admonitions */ + +div.admonition { + margin-top: 10px; + margin-bottom: 10px; + padding: 7px; +} + +div.admonition dt { + font-weight: bold; +} + +div.admonition dl { + margin-bottom: 0; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +p.admonition-title { + margin: 0px 10px 5px 0px; + font-weight: bold; + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +div.body p.centered { + text-align: center; + margin-top: 25px; +} + +table.docutils { + border: 0; +} + +table.docutils td, table.docutils th { + padding: 1px 8px 1px 0; + border-top: 0; + border-left: 0; + border-right: 0; + border-bottom: 1px solid #aaa; +} + +table.field-list td, table.field-list th { + border: 0 !important; +} + +table.footnote td, table.footnote th { + border: 0 !important; +} + +.field-list ul { + margin: 0; + padding-left: 1em; +} + +.field-list p { + margin: 0; +} + +dl { + margin-bottom: 15px; + clear: both; +} + +dd p { + margin-top: 0px; +} + +dd ul, dd table { + margin-bottom: 10px; +} + +dd { + margin-top: 3px; + margin-bottom: 10px; + margin-left: 30px; +} + +.refcount { + color: #060; +} + +dt:target, +.highlight { + background-color: #fbe54e; +} + +dl.glossary dt { + font-weight: bold; + font-size: 1.1em; +} + +th { + text-align: left; + padding-right: 5px; +} + +pre { + padding: 5px; + background-color: #efc; + color: #333; + border: 1px solid #ac9; + border-left: none; + border-right: none; + overflow: auto; +} + +td.linenos pre { + padding: 5px 0px; + border: 0; + background-color: transparent; + color: #aaa; +} + +table.highlighttable { + margin-left: 0.5em; +} + +table.highlighttable td { + padding: 0 0.5em 0 0.5em; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} + +tt.descname { + background-color: transparent; + font-weight: bold; + font-size: 1.2em; +} + +tt.descclassname { + background-color: transparent; +} + +tt.xref, a tt { + background-color: transparent; + font-weight: bold; +} + +.footnote:target { background-color: #ffa } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + background-color: transparent; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +form.comment { + margin: 0; + padding: 10px 30px 10px 30px; + background-color: #eee; +} + +form.comment h3 { + background-color: #326591; + color: white; + margin: -10px -30px 10px -30px; + padding: 5px; + font-size: 1.4em; +} + +form.comment input, +form.comment textarea { + border: 1px solid #ccc; + padding: 2px; + font-family: sans-serif; + font-size: 100%; +} + +form.comment input[type="text"] { + width: 240px; +} + +form.comment textarea { + width: 100%; + height: 200px; + margin-bottom: 10px; +} + +.system-message { + background-color: #fda; + padding: 5px; + border: 3px solid red; +} + +img.math { + vertical-align: middle; +} + +div.math p { + text-align: center; +} + +span.eqno { + float: right; +} + +img.logo { + border: 0; +} + +/* :::: PRINT :::: */ +@media print { + div.document, + div.documentwrapper, + div.bodywrapper { + margin: 0; + width : 100%; + } + + div.sphinxsidebar, + div.related, + div.footer, + div#comments div.new-comment-box, + #top-link { + display: none; + } +} diff --git a/sphinx/themes/basic/static/doctools.js b/sphinx/themes/basic/static/doctools.js new file mode 100644 index 00000000..be4bdc88 --- /dev/null +++ b/sphinx/themes/basic/static/doctools.js @@ -0,0 +1,232 @@ +/// XXX: make it cross browser + +/** + * make the code below compatible with browsers without + * an installed firebug like debugger + */ +if (!window.console || !console.firebug) { + var names = ["log", "debug", "info", "warn", "error", "assert", "dir", "dirxml", + "group", "groupEnd", "time", "timeEnd", "count", "trace", "profile", "profileEnd"]; + window.console = {}; + for (var i = 0; i < names.length; ++i) + window.console[names[i]] = function() {} +} + +/** + * small helper function to urldecode strings + */ +jQuery.urldecode = function(x) { + return decodeURIComponent(x).replace(/\+/g, ' '); +} + +/** + * small helper function to urlencode strings + */ +jQuery.urlencode = encodeURIComponent; + +/** + * This function returns the parsed url parameters of the + * current request. Multiple values per key are supported, + * it will always return arrays of strings for the value parts. + */ +jQuery.getQueryParameters = function(s) { + if (typeof s == 'undefined') + s = document.location.search; + var parts = s.substr(s.indexOf('?') + 1).split('&'); + var result = {}; + for (var i = 0; i < parts.length; i++) { + var tmp = parts[i].split('=', 2); + var key = jQuery.urldecode(tmp[0]); + var value = jQuery.urldecode(tmp[1]); + if (key in result) + result[key].push(value); + else + result[key] = [value]; + } + return result; +} + +/** + * small function to check if an array contains + * a given item. + */ +jQuery.contains = function(arr, item) { + for (var i = 0; i < arr.length; i++) { + if (arr[i] == item) + return true; + } + return false; +} + +/** + * highlight a given string on a jquery object by wrapping it in + * span elements with the given class name. + */ +jQuery.fn.highlightText = function(text, className) { + function highlight(node) { + if (node.nodeType == 3) { + var val = node.nodeValue; + var pos = val.toLowerCase().indexOf(text); + if (pos >= 0 && !jQuery.className.has(node.parentNode, className)) { + var span = document.createElement("span"); + span.className = className; + span.appendChild(document.createTextNode(val.substr(pos, text.length))); + node.parentNode.insertBefore(span, node.parentNode.insertBefore( + document.createTextNode(val.substr(pos + text.length)), + node.nextSibling)); + node.nodeValue = val.substr(0, pos); + } + } + else if (!jQuery(node).is("button, select, textarea")) { + jQuery.each(node.childNodes, function() { + highlight(this) + }); + } + } + return this.each(function() { + highlight(this); + }); +} + +/** + * Small JavaScript module for the documentation. + */ +var Documentation = { + + init : function() { + this.fixFirefoxAnchorBug(); + this.highlightSearchWords(); + this.initModIndex(); + }, + + /** + * i18n support + */ + TRANSLATIONS : {}, + PLURAL_EXPR : function(n) { return n == 1 ? 0 : 1; }, + LOCALE : 'unknown', + + // gettext and ngettext don't access this so that the functions + // can savely bound to a different name (_ = Documentation.gettext) + gettext : function(string) { + var translated = Documentation.TRANSLATIONS[string]; + if (typeof translated == 'undefined') + return string; + return (typeof translated == 'string') ? translated : translated[0]; + }, + + ngettext : function(singular, plural, n) { + var translated = Documentation.TRANSLATIONS[singular]; + if (typeof translated == 'undefined') + return (n == 1) ? singular : plural; + return translated[Documentation.PLURALEXPR(n)]; + }, + + addTranslations : function(catalog) { + for (var key in catalog.messages) + this.TRANSLATIONS[key] = catalog.messages[key]; + this.PLURAL_EXPR = new Function('n', 'return +(' + catalog.plural_expr + ')'); + this.LOCALE = catalog.locale; + }, + + /** + * add context elements like header anchor links + */ + addContextElements : function() { + $('div[@id] > :header:first').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this headline')). + appendTo(this); + }); + $('dt[@id]').each(function() { + $('\u00B6'). + attr('href', '#' + this.id). + attr('title', _('Permalink to this definition')). + appendTo(this); + }); + }, + + /** + * workaround a firefox stupidity + */ + fixFirefoxAnchorBug : function() { + if (document.location.hash && $.browser.mozilla) + window.setTimeout(function() { + document.location.href += ''; + }, 10); + }, + + /** + * highlight the search words provided in the url in the text + */ + highlightSearchWords : function() { + var params = $.getQueryParameters(); + var terms = (params.highlight) ? params.highlight[0].split(/\s+/) : []; + if (terms.length) { + var body = $('div.body'); + window.setTimeout(function() { + $.each(terms, function() { + body.highlightText(this.toLowerCase(), 'highlight'); + }); + }, 10); + $('
    • ' + _('Hide Search Matches') + '
      • ') + .appendTo($('.sidebar .this-page-menu')); + } + }, + + /** + * init the modindex toggle buttons + */ + initModIndex : function() { + var togglers = $('img.toggler').click(function() { + var src = $(this).attr('src'); + var idnum = $(this).attr('id').substr(7); + console.log($('tr.cg-' + idnum).toggle()); + if (src.substr(-9) == 'minus.png') + $(this).attr('src', src.substr(0, src.length-9) + 'plus.png'); + else + $(this).attr('src', src.substr(0, src.length-8) + 'minus.png'); + }).css('display', ''); + if (DOCUMENTATION_OPTIONS.COLLAPSE_MODINDEX) { + togglers.click(); + } + }, + + /** + * helper function to hide the search marks again + */ + hideSearchWords : function() { + $('.sidebar .this-page-menu li.highlight-link').fadeOut(300); + $('span.highlight').removeClass('highlight'); + }, + + /** + * make the url absolute + */ + makeURL : function(relativeURL) { + return DOCUMENTATION_OPTIONS.URL_ROOT + '/' + relativeURL; + }, + + /** + * get the current relative url + */ + getCurrentURL : function() { + var path = document.location.pathname; + var parts = path.split(/\//); + $.each(DOCUMENTATION_OPTIONS.URL_ROOT.split(/\//), function() { + if (this == '..') + parts.pop(); + }); + var url = parts.join('/'); + return path.substring(url.lastIndexOf('/') + 1, path.length - 1); + } +}; + +// quick alias for translations +_ = Documentation.gettext; + +$(document).ready(function() { + Documentation.init(); +}); diff --git a/sphinx/themes/basic/static/file.png b/sphinx/themes/basic/static/file.png new file mode 100644 index 00000000..d18082e3 Binary files /dev/null and b/sphinx/themes/basic/static/file.png differ diff --git a/sphinx/themes/basic/static/jquery.js b/sphinx/themes/basic/static/jquery.js new file mode 100644 index 00000000..82b98e1d --- /dev/null +++ b/sphinx/themes/basic/static/jquery.js @@ -0,0 +1,32 @@ +/* + * jQuery 1.2.6 - New Wave Javascript + * + * Copyright (c) 2008 John Resig (jquery.com) + * Dual licensed under the MIT (MIT-LICENSE.txt) + * and GPL (GPL-LICENSE.txt) licenses. + * + * $Date: 2008-05-24 14:22:17 -0400 (Sat, 24 May 2008) $ + * $Rev: 5685 $ + */ +(function(){var _jQuery=window.jQuery,_$=window.$;var jQuery=window.jQuery=window.$=function(selector,context){return new jQuery.fn.init(selector,context);};var quickExpr=/^[^<]*(<(.|\s)+>)[^>]*$|^#(\w+)$/,isSimple=/^.[^:#\[\.]*$/,undefined;jQuery.fn=jQuery.prototype={init:function(selector,context){selector=selector||document;if(selector.nodeType){this[0]=selector;this.length=1;return this;}if(typeof selector=="string"){var match=quickExpr.exec(selector);if(match&&(match[1]||!context)){if(match[1])selector=jQuery.clean([match[1]],context);else{var elem=document.getElementById(match[3]);if(elem){if(elem.id!=match[3])return jQuery().find(selector);return jQuery(elem);}selector=[];}}else +return jQuery(context).find(selector);}else if(jQuery.isFunction(selector))return jQuery(document)[jQuery.fn.ready?"ready":"load"](selector);return this.setArray(jQuery.makeArray(selector));},jquery:"1.2.6",size:function(){return this.length;},length:0,get:function(num){return num==undefined?jQuery.makeArray(this):this[num];},pushStack:function(elems){var ret=jQuery(elems);ret.prevObject=this;return ret;},setArray:function(elems){this.length=0;Array.prototype.push.apply(this,elems);return this;},each:function(callback,args){return jQuery.each(this,callback,args);},index:function(elem){var ret=-1;return jQuery.inArray(elem&&elem.jquery?elem[0]:elem,this);},attr:function(name,value,type){var options=name;if(name.constructor==String)if(value===undefined)return this[0]&&jQuery[type||"attr"](this[0],name);else{options={};options[name]=value;}return this.each(function(i){for(name in options)jQuery.attr(type?this.style:this,name,jQuery.prop(this,options[name],type,i,name));});},css:function(key,value){if((key=='width'||key=='height')&&parseFloat(value)<0)value=undefined;return this.attr(key,value,"curCSS");},text:function(text){if(typeof text!="object"&&text!=null)return this.empty().append((this[0]&&this[0].ownerDocument||document).createTextNode(text));var ret="";jQuery.each(text||this,function(){jQuery.each(this.childNodes,function(){if(this.nodeType!=8)ret+=this.nodeType!=1?this.nodeValue:jQuery.fn.text([this]);});});return ret;},wrapAll:function(html){if(this[0])jQuery(html,this[0].ownerDocument).clone().insertBefore(this[0]).map(function(){var elem=this;while(elem.firstChild)elem=elem.firstChild;return elem;}).append(this);return this;},wrapInner:function(html){return this.each(function(){jQuery(this).contents().wrapAll(html);});},wrap:function(html){return this.each(function(){jQuery(this).wrapAll(html);});},append:function(){return this.domManip(arguments,true,false,function(elem){if(this.nodeType==1)this.appendChild(elem);});},prepend:function(){return this.domManip(arguments,true,true,function(elem){if(this.nodeType==1)this.insertBefore(elem,this.firstChild);});},before:function(){return this.domManip(arguments,false,false,function(elem){this.parentNode.insertBefore(elem,this);});},after:function(){return this.domManip(arguments,false,true,function(elem){this.parentNode.insertBefore(elem,this.nextSibling);});},end:function(){return this.prevObject||jQuery([]);},find:function(selector){var elems=jQuery.map(this,function(elem){return jQuery.find(selector,elem);});return this.pushStack(/[^+>] [^+>]/.test(selector)||selector.indexOf("..")>-1?jQuery.unique(elems):elems);},clone:function(events){var ret=this.map(function(){if(jQuery.browser.msie&&!jQuery.isXMLDoc(this)){var clone=this.cloneNode(true),container=document.createElement("div");container.appendChild(clone);return jQuery.clean([container.innerHTML])[0];}else +return this.cloneNode(true);});var clone=ret.find("*").andSelf().each(function(){if(this[expando]!=undefined)this[expando]=null;});if(events===true)this.find("*").andSelf().each(function(i){if(this.nodeType==3)return;var events=jQuery.data(this,"events");for(var type in events)for(var handler in events[type])jQuery.event.add(clone[i],type,events[type][handler],events[type][handler].data);});return ret;},filter:function(selector){return this.pushStack(jQuery.isFunction(selector)&&jQuery.grep(this,function(elem,i){return selector.call(elem,i);})||jQuery.multiFilter(selector,this));},not:function(selector){if(selector.constructor==String)if(isSimple.test(selector))return this.pushStack(jQuery.multiFilter(selector,this,true));else +selector=jQuery.multiFilter(selector,this);var isArrayLike=selector.length&&selector[selector.length-1]!==undefined&&!selector.nodeType;return this.filter(function(){return isArrayLike?jQuery.inArray(this,selector)<0:this!=selector;});},add:function(selector){return this.pushStack(jQuery.unique(jQuery.merge(this.get(),typeof selector=='string'?jQuery(selector):jQuery.makeArray(selector))));},is:function(selector){return!!selector&&jQuery.multiFilter(selector,this).length>0;},hasClass:function(selector){return this.is("."+selector);},val:function(value){if(value==undefined){if(this.length){var elem=this[0];if(jQuery.nodeName(elem,"select")){var index=elem.selectedIndex,values=[],options=elem.options,one=elem.type=="select-one";if(index<0)return null;for(var i=one?index:0,max=one?index+1:options.length;i=0||jQuery.inArray(this.name,value)>=0);else if(jQuery.nodeName(this,"select")){var values=jQuery.makeArray(value);jQuery("option",this).each(function(){this.selected=(jQuery.inArray(this.value,values)>=0||jQuery.inArray(this.text,values)>=0);});if(!values.length)this.selectedIndex=-1;}else +this.value=value;});},html:function(value){return value==undefined?(this[0]?this[0].innerHTML:null):this.empty().append(value);},replaceWith:function(value){return this.after(value).remove();},eq:function(i){return this.slice(i,i+1);},slice:function(){return this.pushStack(Array.prototype.slice.apply(this,arguments));},map:function(callback){return this.pushStack(jQuery.map(this,function(elem,i){return callback.call(elem,i,elem);}));},andSelf:function(){return this.add(this.prevObject);},data:function(key,value){var parts=key.split(".");parts[1]=parts[1]?"."+parts[1]:"";if(value===undefined){var data=this.triggerHandler("getData"+parts[1]+"!",[parts[0]]);if(data===undefined&&this.length)data=jQuery.data(this[0],key);return data===undefined&&parts[1]?this.data(parts[0]):data;}else +return this.trigger("setData"+parts[1]+"!",[parts[0],value]).each(function(){jQuery.data(this,key,value);});},removeData:function(key){return this.each(function(){jQuery.removeData(this,key);});},domManip:function(args,table,reverse,callback){var clone=this.length>1,elems;return this.each(function(){if(!elems){elems=jQuery.clean(args,this.ownerDocument);if(reverse)elems.reverse();}var obj=this;if(table&&jQuery.nodeName(this,"table")&&jQuery.nodeName(elems[0],"tr"))obj=this.getElementsByTagName("tbody")[0]||this.appendChild(this.ownerDocument.createElement("tbody"));var scripts=jQuery([]);jQuery.each(elems,function(){var elem=clone?jQuery(this).clone(true)[0]:this;if(jQuery.nodeName(elem,"script"))scripts=scripts.add(elem);else{if(elem.nodeType==1)scripts=scripts.add(jQuery("script",elem).remove());callback.call(obj,elem);}});scripts.each(evalScript);});}};jQuery.fn.init.prototype=jQuery.fn;function evalScript(i,elem){if(elem.src)jQuery.ajax({url:elem.src,async:false,dataType:"script"});else +jQuery.globalEval(elem.text||elem.textContent||elem.innerHTML||"");if(elem.parentNode)elem.parentNode.removeChild(elem);}function now(){return+new Date;}jQuery.extend=jQuery.fn.extend=function(){var target=arguments[0]||{},i=1,length=arguments.length,deep=false,options;if(target.constructor==Boolean){deep=target;target=arguments[1]||{};i=2;}if(typeof target!="object"&&typeof target!="function")target={};if(length==i){target=this;--i;}for(;i-1;}},swap:function(elem,options,callback){var old={};for(var name in options){old[name]=elem.style[name];elem.style[name]=options[name];}callback.call(elem);for(var name in options)elem.style[name]=old[name];},css:function(elem,name,force){if(name=="width"||name=="height"){var val,props={position:"absolute",visibility:"hidden",display:"block"},which=name=="width"?["Left","Right"]:["Top","Bottom"];function getWH(){val=name=="width"?elem.offsetWidth:elem.offsetHeight;var padding=0,border=0;jQuery.each(which,function(){padding+=parseFloat(jQuery.curCSS(elem,"padding"+this,true))||0;border+=parseFloat(jQuery.curCSS(elem,"border"+this+"Width",true))||0;});val-=Math.round(padding+border);}if(jQuery(elem).is(":visible"))getWH();else +jQuery.swap(elem,props,getWH);return Math.max(0,val);}return jQuery.curCSS(elem,name,force);},curCSS:function(elem,name,force){var ret,style=elem.style;function color(elem){if(!jQuery.browser.safari)return false;var ret=defaultView.getComputedStyle(elem,null);return!ret||ret.getPropertyValue("color")=="";}if(name=="opacity"&&jQuery.browser.msie){ret=jQuery.attr(style,"opacity");return ret==""?"1":ret;}if(jQuery.browser.opera&&name=="display"){var save=style.outline;style.outline="0 solid black";style.outline=save;}if(name.match(/float/i))name=styleFloat;if(!force&&style&&style[name])ret=style[name];else if(defaultView.getComputedStyle){if(name.match(/float/i))name="float";name=name.replace(/([A-Z])/g,"-$1").toLowerCase();var computedStyle=defaultView.getComputedStyle(elem,null);if(computedStyle&&!color(elem))ret=computedStyle.getPropertyValue(name);else{var swap=[],stack=[],a=elem,i=0;for(;a&&color(a);a=a.parentNode)stack.unshift(a);for(;i]*?)\/>/g,function(all,front,tag){return tag.match(/^(abbr|br|col|img|input|link|meta|param|hr|area|embed)$/i)?all:front+">";});var tags=jQuery.trim(elem).toLowerCase(),div=context.createElement("div");var wrap=!tags.indexOf("",""]||!tags.indexOf("",""]||tags.match(/^<(thead|tbody|tfoot|colg|cap)/)&&[1,"","
      "]||!tags.indexOf("",""]||(!tags.indexOf("",""]||!tags.indexOf("",""]||jQuery.browser.msie&&[1,"div
      ","
      "]||[0,"",""];div.innerHTML=wrap[1]+elem+wrap[2];while(wrap[0]--)div=div.lastChild;if(jQuery.browser.msie){var tbody=!tags.indexOf(""&&tags.indexOf("=0;--j)if(jQuery.nodeName(tbody[j],"tbody")&&!tbody[j].childNodes.length)tbody[j].parentNode.removeChild(tbody[j]);if(/^\s/.test(elem))div.insertBefore(context.createTextNode(elem.match(/^\s*/)[0]),div.firstChild);}elem=jQuery.makeArray(div.childNodes);}if(elem.length===0&&(!jQuery.nodeName(elem,"form")&&!jQuery.nodeName(elem,"select")))return;if(elem[0]==undefined||jQuery.nodeName(elem,"form")||elem.options)ret.push(elem);else +ret=jQuery.merge(ret,elem);});return ret;},attr:function(elem,name,value){if(!elem||elem.nodeType==3||elem.nodeType==8)return undefined;var notxml=!jQuery.isXMLDoc(elem),set=value!==undefined,msie=jQuery.browser.msie;name=notxml&&jQuery.props[name]||name;if(elem.tagName){var special=/href|src|style/.test(name);if(name=="selected"&&jQuery.browser.safari)elem.parentNode.selectedIndex;if(name in elem&¬xml&&!special){if(set){if(name=="type"&&jQuery.nodeName(elem,"input")&&elem.parentNode)throw"type property can't be changed";elem[name]=value;}if(jQuery.nodeName(elem,"form")&&elem.getAttributeNode(name))return elem.getAttributeNode(name).nodeValue;return elem[name];}if(msie&¬xml&&name=="style")return jQuery.attr(elem.style,"cssText",value);if(set)elem.setAttribute(name,""+value);var attr=msie&¬xml&&special?elem.getAttribute(name,2):elem.getAttribute(name);return attr===null?undefined:attr;}if(msie&&name=="opacity"){if(set){elem.zoom=1;elem.filter=(elem.filter||"").replace(/alpha\([^)]*\)/,"")+(parseInt(value)+''=="NaN"?"":"alpha(opacity="+value*100+")");}return elem.filter&&elem.filter.indexOf("opacity=")>=0?(parseFloat(elem.filter.match(/opacity=([^)]*)/)[1])/100)+'':"";}name=name.replace(/-([a-z])/ig,function(all,letter){return letter.toUpperCase();});if(set)elem[name]=value;return elem[name];},trim:function(text){return(text||"").replace(/^\s+|\s+$/g,"");},makeArray:function(array){var ret=[];if(array!=null){var i=array.length;if(i==null||array.split||array.setInterval||array.call)ret[0]=array;else +while(i)ret[--i]=array[i];}return ret;},inArray:function(elem,array){for(var i=0,length=array.length;i*",this).remove();while(this.firstChild)this.removeChild(this.firstChild);}},function(name,fn){jQuery.fn[name]=function(){return this.each(fn,arguments);};});jQuery.each(["Height","Width"],function(i,name){var type=name.toLowerCase();jQuery.fn[type]=function(size){return this[0]==window?jQuery.browser.opera&&document.body["client"+name]||jQuery.browser.safari&&window["inner"+name]||document.compatMode=="CSS1Compat"&&document.documentElement["client"+name]||document.body["client"+name]:this[0]==document?Math.max(Math.max(document.body["scroll"+name],document.documentElement["scroll"+name]),Math.max(document.body["offset"+name],document.documentElement["offset"+name])):size==undefined?(this.length?jQuery.css(this[0],type):null):this.css(type,size.constructor==String?size:size+"px");};});function num(elem,prop){return elem[0]&&parseInt(jQuery.curCSS(elem[0],prop,true),10)||0;}var chars=jQuery.browser.safari&&parseInt(jQuery.browser.version)<417?"(?:[\\w*_-]|\\\\.)":"(?:[\\w\u0128-\uFFFF*_-]|\\\\.)",quickChild=new RegExp("^>\\s*("+chars+"+)"),quickID=new RegExp("^("+chars+"+)(#)("+chars+"+)"),quickClass=new RegExp("^([#.]?)("+chars+"*)");jQuery.extend({expr:{"":function(a,i,m){return m[2]=="*"||jQuery.nodeName(a,m[2]);},"#":function(a,i,m){return a.getAttribute("id")==m[2];},":":{lt:function(a,i,m){return im[3]-0;},nth:function(a,i,m){return m[3]-0==i;},eq:function(a,i,m){return m[3]-0==i;},first:function(a,i){return i==0;},last:function(a,i,m,r){return i==r.length-1;},even:function(a,i){return i%2==0;},odd:function(a,i){return i%2;},"first-child":function(a){return a.parentNode.getElementsByTagName("*")[0]==a;},"last-child":function(a){return jQuery.nth(a.parentNode.lastChild,1,"previousSibling")==a;},"only-child":function(a){return!jQuery.nth(a.parentNode.lastChild,2,"previousSibling");},parent:function(a){return a.firstChild;},empty:function(a){return!a.firstChild;},contains:function(a,i,m){return(a.textContent||a.innerText||jQuery(a).text()||"").indexOf(m[3])>=0;},visible:function(a){return"hidden"!=a.type&&jQuery.css(a,"display")!="none"&&jQuery.css(a,"visibility")!="hidden";},hidden:function(a){return"hidden"==a.type||jQuery.css(a,"display")=="none"||jQuery.css(a,"visibility")=="hidden";},enabled:function(a){return!a.disabled;},disabled:function(a){return a.disabled;},checked:function(a){return a.checked;},selected:function(a){return a.selected||jQuery.attr(a,"selected");},text:function(a){return"text"==a.type;},radio:function(a){return"radio"==a.type;},checkbox:function(a){return"checkbox"==a.type;},file:function(a){return"file"==a.type;},password:function(a){return"password"==a.type;},submit:function(a){return"submit"==a.type;},image:function(a){return"image"==a.type;},reset:function(a){return"reset"==a.type;},button:function(a){return"button"==a.type||jQuery.nodeName(a,"button");},input:function(a){return/input|select|textarea|button/i.test(a.nodeName);},has:function(a,i,m){return jQuery.find(m[3],a).length;},header:function(a){return/h\d/i.test(a.nodeName);},animated:function(a){return jQuery.grep(jQuery.timers,function(fn){return a==fn.elem;}).length;}}},parse:[/^(\[) *@?([\w-]+) *([!*$^~=]*) *('?"?)(.*?)\4 *\]/,/^(:)([\w-]+)\("?'?(.*?(\(.*?\))?[^(]*?)"?'?\)/,new RegExp("^([:.#]*)("+chars+"+)")],multiFilter:function(expr,elems,not){var old,cur=[];while(expr&&expr!=old){old=expr;var f=jQuery.filter(expr,elems,not);expr=f.t.replace(/^\s*,\s*/,"");cur=not?elems=f.r:jQuery.merge(cur,f.r);}return cur;},find:function(t,context){if(typeof t!="string")return[t];if(context&&context.nodeType!=1&&context.nodeType!=9)return[];context=context||document;var ret=[context],done=[],last,nodeName;while(t&&last!=t){var r=[];last=t;t=jQuery.trim(t);var foundToken=false,re=quickChild,m=re.exec(t);if(m){nodeName=m[1].toUpperCase();for(var i=0;ret[i];i++)for(var c=ret[i].firstChild;c;c=c.nextSibling)if(c.nodeType==1&&(nodeName=="*"||c.nodeName.toUpperCase()==nodeName))r.push(c);ret=r;t=t.replace(re,"");if(t.indexOf(" ")==0)continue;foundToken=true;}else{re=/^([>+~])\s*(\w*)/i;if((m=re.exec(t))!=null){r=[];var merge={};nodeName=m[2].toUpperCase();m=m[1];for(var j=0,rl=ret.length;j=0;if(!not&&pass||not&&!pass)tmp.push(r[i]);}return tmp;},filter:function(t,r,not){var last;while(t&&t!=last){last=t;var p=jQuery.parse,m;for(var i=0;p[i];i++){m=p[i].exec(t);if(m){t=t.substring(m[0].length);m[2]=m[2].replace(/\\/g,"");break;}}if(!m)break;if(m[1]==":"&&m[2]=="not")r=isSimple.test(m[3])?jQuery.filter(m[3],r,true).r:jQuery(r).not(m[3]);else if(m[1]==".")r=jQuery.classFilter(r,m[2],not);else if(m[1]=="["){var tmp=[],type=m[3];for(var i=0,rl=r.length;i=0)^not)tmp.push(a);}r=tmp;}else if(m[1]==":"&&m[2]=="nth-child"){var merge={},tmp=[],test=/(-?)(\d*)n((?:\+|-)?\d*)/.exec(m[3]=="even"&&"2n"||m[3]=="odd"&&"2n+1"||!/\D/.test(m[3])&&"0n+"+m[3]||m[3]),first=(test[1]+(test[2]||1))-0,last=test[3]-0;for(var i=0,rl=r.length;i=0)add=true;if(add^not)tmp.push(node);}r=tmp;}else{var fn=jQuery.expr[m[1]];if(typeof fn=="object")fn=fn[m[2]];if(typeof fn=="string")fn=eval("false||function(a,i){return "+fn+";}");r=jQuery.grep(r,function(elem,i){return fn(elem,i,m,r);},not);}}return{r:r,t:t};},dir:function(elem,dir){var matched=[],cur=elem[dir];while(cur&&cur!=document){if(cur.nodeType==1)matched.push(cur);cur=cur[dir];}return matched;},nth:function(cur,result,dir,elem){result=result||1;var num=0;for(;cur;cur=cur[dir])if(cur.nodeType==1&&++num==result)break;return cur;},sibling:function(n,elem){var r=[];for(;n;n=n.nextSibling){if(n.nodeType==1&&n!=elem)r.push(n);}return r;}});jQuery.event={add:function(elem,types,handler,data){if(elem.nodeType==3||elem.nodeType==8)return;if(jQuery.browser.msie&&elem.setInterval)elem=window;if(!handler.guid)handler.guid=this.guid++;if(data!=undefined){var fn=handler;handler=this.proxy(fn,function(){return fn.apply(this,arguments);});handler.data=data;}var events=jQuery.data(elem,"events")||jQuery.data(elem,"events",{}),handle=jQuery.data(elem,"handle")||jQuery.data(elem,"handle",function(){if(typeof jQuery!="undefined"&&!jQuery.event.triggered)return jQuery.event.handle.apply(arguments.callee.elem,arguments);});handle.elem=elem;jQuery.each(types.split(/\s+/),function(index,type){var parts=type.split(".");type=parts[0];handler.type=parts[1];var handlers=events[type];if(!handlers){handlers=events[type]={};if(!jQuery.event.special[type]||jQuery.event.special[type].setup.call(elem)===false){if(elem.addEventListener)elem.addEventListener(type,handle,false);else if(elem.attachEvent)elem.attachEvent("on"+type,handle);}}handlers[handler.guid]=handler;jQuery.event.global[type]=true;});elem=null;},guid:1,global:{},remove:function(elem,types,handler){if(elem.nodeType==3||elem.nodeType==8)return;var events=jQuery.data(elem,"events"),ret,index;if(events){if(types==undefined||(typeof types=="string"&&types.charAt(0)=="."))for(var type in events)this.remove(elem,type+(types||""));else{if(types.type){handler=types.handler;types=types.type;}jQuery.each(types.split(/\s+/),function(index,type){var parts=type.split(".");type=parts[0];if(events[type]){if(handler)delete events[type][handler.guid];else +for(handler in events[type])if(!parts[1]||events[type][handler].type==parts[1])delete events[type][handler];for(ret in events[type])break;if(!ret){if(!jQuery.event.special[type]||jQuery.event.special[type].teardown.call(elem)===false){if(elem.removeEventListener)elem.removeEventListener(type,jQuery.data(elem,"handle"),false);else if(elem.detachEvent)elem.detachEvent("on"+type,jQuery.data(elem,"handle"));}ret=null;delete events[type];}}});}for(ret in events)break;if(!ret){var handle=jQuery.data(elem,"handle");if(handle)handle.elem=null;jQuery.removeData(elem,"events");jQuery.removeData(elem,"handle");}}},trigger:function(type,data,elem,donative,extra){data=jQuery.makeArray(data);if(type.indexOf("!")>=0){type=type.slice(0,-1);var exclusive=true;}if(!elem){if(this.global[type])jQuery("*").add([window,document]).trigger(type,data);}else{if(elem.nodeType==3||elem.nodeType==8)return undefined;var val,ret,fn=jQuery.isFunction(elem[type]||null),event=!data[0]||!data[0].preventDefault;if(event){data.unshift({type:type,target:elem,preventDefault:function(){},stopPropagation:function(){},timeStamp:now()});data[0][expando]=true;}data[0].type=type;if(exclusive)data[0].exclusive=true;var handle=jQuery.data(elem,"handle");if(handle)val=handle.apply(elem,data);if((!fn||(jQuery.nodeName(elem,'a')&&type=="click"))&&elem["on"+type]&&elem["on"+type].apply(elem,data)===false)val=false;if(event)data.shift();if(extra&&jQuery.isFunction(extra)){ret=extra.apply(elem,val==null?data:data.concat(val));if(ret!==undefined)val=ret;}if(fn&&donative!==false&&val!==false&&!(jQuery.nodeName(elem,'a')&&type=="click")){this.triggered=true;try{elem[type]();}catch(e){}}this.triggered=false;}return val;},handle:function(event){var val,ret,namespace,all,handlers;event=arguments[0]=jQuery.event.fix(event||window.event);namespace=event.type.split(".");event.type=namespace[0];namespace=namespace[1];all=!namespace&&!event.exclusive;handlers=(jQuery.data(this,"events")||{})[event.type];for(var j in handlers){var handler=handlers[j];if(all||handler.type==namespace){event.handler=handler;event.data=handler.data;ret=handler.apply(this,arguments);if(val!==false)val=ret;if(ret===false){event.preventDefault();event.stopPropagation();}}}return val;},fix:function(event){if(event[expando]==true)return event;var originalEvent=event;event={originalEvent:originalEvent};var props="altKey attrChange attrName bubbles button cancelable charCode clientX clientY ctrlKey currentTarget data detail eventPhase fromElement handler keyCode metaKey newValue originalTarget pageX pageY prevValue relatedNode relatedTarget screenX screenY shiftKey srcElement target timeStamp toElement type view wheelDelta which".split(" ");for(var i=props.length;i;i--)event[props[i]]=originalEvent[props[i]];event[expando]=true;event.preventDefault=function(){if(originalEvent.preventDefault)originalEvent.preventDefault();originalEvent.returnValue=false;};event.stopPropagation=function(){if(originalEvent.stopPropagation)originalEvent.stopPropagation();originalEvent.cancelBubble=true;};event.timeStamp=event.timeStamp||now();if(!event.target)event.target=event.srcElement||document;if(event.target.nodeType==3)event.target=event.target.parentNode;if(!event.relatedTarget&&event.fromElement)event.relatedTarget=event.fromElement==event.target?event.toElement:event.fromElement;if(event.pageX==null&&event.clientX!=null){var doc=document.documentElement,body=document.body;event.pageX=event.clientX+(doc&&doc.scrollLeft||body&&body.scrollLeft||0)-(doc.clientLeft||0);event.pageY=event.clientY+(doc&&doc.scrollTop||body&&body.scrollTop||0)-(doc.clientTop||0);}if(!event.which&&((event.charCode||event.charCode===0)?event.charCode:event.keyCode))event.which=event.charCode||event.keyCode;if(!event.metaKey&&event.ctrlKey)event.metaKey=event.ctrlKey;if(!event.which&&event.button)event.which=(event.button&1?1:(event.button&2?3:(event.button&4?2:0)));return event;},proxy:function(fn,proxy){proxy.guid=fn.guid=fn.guid||proxy.guid||this.guid++;return proxy;},special:{ready:{setup:function(){bindReady();return;},teardown:function(){return;}},mouseenter:{setup:function(){if(jQuery.browser.msie)return false;jQuery(this).bind("mouseover",jQuery.event.special.mouseenter.handler);return true;},teardown:function(){if(jQuery.browser.msie)return false;jQuery(this).unbind("mouseover",jQuery.event.special.mouseenter.handler);return true;},handler:function(event){if(withinElement(event,this))return true;event.type="mouseenter";return jQuery.event.handle.apply(this,arguments);}},mouseleave:{setup:function(){if(jQuery.browser.msie)return false;jQuery(this).bind("mouseout",jQuery.event.special.mouseleave.handler);return true;},teardown:function(){if(jQuery.browser.msie)return false;jQuery(this).unbind("mouseout",jQuery.event.special.mouseleave.handler);return true;},handler:function(event){if(withinElement(event,this))return true;event.type="mouseleave";return jQuery.event.handle.apply(this,arguments);}}}};jQuery.fn.extend({bind:function(type,data,fn){return type=="unload"?this.one(type,data,fn):this.each(function(){jQuery.event.add(this,type,fn||data,fn&&data);});},one:function(type,data,fn){var one=jQuery.event.proxy(fn||data,function(event){jQuery(this).unbind(event,one);return(fn||data).apply(this,arguments);});return this.each(function(){jQuery.event.add(this,type,one,fn&&data);});},unbind:function(type,fn){return this.each(function(){jQuery.event.remove(this,type,fn);});},trigger:function(type,data,fn){return this.each(function(){jQuery.event.trigger(type,data,this,true,fn);});},triggerHandler:function(type,data,fn){return this[0]&&jQuery.event.trigger(type,data,this[0],false,fn);},toggle:function(fn){var args=arguments,i=1;while(i=0){var selector=url.slice(off,url.length);url=url.slice(0,off);}callback=callback||function(){};var type="GET";if(params)if(jQuery.isFunction(params)){callback=params;params=null;}else{params=jQuery.param(params);type="POST";}var self=this;jQuery.ajax({url:url,type:type,dataType:"html",data:params,complete:function(res,status){if(status=="success"||status=="notmodified")self.html(selector?jQuery("
      ").append(res.responseText.replace(//g,"")).find(selector):res.responseText);self.each(callback,[res.responseText,status,res]);}});return this;},serialize:function(){return jQuery.param(this.serializeArray());},serializeArray:function(){return this.map(function(){return jQuery.nodeName(this,"form")?jQuery.makeArray(this.elements):this;}).filter(function(){return this.name&&!this.disabled&&(this.checked||/select|textarea/i.test(this.nodeName)||/text|hidden|password/i.test(this.type));}).map(function(i,elem){var val=jQuery(this).val();return val==null?null:val.constructor==Array?jQuery.map(val,function(val,i){return{name:elem.name,value:val};}):{name:elem.name,value:val};}).get();}});jQuery.each("ajaxStart,ajaxStop,ajaxComplete,ajaxError,ajaxSuccess,ajaxSend".split(","),function(i,o){jQuery.fn[o]=function(f){return this.bind(o,f);};});var jsc=now();jQuery.extend({get:function(url,data,callback,type){if(jQuery.isFunction(data)){callback=data;data=null;}return jQuery.ajax({type:"GET",url:url,data:data,success:callback,dataType:type});},getScript:function(url,callback){return jQuery.get(url,null,callback,"script");},getJSON:function(url,data,callback){return jQuery.get(url,data,callback,"json");},post:function(url,data,callback,type){if(jQuery.isFunction(data)){callback=data;data={};}return jQuery.ajax({type:"POST",url:url,data:data,success:callback,dataType:type});},ajaxSetup:function(settings){jQuery.extend(jQuery.ajaxSettings,settings);},ajaxSettings:{url:location.href,global:true,type:"GET",timeout:0,contentType:"application/x-www-form-urlencoded",processData:true,async:true,data:null,username:null,password:null,accepts:{xml:"application/xml, text/xml",html:"text/html",script:"text/javascript, application/javascript",json:"application/json, text/javascript",text:"text/plain",_default:"*/*"}},lastModified:{},ajax:function(s){s=jQuery.extend(true,s,jQuery.extend(true,{},jQuery.ajaxSettings,s));var jsonp,jsre=/=\?(&|$)/g,status,data,type=s.type.toUpperCase();if(s.data&&s.processData&&typeof s.data!="string")s.data=jQuery.param(s.data);if(s.dataType=="jsonp"){if(type=="GET"){if(!s.url.match(jsre))s.url+=(s.url.match(/\?/)?"&":"?")+(s.jsonp||"callback")+"=?";}else if(!s.data||!s.data.match(jsre))s.data=(s.data?s.data+"&":"")+(s.jsonp||"callback")+"=?";s.dataType="json";}if(s.dataType=="json"&&(s.data&&s.data.match(jsre)||s.url.match(jsre))){jsonp="jsonp"+jsc++;if(s.data)s.data=(s.data+"").replace(jsre,"="+jsonp+"$1");s.url=s.url.replace(jsre,"="+jsonp+"$1");s.dataType="script";window[jsonp]=function(tmp){data=tmp;success();complete();window[jsonp]=undefined;try{delete window[jsonp];}catch(e){}if(head)head.removeChild(script);};}if(s.dataType=="script"&&s.cache==null)s.cache=false;if(s.cache===false&&type=="GET"){var ts=now();var ret=s.url.replace(/(\?|&)_=.*?(&|$)/,"$1_="+ts+"$2");s.url=ret+((ret==s.url)?(s.url.match(/\?/)?"&":"?")+"_="+ts:"");}if(s.data&&type=="GET"){s.url+=(s.url.match(/\?/)?"&":"?")+s.data;s.data=null;}if(s.global&&!jQuery.active++)jQuery.event.trigger("ajaxStart");var remote=/^(?:\w+:)?\/\/([^\/?#]+)/;if(s.dataType=="script"&&type=="GET"&&remote.test(s.url)&&remote.exec(s.url)[1]!=location.host){var head=document.getElementsByTagName("head")[0];var script=document.createElement("script");script.src=s.url;if(s.scriptCharset)script.charset=s.scriptCharset;if(!jsonp){var done=false;script.onload=script.onreadystatechange=function(){if(!done&&(!this.readyState||this.readyState=="loaded"||this.readyState=="complete")){done=true;success();complete();head.removeChild(script);}};}head.appendChild(script);return undefined;}var requestDone=false;var xhr=window.ActiveXObject?new ActiveXObject("Microsoft.XMLHTTP"):new XMLHttpRequest();if(s.username)xhr.open(type,s.url,s.async,s.username,s.password);else +xhr.open(type,s.url,s.async);try{if(s.data)xhr.setRequestHeader("Content-Type",s.contentType);if(s.ifModified)xhr.setRequestHeader("If-Modified-Since",jQuery.lastModified[s.url]||"Thu, 01 Jan 1970 00:00:00 GMT");xhr.setRequestHeader("X-Requested-With","XMLHttpRequest");xhr.setRequestHeader("Accept",s.dataType&&s.accepts[s.dataType]?s.accepts[s.dataType]+", */*":s.accepts._default);}catch(e){}if(s.beforeSend&&s.beforeSend(xhr,s)===false){s.global&&jQuery.active--;xhr.abort();return false;}if(s.global)jQuery.event.trigger("ajaxSend",[xhr,s]);var onreadystatechange=function(isTimeout){if(!requestDone&&xhr&&(xhr.readyState==4||isTimeout=="timeout")){requestDone=true;if(ival){clearInterval(ival);ival=null;}status=isTimeout=="timeout"&&"timeout"||!jQuery.httpSuccess(xhr)&&"error"||s.ifModified&&jQuery.httpNotModified(xhr,s.url)&&"notmodified"||"success";if(status=="success"){try{data=jQuery.httpData(xhr,s.dataType,s.dataFilter);}catch(e){status="parsererror";}}if(status=="success"){var modRes;try{modRes=xhr.getResponseHeader("Last-Modified");}catch(e){}if(s.ifModified&&modRes)jQuery.lastModified[s.url]=modRes;if(!jsonp)success();}else +jQuery.handleError(s,xhr,status);complete();if(s.async)xhr=null;}};if(s.async){var ival=setInterval(onreadystatechange,13);if(s.timeout>0)setTimeout(function(){if(xhr){xhr.abort();if(!requestDone)onreadystatechange("timeout");}},s.timeout);}try{xhr.send(s.data);}catch(e){jQuery.handleError(s,xhr,null,e);}if(!s.async)onreadystatechange();function success(){if(s.success)s.success(data,status);if(s.global)jQuery.event.trigger("ajaxSuccess",[xhr,s]);}function complete(){if(s.complete)s.complete(xhr,status);if(s.global)jQuery.event.trigger("ajaxComplete",[xhr,s]);if(s.global&&!--jQuery.active)jQuery.event.trigger("ajaxStop");}return xhr;},handleError:function(s,xhr,status,e){if(s.error)s.error(xhr,status,e);if(s.global)jQuery.event.trigger("ajaxError",[xhr,s,e]);},active:0,httpSuccess:function(xhr){try{return!xhr.status&&location.protocol=="file:"||(xhr.status>=200&&xhr.status<300)||xhr.status==304||xhr.status==1223||jQuery.browser.safari&&xhr.status==undefined;}catch(e){}return false;},httpNotModified:function(xhr,url){try{var xhrRes=xhr.getResponseHeader("Last-Modified");return xhr.status==304||xhrRes==jQuery.lastModified[url]||jQuery.browser.safari&&xhr.status==undefined;}catch(e){}return false;},httpData:function(xhr,type,filter){var ct=xhr.getResponseHeader("content-type"),xml=type=="xml"||!type&&ct&&ct.indexOf("xml")>=0,data=xml?xhr.responseXML:xhr.responseText;if(xml&&data.documentElement.tagName=="parsererror")throw"parsererror";if(filter)data=filter(data,type);if(type=="script")jQuery.globalEval(data);if(type=="json")data=eval("("+data+")");return data;},param:function(a){var s=[];if(a.constructor==Array||a.jquery)jQuery.each(a,function(){s.push(encodeURIComponent(this.name)+"="+encodeURIComponent(this.value));});else +for(var j in a)if(a[j]&&a[j].constructor==Array)jQuery.each(a[j],function(){s.push(encodeURIComponent(j)+"="+encodeURIComponent(this));});else +s.push(encodeURIComponent(j)+"="+encodeURIComponent(jQuery.isFunction(a[j])?a[j]():a[j]));return s.join("&").replace(/%20/g,"+");}});jQuery.fn.extend({show:function(speed,callback){return speed?this.animate({height:"show",width:"show",opacity:"show"},speed,callback):this.filter(":hidden").each(function(){this.style.display=this.oldblock||"";if(jQuery.css(this,"display")=="none"){var elem=jQuery("<"+this.tagName+" />").appendTo("body");this.style.display=elem.css("display");if(this.style.display=="none")this.style.display="block";elem.remove();}}).end();},hide:function(speed,callback){return speed?this.animate({height:"hide",width:"hide",opacity:"hide"},speed,callback):this.filter(":visible").each(function(){this.oldblock=this.oldblock||jQuery.css(this,"display");this.style.display="none";}).end();},_toggle:jQuery.fn.toggle,toggle:function(fn,fn2){return jQuery.isFunction(fn)&&jQuery.isFunction(fn2)?this._toggle.apply(this,arguments):fn?this.animate({height:"toggle",width:"toggle",opacity:"toggle"},fn,fn2):this.each(function(){jQuery(this)[jQuery(this).is(":hidden")?"show":"hide"]();});},slideDown:function(speed,callback){return this.animate({height:"show"},speed,callback);},slideUp:function(speed,callback){return this.animate({height:"hide"},speed,callback);},slideToggle:function(speed,callback){return this.animate({height:"toggle"},speed,callback);},fadeIn:function(speed,callback){return this.animate({opacity:"show"},speed,callback);},fadeOut:function(speed,callback){return this.animate({opacity:"hide"},speed,callback);},fadeTo:function(speed,to,callback){return this.animate({opacity:to},speed,callback);},animate:function(prop,speed,easing,callback){var optall=jQuery.speed(speed,easing,callback);return this[optall.queue===false?"each":"queue"](function(){if(this.nodeType!=1)return false;var opt=jQuery.extend({},optall),p,hidden=jQuery(this).is(":hidden"),self=this;for(p in prop){if(prop[p]=="hide"&&hidden||prop[p]=="show"&&!hidden)return opt.complete.call(this);if(p=="height"||p=="width"){opt.display=jQuery.css(this,"display");opt.overflow=this.style.overflow;}}if(opt.overflow!=null)this.style.overflow="hidden";opt.curAnim=jQuery.extend({},prop);jQuery.each(prop,function(name,val){var e=new jQuery.fx(self,opt,name);if(/toggle|show|hide/.test(val))e[val=="toggle"?hidden?"show":"hide":val](prop);else{var parts=val.toString().match(/^([+-]=)?([\d+-.]+)(.*)$/),start=e.cur(true)||0;if(parts){var end=parseFloat(parts[2]),unit=parts[3]||"px";if(unit!="px"){self.style[name]=(end||1)+unit;start=((end||1)/e.cur(true))*start;self.style[name]=start+unit;}if(parts[1])end=((parts[1]=="-="?-1:1)*end)+start;e.custom(start,end,unit);}else +e.custom(start,val,"");}});return true;});},queue:function(type,fn){if(jQuery.isFunction(type)||(type&&type.constructor==Array)){fn=type;type="fx";}if(!type||(typeof type=="string"&&!fn))return queue(this[0],type);return this.each(function(){if(fn.constructor==Array)queue(this,type,fn);else{queue(this,type).push(fn);if(queue(this,type).length==1)fn.call(this);}});},stop:function(clearQueue,gotoEnd){var timers=jQuery.timers;if(clearQueue)this.queue([]);this.each(function(){for(var i=timers.length-1;i>=0;i--)if(timers[i].elem==this){if(gotoEnd)timers[i](true);timers.splice(i,1);}});if(!gotoEnd)this.dequeue();return this;}});var queue=function(elem,type,array){if(elem){type=type||"fx";var q=jQuery.data(elem,type+"queue");if(!q||array)q=jQuery.data(elem,type+"queue",jQuery.makeArray(array));}return q;};jQuery.fn.dequeue=function(type){type=type||"fx";return this.each(function(){var q=queue(this,type);q.shift();if(q.length)q[0].call(this);});};jQuery.extend({speed:function(speed,easing,fn){var opt=speed&&speed.constructor==Object?speed:{complete:fn||!fn&&easing||jQuery.isFunction(speed)&&speed,duration:speed,easing:fn&&easing||easing&&easing.constructor!=Function&&easing};opt.duration=(opt.duration&&opt.duration.constructor==Number?opt.duration:jQuery.fx.speeds[opt.duration])||jQuery.fx.speeds.def;opt.old=opt.complete;opt.complete=function(){if(opt.queue!==false)jQuery(this).dequeue();if(jQuery.isFunction(opt.old))opt.old.call(this);};return opt;},easing:{linear:function(p,n,firstNum,diff){return firstNum+diff*p;},swing:function(p,n,firstNum,diff){return((-Math.cos(p*Math.PI)/2)+0.5)*diff+firstNum;}},timers:[],timerId:null,fx:function(elem,options,prop){this.options=options;this.elem=elem;this.prop=prop;if(!options.orig)options.orig={};}});jQuery.fx.prototype={update:function(){if(this.options.step)this.options.step.call(this.elem,this.now,this);(jQuery.fx.step[this.prop]||jQuery.fx.step._default)(this);if(this.prop=="height"||this.prop=="width")this.elem.style.display="block";},cur:function(force){if(this.elem[this.prop]!=null&&this.elem.style[this.prop]==null)return this.elem[this.prop];var r=parseFloat(jQuery.css(this.elem,this.prop,force));return r&&r>-10000?r:parseFloat(jQuery.curCSS(this.elem,this.prop))||0;},custom:function(from,to,unit){this.startTime=now();this.start=from;this.end=to;this.unit=unit||this.unit||"px";this.now=this.start;this.pos=this.state=0;this.update();var self=this;function t(gotoEnd){return self.step(gotoEnd);}t.elem=this.elem;jQuery.timers.push(t);if(jQuery.timerId==null){jQuery.timerId=setInterval(function(){var timers=jQuery.timers;for(var i=0;ithis.options.duration+this.startTime){this.now=this.end;this.pos=this.state=1;this.update();this.options.curAnim[this.prop]=true;var done=true;for(var i in this.options.curAnim)if(this.options.curAnim[i]!==true)done=false;if(done){if(this.options.display!=null){this.elem.style.overflow=this.options.overflow;this.elem.style.display=this.options.display;if(jQuery.css(this.elem,"display")=="none")this.elem.style.display="block";}if(this.options.hide)this.elem.style.display="none";if(this.options.hide||this.options.show)for(var p in this.options.curAnim)jQuery.attr(this.elem.style,p,this.options.orig[p]);}if(done)this.options.complete.call(this.elem);return false;}else{var n=t-this.startTime;this.state=n/this.options.duration;this.pos=jQuery.easing[this.options.easing||(jQuery.easing.swing?"swing":"linear")](this.state,n,0,1,this.options.duration);this.now=this.start+((this.end-this.start)*this.pos);this.update();}return true;}};jQuery.extend(jQuery.fx,{speeds:{slow:600,fast:200,def:400},step:{scrollLeft:function(fx){fx.elem.scrollLeft=fx.now;},scrollTop:function(fx){fx.elem.scrollTop=fx.now;},opacity:function(fx){jQuery.attr(fx.elem.style,"opacity",fx.now);},_default:function(fx){fx.elem.style[fx.prop]=fx.now+fx.unit;}}});jQuery.fn.offset=function(){var left=0,top=0,elem=this[0],results;if(elem)with(jQuery.browser){var parent=elem.parentNode,offsetChild=elem,offsetParent=elem.offsetParent,doc=elem.ownerDocument,safari2=safari&&parseInt(version)<522&&!/adobeair/i.test(userAgent),css=jQuery.curCSS,fixed=css(elem,"position")=="fixed";if(elem.getBoundingClientRect){var box=elem.getBoundingClientRect();add(box.left+Math.max(doc.documentElement.scrollLeft,doc.body.scrollLeft),box.top+Math.max(doc.documentElement.scrollTop,doc.body.scrollTop));add(-doc.documentElement.clientLeft,-doc.documentElement.clientTop);}else{add(elem.offsetLeft,elem.offsetTop);while(offsetParent){add(offsetParent.offsetLeft,offsetParent.offsetTop);if(mozilla&&!/^t(able|d|h)$/i.test(offsetParent.tagName)||safari&&!safari2)border(offsetParent);if(!fixed&&css(offsetParent,"position")=="fixed")fixed=true;offsetChild=/^body$/i.test(offsetParent.tagName)?offsetChild:offsetParent;offsetParent=offsetParent.offsetParent;}while(parent&&parent.tagName&&!/^body|html$/i.test(parent.tagName)){if(!/^inline|table.*$/i.test(css(parent,"display")))add(-parent.scrollLeft,-parent.scrollTop);if(mozilla&&css(parent,"overflow")!="visible")border(parent);parent=parent.parentNode;}if((safari2&&(fixed||css(offsetChild,"position")=="absolute"))||(mozilla&&css(offsetChild,"position")!="absolute"))add(-doc.body.offsetLeft,-doc.body.offsetTop);if(fixed)add(Math.max(doc.documentElement.scrollLeft,doc.body.scrollLeft),Math.max(doc.documentElement.scrollTop,doc.body.scrollTop));}results={top:top,left:left};}function border(elem){add(jQuery.curCSS(elem,"borderLeftWidth",true),jQuery.curCSS(elem,"borderTopWidth",true));}function add(l,t){left+=parseInt(l,10)||0;top+=parseInt(t,10)||0;}return results;};jQuery.fn.extend({position:function(){var left=0,top=0,results;if(this[0]){var offsetParent=this.offsetParent(),offset=this.offset(),parentOffset=/^body|html$/i.test(offsetParent[0].tagName)?{top:0,left:0}:offsetParent.offset();offset.top-=num(this,'marginTop');offset.left-=num(this,'marginLeft');parentOffset.top+=num(offsetParent,'borderTopWidth');parentOffset.left+=num(offsetParent,'borderLeftWidth');results={top:offset.top-parentOffset.top,left:offset.left-parentOffset.left};}return results;},offsetParent:function(){var offsetParent=this[0].offsetParent;while(offsetParent&&(!/^body|html$/i.test(offsetParent.tagName)&&jQuery.css(offsetParent,'position')=='static'))offsetParent=offsetParent.offsetParent;return jQuery(offsetParent);}});jQuery.each(['Left','Top'],function(i,name){var method='scroll'+name;jQuery.fn[method]=function(val){if(!this[0])return;return val!=undefined?this.each(function(){this==window||this==document?window.scrollTo(!i?val:jQuery(window).scrollLeft(),i?val:jQuery(window).scrollTop()):this[method]=val;}):this[0]==window||this[0]==document?self[i?'pageYOffset':'pageXOffset']||jQuery.boxModel&&document.documentElement[method]||document.body[method]:this[0][method];};});jQuery.each(["Height","Width"],function(i,name){var tl=i?"Left":"Top",br=i?"Right":"Bottom";jQuery.fn["inner"+name]=function(){return this[name.toLowerCase()]()+num(this,"padding"+tl)+num(this,"padding"+br);};jQuery.fn["outer"+name]=function(margin){return this["inner"+name]()+num(this,"border"+tl+"Width")+num(this,"border"+br+"Width")+(margin?num(this,"margin"+tl)+num(this,"margin"+br):0);};});})(); \ No newline at end of file diff --git a/sphinx/themes/basic/static/minus.png b/sphinx/themes/basic/static/minus.png new file mode 100644 index 00000000..da1c5620 Binary files /dev/null and b/sphinx/themes/basic/static/minus.png differ diff --git a/sphinx/themes/basic/static/plus.png b/sphinx/themes/basic/static/plus.png new file mode 100644 index 00000000..b3cb3742 Binary files /dev/null and b/sphinx/themes/basic/static/plus.png differ diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js new file mode 100644 index 00000000..f9d9b6c3 --- /dev/null +++ b/sphinx/themes/basic/static/searchtools.js @@ -0,0 +1,467 @@ +/** + * helper function to return a node containing the + * search summary for a given text. keywords is a list + * of stemmed words, hlwords is the list of normal, unstemmed + * words. the first one is used to find the occurance, the + * latter for highlighting it. + */ + +jQuery.makeSearchSummary = function(text, keywords, hlwords) { + var textLower = text.toLowerCase(); + var start = 0; + $.each(keywords, function() { + var i = textLower.indexOf(this.toLowerCase()); + if (i > -1) + start = i; + }); + start = Math.max(start - 120, 0); + var excerpt = ((start > 0) ? '...' : '') + + $.trim(text.substr(start, 240)) + + ((start + 240 - text.length) ? '...' : ''); + var rv = $('
      ').text(excerpt); + $.each(hlwords, function() { + rv = rv.highlightText(this, 'highlight'); + }); + return rv; +} + +/** + * Porter Stemmer + */ +var PorterStemmer = function() { + + var step2list = { + ational: 'ate', + tional: 'tion', + enci: 'ence', + anci: 'ance', + izer: 'ize', + bli: 'ble', + alli: 'al', + entli: 'ent', + eli: 'e', + ousli: 'ous', + ization: 'ize', + ation: 'ate', + ator: 'ate', + alism: 'al', + iveness: 'ive', + fulness: 'ful', + ousness: 'ous', + aliti: 'al', + iviti: 'ive', + biliti: 'ble', + logi: 'log' + }; + + var step3list = { + icate: 'ic', + ative: '', + alize: 'al', + iciti: 'ic', + ical: 'ic', + ful: '', + ness: '' + }; + + var c = "[^aeiou]"; // consonant + var v = "[aeiouy]"; // vowel + var C = c + "[^aeiouy]*"; // consonant sequence + var V = v + "[aeiou]*"; // vowel sequence + + var mgr0 = "^(" + C + ")?" + V + C; // [C]VC... is m>0 + var meq1 = "^(" + C + ")?" + V + C + "(" + V + ")?$"; // [C]VC[V] is m=1 + var mgr1 = "^(" + C + ")?" + V + C + V + C; // [C]VCVC... is m>1 + var s_v = "^(" + C + ")?" + v; // vowel in stem + + this.stemWord = function (w) { + var stem; + var suffix; + var firstch; + var origword = w; + + if (w.length < 3) + return w; + + var re; + var re2; + var re3; + var re4; + + firstch = w.substr(0,1); + if (firstch == "y") + w = firstch.toUpperCase() + w.substr(1); + + // Step 1a + re = /^(.+?)(ss|i)es$/; + re2 = /^(.+?)([^s])s$/; + + if (re.test(w)) + w = w.replace(re,"$1$2"); + else if (re2.test(w)) + w = w.replace(re2,"$1$2"); + + // Step 1b + re = /^(.+?)eed$/; + re2 = /^(.+?)(ed|ing)$/; + if (re.test(w)) { + var fp = re.exec(w); + re = new RegExp(mgr0); + if (re.test(fp[1])) { + re = /.$/; + w = w.replace(re,""); + } + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1]; + re2 = new RegExp(s_v); + if (re2.test(stem)) { + w = stem; + re2 = /(at|bl|iz)$/; + re3 = new RegExp("([^aeiouylsz])\\1$"); + re4 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re2.test(w)) + w = w + "e"; + else if (re3.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + else if (re4.test(w)) + w = w + "e"; + } + } + + // Step 1c + re = /^(.+?)y$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(s_v); + if (re.test(stem)) + w = stem + "i"; + } + + // Step 2 + re = /^(.+?)(ational|tional|enci|anci|izer|bli|alli|entli|eli|ousli|ization|ation|ator|alism|iveness|fulness|ousness|aliti|iviti|biliti|logi)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step2list[suffix]; + } + + // Step 3 + re = /^(.+?)(icate|ative|alize|iciti|ical|ful|ness)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + suffix = fp[2]; + re = new RegExp(mgr0); + if (re.test(stem)) + w = stem + step3list[suffix]; + } + + // Step 4 + re = /^(.+?)(al|ance|ence|er|ic|able|ible|ant|ement|ment|ent|ou|ism|ate|iti|ous|ive|ize)$/; + re2 = /^(.+?)(s|t)(ion)$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + if (re.test(stem)) + w = stem; + } + else if (re2.test(w)) { + var fp = re2.exec(w); + stem = fp[1] + fp[2]; + re2 = new RegExp(mgr1); + if (re2.test(stem)) + w = stem; + } + + // Step 5 + re = /^(.+?)e$/; + if (re.test(w)) { + var fp = re.exec(w); + stem = fp[1]; + re = new RegExp(mgr1); + re2 = new RegExp(meq1); + re3 = new RegExp("^" + C + v + "[^aeiouwxy]$"); + if (re.test(stem) || (re2.test(stem) && !(re3.test(stem)))) + w = stem; + } + re = /ll$/; + re2 = new RegExp(mgr1); + if (re.test(w) && re2.test(w)) { + re = /.$/; + w = w.replace(re,""); + } + + // and turn initial Y back to y + if (firstch == "y") + w = firstch.toLowerCase() + w.substr(1); + return w; + } +} + + +/** + * Search Module + */ +var Search = { + + _index : null, + _queued_query : null, + _pulse_status : -1, + + init : function() { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[@name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + /** + * Sets the index + */ + setIndex : function(index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex : function() { + return this._index !== null; + }, + + deferQuery : function(query) { + this._queued_query = query; + }, + + stopPulse : function() { + this._pulse_status = 0; + }, + + startPulse : function() { + if (this._pulse_status >= 0) + return; + function pulse() { + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ''; + for (var i = 0; i < Search._pulse_status; i++) + dotString += '.'; + Search.dots.text(dotString); + if (Search._pulse_status > -1) + window.setTimeout(pulse, 500); + }; + pulse(); + }, + + /** + * perform a search for something + */ + performSearch : function(query) { + // create the required interface elements + this.out = $('#search-results'); + this.title = $('

      ' + _('Searching') + '

      ').appendTo(this.out); + this.dots = $('').appendTo(this.title); + this.status = $('

      ').appendTo(this.out); + this.output = $('
      {%- endmacro %} + {%- macro sidebar() %} {%- if not embedded %}
      @@ -75,7 +77,9 @@ -

      {{ _('Enter search terms or a module, class or function name.') }}

      +

      + {{ _('Enter search terms or a module, class or function name.') }} +

      {%- endif %} @@ -142,6 +146,7 @@ {%- block extrahead %} {% endblock %} +{%- block header %}{% endblock %} {%- block relbar1 %}{{ relbar() }}{% endblock %} diff --git a/sphinx/themes/basic/static/basic.css b/sphinx/themes/basic/static/basic.css index 005caa1f..5a27fc16 100644 --- a/sphinx/themes/basic/static/basic.css +++ b/sphinx/themes/basic/static/basic.css @@ -1,21 +1,9 @@ /** - * Sphinx Doc Design + * Sphinx stylesheet -- basic theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -/* :::: LAYOUT :::: */ - -div.document { - background-color: #1c4e63; -} +/* -- main layout ----------------------------------------------------------- */ div.documentwrapper { float: left; @@ -26,44 +14,14 @@ div.bodywrapper { margin: 0 0 0 230px; } -div.body { - background-color: white; - padding: 0 20px 30px 20px; -} - -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - div.clearer { clear: both; } -div.footer { - color: #fff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #fff; - text-decoration: underline; -} +/* -- relbar ---------------------------------------------------------------- */ div.related { - background-color: #133f52; - color: #fff; width: 100%; - line-height: 30px; font-size: 90%; } @@ -86,46 +44,21 @@ div.related li.right { margin-right: 5px; } -div.related a { - color: white; -} - -/* ::: TOC :::: */ -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: white; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: white; -} +/* -- sidebar --------------------------------------------------------------- */ -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: white; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: white; +div.sphinxsidebarwrapper { + padding: 10px 5px 0 10px; } -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; +div.sphinxsidebar { + float: left; + width: 230px; + margin-left: -100%; + font-size: 90%; } div.sphinxsidebar ul { - margin: 10px; - padding: 0; list-style: none; - color: white; } div.sphinxsidebar ul ul, @@ -139,10 +72,6 @@ div.sphinxsidebar ul ul { margin-bottom: 0; } -div.sphinxsidebar a { - color: #98dbcc; -} - div.sphinxsidebar form { margin-top: 10px; } @@ -153,20 +82,12 @@ div.sphinxsidebar input { font-size: 1em; } -/* :::: MODULE CLOUD :::: */ -div.modulecloud { - margin: -5px 10px 5px 10px; - padding: 10px; - line-height: 160%; - border: 1px solid #cbe7e5; - background-color: #f2fbfd; +img.logo { + border: 0; } -div.modulecloud a { - padding: 0 5px 0 5px; -} +/* -- search page ----------------------------------------------------------- */ -/* :::: SEARCH :::: */ ul.search { margin: 10px 0 0 20px; padding: 0; @@ -193,39 +114,7 @@ ul.keywordmatches li.goodmatch a { font-weight: bold; } -/* :::: COMMON FORM STYLES :::: */ - -div.actions { - padding: 5px 10px 5px 10px; - border-top: 1px solid #cbe7e5; - border-bottom: 1px solid #cbe7e5; - background-color: #e0f6f4; -} - -form dl { - color: #333; -} - -form dt { - clear: both; - float: left; - min-width: 110px; - margin-right: 10px; - padding-top: 2px; -} - -input#homepage { - display: none; -} - -div.error { - margin: 5px 20px 0 0; - padding: 5px; - border: 1px solid #d00; - font-weight: bold; -} - -/* :::: INDEX PAGE :::: */ +/* -- index page ------------------------------------------------------------ */ table.contentstable { width: 90%; @@ -245,7 +134,7 @@ span.linkdescr { font-size: 90%; } -/* :::: INDEX STYLES :::: */ +/* -- general index --------------------------------------------------------- */ table.indextable td { text-align: left; @@ -272,60 +161,9 @@ img.toggler { cursor: pointer; } -form.pfform { - margin: 10px 0 20px 0; -} - -/* :::: GLOBAL STYLES :::: */ - -.docwarning { - background-color: #ffe4e4; - padding: 10px; - margin: 0 -20px 0 -20px; - border-bottom: 1px solid #f66; -} - -p.subhead { - font-weight: bold; - margin-top: 20px; -} - -a { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } +/* -- general body styles --------------------------------------------------- */ a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; visibility: hidden; } @@ -339,16 +177,6 @@ dt:hover > a.headerlink { visibility: visible; } -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: justify; - line-height: 130%; -} - div.body p.caption { text-align: inherit; } @@ -357,12 +185,6 @@ div.body td { text-align: left; } -ul.fakelist { - list-style: none; - margin: 10px 0 10px 20px; - padding: 0; -} - .field-list ul { padding-left: 1em; } @@ -371,13 +193,12 @@ ul.fakelist { margin-top: 0 !important; } -/* "Footnotes" heading */ p.rubric { margin-top: 30px; font-weight: bold; } -/* Sidebars */ +/* -- sidebars -------------------------------------------------------------- */ div.sidebar { margin: 0 0 0.5em 1em; @@ -392,10 +213,9 @@ p.sidebar-title { font-weight: bold; } -/* "Topics" */ +/* -- topics ---------------------------------------------------------------- */ div.topic { - background-color: #eee; border: 1px solid #ccc; padding: 7px 7px 0 7px; margin: 10px 0 10px 0; @@ -407,7 +227,7 @@ p.topic-title { margin-top: 10px; } -/* Admonitions */ +/* -- admonitions ----------------------------------------------------------- */ div.admonition { margin-top: 10px; @@ -423,33 +243,9 @@ div.admonition dl { margin-bottom: 0; } -div.admonition p.admonition-title + p { - display: inline; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - p.admonition-title { margin: 0px 10px 5px 0px; font-weight: bold; - display: inline; -} - -p.admonition-title:after { - content: ":"; } div.body p.centered { @@ -457,8 +253,11 @@ div.body p.centered { margin-top: 25px; } +/* -- tables ---------------------------------------------------------------- */ + table.docutils { border: 0; + border-collapse: collapse; } table.docutils td, table.docutils th { @@ -477,18 +276,15 @@ table.footnote td, table.footnote th { border: 0 !important; } -.field-list ul { - margin: 0; - padding-left: 1em; +th { + text-align: left; + padding-right: 5px; } -.field-list p { - margin: 0; -} +/* -- other body styles ----------------------------------------------------- */ dl { margin-bottom: 15px; - clear: both; } dd p { @@ -505,12 +301,7 @@ dd { margin-left: 30px; } -.refcount { - color: #060; -} - -dt:target, -.highlight { +dt:target, .highlight { background-color: #fbe54e; } @@ -519,18 +310,40 @@ dl.glossary dt { font-size: 1.1em; } -th { - text-align: left; - padding-right: 5px; +.field-list ul { + margin: 0; + padding-left: 1em; } -pre { +.field-list p { + margin: 0; +} + +.refcount { + color: #060; +} + +.optional { + font-size: 1.3em; +} + +.versionmodified { + font-style: italic; +} + +.system-message { + background-color: #fda; padding: 5px; - background-color: #efc; - color: #333; - border: 1px solid #ac9; - border-left: none; - border-right: none; + border: 3px solid red; +} + +.footnote:target { + background-color: #ffa +} + +/* -- code displays --------------------------------------------------------- */ + +pre { overflow: auto; } @@ -549,12 +362,6 @@ table.highlighttable td { padding: 0 0.5em 0 0.5em; } -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} - tt.descname { background-color: transparent; font-weight: bold; @@ -570,57 +377,11 @@ tt.xref, a tt { font-weight: bold; } -.footnote:target { background-color: #ffa } - h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { background-color: transparent; } -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -form.comment { - margin: 0; - padding: 10px 30px 10px 30px; - background-color: #eee; -} - -form.comment h3 { - background-color: #326591; - color: white; - margin: -10px -30px 10px -30px; - padding: 5px; - font-size: 1.4em; -} - -form.comment input, -form.comment textarea { - border: 1px solid #ccc; - padding: 2px; - font-family: sans-serif; - font-size: 100%; -} - -form.comment input[type="text"] { - width: 240px; -} - -form.comment textarea { - width: 100%; - height: 200px; - margin-bottom: 10px; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} +/* -- math display ---------------------------------------------------------- */ img.math { vertical-align: middle; @@ -634,23 +395,19 @@ span.eqno { float: right; } -img.logo { - border: 0; -} +/* -- printout stylesheet --------------------------------------------------- */ -/* :::: PRINT :::: */ @media print { div.document, div.documentwrapper, div.bodywrapper { margin: 0; - width : 100%; + width: 100%; } div.sphinxsidebar, div.related, div.footer, - div#comments div.new-comment-box, #top-link { display: none; } diff --git a/sphinx/themes/default/static/default.css b/sphinx/themes/default/static/default.css index 005caa1f..2ea55176 100644 --- a/sphinx/themes/default/static/default.css +++ b/sphinx/themes/default/static/default.css @@ -1,7 +1,12 @@ /** - * Sphinx Doc Design + * Sphinx stylesheet -- default theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ */ +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + body { font-family: sans-serif; font-size: 100%; @@ -11,41 +16,15 @@ body { padding: 0; } -/* :::: LAYOUT :::: */ - div.document { background-color: #1c4e63; } -div.documentwrapper { - float: left; - width: 100%; -} - -div.bodywrapper { - margin: 0 0 0 230px; -} - div.body { background-color: white; padding: 0 20px 30px 20px; } -div.sphinxsidebarwrapper { - padding: 10px 5px 0 10px; -} - -div.sphinxsidebar { - float: left; - width: 230px; - margin-left: -100%; - font-size: 90%; -} - -div.clearer { - clear: both; -} - div.footer { color: #fff; width: 100%; @@ -61,36 +40,14 @@ div.footer a { div.related { background-color: #133f52; - color: #fff; - width: 100%; line-height: 30px; - font-size: 90%; -} - -div.related h3 { - display: none; -} - -div.related ul { - margin: 0; - padding: 0 0 0 10px; - list-style: none; -} - -div.related li { - display: inline; -} - -div.related li.right { - float: right; - margin-right: 5px; + color: #fff; } div.related a { color: white; } -/* ::: TOC :::: */ div.sphinxsidebar h3 { font-family: 'Trebuchet MS', sans-serif; color: white; @@ -124,171 +81,20 @@ div.sphinxsidebar p.topless { div.sphinxsidebar ul { margin: 10px; padding: 0; - list-style: none; color: white; } -div.sphinxsidebar ul ul, -div.sphinxsidebar ul.want-points { - margin-left: 20px; - list-style: square; -} - -div.sphinxsidebar ul ul { - margin-top: 0; - margin-bottom: 0; -} - div.sphinxsidebar a { color: #98dbcc; } -div.sphinxsidebar form { - margin-top: 10px; -} - div.sphinxsidebar input { border: 1px solid #98dbcc; font-family: sans-serif; font-size: 1em; } -/* :::: MODULE CLOUD :::: */ -div.modulecloud { - margin: -5px 10px 5px 10px; - padding: 10px; - line-height: 160%; - border: 1px solid #cbe7e5; - background-color: #f2fbfd; -} - -div.modulecloud a { - padding: 0 5px 0 5px; -} - -/* :::: SEARCH :::: */ -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -/* :::: COMMON FORM STYLES :::: */ - -div.actions { - padding: 5px 10px 5px 10px; - border-top: 1px solid #cbe7e5; - border-bottom: 1px solid #cbe7e5; - background-color: #e0f6f4; -} - -form dl { - color: #333; -} - -form dt { - clear: both; - float: left; - min-width: 110px; - margin-right: 10px; - padding-top: 2px; -} - -input#homepage { - display: none; -} - -div.error { - margin: 5px 20px 0 0; - padding: 5px; - border: 1px solid #d00; - font-weight: bold; -} - -/* :::: INDEX PAGE :::: */ - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -/* :::: INDEX STYLES :::: */ - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -form.pfform { - margin: 10px 0 20px 0; -} - -/* :::: GLOBAL STYLES :::: */ - -.docwarning { - background-color: #ffe4e4; - padding: 10px; - margin: 0 -20px 0 -20px; - border-bottom: 1px solid #f66; -} - -p.subhead { - font-weight: bold; - margin-top: 20px; -} +/* -- body styles ----------------------------------------------------------- */ a { color: #355f7c; @@ -299,6 +105,11 @@ a:hover { text-decoration: underline; } +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + div.body h1, div.body h2, div.body h3, @@ -326,17 +137,6 @@ a.headerlink { font-size: 0.8em; padding: 0 4px 0 4px; text-decoration: none; - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; } a.headerlink:hover { @@ -349,82 +149,13 @@ div.body p, div.body dd, div.body li { line-height: 130%; } -div.body p.caption { - text-align: inherit; -} - -div.body td { - text-align: left; -} - -ul.fakelist { - list-style: none; - margin: 10px 0 10px 20px; - padding: 0; -} - -.field-list ul { - padding-left: 1em; -} - -.first { - margin-top: 0 !important; -} - -/* "Footnotes" heading */ -p.rubric { - margin-top: 30px; - font-weight: bold; -} - -/* Sidebars */ - -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} - -p.sidebar-title { - font-weight: bold; +div.admonition p.admonition-title + p { + display: inline; } -/* "Topics" */ - -div.topic { +div.note { background-color: #eee; border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; -} - -p.topic-title { - font-size: 1.1em; - font-weight: bold; - margin-top: 10px; -} - -/* Admonitions */ - -div.admonition { - margin-top: 10px; - margin-bottom: 10px; - padding: 7px; -} - -div.admonition dt { - font-weight: bold; -} - -div.admonition dl { - margin-bottom: 0; -} - -div.admonition p.admonition-title + p { - display: inline; } div.seealso { @@ -432,19 +163,16 @@ div.seealso { border: 1px solid #ff6; } +div.topic { + background-color: #eee; +} + div.warning { background-color: #ffe4e4; border: 1px solid #f66; } -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - p.admonition-title { - margin: 0px 10px 5px 0px; - font-weight: bold; display: inline; } @@ -452,78 +180,6 @@ p.admonition-title:after { content: ":"; } -div.body p.centered { - text-align: center; - margin-top: 25px; -} - -table.docutils { - border: 0; -} - -table.docutils td, table.docutils th { - padding: 1px 8px 1px 0; - border-top: 0; - border-left: 0; - border-right: 0; - border-bottom: 1px solid #aaa; -} - -table.field-list td, table.field-list th { - border: 0 !important; -} - -table.footnote td, table.footnote th { - border: 0 !important; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -dl { - margin-bottom: 15px; - clear: both; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -.refcount { - color: #060; -} - -dt:target, -.highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -th { - text-align: left; - padding-right: 5px; -} - pre { padding: 5px; background-color: #efc; @@ -531,22 +187,6 @@ pre { border: 1px solid #ac9; border-left: none; border-right: none; - overflow: auto; -} - -td.linenos pre { - padding: 5px 0px; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; } tt { @@ -554,104 +194,3 @@ tt { padding: 0 1px 0 1px; font-size: 0.95em; } - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; -} - -tt.descclassname { - background-color: transparent; -} - -tt.xref, a tt { - background-color: transparent; - font-weight: bold; -} - -.footnote:target { background-color: #ffa } - -h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { - background-color: transparent; -} - -.optional { - font-size: 1.3em; -} - -.versionmodified { - font-style: italic; -} - -form.comment { - margin: 0; - padding: 10px 30px 10px 30px; - background-color: #eee; -} - -form.comment h3 { - background-color: #326591; - color: white; - margin: -10px -30px 10px -30px; - padding: 5px; - font-size: 1.4em; -} - -form.comment input, -form.comment textarea { - border: 1px solid #ccc; - padding: 2px; - font-family: sans-serif; - font-size: 100%; -} - -form.comment input[type="text"] { - width: 240px; -} - -form.comment textarea { - width: 100%; - height: 200px; - margin-bottom: 10px; -} - -.system-message { - background-color: #fda; - padding: 5px; - border: 3px solid red; -} - -img.math { - vertical-align: middle; -} - -div.math p { - text-align: center; -} - -span.eqno { - float: right; -} - -img.logo { - border: 0; -} - -/* :::: PRINT :::: */ -@media print { - div.document, - div.documentwrapper, - div.bodywrapper { - margin: 0; - width : 100%; - } - - div.sphinxsidebar, - div.related, - div.footer, - div#comments div.new-comment-box, - #top-link { - display: none; - } -} diff --git a/sphinx/themes/sphinxdoc/layout.html b/sphinx/themes/sphinxdoc/layout.html new file mode 100644 index 00000000..48d2118e --- /dev/null +++ b/sphinx/themes/sphinxdoc/layout.html @@ -0,0 +1,5 @@ +{% extends "basic/layout.html" %} + +{# put the sidebar before the body #} +{% block sidebar1 %}{{ sidebar() }}{% endblock %} +{% block sidebar2 %}{% endblock %} diff --git a/sphinx/themes/sphinxdoc/static/sphinxdoc.css b/sphinx/themes/sphinxdoc/static/sphinxdoc.css index 999bf48c..df8c4e02 100644 --- a/sphinx/themes/sphinxdoc/static/sphinxdoc.css +++ b/sphinx/themes/sphinxdoc/static/sphinxdoc.css @@ -1,15 +1,21 @@ /** - * Alternate Sphinx design + * Sphinx stylesheet -- sphinxdoc theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + * * Originally created by Armin Ronacher for Werkzeug, adapted by Georg Brandl. */ +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + body { - font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', 'Verdana', sans-serif; + font-family: 'Lucida Grande', 'Lucida Sans Unicode', 'Geneva', + 'Verdana', sans-serif; font-size: 14px; letter-spacing: -0.01em; line-height: 150%; text-align: center; - /*background-color: #AFC1C4; */ background-color: #BFD1D4; color: black; padding: 0; @@ -19,137 +25,8 @@ body { min-width: 740px; } -a { - color: #CA7900; - text-decoration: none; -} - -a:hover { - color: #2491CF; -} - -pre { - font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.015em; - padding: 0.5em; - border: 1px solid #ccc; - background-color: #f8f8f8; -} - -td.linenos pre { - padding: 0.5em 0; - border: 0; - background-color: transparent; - color: #aaa; -} - -table.highlighttable { - margin-left: 0.5em; -} - -table.highlighttable td { - padding: 0 0.5em 0 0.5em; -} - -cite, code, tt { - font-family: 'Consolas', 'Deja Vu Sans Mono', 'Bitstream Vera Sans Mono', monospace; - font-size: 0.95em; - letter-spacing: 0.01em; -} - -hr { - border: 1px solid #abc; - margin: 2em; -} - -tt { - background-color: #f2f2f2; - border-bottom: 1px solid #ddd; - color: #333; -} - -tt.descname { - background-color: transparent; - font-weight: bold; - font-size: 1.2em; - border: 0; -} - -tt.descclassname { - background-color: transparent; - border: 0; -} - -tt.xref { - background-color: transparent; - font-weight: bold; - border: 0; -} - -a tt { - background-color: transparent; - font-weight: bold; - border: 0; - color: #CA7900; -} - -a tt:hover { - color: #2491CF; -} - -.field-list ul { - margin: 0; - padding-left: 1em; -} - -.field-list p { - margin: 0; -} - -dl { - margin-bottom: 15px; -} - -dd p { - margin-top: 0px; -} - -dd ul, dd table { - margin-bottom: 10px; -} - -dd { - margin-top: 3px; - margin-bottom: 10px; - margin-left: 30px; -} - -.refcount { - color: #060; -} - -dt:target, -.highlight { - background-color: #fbe54e; -} - -dl.glossary dt { - font-weight: bold; - font-size: 1.1em; -} - -pre { - line-height: 120%; -} - -pre a { - color: inherit; - text-decoration: underline; -} - -.first { - margin-top: 0 !important; +div.documentwrapper { + float: none; } div.document { @@ -159,28 +36,21 @@ div.document { background-repeat: repeat-x; } -/* -div.documentwrapper { - width: 100%; -} -*/ - -div.clearer { - clear: both; +div.bodywrapper { + margin: 0 240px 0 0; + border-right: 1px solid #ccc; } -div.related h3 { - display: none; +div.body { + margin: 0; + padding: 0.5em 20px 20px 20px; } div.related ul { background-image: url(navigation.png); height: 2em; - list-style: none; border-top: 1px solid #ddd; border-bottom: 1px solid #ddd; - margin: 0; - padding-left: 10px; } div.related ul li { @@ -206,18 +76,8 @@ div.related ul li a:hover { color: #3CA8E7; } -div.body { - margin: 0; - padding: 0.5em 20px 20px 20px; -} - -div.bodywrapper { - margin: 0 240px 0 0; - border-right: 1px solid #ccc; -} - -div.body a { - text-decoration: underline; +div.sphinxsidebarwrapper { + padding: 0; } div.sphinxsidebar { @@ -226,12 +86,11 @@ div.sphinxsidebar { width: 210px; float: right; text-align: left; -/* margin-left: -100%; */ } -div.sphinxsidebar h4, div.sphinxsidebar h3 { +div.sphinxsidebar h3, div.sphinxsidebar h4 { margin: 1em 0 0.5em 0; - font-size: 0.9em; + font-size: 1em; padding: 0.1em 0 0.1em 0.5em; color: white; border: 1px solid #86989B; @@ -245,55 +104,45 @@ div.sphinxsidebar h3 a { div.sphinxsidebar ul { padding-left: 1.5em; margin-top: 7px; - list-style: none; padding: 0; line-height: 130%; } div.sphinxsidebar ul ul { - list-style: square; margin-left: 20px; } -p { - margin: 0.8em 0 0.5em 0; +div.footer { + background-color: #E3EFF1; + color: #86989B; + padding: 3px 8px 3px 0; + clear: both; + font-size: 0.8em; + text-align: right; } -p.rubric { - font-weight: bold; +div.footer a { + color: #86989B; + text-decoration: underline; } -div.sidebar { - margin: 0 0 0.5em 1em; - border: 1px solid #ddb; - padding: 7px 7px 0 7px; - background-color: #ffe; - width: 40%; - float: right; -} +/* -- body styles ----------------------------------------------------------- */ -div.quotebar { - background-color: #f8f8f8; - max-width: 250px; - float: right; - padding: 2px 7px; - border: 1px solid #ccc; +p { + margin: 0.8em 0 0.5em 0; } -p.sidebar-title { - font-weight: bold; +a { + color: #CA7900; + text-decoration: none; } -div.topic { - background-color: #f8f8f8; - border: 1px solid #ccc; - padding: 7px 7px 0 7px; - margin: 10px 0 10px 0; +a:hover { + color: #2491CF; } -p.topic-title { - font-size: 1.1em; - font-weight: bold; +div.body a { + text-decoration: underline; } h1 { @@ -336,67 +185,97 @@ h5 a.anchor:hover, h6 a.anchor:hover { background-color: #eee; } -table { - border-collapse: collapse; - margin: 0 -0.5em 0 -0.5em; +a.headerlink { + color: #c60f0f!important; + font-size: 1em; + margin-left: 6px; + padding: 0 4px 0 4px; + text-decoration: none!important; } -table td, table th { - padding: 0.2em 0.5em 0.2em 0.5em; +a.headerlink:hover { + background-color: #ccc; + color: white!important; } -div.footer { - background-color: #E3EFF1; - color: #86989B; - padding: 3px 8px 3px 0; - clear: both; - font-size: 0.8em; - text-align: right; +cite, code, tt { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.01em; } -div.footer a { - color: #86989B; - text-decoration: underline; +tt { + background-color: #f2f2f2; + border-bottom: 1px solid #ddd; + color: #333; } -div.pagination { - margin-top: 2em; - padding-top: 0.5em; - border-top: 1px solid black; - text-align: center; +tt.descname, tt.descclassname, tt.xref { + border: 0; } -div.sphinxsidebar ul.toc { - margin: 1em 0 1em 0; - padding: 0 0 0 0.5em; - list-style: none; +hr { + border: 1px solid #abc; + margin: 2em; } -div.sphinxsidebar ul.toc li { - margin: 0.5em 0 0.5em 0; - font-size: 0.9em; - line-height: 130%; +a tt { + border: 0; + color: #CA7900; } -div.sphinxsidebar ul.toc li p { - margin: 0; - padding: 0; +a tt:hover { + color: #2491CF; } -div.sphinxsidebar ul.toc ul { - margin: 0.2em 0 0.2em 0; - padding: 0 0 0 1.8em; +pre { + font-family: 'Consolas', 'Deja Vu Sans Mono', + 'Bitstream Vera Sans Mono', monospace; + font-size: 0.95em; + letter-spacing: 0.015em; + line-height: 120%; + padding: 0.5em; + border: 1px solid #ccc; + background-color: #f8f8f8; } -div.sphinxsidebar ul.toc ul li { - padding: 0; +pre a { + color: inherit; + text-decoration: underline; +} + +td.linenos pre { + padding: 0.5em 0; +} + +div.quotebar { + background-color: #f8f8f8; + max-width: 250px; + float: right; + padding: 2px 7px; + border: 1px solid #ccc; +} + +div.topic { + background-color: #f8f8f8; +} + +table { + border-collapse: collapse; + margin: 0 -0.5em 0 -0.5em; +} + +table td, table th { + padding: 0.2em 0.5em 0.2em 0.5em; } div.admonition, div.warning { font-size: 0.9em; - margin: 1em 0 0 0; + margin: 1em 0 1em 0; border: 1px solid #86989B; background-color: #f7f7f7; + padding: 0; } div.admonition p, div.warning p { @@ -441,117 +320,3 @@ div.versioninfo { line-height: 1.3em; font-size: 0.9em; } - - -a.headerlink { - color: #c60f0f!important; - font-size: 1em; - margin-left: 6px; - padding: 0 4px 0 4px; - text-decoration: none!important; - visibility: hidden; -} - -h1:hover > a.headerlink, -h2:hover > a.headerlink, -h3:hover > a.headerlink, -h4:hover > a.headerlink, -h5:hover > a.headerlink, -h6:hover > a.headerlink, -dt:hover > a.headerlink { - visibility: visible; -} - -a.headerlink:hover { - background-color: #ccc; - color: white!important; -} - -table.indextable td { - text-align: left; - vertical-align: top; -} - -table.indextable dl, table.indextable dd { - margin-top: 0; - margin-bottom: 0; -} - -table.indextable tr.pcap { - height: 10px; -} - -table.indextable tr.cap { - margin-top: 10px; - background-color: #f2f2f2; -} - -img.toggler { - margin-right: 3px; - margin-top: 3px; - cursor: pointer; -} - -form.pfform { - margin: 10px 0 20px 0; -} - -table.contentstable { - width: 90%; -} - -table.contentstable p.biglink { - line-height: 150%; -} - -a.biglink { - font-size: 1.3em; -} - -span.linkdescr { - font-style: italic; - padding-top: 5px; - font-size: 90%; -} - -ul.search { - margin: 10px 0 0 20px; - padding: 0; -} - -ul.search li { - padding: 5px 0 5px 20px; - background-image: url(file.png); - background-repeat: no-repeat; - background-position: 0 7px; -} - -ul.search li a { - font-weight: bold; -} - -ul.search li div.context { - color: #888; - margin: 2px 0 0 30px; - text-align: left; -} - -ul.keywordmatches li.goodmatch a { - font-weight: bold; -} - -img.math { - vertical-align: center; -} - -div.math { - text-align: center; -} - -span.eqno { - float: right; -} - -img.logo { - border: 0; -} -- cgit v1.2.1 From ac92e5497ec6704b661ca3e7539ce2799fda2ef4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 10 Jan 2009 21:23:39 +0100 Subject: Reformat to EOL80. --- sphinx/application.py | 31 +++++--- sphinx/builders/__init__.py | 47 ++++++----- sphinx/builders/changes.py | 14 +++- sphinx/builders/html.py | 83 ++++++++++++------- sphinx/builders/htmlhelp.py | 22 +++--- sphinx/builders/latex.py | 14 ++-- sphinx/builders/linkcheck.py | 3 +- sphinx/builders/qthelp.py | 6 +- sphinx/builders/text.py | 5 +- sphinx/cmdline.py | 28 ++++--- sphinx/config.py | 3 +- sphinx/directives/code.py | 32 ++++---- sphinx/directives/desc.py | 30 ++++--- sphinx/directives/other.py | 36 +++++---- sphinx/environment.py | 171 ++++++++++++++++++++++++---------------- sphinx/ext/autodoc.py | 112 +++++++++++++++----------- sphinx/ext/coverage.py | 28 ++++--- sphinx/ext/doctest.py | 9 ++- sphinx/ext/ifconfig.py | 4 +- sphinx/ext/jsmath.py | 3 +- sphinx/ext/pngmath.py | 23 +++--- sphinx/ext/refcounting.py | 6 +- sphinx/ext/todo.py | 4 +- sphinx/highlighting.py | 3 +- sphinx/pycode/__init__.py | 14 ++-- sphinx/pycode/nodes.py | 6 +- sphinx/quickstart.py | 54 ++++++------- sphinx/roles.py | 33 +++++--- sphinx/setup_command.py | 3 +- sphinx/themes/basic/layout.html | 6 +- sphinx/util/smartypants.py | 9 ++- sphinx/util/stemmer.py | 15 ++-- sphinx/writers/html.py | 21 +++-- sphinx/writers/latex.py | 40 ++++++---- sphinx/writers/text.py | 3 +- utils/check_sources.py | 2 +- 36 files changed, 554 insertions(+), 369 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 1ad7823f..76118804 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -22,7 +22,8 @@ import sphinx from sphinx.roles import xfileref_role, innernodetypes from sphinx.config import Config from sphinx.builders import BUILTIN_BUILDERS -from sphinx.directives import desc_directive, target_directive, additional_xref_types +from sphinx.directives import desc_directive, target_directive, \ + additional_xref_types from sphinx.environment import SphinxStandaloneReader from sphinx.util.console import bold @@ -152,7 +153,8 @@ class Sphinx(object): self._warning.write('WARNING: %s\n' % message) except UnicodeEncodeError: encoding = getattr(self._warning, 'encoding', 'ascii') - self._warning.write(('WARNING: %s\n' % message).encode(encoding, 'replace')) + self._warning.write(('WARNING: %s\n' % message).encode(encoding, + 'replace')) def info(self, message='', nonl=False): try: @@ -171,7 +173,8 @@ class Sphinx(object): try: mod = __import__(extension, None, None, ['setup']) except ImportError, err: - raise ExtensionError('Could not import extension %s' % extension, err) + raise ExtensionError('Could not import extension %s' % extension, + err) if hasattr(mod, 'setup'): mod.setup(self) @@ -181,15 +184,18 @@ class Sphinx(object): module, name = objname.rsplit('.', 1) except ValueError, err: raise ExtensionError('Invalid full object name %s' % objname + - (source and ' (needed for %s)' % source or ''), err) + (source and ' (needed for %s)' % source or ''), + err) try: return getattr(__import__(module, None, None, [name]), name) except ImportError, err: raise ExtensionError('Could not import %s' % module + - (source and ' (needed for %s)' % source or ''), err) + (source and ' (needed for %s)' % source or ''), + err) except AttributeError, err: raise ExtensionError('Could not find %s' % objname + - (source and ' (needed for %s)' % source or ''), err) + (source and ' (needed for %s)' % source or ''), + err) # event interface @@ -229,13 +235,15 @@ class Sphinx(object): def add_builder(self, builder): if not hasattr(builder, 'name'): - raise ExtensionError('Builder class %s has no "name" attribute' % builder) + raise ExtensionError('Builder class %s has no "name" attribute' + % builder) if builder.name in self.builderclasses: if isinstance(self.builderclasses[builder.name], tuple): raise ExtensionError('Builder %r is a builtin builder' % builder.name) else: - raise ExtensionError('Builder %r already exists (in module %s)' % ( + raise ExtensionError( + 'Builder %r already exists (in module %s)' % ( builder.name, self.builderclasses[builder.name].__module__)) self.builderclasses[builder.name] = builder @@ -255,8 +263,8 @@ class Sphinx(object): try: visit, depart = val except ValueError: - raise ExtensionError('Value for key %r must be a (visit, depart) ' - 'function tuple' % key) + raise ExtensionError('Value for key %r must be a ' + '(visit, depart) function tuple' % key) if key == 'html': from sphinx.writers.html import HTMLTranslator as translator elif key == 'latex': @@ -281,7 +289,8 @@ class Sphinx(object): def add_description_unit(self, directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None): - additional_xref_types[directivename] = (rolename, indextemplate, parse_node) + additional_xref_types[directivename] = (rolename, indextemplate, + parse_node) directives.register_directive(directivename, desc_directive) roles.register_canonical_role(rolename, xfileref_role) if ref_nodeclass is not None: diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 5179cba0..ee13947e 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -97,20 +97,20 @@ class Builder(object): def get_relative_uri(self, from_, to, typ=None): """ - Return a relative URI between two source filenames. May raise environment.NoUri - if there's no way to return a sensible URI. + Return a relative URI between two source filenames. May raise + environment.NoUri if there's no way to return a sensible URI. """ return relative_uri(self.get_target_uri(from_), self.get_target_uri(to, typ)) def get_outdated_docs(self): """ - Return an iterable of output files that are outdated, or a string describing - what an update build will build. + Return an iterable of output files that are outdated, or a string + describing what an update build will build. - If the builder does not output individual files corresponding to source files, - return a string here. If it does, return an iterable of those files that need - to be written. + If the builder does not output individual files corresponding to + source files, return a string here. If it does, return an iterable + of those files that need to be written. """ raise NotImplementedError @@ -142,7 +142,8 @@ class Builder(object): break else: self.warn('%s:%s: no matching candidate for image URI %r' % - (node.source, getattr(node, 'lineno', ''), node['uri'])) + (node.source, getattr(node, 'lineno', ''), + node['uri'])) continue node['uri'] = candidate else: @@ -161,10 +162,10 @@ class Builder(object): """ self.translator = None if self.config.language is not None: - self.info(bold('loading translations [%s]... ' % self.config.language), - nonl=True) + self.info(bold('loading translations [%s]... ' % + self.config.language), nonl=True) locale_dirs = [path.join(package_dir, 'locale')] + \ - [path.join(self.srcdir, x) for x in self.config.locale_dirs] + [path.join(self.srcdir, x) for x in self.config.locale_dirs] for dir_ in locale_dirs: try: trans = gettext.translation('sphinx', localedir=dir_, @@ -200,10 +201,12 @@ class Builder(object): self.info('not found') else: self.info('failed: %s' % err) - self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) + self.env = BuildEnvironment(self.srcdir, self.doctreedir, + self.config) self.env.find_files(self.config) else: - self.env = BuildEnvironment(self.srcdir, self.doctreedir, self.config) + self.env = BuildEnvironment(self.srcdir, self.doctreedir, + self.config) self.env.find_files(self.config) self.env.set_warnfunc(self.warn) @@ -241,7 +244,8 @@ class Builder(object): def build(self, docnames, summary=None, method='update'): """ - Main build method. First updates the environment, and then calls :meth:`write`. + Main build method. First updates the environment, and then + calls :meth:`write`. """ if summary: self.info(bold('building [%s]: ' % self.name), nonl=1) @@ -252,12 +256,15 @@ class Builder(object): warnings = [] self.env.set_warnfunc(warnings.append) self.info(bold('updating environment: '), nonl=1) - iterator = self.env.update(self.config, self.srcdir, self.doctreedir, self.app) + iterator = self.env.update(self.config, self.srcdir, + self.doctreedir, self.app) # the first item in the iterator is a summary message self.info(iterator.next()) - for docname in self.status_iterator(iterator, 'reading sources... ', purple): + for docname in self.status_iterator(iterator, 'reading sources... ', + purple): updated_docnames.append(docname) - # nothing further to do, the environment has already done the reading + # nothing further to do, the environment has already + # done the reading for warning in warnings: if warning.strip(): self.warn(warning) @@ -278,12 +285,14 @@ class Builder(object): self.info(bold('no targets are out of date.')) return - # another indirection to support builders that don't build files individually + # another indirection to support builders that don't build + # files individually self.write(docnames, updated_docnames, method) # finish (write static files etc.) self.finish() - status = self.app.statuscode == 0 and 'succeeded' or 'finished with problems' + status = (self.app.statuscode == 0 and 'succeeded' + or 'finished with problems') if self.app._warncount: self.info(bold('build %s, %s warning%s.' % (status, self.app._warncount, diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py index 8770d49b..6f057b49 100644 --- a/sphinx/builders/changes.py +++ b/sphinx/builders/changes.py @@ -55,7 +55,8 @@ class ChangesBuilder(Builder): if not descname: continue if context: - entry = '%s: %s: %s' % (descname, ttext, context) + entry = '%s: %s: %s' % (descname, ttext, + context) else: entry = '%s: %s.' % (descname, ttext) apichanges.append((entry, docname, lineno)) @@ -65,10 +66,12 @@ class ChangesBuilder(Builder): if not descname: descname = _('Module level') if context: - entry = '%s: %s: %s' % (descname, ttext, context) + entry = '%s: %s: %s' % (descname, ttext, + context) else: entry = '%s: %s.' % (descname, ttext) - libchanges.setdefault(module, []).append((entry, docname, lineno)) + libchanges.setdefault(module, []).append((entry, docname, + lineno)) else: if not context: continue @@ -119,7 +122,10 @@ class ChangesBuilder(Builder): f = codecs.open(targetfn, 'w', 'latin1') try: text = ''.join(hl(i+1, line) for (i, line) in enumerate(lines)) - ctx = {'filename': self.env.doc2path(docname, None), 'text': text} + ctx = { + 'filename': self.env.doc2path(docname, None), + 'text': text + } f.write(self.templates.render('changes/rstsource.html', ctx)) finally: f.close() diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index bfbe299a..6d9a2ba8 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -27,7 +27,8 @@ from sphinx.search import js_index from sphinx.builders import Builder, ENV_PICKLE_FILENAME from sphinx.highlighting import PygmentsBridge from sphinx.util.console import bold -from sphinx.writers.html import HTMLWriter, HTMLTranslator, SmartyPantsHTMLTranslator +from sphinx.writers.html import HTMLWriter, HTMLTranslator, \ + SmartyPantsHTMLTranslator try: import json @@ -88,7 +89,8 @@ class StandaloneHTMLBuilder(Builder): def init_translator_class(self): if self.config.html_translator_class: self.translator_class = self.app.import_object( - self.config.html_translator_class, 'html_translator_class setting') + self.config.html_translator_class, + 'html_translator_class setting') elif self.config.html_use_smartypants: self.translator_class = SmartyPantsHTMLTranslator else: @@ -141,7 +143,8 @@ class StandaloneHTMLBuilder(Builder): if self.config.html_use_index: rellinks.append(('genindex', _('General Index'), 'I', _('index'))) if self.config.html_use_modindex and self.env.modules: - rellinks.append(('modindex', _('Global Module Index'), 'M', _('modules'))) + rellinks.append(('modindex', _('Global Module Index'), + 'M', _('modules'))) if self.config.html_style is not None: stylename = self.config.html_style @@ -184,18 +187,23 @@ class StandaloneHTMLBuilder(Builder): titles = self.env.titles if related and related[2]: try: - next = {'link': self.get_relative_uri(docname, related[2]), - 'title': self.render_partial(titles[related[2]])['title']} + next = { + 'link': self.get_relative_uri(docname, related[2]), + 'title': self.render_partial(titles[related[2]])['title'] + } rellinks.append((related[2], next['title'], 'N', _('next'))) except KeyError: next = None if related and related[1]: try: - prev = {'link': self.get_relative_uri(docname, related[1]), - 'title': self.render_partial(titles[related[1]])['title']} + prev = { + 'link': self.get_relative_uri(docname, related[1]), + 'title': self.render_partial(titles[related[1]])['title'] + } rellinks.append((related[1], prev['title'], 'P', _('previous'))) except KeyError: - # the relation is (somehow) not in the TOC tree, handle that gracefully + # the relation is (somehow) not in the TOC tree, handle + # that gracefully prev = None while related and related[0]: try: @@ -219,6 +227,9 @@ class StandaloneHTMLBuilder(Builder): # metadata for the document meta = self.env.metadata.get(docname) + # TOC + toc = self.render_partial(self.env.get_toc_for(docname))['fragment'] + return dict( parents = parents, prev = prev, @@ -229,7 +240,7 @@ class StandaloneHTMLBuilder(Builder): metatags = metatags, rellinks = rellinks, sourcename = sourcename, - toc = self.render_partial(self.env.get_toc_for(docname))['fragment'], + toc = toc, # only display a TOC if there's more than one item to show display_toc = (self.env.toc_num_entries[docname] > 1), ) @@ -272,12 +283,15 @@ class StandaloneHTMLBuilder(Builder): self.info(' genindex', nonl=1) if self.config.html_split_index: - self.handle_page('genindex', genindexcontext, 'genindex-split.html') - self.handle_page('genindex-all', genindexcontext, 'genindex.html') + self.handle_page('genindex', genindexcontext, + 'genindex-split.html') + self.handle_page('genindex-all', genindexcontext, + 'genindex.html') for (key, entries), count in zip(genindex, indexcounts): ctx = {'key': key, 'entries': entries, 'count': count, 'genindexentries': genindex} - self.handle_page('genindex-' + key, ctx, 'genindex-single.html') + self.handle_page('genindex-' + key, ctx, + 'genindex-single.html') else: self.handle_page('genindex', genindexcontext, 'genindex.html') @@ -318,11 +332,13 @@ class StandaloneHTMLBuilder(Builder): elif not pmn.startswith(tn): # submodule without parent in list, add dummy entry cg += 1 - modindexentries.append([tn, True, cg, False, '', '', [], False]) + modindexentries.append([tn, True, cg, + False, '', '', [], False]) else: num_toplevels += 1 cg += 1 - modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, dep]) + modindexentries.append([mn, False, cg, (tn != mn), + fn, sy, pl, dep]) pmn = mn fl = mn[0].lower() platforms = sorted(platforms) @@ -430,7 +446,8 @@ class StandaloneHTMLBuilder(Builder): if docname not in self.env.all_docs: yield docname continue - targetname = self.env.doc2path(docname, self.outdir, self.out_suffix) + targetname = self.env.doc2path(docname, self.outdir, + self.out_suffix) try: targetmtime = path.getmtime(targetname) except Exception: @@ -454,8 +471,9 @@ class StandaloneHTMLBuilder(Builder): f.close() except (IOError, OSError, ValueError): if keep: - self.warn("search index couldn't be loaded, but not all documents " - "will be built: the index will be incomplete.") + self.warn('search index couldn\'t be loaded, but not all ' + 'documents will be built: the index will be ' + 'incomplete.') # delete all entries for files that will be rebuilt self.indexer.prune(keep) @@ -485,12 +503,15 @@ class StandaloneHTMLBuilder(Builder): ctx['customsidebar'] = self.config.html_sidebars.get(pagename) ctx.update(addctx) - self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) + self.app.emit('html-page-context', pagename, templatename, + ctx, event_arg) output = self.templates.render(templatename, ctx) if not outfilename: - outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) - ensuredir(path.dirname(outfilename)) # normally different from self.outdir + outfilename = path.join(self.outdir, + os_path(pagename) + self.out_suffix) + # outfilename's path is in general different from self.outdir + ensuredir(path.dirname(outfilename)) try: f = codecs.open(outfilename, 'w', 'utf-8') try: @@ -501,7 +522,8 @@ class StandaloneHTMLBuilder(Builder): self.warn("Error writing file %s: %s" % (outfilename, err)) if self.copysource and ctx.get('sourcename'): # copy the source file for the "show source" link - source_name = path.join(self.outdir, '_sources', os_path(ctx['sourcename'])) + source_name = path.join(self.outdir, '_sources', + os_path(ctx['sourcename'])) ensuredir(path.dirname(source_name)) shutil.copyfile(self.env.doc2path(pagename), source_name) @@ -509,8 +531,8 @@ class StandaloneHTMLBuilder(Builder): self.info(bold('dumping search index... '), nonl=True) self.indexer.prune(self.env.all_docs) searchindexfn = path.join(self.outdir, self.searchindex_filename) - # first write to a temporary file, so that if dumping fails, the existing - # index won't be overwritten + # first write to a temporary file, so that if dumping fails, + # the existing index won't be overwritten f = open(searchindexfn + '.tmp', 'wb') try: self.indexer.dump(f, self.indexer_format) @@ -528,7 +550,8 @@ class StandaloneHTMLBuilder(Builder): for modname, info in self.env.modules.iteritems(): f.write('%s mod %s\n' % (modname, self.get_target_uri(info[0]))) for refname, (docname, desctype) in self.env.descrefs.iteritems(): - f.write('%s %s %s\n' % (refname, desctype, self.get_target_uri(docname))) + f.write('%s %s %s\n' % (refname, desctype, + self.get_target_uri(docname))) finally: f.close() self.info('done') @@ -568,9 +591,11 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): ctx['customsidebar'] = sidebarfile if not outfilename: - outfilename = path.join(self.outdir, os_path(pagename) + self.out_suffix) + outfilename = path.join(self.outdir, + os_path(pagename) + self.out_suffix) - self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) + self.app.emit('html-page-context', pagename, templatename, + ctx, event_arg) ensuredir(path.dirname(outfilename)) f = open(outfilename, 'wb') @@ -638,7 +663,7 @@ class JSONHTMLBuilder(SerializingHTMLBuilder): def init(self): if json is None: from sphinx.application import SphinxError - raise SphinxError('The module simplejson (or json in Python >= 2.6) ' - 'is not available. The JSONHTMLBuilder builder ' - 'will not work.') + raise SphinxError( + 'The module simplejson (or json in Python >= 2.6) ' + 'is not available. The JSONHTMLBuilder builder will not work.') SerializingHTMLBuilder.init(self) diff --git a/sphinx/builders/htmlhelp.py b/sphinx/builders/htmlhelp.py index 9baaa235..8d17f91b 100644 --- a/sphinx/builders/htmlhelp.py +++ b/sphinx/builders/htmlhelp.py @@ -122,8 +122,8 @@ was will with class HTMLHelpBuilder(StandaloneHTMLBuilder): """ - Builder that also outputs Windows HTML help project, contents and index files. - Adapted from the original Doc/tools/prechm.py. + Builder that also outputs Windows HTML help project, contents and + index files. Adapted from the original Doc/tools/prechm.py. """ name = 'htmlhelp' @@ -166,8 +166,10 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): for root, dirs, files in os.walk(outdir): staticdir = (root == path.join(outdir, '_static')) for fn in files: - if (staticdir and not fn.endswith('.js')) or fn.endswith('.html'): - print >>f, path.join(root, fn)[olen:].replace(os.sep, '\\') + if (staticdir and not fn.endswith('.js')) or \ + fn.endswith('.html'): + print >>f, path.join(root, fn)[olen:].replace(os.sep, + '\\') finally: f.close() @@ -182,8 +184,8 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): f.write('
    • ' + object_sitemap % (_('Global Module Index'), 'modindex.html')) # the TOC - tocdoc = self.env.get_and_resolve_doctree(self.config.master_doc, self, - prune_toctrees=False) + tocdoc = self.env.get_and_resolve_doctree( + self.config.master_doc, self, prune_toctrees=False) def write_toc(node, ullevel=0): if isinstance(node, nodes.list_item): f.write('
    • ') @@ -204,8 +206,9 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): elif isinstance(node, addnodes.compact_paragraph): for subnode in node: write_toc(subnode, ullevel) - istoctree = lambda node: isinstance(node, addnodes.compact_paragraph) and \ - node.has_key('toctree') + def istoctree(node): + return isinstance(node, addnodes.compact_paragraph) and \ + node.has_key('toctree') for node in tocdoc.traverse(istoctree): write_toc(node) f.write(contents_footer) @@ -230,7 +233,8 @@ class HTMLHelpBuilder(StandaloneHTMLBuilder): write_param('Local', refs[0]) else: for i, ref in enumerate(refs): - write_param('Name', '[%d] %s' % (i, ref)) # XXX: better title? + # XXX: better title? + write_param('Name', '[%d] %s' % (i, ref)) write_param('Local', ref) f.write('\n') if subitems: diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index 3b7b0c19..62da7491 100644 --- a/sphinx/builders/latex.py +++ b/sphinx/builders/latex.py @@ -116,12 +116,12 @@ class LaTeXBuilder(Builder): for includefile in includefiles: try: self.info(darkgreen(includefile) + " ", nonl=1) - subtree = process_tree(includefile, - self.env.get_doctree(includefile)) + subtree = process_tree( + includefile, self.env.get_doctree(includefile)) self.docnames.add(includefile) except Exception: - self.warn('%s: toctree contains ref to nonexisting file %r' % - (docname, includefile)) + self.warn('%s: toctree contains ref to nonexisting ' + 'file %r' % (docname, includefile)) else: sof = addnodes.start_of_file(docname=includefile) sof.children = subtree.children @@ -131,10 +131,12 @@ class LaTeXBuilder(Builder): tree = self.env.get_doctree(indexfile) tree['docname'] = indexfile if toctree_only: - # extract toctree nodes from the tree and put them in a fresh document + # extract toctree nodes from the tree and put them in a + # fresh document new_tree = new_document('') new_sect = nodes.section() - new_sect += nodes.title(u'', u'') + new_sect += nodes.title(u'', + u'') new_tree += new_sect for node in tree.traverse(addnodes.toctree): new_sect += node diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py index 5fcda231..b0fa9ba6 100644 --- a/sphinx/builders/linkcheck.py +++ b/sphinx/builders/linkcheck.py @@ -90,7 +90,8 @@ class CheckExternalLinksBuilder(Builder): self.warn('%s:%s: broken link: %s' % (docname, lineno, uri)) else: self.info(' - ' + purple('redirected') + ' to ' + s) - self.write_entry('redirected', docname, lineno, uri + ' to ' + s) + self.write_entry('redirected', docname, + lineno, uri + ' to ' + s) self.redirected[uri] = (r, s) elif len(uri) == 0 or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:': return diff --git a/sphinx/builders/qthelp.py b/sphinx/builders/qthelp.py index 855b340e..7c2af1ef 100644 --- a/sphinx/builders/qthelp.py +++ b/sphinx/builders/qthelp.py @@ -19,7 +19,8 @@ from docutils import nodes from sphinx import addnodes from sphinx.builders.html import StandaloneHTMLBuilder -_idpattern = re.compile('(?P.+) (\((?P<id>[\w\.]+)( (?P<descr>\w+))?\))$') +_idpattern = re.compile( + r'(?P<title>.+) (\((?P<id>[\w\.]+)( (?P<descr>\w+))?\))$') # Qt Help Collection Project (.qhcp). @@ -149,7 +150,8 @@ class QtHelpBuilder(StandaloneHTMLBuilder): for root, dirs, files in os.walk(outdir): staticdir = (root == path.join(outdir, '_static')) for fn in files: - if (staticdir and not fn.endswith('.js')) or fn.endswith('.html'): + if (staticdir and not fn.endswith('.js')) or \ + fn.endswith('.html'): filename = path.join(root, fn)[olen:] #filename = filename.replace(os.sep, '\\') # XXX projectfiles.append(file_template % {'filename': filename}) diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py index aaafedb4..d243e5c7 100644 --- a/sphinx/builders/text.py +++ b/sphinx/builders/text.py @@ -31,7 +31,8 @@ class TextBuilder(Builder): if docname not in self.env.all_docs: yield docname continue - targetname = self.env.doc2path(docname, self.outdir, self.out_suffix) + targetname = self.env.doc2path(docname, self.outdir, + self.out_suffix) try: targetmtime = path.getmtime(targetname) except Exception: @@ -54,7 +55,7 @@ class TextBuilder(Builder): destination = StringOutput(encoding='utf-8') self.writer.write(doctree, destination) outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix) - ensuredir(path.dirname(outfilename)) # normally different from self.outdir + ensuredir(path.dirname(outfilename)) try: f = codecs.open(outfilename, 'w', 'utf-8') try: diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 20767f0d..5b57a7c3 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -31,7 +31,8 @@ def usage(argv, msg=None): Sphinx v%s Usage: %s [options] sourcedir outdir [filenames...] Options: -b <builder> -- builder to use; default is html - -a -- write all files; default is to only write new and changed files + -a -- write all files; default is to only write \ +new and changed files -E -- don't use a saved environment, always read all files -d <path> -- path for the cached environment and doctree files (default: outdir/.doctrees) @@ -64,7 +65,8 @@ def main(argv): return 1 if not path.isfile(path.join(srcdir, 'conf.py')) and \ '-c' not in allopts and '-C' not in allopts: - print >>sys.stderr, 'Error: Source directory doesn\'t contain conf.py file.' + print >>sys.stderr, ('Error: Source directory doesn\'t ' + 'contain conf.py file.') return 1 outdir = path.abspath(args[1]) if not path.isdir(outdir): @@ -103,8 +105,8 @@ def main(argv): elif opt == '-c': confdir = path.abspath(val) if not path.isfile(path.join(confdir, 'conf.py')): - print >>sys.stderr, \ - 'Error: Configuration directory doesn\'t contain conf.py file.' + print >>sys.stderr, ('Error: Configuration directory ' + 'doesn\'t contain conf.py file.') return 1 elif opt == '-C': confdir = None @@ -112,8 +114,8 @@ def main(argv): try: key, val = val.split('=') except ValueError: - print >>sys.stderr, \ - 'Error: -D option argument must be in the form name=value.' + print >>sys.stderr, ('Error: -D option argument must be ' + 'in the form name=value.') return 1 try: val = int(val) @@ -124,8 +126,8 @@ def main(argv): try: key, val = val.split('=') except ValueError: - print >>sys.stderr, \ - 'Error: -A option argument must be in the form name=value.' + print >>sys.stderr, ('Error: -A option argument must be ' + 'in the form name=value.') return 1 try: val = int(val) @@ -153,7 +155,8 @@ def main(argv): except KeyboardInterrupt: if use_pdb: import pdb - print >>sys.stderr, darkred('Interrupted while building, starting debugger:') + print >>sys.stderr, darkred('Interrupted while building, ' + 'starting debugger:') traceback.print_exc() pdb.post_mortem(sys.exc_info()[2]) return 1 @@ -167,7 +170,8 @@ def main(argv): else: if isinstance(err, SystemMessage): print >>sys.stderr, darkred('reST markup error:') - print >>sys.stderr, err.args[0].encode('ascii', 'backslashreplace') + print >>sys.stderr, err.args[0].encode('ascii', + 'backslashreplace') elif isinstance(err, SphinxError): print >>sys.stderr, darkred('%s:' % err.category) print >>sys.stderr, err @@ -181,6 +185,6 @@ def main(argv): print >>sys.stderr, ('Please also report this if it was a user ' 'error, so that a better error message ' 'can be provided next time.') - print >>sys.stderr, ('Send reports to sphinx-dev@googlegroups.com. ' - 'Thanks!') + print >>sys.stderr, ('Send reports to ' + 'sphinx-dev@googlegroups.com. Thanks!') return 1 diff --git a/sphinx/config.py b/sphinx/config.py index 5942fcf8..5c3b7dfe 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -63,7 +63,8 @@ class Config(object): html_logo = (None, False), html_favicon = (None, False), html_static_path = ([], False), - html_last_updated_fmt = (None, False), # the real default is locale-dependent + # the real default is locale-dependent + html_last_updated_fmt = (None, False), html_use_smartypants = (True, False), html_translator_class = (None, False), html_sidebars = ({}, False), diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 74ac8e7f..da68cf2e 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -18,7 +18,7 @@ from sphinx import addnodes from sphinx.util import parselinenos -# ------ highlight directive -------------------------------------------------------- +# ------ highlight directive --------------------------------------------------- def highlightlang_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -36,10 +36,11 @@ highlightlang_directive.content = 0 highlightlang_directive.arguments = (1, 0, 0) highlightlang_directive.options = {'linenothreshold': directives.unchanged} directives.register_directive('highlight', highlightlang_directive) -directives.register_directive('highlightlang', highlightlang_directive) # old name +# old name +directives.register_directive('highlightlang', highlightlang_directive) -# ------ code-block directive ------------------------------------------------------- +# ------ code-block directive -------------------------------------------------- def codeblock_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -56,13 +57,15 @@ directives.register_directive('code-block', codeblock_directive) directives.register_directive('sourcecode', codeblock_directive) -# ------ literalinclude directive --------------------------------------------------- +# ------ literalinclude directive ---------------------------------------------- def literalinclude_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): - """Like .. include:: :literal:, but only warns if the include file is not found.""" + """Like .. include:: :literal:, but only warns if the include file is + not found.""" if not state.document.settings.file_insertion_enabled: - return [state.document.reporter.warning('File insertion disabled', line=lineno)] + return [state.document.reporter.warning('File insertion disabled', + line=lineno)] env = state.document.settings.env rel_fn = arguments[0] source_dir = path.dirname(path.abspath(state_machine.input_lines.source( @@ -133,14 +136,15 @@ def literalinclude_directive(name, arguments, options, content, lineno, state.document.settings.env.note_dependency(rel_fn) return [retnode] -literalinclude_directive.options = {'linenos': directives.flag, - 'language': directives.unchanged_required, - 'encoding': directives.encoding, - 'pyobject': directives.unchanged_required, - 'lines': directives.unchanged_required, - 'start-after': directives.unchanged_required, - 'end-before': directives.unchanged_required, - } +literalinclude_directive.options = { + 'linenos': directives.flag, + 'language': directives.unchanged_required, + 'encoding': directives.encoding, + 'pyobject': directives.unchanged_required, + 'lines': directives.unchanged_required, + 'start-after': directives.unchanged_required, + 'end-before': directives.unchanged_required, +} literalinclude_directive.content = 0 literalinclude_directive.arguments = (1, 0, 0) directives.register_directive('literalinclude', literalinclude_directive) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index 3ffe048b..05df4ffa 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -17,7 +17,7 @@ from sphinx import addnodes from sphinx.util import ws_re -# ------ information units --------------------------------------------------------- +# ------ information units ----------------------------------------------------- def desc_index_text(desctype, module, name, add_modules): if desctype == 'function': @@ -342,7 +342,8 @@ def parse_c_type(node, ctype): tnode = nodes.Text(part, part) if part[0] in string.ascii_letters+'_' and part not in stopwords: pnode = addnodes.pending_xref( - '', reftype='ctype', reftarget=part, modname=None, classname=None) + '', reftype='ctype', reftarget=part, + modname=None, classname=None) pnode += tnode node += pnode else: @@ -449,8 +450,10 @@ def desc_directive(desctype, arguments, options, content, lineno, if desctype in ('function', 'data', 'class', 'exception', 'method', 'staticmethod', 'classmethod', 'attribute'): - name, clsname = parse_py_signature(signode, sig, desctype, module, env) - elif desctype in ('cfunction', 'cmember', 'cmacro', 'ctype', 'cvar'): + name, clsname = parse_py_signature(signode, sig, + desctype, module, env) + elif desctype in ('cfunction', 'cmember', 'cmacro', + 'ctype', 'cvar'): name = parse_c_signature(signode, sig, desctype) elif desctype == 'cmdoption': optname = parse_option_desc(signode, sig) @@ -463,7 +466,8 @@ def desc_directive(desctype, arguments, options, content, lineno, state.document.note_explicit_target(signode) inode['entries'].append( ('pair', _('%scommand line option; %s') % - ((env.currprogram and env.currprogram + ' ' or ''), sig), + ((env.currprogram and env.currprogram + ' ' or ''), + sig), targetname, targetname)) env.note_progoption(optname, targetname) continue @@ -473,7 +477,8 @@ def desc_directive(desctype, arguments, options, content, lineno, continue else: # another registered generic x-ref directive - rolename, indextemplate, parse_node = additional_xref_types[desctype] + rolename, indextemplate, parse_node = \ + additional_xref_types[desctype] if parse_node: fullname = parse_node(env, sig, signode) else: @@ -502,8 +507,8 @@ def desc_directive(desctype, arguments, options, content, lineno, signode.clear() signode += addnodes.desc_name(sig, sig) continue # we don't want an index entry here - # only add target and index entry if this is the first description of the - # function name in this desc block + # only add target and index entry if this is the first description + # of the function name in this desc block if not noindex and name not in names: fullname = (module and module + '.' or '') + name # note target @@ -583,7 +588,7 @@ additional_xref_types = { del _ -# ------ target -------------------------------------------------------------------- +# ------ target ---------------------------------------------------------------- def target_directive(targettype, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -603,7 +608,8 @@ def target_directive(targettype, arguments, options, content, lineno, if colon != -1: indextype = indexentry[:colon].strip() indexentry = indexentry[colon+1:].strip() - inode = addnodes.index(entries=[(indextype, indexentry, targetname, targetname)]) + inode = addnodes.index(entries=[(indextype, indexentry, + targetname, targetname)]) ret.insert(0, inode) env.note_reftarget(rolename, fullname, targetname) return ret @@ -611,5 +617,5 @@ def target_directive(targettype, arguments, options, content, lineno, target_directive.content = 0 target_directive.arguments = (1, 0, 1) -# note, the target directive is not registered here, it is used by the application -# when registering additional xref types +# note, the target directive is not registered here, it is used by the +# application when registering additional xref types diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index cbf548be..18e18fd9 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -18,7 +18,7 @@ from sphinx.util import patfilter, ws_re, caption_ref_re, docname_join from sphinx.util.compat import make_admonition -# ------ the TOC tree --------------------------------------------------------------- +# ------ the TOC tree ---------------------------------------------------------- def toctree_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -50,7 +50,8 @@ def toctree_directive(name, arguments, options, content, lineno, docname = docname_join(env.docname, docname) if docname not in env.found_docs: ret.append(state.document.reporter.warning( - 'toctree references unknown document %r' % docname, line=lineno)) + 'toctree references unknown document %r' % docname, + line=lineno)) else: includefiles.append(docname) else: @@ -61,8 +62,8 @@ def toctree_directive(name, arguments, options, content, lineno, includefiles.append(docname) if not docnames: ret.append(state.document.reporter.warning( - 'toctree glob pattern %r didn\'t match any documents' % entry, - line=lineno)) + 'toctree glob pattern %r didn\'t match any documents' + % entry, line=lineno)) subnode = addnodes.toctree() subnode['includefiles'] = includefiles subnode['includetitles'] = includetitles @@ -78,7 +79,7 @@ toctree_directive.options = {'maxdepth': int, 'glob': directives.flag, directives.register_directive('toctree', toctree_directive) -# ------ section metadata ---------------------------------------------------------- +# ------ section metadata ------------------------------------------------------ def module_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -101,7 +102,8 @@ def module_directive(name, arguments, options, content, lineno, node += nodes.emphasis('', _('Platforms: ')) node += nodes.Text(options['platform'], options['platform']) ret.append(node) - # the synopsis isn't printed; in fact, it is only used in the modindex currently + # the synopsis isn't printed; in fact, it is only used in the + # modindex currently if not noindex: indextext = _('%s (module)') % modname inode = addnodes.index(entries=[('single', indextext, @@ -172,7 +174,7 @@ program_directive.arguments = (1, 0, 1) directives.register_directive('program', program_directive) -# ------ index markup -------------------------------------------------------------- +# ------ index markup ---------------------------------------------------------- indextypes = [ 'single', 'pair', 'triple', @@ -214,7 +216,7 @@ def index_directive(name, arguments, options, content, lineno, index_directive.arguments = (1, 0, 1) directives.register_directive('index', index_directive) -# ------ versionadded/versionchanged ----------------------------------------------- +# ------ versionadded/versionchanged ------------------------------------------- def version_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -241,7 +243,7 @@ directives.register_directive('versionadded', version_directive) directives.register_directive('versionchanged', version_directive) -# ------ see also ------------------------------------------------------------------ +# ------ see also -------------------------------------------------------------- def seealso_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -261,7 +263,7 @@ seealso_directive.arguments = (0, 1, 1) directives.register_directive('seealso', seealso_directive) -# ------ production list (for the reference) --------------------------------------- +# ------ production list (for the reference) ----------------------------------- token_re = re.compile('`([a-z_]+)`') @@ -317,7 +319,7 @@ productionlist_directive.arguments = (1, 0, 1) directives.register_directive('productionlist', productionlist_directive) -# ------ glossary directive --------------------------------------------------------- +# ------ glossary directive ---------------------------------------------------- def glossary_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -354,7 +356,7 @@ glossary_directive.arguments = (0, 0, 0) directives.register_directive('glossary', glossary_directive) -# ------ miscellaneous markup ------------------------------------------------------- +# ------ miscellaneous markup -------------------------------------------------- def centered_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -373,7 +375,8 @@ def acks_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): node = addnodes.acks() state.nested_parse(content, content_offset, node) - if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): + if len(node.children) != 1 or not isinstance(node.children[0], + nodes.bullet_list): return [state.document.reporter.warning('.. acks content is not a list', line=lineno)] return [node] @@ -388,9 +391,10 @@ def hlist_directive(name, arguments, options, content, lineno, ncolumns = options.get('columns', 2) node = nodes.paragraph() state.nested_parse(content, content_offset, node) - if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): - return [state.document.reporter.warning('.. hlist content is not a list', - line=lineno)] + if len(node.children) != 1 or not isinstance(node.children[0], + nodes.bullet_list): + return [state.document.reporter.warning( + '.. hlist content is not a list', line=lineno)] fulllist = node.children[0] # create a hlist node where the items are distributed npercol, nmore = divmod(len(fulllist), ncolumns) diff --git a/sphinx/environment.py b/sphinx/environment.py index fe4cba6b..d2804332 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -205,8 +205,8 @@ class BuildEnvironment: self.set_warnfunc(None) values = self.config.values del self.config.values - # first write to a temporary file, so that if dumping fails, the existing - # environment won't be overwritten + # first write to a temporary file, so that if dumping fails, + # the existing environment won't be overwritten picklefile = open(filename + '.tmp', 'wb') # remove potentially pickling-problematic values from config for key, val in vars(self.config).items(): @@ -244,13 +244,14 @@ class BuildEnvironment: # this is to invalidate old pickles self.version = ENV_VERSION - # All "docnames" here are /-separated and relative and exclude the source suffix. + # All "docnames" here are /-separated and relative and exclude + # the source suffix. self.found_docs = set() # contains all existing docnames self.all_docs = {} # docname -> mtime at the time of build # contains all built docnames - self.dependencies = {} # docname -> set of dependent file names, relative to - # documentation root + self.dependencies = {} # docname -> set of dependent file + # names, relative to documentation root # File metadata self.metadata = {} # docname -> dict of metadata items @@ -259,30 +260,34 @@ class BuildEnvironment: self.titles = {} # docname -> title node self.tocs = {} # docname -> table of contents nodetree self.toc_num_entries = {} # docname -> number of real entries - # used to determine when to show the TOC in a sidebar - # (don't show if it's only one item) + # used to determine when to show the TOC + # in a sidebar (don't show if it's only one item) + self.toctree_includes = {} # docname -> list of toctree includefiles - self.files_to_rebuild = {} # docname -> set of files (containing its TOCs) - # to rebuild too + self.files_to_rebuild = {} # docname -> set of files + # (containing its TOCs) to rebuild too self.glob_toctrees = set() # docnames that have :glob: toctrees # X-ref target inventory self.descrefs = {} # fullname -> docname, desctype self.filemodules = {} # docname -> [modules] - self.modules = {} # modname -> docname, synopsis, platform, deprecated + self.modules = {} # modname -> docname, synopsis, + # platform, deprecated self.labels = {} # labelname -> docname, labelid, sectionname self.anonlabels = {} # labelname -> docname, labelid self.progoptions = {} # (program, name) -> docname, labelid self.reftargets = {} # (type, name) -> docname, labelid - # where type is term, token, envvar, citation + # type: term, token, envvar, citation # Other inventories self.indexentries = {} # docname -> list of # (type, string, target, aliasname) - self.versionchanges = {} # version -> list of - # (type, docname, lineno, module, descname, content) - self.images = FilenameUniqDict() # absolute path -> (docnames, unique filename) - self.dlfiles = FilenameUniqDict() # absolute path -> (docnames, unique filename) + self.versionchanges = {} # version -> list of (type, docname, + # lineno, module, descname, content) + + # these map absolute path -> (docnames, unique filename) + self.images = FilenameUniqDict() + self.dlfiles = FilenameUniqDict() # These are set while parsing a file self.docname = None # current document name @@ -362,7 +367,8 @@ class BuildEnvironment: """ suffix = suffix or self.config.source_suffix if base is True: - return path.join(self.srcdir, docname.replace(SEP, path.sep)) + suffix + return path.join(self.srcdir, + docname.replace(SEP, path.sep)) + suffix elif base is None: return docname.replace(SEP, path.sep) + suffix else: @@ -375,8 +381,10 @@ class BuildEnvironment: exclude_dirs = [d.replace(SEP, path.sep) for d in config.exclude_dirs] exclude_trees = [d.replace(SEP, path.sep) for d in config.exclude_trees] self.found_docs = set(get_matching_docs( - self.srcdir, config.source_suffix, exclude_docs=set(config.unused_docs), - exclude_dirs=exclude_dirs, exclude_trees=exclude_trees, + self.srcdir, config.source_suffix, + exclude_docs=set(config.unused_docs), + exclude_dirs=exclude_dirs, + exclude_trees=exclude_trees, exclude_dirnames=['_sources'] + config.exclude_dirnames)) def get_outdated_files(self, config_changed): @@ -428,16 +436,17 @@ class BuildEnvironment: return added, changed, removed def update(self, config, srcdir, doctreedir, app=None): - """(Re-)read all files new or changed since last update. Yields a summary - and then docnames as it processes them. Store all environment docnames - in the canonical format (ie using SEP as a separator in place of - os.path.sep).""" + """(Re-)read all files new or changed since last update. + Yields a summary and then docnames as it processes them. + Store all environment docnames in the canonical format + (ie using SEP as a separator in place of os.path.sep).""" config_changed = False if self.config is None: msg = '[new config] ' config_changed = True else: - # check if a config value was changed that affects how doctrees are read + # check if a config value was changed that affects how + # doctrees are read for key, descr in config.config_values.iteritems(): if not descr[1]: continue @@ -577,7 +586,8 @@ class BuildEnvironment: if save_parsed: # save the parsed doctree - doctree_filename = self.doc2path(docname, self.doctreedir, '.doctree') + doctree_filename = self.doc2path(docname, self.doctreedir, + '.doctree') dirname = path.dirname(doctree_filename) if not path.isdir(dirname): os.makedirs(dirname) @@ -638,7 +648,8 @@ class BuildEnvironment: node['candidates'] = candidates = {} imguri = node['uri'] if imguri.find('://') != -1: - self.warn(docname, 'Nonlocal image URI found: %s' % imguri, node.line) + self.warn(docname, 'Nonlocal image URI found: %s' % imguri, + node.line) candidates['?'] = imguri continue # imgpath is the image path *from srcdir* @@ -660,7 +671,8 @@ class BuildEnvironment: finally: f.close() except (OSError, IOError): - self.warn(docname, 'Image file %s not readable' % filename) + self.warn(docname, + 'Image file %s not readable' % filename) if imgtype: candidates['image/' + imgtype] = new_imgpath else: @@ -725,7 +737,8 @@ class BuildEnvironment: continue if name in self.labels: self.warn(docname, 'duplicate label %s, ' % name + - 'other instance in %s' % self.doc2path(self.labels[name][0]), + 'other instance in ' + + self.doc2path(self.labels[name][0]), node.line) self.anonlabels[name] = docname, labelid if node.tagname == 'section': @@ -835,7 +848,8 @@ class BuildEnvironment: if fullname in self.descrefs: self.warn(self.docname, 'duplicate canonical description name %s, ' % fullname + - 'other instance in %s' % self.doc2path(self.descrefs[fullname][0]), + 'other instance in ' + + self.doc2path(self.descrefs[fullname][0]), line) self.descrefs[fullname] = (self.docname, desctype) @@ -851,7 +865,8 @@ class BuildEnvironment: def note_versionchange(self, type, version, node, lineno): self.versionchanges.setdefault(version, []).append( - (type, self.docname, lineno, self.currmodule, self.currdesc, node.astext())) + (type, self.docname, lineno, self.currmodule, self.currdesc, + node.astext())) def note_dependency(self, filename): basename = path.dirname(self.doc2path(self.docname, base=None)) @@ -915,7 +930,8 @@ class BuildEnvironment: def _walk_depth(node, depth, maxdepth, titleoverrides): """Utility: Cut a TOC at a specified depth.""" for subnode in node.children[:]: - if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)): + if isinstance(subnode, (addnodes.compact_paragraph, + nodes.list_item)): subnode['classes'].append('toctree-l%d' % (depth-1)) _walk_depth(subnode, depth, maxdepth, titleoverrides) elif isinstance(subnode, nodes.bullet_list): @@ -934,27 +950,30 @@ class BuildEnvironment: toc = self.tocs[includefile].deepcopy() if not toc.children: # empty toc means: no titles will show up in the toctree - self.warn(docname, 'toctree contains reference to document ' - '%r that doesn\'t have a title: no link will be ' - 'generated' % includefile) + self.warn(docname, + 'toctree contains reference to document ' + '%r that doesn\'t have a title: no link ' + 'will be generated' % includefile) except KeyError: # this is raised if the included file does not exist - self.warn(docname, 'toctree contains reference to nonexisting ' - 'document %r' % includefile) + self.warn(docname, 'toctree contains reference to ' + 'nonexisting document %r' % includefile) else: # if titles_only is given, only keep the main title and # sub-toctrees if titles_only: - # delete everything but the toplevel title(s) and toctrees + # delete everything but the toplevel title(s) + # and toctrees for toplevel in toc: # nodes with length 1 don't have any children anyway if len(toplevel) > 1: - subtoctrees = toplevel.traverse(addnodes.toctree) - toplevel[1][:] = subtoctrees + subtrees = toplevel.traverse(addnodes.toctree) + toplevel[1][:] = subtrees # resolve all sub-toctrees for toctreenode in toc.traverse(addnodes.toctree): i = toctreenode.parent.index(toctreenode) + 1 - for item in _entries_from_toctree(toctreenode, subtree=True): + for item in _entries_from_toctree(toctreenode, + subtree=True): toctreenode.parent.insert(i, item) i += 1 toctreenode.parent.remove(toctreenode) @@ -993,8 +1012,9 @@ class BuildEnvironment: refnode.children = [nodes.Text(newtitle)] return newnode - descroles = frozenset(('data', 'exc', 'func', 'class', 'const', 'attr', 'obj', - 'meth', 'cfunc', 'cmember', 'cdata', 'ctype', 'cmacro')) + descroles = frozenset(('data', 'exc', 'func', 'class', 'const', + 'attr', 'obj', 'meth', 'cfunc', 'cmember', + 'cdata', 'ctype', 'cmacro')) def resolve_references(self, doctree, fromdocname, builder): reftarget_roles = set(('token', 'term', 'citation')) @@ -1011,30 +1031,32 @@ class BuildEnvironment: try: if typ == 'ref': if node['refcaption']: - # reference to anonymous label; the reference uses the supplied - # link caption + # reference to anonymous label; the reference uses + # the supplied link caption docname, labelid = self.anonlabels.get(target, ('','')) sectname = node.astext() if not docname: newnode = doctree.reporter.system_message( 2, 'undefined label: %s' % target) else: - # reference to the named label; the final node will contain the - # section name after the label - docname, labelid, sectname = self.labels.get(target, ('','','')) + # reference to the named label; the final node will + # contain the section name after the label + docname, labelid, sectname = self.labels.get(target, + ('','','')) if not docname: newnode = doctree.reporter.system_message( - 2, 'undefined label: %s -- if you don\'t ' % target + - 'give a link caption the label must precede a section ' - 'header.') + 2, 'undefined label: %s' % target + + ' -- if you don\'t give a link caption ' + 'the label must precede a section header.') if docname: newnode = nodes.reference('', '') innernode = nodes.emphasis(sectname, sectname) if docname == fromdocname: newnode['refid'] = labelid else: - # set more info in contnode in case the get_relative_uri call - # raises NoUri, the builder will then have to resolve these + # set more info in contnode; in case the + # get_relative_uri call raises NoUri, + # the builder will then have to resolve these contnode = addnodes.pending_xref('') contnode['refdocname'] = docname contnode['refsectname'] = sectname @@ -1044,8 +1066,8 @@ class BuildEnvironment: newnode['refuri'] += '#' + labelid newnode.append(innernode) elif typ == 'doc': - # directly reference to document by source name; can be absolute - # or relative + # directly reference to document by source name; + # can be absolute or relative docname = docname_join(fromdocname, target) if docname not in self.all_docs: newnode = doctree.reporter.system_message( @@ -1077,7 +1099,8 @@ class BuildEnvironment: newnode.append(contnode) elif typ == 'option': progname = node['refprogram'] - docname, labelid = self.progoptions.get((progname, target), ('', '')) + docname, labelid = self.progoptions.get((progname, target), + ('', '')) if not docname: newnode = contnode else: @@ -1089,13 +1112,16 @@ class BuildEnvironment: fromdocname, docname) + '#' + labelid newnode.append(contnode) elif typ in reftarget_roles: - docname, labelid = self.reftargets.get((typ, target), ('', '')) + docname, labelid = self.reftargets.get((typ, target), + ('', '')) if not docname: if typ == 'term': - self.warn(fromdocname, 'term not in glossary: %s' % target, + self.warn(fromdocname, + 'term not in glossary: %s' % target, node.line) elif typ == 'citation': - self.warn(fromdocname, 'citation not found: %s' % target, + self.warn(fromdocname, + 'citation not found: %s' % target, node.line) newnode = contnode else: @@ -1110,8 +1136,8 @@ class BuildEnvironment: docname, synopsis, platform, deprecated = \ self.modules.get(target, ('','','', '')) if not docname: - newnode = builder.app.emit_firstresult('missing-reference', - self, node, contnode) + newnode = builder.app.emit_firstresult( + 'missing-reference', self, node, contnode) if not newnode: newnode = contnode elif docname == fromdocname: @@ -1133,8 +1159,8 @@ class BuildEnvironment: name, desc = self.find_desc(modname, clsname, target, typ, searchorder) if not desc: - newnode = builder.app.emit_firstresult('missing-reference', - self, node, contnode) + newnode = builder.app.emit_firstresult( + 'missing-reference', self, node, contnode) if not newnode: newnode = contnode else: @@ -1148,7 +1174,8 @@ class BuildEnvironment: newnode['reftitle'] = name newnode.append(contnode) else: - raise RuntimeError('unknown xfileref node encountered: %s' % node) + raise RuntimeError('unknown xfileref node encountered: %s' + % node) except NoUri: newnode = contnode if newnode: @@ -1232,8 +1259,10 @@ class BuildEnvironment: m = _fixre.match(key) if m: if oldkey == m.group(1): - # prefixes match: add entry as subitem of the previous entry - oldsubitems.setdefault(m.group(2), [[], {}])[0].extend(targets) + # prefixes match: add entry as subitem of the + # previous entry + oldsubitems.setdefault(m.group(2), [[], {}])[0].\ + extend(targets) del newlist[i] continue oldkey = m.group(1) @@ -1253,7 +1282,8 @@ class BuildEnvironment: else: # get all other symbols under one heading return 'Symbols' - return [(key, list(group)) for (key, group) in groupby(newlist, keyfunc)] + return [(key, list(group)) + for (key, group) in groupby(newlist, keyfunc)] def collect_relations(self): relations = {} @@ -1292,7 +1322,8 @@ class BuildEnvironment: # else it will stay None # same for children if includes: - for subindex, args in enumerate(izip(includes, [None] + includes, + for subindex, args in enumerate(izip(includes, + [None] + includes, includes[1:] + [None])): collect([(docname, subindex)] + parents, *args) relations[docname] = [parents[0][0], previous, next] @@ -1360,14 +1391,16 @@ class BuildEnvironment: def find_keyword(self, keyword, avoid_fuzzy=False, cutoff=0.6, n=20): """ - Find keyword matches for a keyword. If there's an exact match, just return - it, else return a list of fuzzy matches if avoid_fuzzy isn't True. + Find keyword matches for a keyword. If there's an exact match, + just return it, else return a list of fuzzy matches if avoid_fuzzy + isn't True. Keywords searched are: first modules, then descrefs. Returns: None if nothing found (type, docname, anchorname) if exact match found - list of (quality, type, docname, anchorname, description) if fuzzy + list of (quality, type, docname, anchorname, description) + if fuzzy """ if keyword in self.modules: diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index d0512f2b..c005e36a 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -54,7 +54,7 @@ def get_method_type(obj): (isinstance(obj, MethodType) and obj.im_self is not None): return 'classmethod' elif isinstance(obj, FunctionType) or \ - (isinstance(obj, BuiltinFunctionType) and obj.__self__ is not None): + (isinstance(obj, BuiltinFunctionType) and obj.__self__ is not None): return 'staticmethod' else: return 'method' @@ -193,7 +193,8 @@ class RstGenerator(object): docstrings.append(obj.__doc__) # skip some lines in module docstrings if configured (deprecated!) - if what == 'module' and self.env.config.automodule_skip_lines and docstrings: + if what == 'module' and self.env.config.automodule_skip_lines \ + and docstrings: docstrings[0] = '\n'.join(docstrings[0].splitlines() [self.env.config.automodule_skip_lines:]) @@ -212,7 +213,8 @@ class RstGenerator(object): docstrings.append(initdocstring) # the default is only the class docstring - # make sure we have Unicode docstrings, then sanitize and split into lines + # make sure we have Unicode docstrings, then sanitize and split + # into lines return [prepare_docstring(force_decode(docstring, encoding)) for docstring in docstrings] @@ -233,8 +235,9 @@ class RstGenerator(object): Returns a tuple of: the full name, the module name, a path of names to get via getattr, the signature and return annotation. """ - # first, parse the definition -- auto directives for classes and functions - # can contain a signature which is then used instead of an autogenerated one + # first, parse the definition -- auto directives for classes and + # functions can contain a signature which is then used instead of + # an autogenerated one try: mod, path, base, args, retann = py_ext_sig_re.match(name).groups() except: @@ -261,8 +264,8 @@ class RstGenerator(object): if path: mod = path.rstrip('.') else: - # if documenting a toplevel object without explicit module, it can - # be contained in another auto directive ... + # if documenting a toplevel object without explicit module, + # it can be contained in another auto directive ... if hasattr(self.env, 'autodoc_current_module'): mod = self.env.autodoc_current_module # ... or in the scope of a module directive @@ -276,8 +279,9 @@ class RstGenerator(object): mod_cls = path.rstrip('.') else: mod_cls = None - # if documenting a class-level object without path, there must be a - # current class, either from a parent auto directive ... + # if documenting a class-level object without path, + # there must be a current class, either from a parent + # auto directive ... if hasattr(self.env, 'autodoc_current_class'): mod_cls = self.env.autodoc_current_class # ... or from a class directive @@ -313,7 +317,8 @@ class RstGenerator(object): args = None getargs = True if what == 'class': - # for classes, the relevant signature is the __init__ method's + # for classes, the relevant signature is the + # __init__ method's obj = getattr(obj, '__init__', None) # classes without __init__ method, default __init__ or # __init__ written in C? @@ -334,8 +339,9 @@ class RstGenerator(object): args = None err = e - result = self.env.app.emit_firstresult('autodoc-process-signature', what, - name, obj, self.options, args, retann) + result = self.env.app.emit_firstresult( + 'autodoc-process-signature', what, name, obj, + self.options, args, retann) if result: args, retann = result @@ -347,22 +353,24 @@ class RstGenerator(object): else: return '' - def generate(self, what, name, members, add_content, indent=u'', check_module=False, - no_docstring=False): + def generate(self, what, name, members, add_content, indent=u'', + check_module=False, no_docstring=False): """ Generate reST for the object in self.result. """ mod, objpath, args, retann = self.resolve_name(what, name) if not mod: # need a module to import - self.warn('don\'t know which module to import for autodocumenting %r ' - '(try placing a "module" or "currentmodule" directive in the ' - 'document, or giving an explicit module name)' % name) + self.warn('don\'t know which module to import for autodocumenting ' + '%r (try placing a "module" or "currentmodule" directive ' + 'in the document, or giving an explicit module name)' + % name) return # fully-qualified name fullname = mod + (objpath and '.' + '.'.join(objpath) or '') - # the name to put into the generated directive -- doesn't contain the module + # the name to put into the generated directive -- doesn't contain + # the module name_in_directive = '.'.join(objpath) or mod # now, import the module and get object to document @@ -372,8 +380,8 @@ class RstGenerator(object): for part in objpath: todoc = getattr(todoc, part) except (ImportError, AttributeError), err: - self.warn('autodoc can\'t import/find %s %r, it reported error: "%s", ' - 'please check your spelling and sys.path' % + self.warn('autodoc can\'t import/find %s %r, it reported error: ' + '"%s", please check your spelling and sys.path' % (what, str(fullname), err)) return @@ -388,7 +396,7 @@ class RstGenerator(object): else: self.filename_set.add(analyzer.srcname) - # check __module__ of object if wanted (for members not given explicitly) + # check __module__ of object for members not given explicitly if check_module: if hasattr(todoc, '__module__'): if todoc.__module__ != mod: @@ -417,16 +425,16 @@ class RstGenerator(object): if what == 'module': # Add some module-specific options if self.options.synopsis: - self.result.append(indent + u' :synopsis: ' + self.options.synopsis, - '<autodoc>') + self.result.append(indent + u' :synopsis: ' + + self.options.synopsis, '<autodoc>') if self.options.platform: - self.result.append(indent + u' :platform: ' + self.options.platform, - '<autodoc>') + self.result.append(indent + u' :platform: ' + + self.options.platform, '<autodoc>') if self.options.deprecated: self.result.append(indent + u' :deprecated:', '<autodoc>') else: - # Be explicit about the module, this is necessary since .. class:: doesn't - # support a prepended module name + # Be explicit about the module, this is necessary since .. class:: + # doesn't support a prepended module name self.result.append(indent + u' :module: %s' % mod, '<autodoc>') if self.options.noindex: self.result.append(indent + u' :noindex:', '<autodoc>') @@ -439,7 +447,8 @@ class RstGenerator(object): u':class:`%s`' % b.__name__ or u':class:`%s.%s`' % (b.__module__, b.__name__) for b in todoc.__bases__] - self.result.append(indent + _(u' Bases: %s') % ', '.join(bases), + self.result.append(indent + _(u' Bases: %s') % + ', '.join(bases), '<autodoc>') self.result.append(u'', '<autodoc>') @@ -513,7 +522,8 @@ class RstGenerator(object): # base classes all_members = inspect.getmembers(todoc) else: - # __dict__ contains only the members directly defined in the class + # __dict__ contains only the members directly defined + # in the class all_members = sorted(todoc.__dict__.iteritems()) else: all_members = [(mname, getattr(todoc, mname)) for mname in members] @@ -524,7 +534,8 @@ class RstGenerator(object): for (membername, member) in all_members: # if isattr is True, the member is documented as an attribute isattr = False - # if content is not None, no extra content from docstrings will be added + # if content is not None, no extra content from docstrings + # will be added content = None if want_all_members and membername.startswith('_'): @@ -536,15 +547,18 @@ class RstGenerator(object): skip = False isattr = True else: - # ignore undocumented members if :undoc-members: is not given + # ignore undocumented members if :undoc-members: + # is not given doc = getattr(member, '__doc__', None) skip = not self.options.undoc_members and not doc - # give the user a chance to decide whether this member should be skipped + # give the user a chance to decide whether this member + # should be skipped if self.env.app: # let extensions preprocess docstrings skip_user = self.env.app.emit_firstresult( - 'autodoc-skip-member', what, membername, member, skip, self.options) + 'autodoc-skip-member', what, membername, member, + skip, self.options) if skip_user is not None: skip = skip_user if skip: @@ -560,8 +574,9 @@ class RstGenerator(object): if member.__name__ != membername: # assume it's aliased memberwhat = 'data' - content = ViewList([_('alias of :class:`%s`') % member.__name__], - source='') + content = ViewList( + [_('alias of :class:`%s`') % member.__name__], + source='') elif issubclass(member, base_exception): memberwhat = 'exception' else: @@ -577,8 +592,9 @@ class RstGenerator(object): if member.__name__ != membername: # assume it's aliased memberwhat = 'attribute' - content = ViewList([_('alias of :class:`%s`') % member.__name__], - source='') + content = ViewList( + [_('alias of :class:`%s`') % member.__name__], + source='') else: memberwhat = 'class' elif isdescriptor(member): @@ -586,8 +602,8 @@ class RstGenerator(object): else: continue - # give explicitly separated module name, so that members of inner classes - # can be documented + # give explicitly separated module name, so that members + # of inner classes can be documented full_membername = mod + '::' + '.'.join(objpath + [membername]) self.generate(memberwhat, full_membername, ['__all__'], add_content=content, no_docstring=bool(content), @@ -653,13 +669,17 @@ def members_option(arg): def setup(app): - mod_options = {'members': members_option, 'undoc-members': directives.flag, - 'noindex': directives.flag, 'inherited-members': directives.flag, - 'show-inheritance': directives.flag, 'synopsis': lambda x: x, - 'platform': lambda x: x, 'deprecated': directives.flag} - cls_options = {'members': members_option, 'undoc-members': directives.flag, - 'noindex': directives.flag, 'inherited-members': directives.flag, - 'show-inheritance': directives.flag} + mod_options = { + 'members': members_option, 'undoc-members': directives.flag, + 'noindex': directives.flag, 'inherited-members': directives.flag, + 'show-inheritance': directives.flag, 'synopsis': lambda x: x, + 'platform': lambda x: x, 'deprecated': directives.flag + } + cls_options = { + 'members': members_option, 'undoc-members': directives.flag, + 'noindex': directives.flag, 'inherited-members': directives.flag, + 'show-inheritance': directives.flag + } app.add_directive('automodule', automodule_directive, 1, (1, 0, 1), **mod_options) app.add_directive('autoclass', autoclass_directive, diff --git a/sphinx/ext/coverage.py b/sphinx/ext/coverage.py index a3dc5889..964e58ee 100644 --- a/sphinx/ext/coverage.py +++ b/sphinx/ext/coverage.py @@ -53,17 +53,17 @@ class CoverageBuilder(Builder): self.c_ignorexps = {} for (name, exps) in self.config.coverage_ignore_c_items.iteritems(): - self.c_ignorexps[name] = compile_regex_list('coverage_ignore_c_items', - exps, self.warn) - self.mod_ignorexps = compile_regex_list('coverage_ignore_modules', - self.config.coverage_ignore_modules, - self.warn) - self.cls_ignorexps = compile_regex_list('coverage_ignore_classes', - self.config.coverage_ignore_classes, - self.warn) - self.fun_ignorexps = compile_regex_list('coverage_ignore_functions', - self.config.coverage_ignore_functions, - self.warn) + self.c_ignorexps[name] = compile_regex_list( + 'coverage_ignore_c_items', exps, self.warn) + self.mod_ignorexps = compile_regex_list( + 'coverage_ignore_modules', self.config.coverage_ignore_modules, + self.warn) + self.cls_ignorexps = compile_regex_list( + 'coverage_ignore_classes', self.config.coverage_ignore_classes, + self.warn) + self.fun_ignorexps = compile_regex_list( + 'coverage_ignore_functions', self.config.coverage_ignore_functions, + self.warn) def get_outdated_docs(self): return 'coverage overview' @@ -128,7 +128,8 @@ class CoverageBuilder(Builder): try: mod = __import__(mod_name, fromlist=['foo']) except ImportError, err: - self.warn('module %s could not be imported: %s' % (mod_name, err)) + self.warn('module %s could not be imported: %s' % + (mod_name, err)) self.py_undoc[mod_name] = {'error': err} continue @@ -168,7 +169,8 @@ class CoverageBuilder(Builder): attrs = [] - for attr_name, attr in inspect.getmembers(obj, inspect.ismethod): + for attr_name, attr in inspect.getmembers( + obj, inspect.ismethod): if attr_name[0] == '_': # starts with an underscore, ignore it continue diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index d6697f98..d2aacaa4 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -262,13 +262,15 @@ Doctest summary for group in groups.itervalues(): group.add_code(code) if self.config.doctest_global_setup: - code = TestCode(self.config.doctest_global_setup, 'testsetup', lineno=0) + code = TestCode(self.config.doctest_global_setup, + 'testsetup', lineno=0) for group in groups.itervalues(): group.add_code(code, prepend=True) if not groups: return - self._out('\nDocument: %s\n----------%s\n' % (docname, '-'*len(docname))) + self._out('\nDocument: %s\n----------%s\n' % + (docname, '-'*len(docname))) for group in groups.itervalues(): self.test_group(group, self.env.doc2path(docname, base=None)) # Separately count results from setup code @@ -287,7 +289,8 @@ Doctest summary ns = {} examples = [] for setup in group.setup: - examples.append(doctest.Example(setup.code, '', lineno=setup.lineno)) + examples.append(doctest.Example(setup.code, '', + lineno=setup.lineno)) if examples: # simulate a doctest with the setup code setup_doctest = doctest.DocTest(examples, {}, diff --git a/sphinx/ext/ifconfig.py b/sphinx/ext/ifconfig.py index f622ec49..af3975b8 100644 --- a/sphinx/ext/ifconfig.py +++ b/sphinx/ext/ifconfig.py @@ -13,8 +13,8 @@ This stuff is only included in the built docs for unstable versions. The argument for ``ifconfig`` is a plain Python expression, evaluated in the - namespace of the project configuration (that is, all variables from ``conf.py`` - are available.) + namespace of the project configuration (that is, all variables from + ``conf.py`` are available.) :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. diff --git a/sphinx/ext/jsmath.py b/sphinx/ext/jsmath.py index 1bea3304..e51af455 100644 --- a/sphinx/ext/jsmath.py +++ b/sphinx/ext/jsmath.py @@ -32,7 +32,8 @@ def html_visit_displaymath(self, node): if i == 0: # necessary to e.g. set the id property correctly if node['number']: - self.body.append('<span class="eqno">(%s)</span>' % node['number']) + self.body.append('<span class="eqno">(%s)</span>' % + node['number']) self.body.append(self.starttag(node, 'div', CLASS='math')) else: # but only once! diff --git a/sphinx/ext/pngmath.py b/sphinx/ext/pngmath.py index dc1d2ee8..61df53a5 100644 --- a/sphinx/ext/pngmath.py +++ b/sphinx/ext/pngmath.py @@ -117,9 +117,9 @@ def render_math(self, math): if err.errno != 2: # No such file or directory raise if not hasattr(self.builder, '_mathpng_warned_latex'): - self.builder.warn('LaTeX command %r cannot be run (needed for math ' - 'display), check the pngmath_latex setting' % - self.builder.config.pngmath_latex) + self.builder.warn('LaTeX command %r cannot be run (needed for ' + 'math display), check the pngmath_latex ' + 'setting' % self.builder.config.pngmath_latex) self.builder._mathpng_warned_latex = True return relfn, None finally: @@ -127,8 +127,8 @@ def render_math(self, math): stdout, stderr = p.communicate() if p.returncode != 0: - raise MathExtError('latex exited with error:\n[stderr]\n%s\n[stdout]\n%s' - % (stderr, stdout)) + raise MathExtError('latex exited with error:\n[stderr]\n%s\n' + '[stdout]\n%s' % (stderr, stdout)) ensuredir(path.dirname(outfn)) # use some standard dvipng arguments @@ -146,15 +146,15 @@ def render_math(self, math): if err.errno != 2: # No such file or directory raise if not hasattr(self.builder, '_mathpng_warned_dvipng'): - self.builder.warn('dvipng command %r cannot be run (needed for math ' - 'display), check the pngmath_dvipng setting' % - self.builder.config.pngmath_dvipng) + self.builder.warn('dvipng command %r cannot be run (needed for ' + 'math display), check the pngmath_dvipng setting' + % self.builder.config.pngmath_dvipng) self.builder._mathpng_warned_dvipng = True return relfn, None stdout, stderr = p.communicate() if p.returncode != 0: - raise MathExtError('dvipng exited with error:\n[stderr]\n%s\n[stdout]\n%s' - % (stderr, stdout)) + raise MathExtError('dvipng exited with error:\n[stderr]\n%s\n' + '[stdout]\n%s' % (stderr, stdout)) depth = None if use_preview: for line in stdout.splitlines(): @@ -187,7 +187,8 @@ def html_visit_math(self, node): raise nodes.SkipNode self.body.append('<img class="math" src="%s" alt="%s" %s/>' % (fname, self.encode(node['latex']).strip(), - depth and 'style="vertical-align: %dpx" ' % (-depth) or '')) + depth and 'style="vertical-align: %dpx" ' % + (-depth) or '')) raise nodes.SkipNode def html_visit_displaymath(self, node): diff --git a/sphinx/ext/refcounting.py b/sphinx/ext/refcounting.py index c31d6627..cad9d7f1 100644 --- a/sphinx/ext/refcounting.py +++ b/sphinx/ext/refcounting.py @@ -55,7 +55,8 @@ class Refcounts(dict): refcount = None else: refcount = int(refcount) - # Update the entry with the new parameter or the result information. + # Update the entry with the new parameter or the result + # information. if arg: entry.args.append((arg, type, refcount)) else: @@ -81,7 +82,8 @@ class Refcounts(dict): if entry.result_refs is None: rc += "Always NULL." else: - rc += (entry.result_refs and "New" or "Borrowed") + " reference." + rc += (entry.result_refs and "New" or "Borrowed") + \ + " reference." node.insert(0, refcount(rc, rc)) diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index dac90660..b7a8d500 100644 --- a/sphinx/ext/todo.py +++ b/sphinx/ext/todo.py @@ -72,8 +72,8 @@ def process_todo_nodes(app, doctree, fromdocname): para = nodes.paragraph() filename = env.doc2path(todo_info['docname'], base=None) description = ( - _('(The original entry is located in %s, line %d and can be found ') % - (filename, todo_info['lineno'])) + _('(The original entry is located in %s, line %d and ' + 'can be found ') % (filename, todo_info['lineno'])) para += nodes.Text(description, description) # Create a reference diff --git a/sphinx/highlighting.py b/sphinx/highlighting.py index 61cea214..61c413d7 100644 --- a/sphinx/highlighting.py +++ b/sphinx/highlighting.py @@ -101,7 +101,8 @@ class PygmentsBridge(object): style = NoneStyle elif '.' in stylename: module, stylename = stylename.rsplit('.', 1) - style = getattr(__import__(module, None, None, ['__name__']), stylename) + style = getattr(__import__(module, None, None, ['__name__']), + stylename) else: style = get_style_by_name(stylename) if dest == 'html': diff --git a/sphinx/pycode/__init__.py b/sphinx/pycode/__init__.py index c2086da5..d195d6c3 100644 --- a/sphinx/pycode/__init__.py +++ b/sphinx/pycode/__init__.py @@ -91,7 +91,8 @@ class AttrDocVisitor(nodes.NodeVisitor): return if prev.type == sym.simple_stmt and \ prev[0].type == sym.expr_stmt and _eq in prev[0].children: - # need to "eval" the string because it's returned in its original form + # need to "eval" the string because it's returned in its + # original form docstring = literals.evalString(node[0].value, self.encoding) docstring = prepare_docstring(docstring) self.add_docstring(prev[0], docstring) @@ -159,7 +160,8 @@ class ModuleAnalyzer(object): try: source = mod.__loader__.get_source(modname) except Exception, err: - raise PycodeError('error getting source for %r' % modname, err) + raise PycodeError('error getting source for %r' % modname, + err) obj = cls.for_string(source, modname) cls.cache['module', modname] = obj return obj @@ -279,8 +281,9 @@ class ModuleAnalyzer(object): namespace.pop() result[fullname] = (dtype, startline, endline) elif type == token.NEWLINE: - # if this line contained a definition, expect an INDENT to start the - # suite; if there is no such INDENT it's a one-line definition + # if this line contained a definition, expect an INDENT + # to start the suite; if there is no such INDENT + # it's a one-line definition if defline: defline = False expect_indent = True @@ -292,7 +295,8 @@ if __name__ == '__main__': import time, pprint x0 = time.time() #ma = ModuleAnalyzer.for_file(__file__.rstrip('c'), 'sphinx.builders.html') - ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', 'sphinx.builders.html') + ma = ModuleAnalyzer.for_file('sphinx/builders/html.py', + 'sphinx.builders.html') ma.tokenize() x1 = time.time() ma.parse() diff --git a/sphinx/pycode/nodes.py b/sphinx/pycode/nodes.py index 4d27fc66..efdf8f06 100644 --- a/sphinx/pycode/nodes.py +++ b/sphinx/pycode/nodes.py @@ -102,7 +102,8 @@ class Node(BaseNode): ch.parent = self def __repr__(self): - return '%s(%s, %r)' % (self.__class__.__name__, self.type, self.children) + return '%s(%s, %r)' % (self.__class__.__name__, + self.type, self.children) def __str__(self): """This reproduces the input source exactly.""" @@ -174,7 +175,8 @@ def nice_repr(node, number2name, prefix=False): ', '.join(map(_repr, node.children))) def _prepr(node): if isinstance(node, Leaf): - return "%s(%r, %r)" % (number2name[node.type], node.prefix, node.value) + return "%s(%r, %r)" % (number2name[node.type], + node.prefix, node.value) else: return "%s(%s)" % (number2name[node.type], ', '.join(map(_prepr, node.children))) diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 67ab6273..c0a219ef 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -15,7 +15,8 @@ from os import path TERM_ENCODING = getattr(sys.stdin, 'encoding', None) from sphinx.util import make_filename -from sphinx.util.console import purple, bold, red, turquoise, nocolor, color_terminal +from sphinx.util.console import purple, bold, red, turquoise, \ + nocolor, color_terminal from sphinx.util import texescape @@ -29,9 +30,6 @@ QUICKSTART_CONF = '''\ # # This file is execfile()d with the current directory set to its containing dir. # -# 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). -# # Note that not all possible configuration values are present in this # autogenerated file. # @@ -45,8 +43,7 @@ import sys, os # absolute, like shown here. #sys.path.append(os.path.abspath('.')) -# General configuration -# --------------------- +# -- General configuration ----------------------------------------------------- # Add any Sphinx extension module names here, as strings. They can be extensions # coming with Sphinx (named 'sphinx.ext.*') or your custom ones. @@ -112,8 +109,7 @@ exclude_trees = [%(exclude_trees)s] pygments_style = 'sphinx' -# Options for HTML output -# ----------------------- +# -- Options for HTML output --------------------------------------------------- # The style sheet to use for HTML and HTML Help pages. A file of that name # must exist either in Sphinx' static/ path, or in one of the custom paths @@ -180,8 +176,7 @@ html_static_path = ['%(dot)sstatic'] htmlhelp_basename = '%(project_fn)sdoc' -# Options for LaTeX output -# ------------------------ +# -- Options for LaTeX output -------------------------------------------------- # The paper size ('letter' or 'a4'). #latex_paper_size = 'letter' @@ -190,7 +185,7 @@ htmlhelp_basename = '%(project_fn)sdoc' #latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). +# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('%(master)s', '%(project_fn)s.tex', ur'%(project_doc_texescaped)s', ur'%(author_texescaped)s', 'manual'), @@ -217,11 +212,12 @@ latex_documents = [ INTERSPHINX_CONFIG = ''' # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {'http://docs.python.org/dev': None} +intersphinx_mapping = {'http://docs.python.org/': None} ''' MASTER_FILE = '''\ -.. %(project)s documentation master file, created by sphinx-quickstart on %(now)s. +.. %(project)s documentation master file, created by + sphinx-quickstart on %(now)s. You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. @@ -267,7 +263,7 @@ help: \t@echo " htmlhelp to make HTML files and a HTML help project" \t@echo " qthelp to make HTML files and a qthelp project" \t@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" -\t@echo " changes to make an overview over all changed/added/deprecated items" +\t@echo " changes to make an overview of all changed/added/deprecated items" \t@echo " linkcheck to check all external links for integrity" clean: @@ -466,8 +462,9 @@ def do_prompt(d, key, text, default=None, validator=nonempty): if TERM_ENCODING: x = x.decode(TERM_ENCODING) else: - print turquoise('* Note: non-ASCII characters entered and terminal ' - 'encoding unknown -- assuming UTF-8 or Latin-1.') + print turquoise('* Note: non-ASCII characters entered ' + 'and terminal encoding unknown -- assuming ' + 'UTF-8 or Latin-1.') try: x = x.decode('utf-8') except UnicodeDecodeError: @@ -502,8 +499,8 @@ Enter the root path for documentation.''' 'selected root path.') print 'sphinx-quickstart will not overwrite existing Sphinx projects.' print - do_prompt(d, 'path', 'Please enter a new root path (or just Enter to exit)', - '', is_path) + do_prompt(d, 'path', 'Please enter a new root path (or just Enter ' + 'to exit)', '', is_path) if not d['path']: sys.exit(1) @@ -516,8 +513,8 @@ Either, you use a directory "_build" within the root path, or you separate print ''' Inside the root directory, two more directories will be created; "_templates" -for custom HTML templates and "_static" for custom stylesheets and other -static files. You can enter another prefix (such as ".") to replace the underscore.''' +for custom HTML templates and "_static" for custom stylesheets and other static +files. You can enter another prefix (such as ".") to replace the underscore.''' do_prompt(d, 'dot', 'Name prefix for templates and static dir', '_', ok) print ''' @@ -549,26 +546,29 @@ Please indicate if you want to use one of the following Sphinx extensions:''' 'from modules (y/N)', 'n', boolean) do_prompt(d, 'ext_doctest', 'doctest: automatically test code snippets ' 'in doctest blocks (y/N)', 'n', boolean) - do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx documentation ' - 'of different projects (y/N)', 'n', boolean) + do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx ' + 'documentation of different projects (y/N)', 'n', boolean) print ''' A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build directly.''' do_prompt(d, 'makefile', 'Create Makefile? (Y/n)', 'y', boolean) - do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)', 'y', boolean) + do_prompt(d, 'batchfile', 'Create Windows command file? (Y/n)', + 'y', boolean) d['project_fn'] = make_filename(d['project']) d['now'] = time.asctime() d['underline'] = len(d['project']) * '=' d['extensions'] = ', '.join( - repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', 'intersphinx') + repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', + 'intersphinx') if d['ext_' + name].upper() in ('Y', 'YES')) d['copyright'] = time.strftime('%Y') + ', ' + d['author'] - d['author_texescaped'] = unicode(d['author']).translate(texescape.tex_escape_map) + d['author_texescaped'] = unicode(d['author']).\ + translate(texescape.tex_escape_map) d['project_doc'] = d['project'] + ' Documentation' - d['project_doc_texescaped'] = \ - unicode(d['project'] + ' Documentation').translate(texescape.tex_escape_map) + d['project_doc_texescaped'] = unicode(d['project'] + ' Documentation').\ + translate(texescape.tex_escape_map) if not path.isdir(d['path']): mkdir_p(d['path']) diff --git a/sphinx/roles.py b/sphinx/roles.py index d2e9558e..837b5cb8 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -36,7 +36,8 @@ for rolename, nodeclass in generic_docroles.iteritems(): roles.register_generic_role(rolename, nodeclass) -def indexmarkup_role(typ, rawtext, etext, lineno, inliner, options={}, content=[]): +def indexmarkup_role(typ, rawtext, etext, lineno, inliner, + options={}, content=[]): env = inliner.document.settings.env if not typ: typ = env.config.default_role @@ -56,13 +57,14 @@ def indexmarkup_role(typ, rawtext, etext, lineno, inliner, options={}, content=[ options, content)[0] return [indexnode, targetnode] + xref_nodes, [] elif typ == 'pep': - indexnode['entries'] = [('single', - _('Python Enhancement Proposals!PEP %s') % text, - targetid, 'PEP %s' % text)] + indexnode['entries'] = [ + ('single', _('Python Enhancement Proposals!PEP %s') % text, + targetid, 'PEP %s' % text)] try: pepnum = int(text) except ValueError: - msg = inliner.reporter.error('invalid PEP number %s' % text, line=lineno) + msg = inliner.reporter.error('invalid PEP number %s' % text, + line=lineno) prb = inliner.problematic(rawtext, rawtext, msg) return [prb], [msg] ref = inliner.document.settings.pep_base_url + 'pep-%04d' % pepnum @@ -76,7 +78,8 @@ def indexmarkup_role(typ, rawtext, etext, lineno, inliner, options={}, content=[ try: rfcnum = int(text) except ValueError: - msg = inliner.reporter.error('invalid RFC number %s' % text, line=lineno) + msg = inliner.reporter.error('invalid RFC number %s' % text, + line=lineno) prb = inliner.problematic(rawtext, rawtext, msg) return [prb], [msg] ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum @@ -129,7 +132,8 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): modname=env.currmodule, classname=env.currclass) # we may need the line number for warnings pnode.line = lineno - # the link title may differ from the target, but by default they are the same + # the link title may differ from the target, but by default + # they are the same title = target = text titleistarget = True # look if explicit title and target are given with `foo <bar>` syntax @@ -146,7 +150,8 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): target = text[brace+1:] title = text[:brace] # special target for Python object cross-references - if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', 'meth', 'mod', 'obj'): + if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', + 'meth', 'mod', 'obj'): # fix-up parentheses in link title if titleistarget: title = title.lstrip('.') # only has a meaning for the target @@ -171,7 +176,8 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): elif typ == 'option': program = env.currprogram if titleistarget: - if ' ' in title and not (title.startswith('/') or title.startswith('-')): + if ' ' in title and not (title.startswith('/') or + title.startswith('-')): program, target = re.split(' (?=-|--|/)', title, 1) program = ws_re.sub('-', program) target = target.strip() @@ -190,18 +196,21 @@ def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): # remove all whitespace to avoid referencing problems target = ws_re.sub('', target) pnode['reftarget'] = target - pnode += innernodetypes.get(typ, nodes.literal)(rawtext, title, classes=['xref']) + pnode += innernodetypes.get(typ, nodes.literal)(rawtext, title, + classes=['xref']) return [pnode], [] def menusel_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): return [nodes.emphasis( - rawtext, utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], [] + rawtext, + utils.unescape(text).replace('-->', u'\N{TRIANGULAR BULLET}'))], [] _litvar_re = re.compile('{([^}]+)}') -def emph_literal_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): +def emph_literal_role(typ, rawtext, text, lineno, inliner, + options={}, content=[]): text = utils.unescape(text) pos = 0 retnode = nodes.literal(role=typ.lower()) diff --git a/sphinx/setup_command.py b/sphinx/setup_command.py index c874bdd4..ac395f39 100644 --- a/sphinx/setup_command.py +++ b/sphinx/setup_command.py @@ -84,6 +84,7 @@ class BuildDoc(Command): from docutils.utils import SystemMessage if isinstance(err, SystemMessage): sys.stderr, darkred('reST markup error:') - print >>sys.stderr, err.args[0].encode('ascii', 'backslashreplace') + print >>sys.stderr, err.args[0].encode('ascii', + 'backslashreplace') else: raise diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html index f92e188c..b4b1e7c5 100644 --- a/sphinx/themes/basic/layout.html +++ b/sphinx/themes/basic/layout.html @@ -68,8 +68,8 @@ {% include customsidebar %} {%- endif %} {%- block sidebarsearch %} - {%- if pagename != "search" %} - <div id="searchbox" style="display: none"> + {%- if pagename != "search" %} + <div id="searchbox" style="display: none"> <h3>{{ _('Quick search') }}</h3> <form class="search" action="{{ pathto('search') }}" method="get"> <input type="text" name="q" size="18" /> @@ -77,7 +77,7 @@ <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> - <p class="searchtip" style="font-size: 90%"> + <p class="searchtip" style="font-size: 90%"> {{ _('Enter search terms or a module, class or function name.') }} </p> </div> diff --git a/sphinx/util/smartypants.py b/sphinx/util/smartypants.py index 42f20f36..75888ea4 100644 --- a/sphinx/util/smartypants.py +++ b/sphinx/util/smartypants.py @@ -162,7 +162,8 @@ def educateQuotes(s): """ # Special case if the very first character is a quote - # followed by punctuation at a non-word-break. Close the quotes by brute force: + # followed by punctuation at a non-word-break. Close the quotes + # by brute force: s = single_quote_start_re.sub("’", s) s = double_quote_start_re.sub("”", s) @@ -200,7 +201,8 @@ def educateQuotesLatex(s, dquotes=("``", "''")): """ # Special case if the very first character is a quote - # followed by punctuation at a non-word-break. Close the quotes by brute force: + # followed by punctuation at a non-word-break. Close the quotes + # by brute force: s = single_quote_start_re.sub("\x04", s) s = double_quote_start_re.sub("\x02", s) @@ -300,4 +302,5 @@ __author__ = "Chad Miller <smartypantspy@chad.org>" __version__ = "1.5_1.5: Sat, 13 Aug 2005 15:50:24 -0400" __url__ = "http://wiki.chad.org/SmartyPantsPy" __description__ = \ - "Smart-quotes, smart-ellipses, and smart-dashes for weblog entries in pyblosxom" + "Smart-quotes, smart-ellipses, and smart-dashes for weblog entries" \ + " in pyblosxom" diff --git a/sphinx/util/stemmer.py b/sphinx/util/stemmer.py index 7eeb77b2..10ce9065 100644 --- a/sphinx/util/stemmer.py +++ b/sphinx/util/stemmer.py @@ -111,14 +111,16 @@ class PorterStemmer(object): return self.cons(j) def cvc(self, i): - """cvc(i) is TRUE <=> i-2,i-1,i has the form consonant - vowel - consonant + """cvc(i) is TRUE <=> i-2,i-1,i has the form + consonant - vowel - consonant and also if the second c is not w,x or y. this is used when trying to restore an e at the end of a short e.g. cav(e), lov(e), hop(e), crim(e), but snow, box, tray. """ - if i < (self.k0 + 2) or not self.cons(i) or self.cons(i-1) or not self.cons(i-2): + if i < (self.k0 + 2) or not self.cons(i) or self.cons(i-1) \ + or not self.cons(i-2): return 0 ch = self.b[i] if ch == 'w' or ch == 'x' or ch == 'y': @@ -138,7 +140,8 @@ class PorterStemmer(object): return 1 def setto(self, s): - """setto(s) sets (j+1),...k to the characters in the string s, readjusting k.""" + """setto(s) sets (j+1),...k to the characters in the string s, + readjusting k.""" length = len(s) self.b = self.b[:self.j+1] + s + self.b[self.j+length+1:] self.k = self.j + length @@ -193,7 +196,8 @@ class PorterStemmer(object): self.setto("e") def step1c(self): - """step1c() turns terminal y to i when there is another vowel in the stem.""" + """step1c() turns terminal y to i when there is another vowel in + the stem.""" if (self.ends("y") and self.vowelinstem()): self.b = self.b[:self.k] + 'i' + self.b[self.k+1:] @@ -236,7 +240,8 @@ class PorterStemmer(object): # To match the published algorithm, delete this phrase def step3(self): - """step3() dels with -ic-, -full, -ness etc. similar strategy to step2.""" + """step3() dels with -ic-, -full, -ness etc. similar strategy + to step2.""" if self.b[self.k] == 'e': if self.ends("icate"): self.r("ic") elif self.ends("ative"): self.r("") diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 79197606..17a22b7a 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -68,13 +68,15 @@ class HTMLTranslator(BaseTranslator): # the id is set automatically self.body.append(self.starttag(node, 'dt')) # anchor for per-desc interactive data - if node.parent['desctype'] != 'describe' and node['ids'] and node['first']: + if node.parent['desctype'] != 'describe' \ + and node['ids'] and node['first']: self.body.append('<!--[%s]-->' % node['ids'][0]) if node.parent['desctype'] in ('class', 'exception'): self.body.append('%s ' % node.parent['desctype']) def depart_desc_signature(self, node): if node['ids'] and self.add_permalinks and self.builder.add_permalinks: - self.body.append(u'<a class="headerlink" href="#%s" ' % node['ids'][0] + + self.body.append(u'<a class="headerlink" href="#%s" ' + % node['ids'][0] + u'title="%s">\u00B6</a>' % _('Permalink to this definition')) self.body.append('</dt>\n') @@ -192,14 +194,17 @@ class HTMLTranslator(BaseTranslator): # most probably a parsed-literal block -- don't highlight return BaseTranslator.visit_literal_block(self, node) lang = self.highlightlang - linenos = node.rawsource.count('\n') >= self.highlightlinenothreshold - 1 + linenos = node.rawsource.count('\n') >= \ + self.highlightlinenothreshold - 1 if node.has_key('language'): # code-block directives lang = node['language'] if node.has_key('linenos'): linenos = node['linenos'] - highlighted = self.highlighter.highlight_block(node.rawsource, lang, linenos) - starttag = self.starttag(node, 'div', suffix='', CLASS='highlight-%s' % lang) + highlighted = self.highlighter.highlight_block(node.rawsource, + lang, linenos) + starttag = self.starttag(node, 'div', suffix='', + CLASS='highlight-%s' % lang) self.body.append(starttag + highlighted + '</div>\n') raise nodes.SkipNode @@ -211,7 +216,8 @@ class HTMLTranslator(BaseTranslator): if len(node.children) == 1 and \ node.children[0] in ('None', 'True', 'False'): node['classes'].append('xref') - self.body.append(self.starttag(node, 'tt', '', CLASS='docutils literal')) + self.body.append(self.starttag(node, 'tt', '', + CLASS='docutils literal')) self.protect_literal_text += 1 def depart_literal(self, node): self.protect_literal_text -= 1 @@ -243,7 +249,8 @@ class HTMLTranslator(BaseTranslator): pass def visit_centered(self, node): - self.body.append(self.starttag(node, 'p', CLASS="centered") + '<strong>') + self.body.append(self.starttag(node, 'p', CLASS="centered") + + '<strong>') def depart_centered(self, node): self.body.append('</strong></p>') diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 885cac44..a9fa7662 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -167,7 +167,8 @@ class LaTeXTranslator(nodes.NodeVisitor): 'pointsize': builder.config.latex_font_size, # if empty, the title is set to the first section title 'title': document.settings.title, - 'date': ustrftime(builder.config.today_fmt or _('%B %d, %Y')), + 'date': ustrftime(builder.config.today_fmt + or _('%B %d, %Y')), 'release': builder.config.release, 'author': document.settings.author, 'releasename': _('Release'), @@ -253,7 +254,8 @@ class LaTeXTranslator(nodes.NodeVisitor): for bi in self.bibitems: # cite_key: underscores must not be escaped cite_key = bi[0].replace(r"\_", "_") - self.body.append('\\bibitem[%s]{%s}{%s}\n' % (bi[0], cite_key, bi[1])) + self.body.append('\\bibitem[%s]{%s}{%s}\n' % + (bi[0], cite_key, bi[1])) self.body.append('\\end{thebibliography}\n') self.bibitems = [] @@ -304,7 +306,8 @@ class LaTeXTranslator(nodes.NodeVisitor): # self.body.append(r'\hypertarget{%s}{}' % id) # self.written_ids.add(id) def depart_section(self, node): - self.sectionlevel = max(self.sectionlevel - 1, self.top_sectionlevel - 1) + self.sectionlevel = max(self.sectionlevel - 1, + self.top_sectionlevel - 1) def visit_problematic(self, node): self.body.append(r'{\color{red}\bfseries{}') @@ -335,7 +338,8 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_production(self, node): if node['tokenname']: - self.body.append('\\production{%s}{' % self.encode(node['tokenname'])) + self.body.append('\\production{%s}{' % + self.encode(node['tokenname'])) else: self.body.append('\\productioncont{') def depart_production(self, node): @@ -352,7 +356,8 @@ class LaTeXTranslator(nodes.NodeVisitor): # the environment already handles this raise nodes.SkipNode elif self.this_is_the_title: - if len(node.children) != 1 and not isinstance(node.children[0], nodes.Text): + if len(node.children) != 1 and not isinstance(node.children[0], + nodes.Text): self.builder.warn('document title is not a single Text node') if not self.elements['title']: # text needs to be escaped since it is inserted into @@ -585,7 +590,8 @@ class LaTeXTranslator(nodes.NodeVisitor): else: if self.table.has_verbatim: colwidth = 0.95 / self.table.colcount - colspec = ('p{%.3f\\textwidth}|' % colwidth) * self.table.colcount + colspec = ('p{%.3f\\textwidth}|' % colwidth) * \ + self.table.colcount self.body.append('{|' + colspec + '}\n') else: self.body.append('{|' + ('L|' * self.table.colcount) + '}\n') @@ -648,7 +654,8 @@ class LaTeXTranslator(nodes.NodeVisitor): # this is a list in the source, but should be rendered as a # comma-separated list here self.body.append('\n\n') - self.body.append(', '.join(n.astext() for n in node.children[0].children) + '.') + self.body.append(', '.join(n.astext() + for n in node.children[0].children) + '.') self.body.append('\n\n') raise nodes.SkipNode @@ -743,9 +750,10 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_module(self, node): modname = node['modname'] - self.body.append('\n\\declaremodule[%s]{}{%s}' % (modname.replace('_', ''), - self.encode(modname))) - self.body.append('\n\\modulesynopsis{%s}' % self.encode(node['synopsis'])) + self.body.append('\n\\declaremodule[%s]{}{%s}' % ( + modname.replace('_', ''), self.encode(modname))) + self.body.append('\n\\modulesynopsis{%s}' % + self.encode(node['synopsis'])) if node.has_key('platform'): self.body.append('\\platform{%s}' % self.encode(node['platform'])) def depart_module(self, node): @@ -922,15 +930,18 @@ class LaTeXTranslator(nodes.NodeVisitor): entries = node['entries'] for type, string, tid, _ in entries: if type == 'single': - self.body.append(r'\index{%s}' % scre.sub('!', self.encode(string))) + self.body.append(r'\index{%s}' % + scre.sub('!', self.encode(string))) elif type == 'pair': - parts = tuple(self.encode(x.strip()) for x in string.split(';', 1)) + parts = tuple(self.encode(x.strip()) + for x in string.split(';', 1)) try: self.body.append(r'\indexii{%s}{%s}' % parts) except TypeError: self.builder.warn('invalid pair index entry %r' % string) elif type == 'triple': - parts = tuple(self.encode(x.strip()) for x in string.split(';', 2)) + parts = tuple(self.encode(x.strip()) + for x in string.split(';', 2)) try: self.body.append(r'\indexiii{%s}{%s}{%s}' % parts) except TypeError: @@ -957,7 +968,8 @@ class LaTeXTranslator(nodes.NodeVisitor): self.context.append('}') elif uri.startswith('%'): hashindex = uri.find('#') - targetname = (hashindex == -1) and '--doc-' + uri[1:] or uri[hashindex+1:] + targetname = (hashindex == -1) and '--doc-' + uri[1:] \ + or uri[hashindex+1:] self.body.append('\\hyperlink{%s}{' % targetname) self.context.append('}') elif uri.startswith('@token'): diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py index 4718d41d..787e7020 100644 --- a/sphinx/writers/text.py +++ b/sphinx/writers/text.py @@ -419,7 +419,8 @@ class TextTranslator(nodes.NodeVisitor): def visit_acks(self, node): self.new_state(0) - self.add_text(', '.join(n.astext() for n in node.children[0].children) + '.') + self.add_text(', '.join(n.astext() for n in node.children[0].children) + + '.') self.end_state() raise nodes.SkipNode diff --git a/utils/check_sources.py b/utils/check_sources.py index c244d9c0..def13ee9 100755 --- a/utils/check_sources.py +++ b/utils/check_sources.py @@ -56,7 +56,7 @@ def check_syntax(fn, lines): def check_style_and_encoding(fn, lines): encoding = 'ascii' for lno, line in enumerate(lines): - if len(line) > 90: + if len(line) > 81: yield lno+1, "line too long" if lno < 2: co = coding_re.search(line) -- cgit v1.2.1 From 0c000f5e64f324c3fa8d05f8bf0c884a7bc39cdf Mon Sep 17 00:00:00 2001 From: mq <devnull@localhost> Date: Sat, 10 Jan 2009 21:54:26 +0100 Subject: add modindex_common_prefix config value --- CHANGES | 3 +++ doc/conf.py | 3 +++ doc/config.rst | 32 +++++++++++++++++++++----------- sphinx/builders/html.py | 38 +++++++++++++++++++++++++++++++++----- sphinx/config.py | 1 + sphinx/quickstart.py | 3 +++ sphinx/templates/modindex.html | 4 ++-- 7 files changed, 66 insertions(+), 18 deletions(-) diff --git a/CHANGES b/CHANGES index 47cfa672..6e7d5934 100644 --- a/CHANGES +++ b/CHANGES @@ -61,6 +61,9 @@ New features added - The default value for ``htmlhelp_basename`` is now the project title, cleaned up as a filename. + - The new ``modindex_common_prefix`` config value can be used to + ignore certain package names for module index sorting. + * Builders: - New builder for Qt help collections, by Antonio Valentino. diff --git a/doc/conf.py b/doc/conf.py index 709d6f75..87afc659 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -68,6 +68,9 @@ show_authors = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'friendly' +# A list of ignored prefixes names for module index sorting. +modindex_common_prefix = ['sphinx.'] + # Options for HTML output # ----------------------- diff --git a/doc/config.rst b/doc/config.rst index dd25cf22..ad14d1ed 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -76,7 +76,7 @@ General configuration .. versionadded:: 0.5 Previously, Sphinx accepted only UTF-8 encoded sources. - + .. confval:: master_doc The document name of the "master" document, that is, the document that @@ -164,9 +164,19 @@ General configuration .. versionadded:: 0.5 +.. confval:: modindex_common_prefix + + A list of prefixes that are ignored for sorting the module index (e.g., + if this is set to ``['foo.']``, then ``foo.bar`` is shown under ``B``, not + ``F``). This can be handy if you document a project that consists of a single + package. Works only for the HTML builder currently. Default is ``[]``. + + .. versionadded:: 0.6 + + Project information ------------------- - + .. confval:: project The documented project's name. @@ -233,7 +243,7 @@ Project information :ref:`code-examples` for more details. .. versionadded:: 0.5 - + .. confval:: pygments_style The style name to use for Pygments highlighting of source code. Default is @@ -341,7 +351,7 @@ that use Sphinx' HTMLWriter class. .. versionadded:: 0.6 Previously, this was always activated. - + .. confval:: html_sidebars Custom sidebar templates, must be a dictionary that maps document names to @@ -439,7 +449,7 @@ that use Sphinx' HTMLWriter class. support different web server setups). .. versionadded:: 0.6 - + .. confval:: html_translator_class A string with the fully-qualified name of a HTML Translator class, that is, a @@ -527,7 +537,7 @@ These options influence LaTeX output. avoid interpretation as escape sequences. * Keys that you may want to override include: - + ``'papersize'`` Paper size option of the document class (``'a4paper'`` or ``'letterpaper'``), default ``'letterpaper'``. @@ -551,9 +561,9 @@ These options influence LaTeX output. Additional preamble content, default empty. ``'footer'``` Additional footer content (before the indices), default empty. - + * Keys that don't need be overridden unless in special cases are: - + ``'inputenc'`` "inputenc" package inclusion, default ``'\\usepackage[utf8]{inputenc}'``. @@ -570,9 +580,9 @@ These options influence LaTeX output. "printindex" call, the last thing in the file, default ``'\\printindex'``. Override if you want to generate the index differently or append some content after the index. - + * Keys that are set by other options and therefore should not be overridden are: - + ``'docclass'`` ``'classoptions'`` ``'title'`` @@ -585,7 +595,7 @@ These options influence LaTeX output. ``'makemodindex'`` ``'shorthandoff'`` ``'printmodindex'`` - + .. confval:: latex_preamble Additional LaTeX markup for the preamble. diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 91682aa2..20223ee0 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -292,11 +292,24 @@ class StandaloneHTMLBuilder(Builder): for mn, (fn, sy, pl, dep) in modules: pl = pl and pl.split(', ') or [] platforms.update(pl) + + ignore = self.env.config['modindex_common_prefix'] + ignore = sorted(ignore, key=len, reverse=True) + for i in ignore: + if mn.startswith(i): + mn = mn[len(i):] + stripped = i + break + else: + stripped = '' + if fl != mn[0].lower() and mn[0] != '_': # heading - modindexentries.append(['', False, 0, False, - mn[0].upper(), '', [], False]) - letters.append(mn[0].upper()) + letter = mn[0].upper() + if letter not in letters: + modindexentries.append(['', False, 0, False, + letter, '', [], False, '']) + letters.append(letter) tn = mn.split('.')[0] if tn != mn: # submodule @@ -307,11 +320,13 @@ class StandaloneHTMLBuilder(Builder): elif not pmn.startswith(tn): # submodule without parent in list, add dummy entry cg += 1 - modindexentries.append([tn, True, cg, False, '', '', [], False]) + modindexentries.append([tn, True, cg, False, '', '', + [], False, stripped]) else: num_toplevels += 1 cg += 1 - modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, dep]) + modindexentries.append([mn, False, cg, (tn != mn), fn, sy, pl, + dep, stripped]) pmn = mn fl = mn[0].lower() platforms = sorted(platforms) @@ -321,6 +336,19 @@ class StandaloneHTMLBuilder(Builder): # number of submodules collapse = len(modules) - num_toplevels < num_toplevels + # As some parts of the module names may have been stripped, those + # names have changed, thus it is necessary to sort the entries. + if ignore: + def sorthelper(entry): + name = entry[0] + if name == '': + # heading + name = entry[4] + return name.lower() + + modindexentries.sort(key=sorthelper) + letters.sort() + modindexcontext = dict( modindexentries = modindexentries, platforms = platforms, diff --git a/sphinx/config.py b/sphinx/config.py index 428c0bf4..2f8ee1e5 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -51,6 +51,7 @@ class Config(object): templates_path = ([], False), template_bridge = (None, False), keep_warnings = (False, True), + modindex_common_prefix = ([], False), # HTML options html_title = (lambda self: '%s v%s documentation' % diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 67ab6273..343ea0cf 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -111,6 +111,9 @@ exclude_trees = [%(exclude_trees)s] # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + # Options for HTML output # ----------------------- diff --git a/sphinx/templates/modindex.html b/sphinx/templates/modindex.html index 6e33e55c..0392edc8 100644 --- a/sphinx/templates/modindex.html +++ b/sphinx/templates/modindex.html @@ -18,7 +18,7 @@ <hr/> <table width="100%" class="indextable" cellspacing="0" cellpadding="2"> - {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep in modindexentries %} + {%- for modname, collapse, cgroup, indent, fname, synops, pform, dep, stripped in modindexentries %} {%- if not modname -%} <tr class="pcap"><td></td><td> </td><td></td></tr> <tr class="cap"><td></td><td><a name="cap-{{ fname }}"><strong>{{ fname }}</strong></a></td><td></td></tr> @@ -30,7 +30,7 @@ {%- endif %}</td> <td>{% if indent %}   {% endif %} {% if fname %}<a href="{{ fname }}">{% endif -%} - <tt class="xref">{{ modname|e }}</tt> + <tt class="xref">{{ stripped|e }}{{ modname|e }}</tt> {%- if fname %}</a>{% endif %} {%- if pform and pform[0] %} <em>({{ pform|join(', ') }})</em>{% endif -%} </td><td>{% if dep %}<strong>{{ _('Deprecated')}}:</strong>{% endif %} -- cgit v1.2.1 From 6d564844e830c1faaf746460327bd14f3234171e Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 10 Jan 2009 22:18:18 +0100 Subject: Fix more line length and trailing whitespace. --- Makefile | 4 +++- doc/_templates/index.html | 2 +- doc/builders.rst | 4 ++-- doc/concepts.rst | 10 ++++----- doc/conf.py | 5 +++-- doc/config.rst | 22 +++++++++--------- doc/contents.rst | 2 +- doc/ext/appapi.rst | 16 ++++++------- doc/ext/autodoc.rst | 2 +- doc/ext/doctest.rst | 6 ++--- doc/ext/intersphinx.rst | 2 +- doc/ext/math.rst | 6 ++--- doc/ext/todo.rst | 4 ++-- doc/ext/tutorial.rst | 24 ++++++++++---------- doc/intro.rst | 2 +- doc/markup/code.rst | 2 +- doc/markup/desc.rst | 2 +- doc/markup/para.rst | 8 +++---- doc/rest.rst | 6 ++--- setup.py | 3 ++- sphinx/theming.py | 2 +- tests/root/conf.py | 9 +++----- tests/test_autodoc.py | 57 ++++++++++++++++++++++++++++++----------------- tests/test_build.py | 22 ++++++++++-------- tests/test_env.py | 9 +++++--- tests/test_markup.py | 6 +++-- tests/util.py | 3 ++- utils/check_sources.py | 6 ++--- utils/reindent.py | 6 +++-- 29 files changed, 140 insertions(+), 112 deletions(-) diff --git a/Makefile b/Makefile index 721986b2..4d5048d1 100644 --- a/Makefile +++ b/Makefile @@ -7,7 +7,9 @@ export PYTHONPATH = $(shell echo "$$PYTHONPATH"):./sphinx all: clean-pyc check test check: - @$(PYTHON) utils/check_sources.py -i sphinx/style/jquery.js sphinx + @$(PYTHON) utils/check_sources.py -i sphinx/style/jquery.js \ + -i sphinx/pycode/pgen2 -i sphinx/util/smartypants.py \ + -i doc/_build -i ez_setup.py -i tests/path.py . clean: clean-pyc clean-patchfiles diff --git a/doc/_templates/index.html b/doc/_templates/index.html index 43d07e82..1c399f92 100644 --- a/doc/_templates/index.html +++ b/doc/_templates/index.html @@ -81,5 +81,5 @@ </p> <p>The code can be found in a Mercurial repository, at <tt>http://bitbucket.org/birkenfeld/sphinx/</tt>.</p> - + {% endblock %} diff --git a/doc/builders.rst b/doc/builders.rst index dd07a96a..0055a28b 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -29,7 +29,7 @@ The builder's "name" must be given to the **-b** command-line option of also generates HTML Help support files that allow the Microsoft HTML Help Workshop to compile them into a CHM file. - Its name is ``htmlhelp``. + Its name is ``htmlhelp``. .. module:: sphinx.builders.latex .. class:: LaTeXBuilder @@ -85,7 +85,7 @@ The builder's "name" must be given to the **-b** command-line option of .. _PHP serialization: http://pypi.python.org/pypi/phpserialize .. attribute:: implementation - + A module that implements `dump()`, `load()`, `dumps()` and `loads()` functions that conform to the functions with the same names from the pickle module. Known modules implementing this interface are diff --git a/doc/concepts.rst b/doc/concepts.rst index 379888ff..afb9503b 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -55,19 +55,19 @@ tables of contents. The ``toctree`` directive is the central element. ``strings`` and so forth, and it knows that they are children of the shown document, the library index. From this information it generates "next chapter", "previous chapter" and "parent chapter" links. - + Document titles in the :dir:`toctree` will be automatically read from the title of the referenced document. If that isn't what you want, you can give the specify an explicit title and target using a similar syntax to reST hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This looks like:: - + .. toctree:: - + intro All about strings <strings> datatypes - + The second line above will link to the ``strings`` document, but will use the title "All about strings" instead of the title of the ``strings`` document. @@ -97,7 +97,7 @@ tables of contents. The ``toctree`` directive is the central element. This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive -- this makes sense if you intend to insert these links yourself, in a different style. - + In the end, all documents in the :term:`source directory` (or subdirectories) must occur in some ``toctree`` directive; Sphinx will emit a warning if it finds a file that is not included, because that means that this file will not diff --git a/doc/conf.py b/doc/conf.py index b3bd7149..e1c89eae 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -59,7 +59,7 @@ html_use_opensearch = 'http://sphinx.pocoo.org' htmlhelp_basename = 'Sphinxdoc' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). +# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation', 'Georg Brandl', 'manual', 1)] @@ -125,5 +125,6 @@ def setup(app): app.add_description_unit('directive', 'dir', 'pair: %s; directive', parse_directive) app.add_description_unit('role', 'role', 'pair: %s; role', parse_role) - app.add_description_unit('confval', 'confval', 'pair: %s; configuration value') + app.add_description_unit('confval', 'confval', + 'pair: %s; configuration value') app.add_description_unit('event', 'event', 'pair: %s; event', parse_event) diff --git a/doc/config.rst b/doc/config.rst index dd25cf22..ff2ca909 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -76,7 +76,7 @@ General configuration .. versionadded:: 0.5 Previously, Sphinx accepted only UTF-8 encoded sources. - + .. confval:: master_doc The document name of the "master" document, that is, the document that @@ -166,7 +166,7 @@ General configuration Project information ------------------- - + .. confval:: project The documented project's name. @@ -233,7 +233,7 @@ Project information :ref:`code-examples` for more details. .. versionadded:: 0.5 - + .. confval:: pygments_style The style name to use for Pygments highlighting of source code. Default is @@ -341,7 +341,7 @@ that use Sphinx' HTMLWriter class. .. versionadded:: 0.6 Previously, this was always activated. - + .. confval:: html_sidebars Custom sidebar templates, must be a dictionary that maps document names to @@ -439,7 +439,7 @@ that use Sphinx' HTMLWriter class. support different web server setups). .. versionadded:: 0.6 - + .. confval:: html_translator_class A string with the fully-qualified name of a HTML Translator class, that is, a @@ -527,7 +527,7 @@ These options influence LaTeX output. avoid interpretation as escape sequences. * Keys that you may want to override include: - + ``'papersize'`` Paper size option of the document class (``'a4paper'`` or ``'letterpaper'``), default ``'letterpaper'``. @@ -551,9 +551,9 @@ These options influence LaTeX output. Additional preamble content, default empty. ``'footer'``` Additional footer content (before the indices), default empty. - + * Keys that don't need be overridden unless in special cases are: - + ``'inputenc'`` "inputenc" package inclusion, default ``'\\usepackage[utf8]{inputenc}'``. @@ -570,9 +570,9 @@ These options influence LaTeX output. "printindex" call, the last thing in the file, default ``'\\printindex'``. Override if you want to generate the index differently or append some content after the index. - + * Keys that are set by other options and therefore should not be overridden are: - + ``'docclass'`` ``'classoptions'`` ``'title'`` @@ -585,7 +585,7 @@ These options influence LaTeX output. ``'makemodindex'`` ``'shorthandoff'`` ``'printmodindex'`` - + .. confval:: latex_preamble Additional LaTeX markup for the preamble. diff --git a/doc/contents.rst b/doc/contents.rst index 6ddbcbcb..5a1187ee 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -14,7 +14,7 @@ Sphinx documentation contents config templating extensions - + glossary changes examples diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 3dd5282b..84978da3 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -45,12 +45,12 @@ the following public API: :exc:`docutils.nodes.SkipNode`. Example:: class math(docutils.nodes.Element) - + def visit_math_html(self, node): self.body.append(self.starttag(node, 'math')) def depart_math_html(self, node): self.body.append('</math>') - + app.add_node(math, html=(visit_math_html, depart_math_html)) Obviously, translators for which you don't specify visitor methods will choke @@ -174,7 +174,7 @@ the following public API: highlight code blocks with the given language *alias*. .. versionadded:: 0.6 - + .. method:: Sphinx.connect(event, callback) Register *callback* to be called when *event* is emitted. For details on @@ -237,7 +237,7 @@ registered event handlers. since the module declarations could have been removed from the file. .. versionadded:: 0.5 - + .. event:: source-read (app, docname, source) Emitted when a source file has been read. The *source* argument is a list @@ -249,7 +249,7 @@ registered event handlers. ``:math:`...```. .. versionadded:: 0.5 - + .. event:: doctree-read (app, doctree) Emitted when a doctree has been parsed and read by the environment, and is @@ -271,7 +271,7 @@ registered event handlers. future reference and should be a child of the returned reference node. .. versionadded:: 0.5 - + .. event:: doctree-resolved (app, doctree, docname) Emitted when a doctree has been "resolved" by the environment, that is, all @@ -287,7 +287,7 @@ registered event handlers. completed, that is, the environment and all doctrees are now up-to-date. .. versionadded:: 0.5 - + .. event:: page-context (app, pagename, templatename, context, doctree) Emitted when the HTML builder has created a context dictionary to render a @@ -318,7 +318,7 @@ registered event handlers. cleanup actions depending on the exception status. .. versionadded:: 0.5 - + .. _template-bridge: diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index e0766938..11ea4ab4 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -61,7 +61,7 @@ directive. Boil the noodle *time* minutes. **Options and advanced usage** - + * If you want to automatically document members, there's a ``members`` option:: diff --git a/doc/ext/doctest.rst b/doc/ext/doctest.rst index 7117f6a9..19905dc7 100644 --- a/doc/ext/doctest.rst +++ b/doc/ext/doctest.rst @@ -131,7 +131,7 @@ completely equivalent. :: Test-Output example: - .. testcode:: + .. testcode:: parrot.voom(3000) @@ -156,7 +156,7 @@ There are also these config values for customizing the doctest extension: e.g. import modules you will always need in your doctests. .. versionadded:: 0.6 - + .. confval:: doctest_test_doctest_blocks If this is a nonempty string (the default is ``'default'``), standard reST @@ -187,7 +187,7 @@ There are also these config values for customizing the doctest extension: >>> print 1 1 - Some more documentation text. + Some more documentation text. This feature makes it easy for you to test doctests in docstrings included with the :mod:`~sphinx.ext.autodoc` extension without marking them up with a diff --git a/doc/ext/intersphinx.rst b/doc/ext/intersphinx.rst index befae2c0..302ab6a3 100644 --- a/doc/ext/intersphinx.rst +++ b/doc/ext/intersphinx.rst @@ -49,7 +49,7 @@ linking: This will download the corresponding :file:`objects.inv` file from the Internet and generate links to the pages under the given URI. The downloaded inventory is cached in the Sphinx environment, so it must be redownloaded - whenever you do a full rebuild. + whenever you do a full rebuild. A second example, showing the meaning of a non-``None`` value:: diff --git a/doc/ext/math.rst b/doc/ext/math.rst index f2664dfe..57d844ff 100644 --- a/doc/ext/math.rst +++ b/doc/ext/math.rst @@ -90,7 +90,7 @@ further translation is necessary when building LaTeX output. Euler's identity, equation :eq:`euler`, was elected one of the most beautiful mathematical formulas. - + :mod:`sphinx.ext.pngmath` -- Render math as PNG images ------------------------------------------------------ @@ -133,7 +133,7 @@ There are various config values you can set to influence how the images are buil list. .. versionadded:: 0.5.1 - + .. confval:: pngmath_latex_preamble Additional LaTeX code to put into the preamble of the short LaTeX files that @@ -145,7 +145,7 @@ There are various config values you can set to influence how the images are buil Additional arguments to give to dvipng, as a list. The default value is ``['-gamma 1.5', '-D 110']`` which makes the image a bit darker and larger then it is by default. - + An arguments you might want to add here is e.g. ``'-bg Transparent'``, which produces PNGs with a transparent background. This is not enabled by default because some Internet Explorer versions don't like transparent PNGs. diff --git a/doc/ext/todo.rst b/doc/ext/todo.rst index 7bc65a02..4f5a379d 100644 --- a/doc/ext/todo.rst +++ b/doc/ext/todo.rst @@ -21,9 +21,9 @@ There are two additional directives when using this extension: This directive is replaced by a list of all todo directives in the whole documentation, if :confval:`todo_include_todos` is true. - + There is also an additional config value: - + .. confval:: todo_include_todos If this is ``True``, :dir:`todo` and :dir:`todolist` produce output, else diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst index ae9b7a77..85763e83 100644 --- a/doc/ext/tutorial.rst +++ b/doc/ext/tutorial.rst @@ -158,7 +158,7 @@ Let's start with the node classes:: def visit_todo_node(self, node): self.visit_admonition(node) - + def depart_todo_node(self, node): self.depart_admonition(node) @@ -190,14 +190,14 @@ The ``todo`` directive function looks like this:: def todo_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): env = state.document.settings.env - + targetid = "todo-%s" % env.index_num env.index_num += 1 targetnode = nodes.target('', '', ids=[targetid]) - + ad = make_admonition(todo, name, [_('Todo')], options, content, lineno, content_offset, block_text, state, state_machine) - + if not hasattr(env, 'todo_all_todos'): env.todo_all_todos = [] env.todo_all_todos.append({ @@ -206,7 +206,7 @@ The ``todo`` directive function looks like this:: 'todo': ad[0].deepcopy(), 'target': targetnode, }) - + return [targetnode] + ad Several important things are covered here. First, as you can see, you can refer @@ -264,18 +264,18 @@ emitted at the end of phase 3 and allows custom resolving to be done:: if not app.config.todo_include_todos: for node in doctree.traverse(todo_node): node.parent.remove(node) - + # Replace all todolist nodes with a list of the collected todos. # Augment each todo with a backlink to the original location. env = app.builder.env - + for node in doctree.traverse(todolist): if not app.config.todo_include_todos: node.replace_self([]) continue - + content = [] - + for todo_info in env.todo_all_todos: para = nodes.paragraph() filename = env.doc2path(todo_info['docname'], base=None) @@ -283,7 +283,7 @@ emitted at the end of phase 3 and allows custom resolving to be done:: _('(The original entry is located in %s, line %d and can be found ') % (filename, todo_info['lineno'])) para += nodes.Text(description, description) - + # Create a reference newnode = nodes.reference('', '') innernode = nodes.emphasis(_('here'), _('here')) @@ -294,11 +294,11 @@ emitted at the end of phase 3 and allows custom resolving to be done:: newnode.append(innernode) para += newnode para += nodes.Text('.)', '.)') - + # Insert into the todolist content.append(todo_info['todo']) content.append(para) - + node.replace_self(content) It is a bit more involved. If our new "todo_include_todos" config value is diff --git a/doc/intro.rst b/doc/intro.rst index 7ce9d1fa..f9e23e18 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -109,7 +109,7 @@ The :program:`sphinx-build` script has several more options: Don't look for a configuration file; only take options via the ``-D`` option. .. versionadded:: 0.5 - + **-D** *setting=value* Override a configuration value set in the :file:`conf.py` file. The value must be a string or dictionary value. For the latter, supply the setting diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 0bf8343b..4872d6a4 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -101,7 +101,7 @@ Includes The directive also supports the ``linenos`` flag option to switch on line numbers, and a ``language`` option to select a language different from the current file's standard language. Example with options:: - + .. literalinclude:: example.rb :language: ruby :linenos: diff --git a/doc/markup/desc.rst b/doc/markup/desc.rst index 67605c77..ec8ede37 100644 --- a/doc/markup/desc.rst +++ b/doc/markup/desc.rst @@ -260,7 +260,7 @@ explained by an example:: .. function:: format_exception(etype, value, tb[, limit=None]) Format the exception with a traceback. - + :param etype: exception type :param value: exception value :param tb: traceback object diff --git a/doc/markup/para.rst b/doc/markup/para.rst index b071e46c..2ea2fd2d 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -1,4 +1,4 @@ -.. highlight:: rest +x.. highlight:: rest Paragraph-level markup ---------------------- @@ -85,9 +85,9 @@ units as well as normal text: This directive creates a paragraph heading that is not used to create a table of contents node. - + .. note:: - + If the *title* of the rubric is "Footnotes", this rubric is ignored by the LaTeX writer, since it is assumed to only contain footnote definitions and therefore would create an empty heading. @@ -239,7 +239,7 @@ the definition of the symbol. There is this directive: Note that no further reST parsing is done in the production, so that you don't have to escape ``*`` or ``|`` characters. -.. XXX describe optional first parameter +.. XXX describe optional first parameter The following is an example taken from the Python Reference Manual:: diff --git a/doc/rest.rst b/doc/rest.rst index d7ef5c7b..2b6ba8c5 100644 --- a/doc/rest.rst +++ b/doc/rest.rst @@ -282,7 +282,7 @@ markup blocks, like this:: See the `reST reference for substitutions <http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions>`_ for details. - + If you want to use some substitutions for all documents, put them into a separate file and include it into all documents you want to use them in, using the :dir:`include` directive. Be sure to give the include file a file name @@ -301,7 +301,7 @@ footnotes above) is regarded as a comment. For example:: .. This is a comment. You can indent text after a comment start to form multiline comments:: - + .. This whole indented block is a comment. @@ -329,5 +329,5 @@ There are some problems one commonly runs into while authoring reST documents: * **No nested inline markup:** Something like ``*see :func:`foo`*`` is not possible. - + .. XXX more? diff --git a/setup.py b/setup.py index 37cdd1e8..095ef114 100644 --- a/setup.py +++ b/setup.py @@ -98,7 +98,8 @@ else: else: for locale in os.listdir(self.directory): po_file = os.path.join(self.directory, locale, - 'LC_MESSAGES', self.domain + '.po') + 'LC_MESSAGES', + self.domain + '.po') if os.path.exists(po_file): po_files.append((locale, po_file)) js_files.append(os.path.join(self.directory, locale, diff --git a/sphinx/theming.py b/sphinx/theming.py index ff14dacc..d0727c98 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -5,7 +5,7 @@ Theming support for HTML builders. - :copyright: 2007-2009 by the Sphinx team, see AUTHORS. + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. :license: BSD, see LICENSE for details. """ diff --git a/tests/root/conf.py b/tests/root/conf.py index 12951d03..a2054f45 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -5,9 +5,6 @@ # # This file is execfile()d with the current directory set to its containing dir. # -# 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). -# # All configuration values have a default value; values that are commented out # serve to show the default value. @@ -57,8 +54,8 @@ today_fmt = '%B %d, %Y' # List of documents that shouldn't be included in the build. #unused_docs = [] -# List of directories, relative to source directories, that shouldn't be searched -# for source files. +# List of directories, relative to source directories, that shouldn't be +# searched for source files. exclude_trees = ['_build'] keep_warnings = True @@ -150,7 +147,7 @@ htmlhelp_basename = 'SphinxTestsdoc' #latex_font_size = '10pt' # Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, document class [howto/manual]). +# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('contents', 'SphinxTests.tex', 'Sphinx Tests Documentation', 'Georg Brandl', 'manual'), diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 67220180..d59ff304 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -131,7 +131,8 @@ def test_format_signature(): # test for functions def f(a, b, c=1, **d): pass - assert gen.format_signature('function', 'f', f, None, None) == '(a, b, c=1, **d)' + assert gen.format_signature('function', 'f', f, None, None) == \ + '(a, b, c=1, **d)' assert gen.format_signature('function', 'f', f, 'a, b, c, d', None) == \ '(a, b, c, d)' assert gen.format_signature('function', 'f', f, None, 'None') == \ @@ -151,7 +152,8 @@ def test_format_signature(): class G(F, object): pass for C in (F, G): - assert gen.format_signature('class', 'C', C, None, None) == '(a, b=None)' + assert gen.format_signature('class', 'C', C, None, None) == \ + '(a, b=None)' assert gen.format_signature('class', 'C', D, 'a, b', 'X') == '(a, b) -> X' # test for methods @@ -160,12 +162,16 @@ def test_format_signature(): pass def foo2(b, *c): pass - assert gen.format_signature('method', 'H.foo', H.foo1, None, None) == '(b, *c)' - assert gen.format_signature('method', 'H.foo', H.foo1, 'a', None) == '(a)' - assert gen.format_signature('method', 'H.foo', H.foo2, None, None) == '(b, *c)' + assert gen.format_signature('method', 'H.foo', H.foo1, None, None) == \ + '(b, *c)' + assert gen.format_signature('method', 'H.foo', H.foo1, 'a', None) == \ + '(a)' + assert gen.format_signature('method', 'H.foo', H.foo2, None, None) == \ + '(b, *c)' # test exception handling - raises(RuntimeError, gen.format_signature, 'function', 'int', int, None, None) + raises(RuntimeError, gen.format_signature, + 'function', 'int', int, None, None) # test processing by event handler assert gen.format_signature('method', 'bar', H.foo1, None, None) == '42' @@ -248,7 +254,8 @@ def test_docstring_processing(): # docstring processing by event handler assert process('class', 'bar', E) == ['Init docstring', '', '42', ''] - lid = app.connect('autodoc-process-docstring', cut_lines(1, 1, ['function'])) + lid = app.connect('autodoc-process-docstring', + cut_lines(1, 1, ['function'])) def f(): """ first line @@ -289,7 +296,8 @@ def test_generate(): del processed_docstrings[:] del processed_signatures[:] assert_works(*args) - assert set(processed_docstrings) | set(processed_signatures) == set(items) + assert set(processed_docstrings) | set(processed_signatures) == \ + set(items) def assert_result_contains(item, *args): gen.generate(*args) @@ -313,8 +321,10 @@ def test_generate(): assert_result_contains(' Function.', 'method', 'Class.meth', [], None) add_content = ViewList() add_content.append('Content.', '', 0) - assert_result_contains(' Function.', 'method', 'Class.meth', [], add_content) - assert_result_contains(' Content.', 'method', 'Class.meth', [], add_content) + assert_result_contains(' Function.', 'method', + 'Class.meth', [], add_content) + assert_result_contains(' Content.', 'method', + 'Class.meth', [], add_content) # test check_module gen.generate('function', 'raises', None, None, check_module=True) @@ -342,20 +352,23 @@ def test_generate(): assert_processes(should, 'class', 'Class', ['__all__'], None) # test module flags - assert_result_contains('.. module:: test_autodoc', 'module', - 'test_autodoc', [], None) + assert_result_contains('.. module:: test_autodoc', + 'module', 'test_autodoc', [], None) options.synopsis = 'Synopsis' - assert_result_contains(' :synopsis: Synopsis', 'module', 'test_autodoc', [], None) + assert_result_contains(' :synopsis: Synopsis', + 'module', 'test_autodoc', [], None) options.deprecated = True - assert_result_contains(' :deprecated:', 'module', 'test_autodoc', [], None) + assert_result_contains(' :deprecated:', + 'module', 'test_autodoc', [], None) options.platform = 'Platform' - assert_result_contains(' :platform: Platform', 'module', 'test_autodoc', [], None) + assert_result_contains(' :platform: Platform', + 'module', 'test_autodoc', [], None) # test if __all__ is respected for modules - assert_result_contains('.. class:: Class', 'module', 'test_autodoc', - ['__all__'], None) + assert_result_contains('.. class:: Class', + 'module', 'test_autodoc', ['__all__'], None) try: - assert_result_contains('.. exception:: CustomEx', 'module', 'test_autodoc', - ['__all__'], None) + assert_result_contains('.. exception:: CustomEx', + 'module', 'test_autodoc', ['__all__'], None) except AssertionError: pass else: @@ -378,8 +391,10 @@ def test_generate(): # test generation for C modules (which have no source file) gen.env.currmodule = 'time' - assert_processes([('function', 'time.asctime')], 'function', 'asctime', [], None) - assert_processes([('function', 'time.asctime')], 'function', 'asctime', [], None) + assert_processes([('function', 'time.asctime')], + 'function', 'asctime', [], None) + assert_processes([('function', 'time.asctime')], + 'function', 'asctime', [], None) # --- generate fodder ------------ diff --git a/tests/test_build.py b/tests/test_build.py index 9999abd0..cb206979 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -30,9 +30,10 @@ latex_warnfile = StringIO() ENV_WARNINGS = """\ WARNING: %(root)s/images.txt:9: Image file not readable: foo.png -WARNING: %(root)s/images.txt:23: Nonlocal image URI found: http://www.python.org/logo.png -WARNING: %(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading included \ -file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option +WARNING: %(root)s/images.txt:23: Nonlocal image URI found: \ +http://www.python.org/logo.png +WARNING: %(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading \ +included file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option WARNING: %(root)s/includes.txt:56: Download file not readable: nonexisting.png """ @@ -172,12 +173,15 @@ def test_latex(app): return True if kpsetest('article.sty') is None: - print >>sys.stderr, 'info: not running latex, it doesn\'t seem to be installed' + print >>sys.stderr, \ + 'info: not running latex, it doesn\'t seem to be installed' return - for filename in ['fancyhdr.sty', 'fancybox.sty', 'titlesec.sty', 'amsmath.sty', - 'framed.sty', 'color.sty', 'fancyvrb.sty', 'threeparttable.sty']: + for filename in ['fancyhdr.sty', 'fancybox.sty', 'titlesec.sty', + 'amsmath.sty', 'framed.sty', 'color.sty', 'fancyvrb.sty', + 'threeparttable.sty']: if not kpsetest(filename): - print >>sys.stderr, 'info: not running latex, the %s package doesn\'t ' \ + print >>sys.stderr, \ + 'info: not running latex, the %s package doesn\'t ' \ 'seem to be installed' % filename return @@ -186,8 +190,8 @@ def test_latex(app): os.chdir(app.outdir) try: try: - p = Popen(['pdflatex', '--interaction=nonstopmode', 'SphinxTests.tex'], - stdout=PIPE, stderr=PIPE) + p = Popen(['pdflatex', '--interaction=nonstopmode', + 'SphinxTests.tex'], stdout=PIPE, stderr=PIPE) except OSError, err: pass # most likely pdflatex was not found else: diff --git a/tests/test_env.py b/tests/test_env.py index 685311e6..32d87ebf 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -54,7 +54,8 @@ def test_images(): app._warning.reset() htmlbuilder = StandaloneHTMLBuilder(app, env) htmlbuilder.post_process_images(tree) - assert "no matching candidate for image URI u'foo.*'" in app._warning.content[-1] + assert "no matching candidate for image URI u'foo.*'" in \ + app._warning.content[-1] assert set(htmlbuilder.images.keys()) == set(['subdir/img.png', 'img.png', 'subdir/simg.png']) assert set(htmlbuilder.images.values()) == set(['img.png', 'img1.png', @@ -63,8 +64,10 @@ def test_images(): app._warning.reset() latexbuilder = LaTeXBuilder(app, env) latexbuilder.post_process_images(tree) - assert "no matching candidate for image URI u'foo.*'" in app._warning.content[-1] - assert set(latexbuilder.images.keys()) == set(['subdir/img.png', 'subdir/simg.png', + assert "no matching candidate for image URI u'foo.*'" in \ + app._warning.content[-1] + assert set(latexbuilder.images.keys()) == set(['subdir/img.png', + 'subdir/simg.png', 'img.png', 'img.pdf']) assert set(latexbuilder.images.values()) == set(['img.pdf', 'img.png', 'img1.png', 'simg.png']) diff --git a/tests/test_markup.py b/tests/test_markup.py index 99c85911..cd6de561 100644 --- a/tests/test_markup.py +++ b/tests/test_markup.py @@ -25,7 +25,8 @@ def setup_module(): global app, settings, parser texescape.init() # otherwise done by the latex builder app = TestApp(cleanenv=True) - optparser = frontend.OptionParser(components=(rst.Parser, HTMLWriter, LaTeXWriter)) + optparser = frontend.OptionParser( + components=(rst.Parser, HTMLWriter, LaTeXWriter)) settings = optparser.get_default_values() settings.env = app.builder.env parser = rst.Parser() @@ -85,7 +86,8 @@ def test_inline(): # interpolation of braces in samp and file roles (HTML only) verify(':samp:`a{b}c`', '<p><tt class="docutils literal"><span class="pre">a</span>' - '<em><span class="pre">b</span></em><span class="pre">c</span></tt></p>', + '<em><span class="pre">b</span></em>' + '<span class="pre">c</span></tt></p>', '\\samp{abc}') # interpolation of arrows in menuselection diff --git a/tests/util.py b/tests/util.py index 03363af9..dcaf74ad 100644 --- a/tests/util.py +++ b/tests/util.py @@ -97,7 +97,8 @@ class TestApp(application.Sphinx): """ def __init__(self, srcdir=None, confdir=None, outdir=None, doctreedir=None, - buildername='html', confoverrides=None, status=None, warning=None, + buildername='html', confoverrides=None, + status=None, warning=None, freshenv=None, confname='conf.py', cleanenv=False): application.CONFIG_FILENAME = confname diff --git a/utils/check_sources.py b/utils/check_sources.py index def13ee9..8a115c71 100755 --- a/utils/check_sources.py +++ b/utils/check_sources.py @@ -30,7 +30,7 @@ def checker(*suffixes, **kwds): name_mail_re = r'[\w ]+(<.*?>)?' -copyright_re = re.compile(r'^ :copyright: Copyright 200\d(-200\d)?' +copyright_re = re.compile(r'^ :copyright: Copyright 200\d(-200\d)? ' r'by %s(, %s)*[,.]$' % (name_mail_re, name_mail_re)) license_re = re.compile(r" :license: (.*?).\n") @@ -142,7 +142,7 @@ def check_fileheader(fn, lines): yield 0, "no correct copyright info" -@checker('.py', '.html') +@checker('.py', '.html', '.rst') def check_whitespace_and_spelling(fn, lines): for lno, line in enumerate(lines): if "\t" in line: @@ -154,7 +154,7 @@ def check_whitespace_and_spelling(fn, lines): yield lno+1, '"%s" used' % word -bad_tags = ('<b>', '<i>', '<u>', '<s>', '<strike>' +bad_tags = ('<u>', '<s>', '<strike>' '<center>', '<big>', '<small>', '<font') @checker('.html') diff --git a/utils/reindent.py b/utils/reindent.py index e6ee8287..c499f671 100755 --- a/utils/reindent.py +++ b/utils/reindent.py @@ -8,7 +8,8 @@ -d (--dryrun) Dry run. Analyze, but don't make any changes to files. -r (--recurse) Recurse. Search for all .py files in subdirectories too. -B (--no-backup) Don't write .bak backup files. --v (--verbose) Verbose. Print informative msgs; else only names of changed files. +-v (--verbose) Verbose. Print informative msgs; else only names of \ +changed files. -h (--help) Help. Print this usage information and exit. Change Python (.py) files to use 4-space indents and no hard tab characters. @@ -118,7 +119,8 @@ def check(file): if dryrun: print "But this is a dry run, so leaving it alone." else: - print "reindented", file, (dryrun and "(dry run => not really)" or "") + print "reindented", file, \ + (dryrun and "(dry run => not really)" or "") if not dryrun: if not no_backup: bak = file + ".bak" -- cgit v1.2.1 From b168c19de190a4b5bc1702ee66738c944bd8147d Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 10 Jan 2009 22:32:19 +0100 Subject: Fix bugs in the template loader and the changes builder. --- sphinx/builders/changes.py | 6 +++++- sphinx/jinja2glue.py | 3 ++- 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py index 6f057b49..d4520fa5 100644 --- a/sphinx/builders/changes.py +++ b/sphinx/builders/changes.py @@ -129,8 +129,12 @@ class ChangesBuilder(Builder): f.write(self.templates.render('changes/rstsource.html', ctx)) finally: f.close() - shutil.copyfile(path.join(package_dir, 'static', 'default.css'), + shutil.copyfile(path.join(package_dir, 'themes', 'default', + 'static', 'default.css'), path.join(self.outdir, 'default.css')) + shutil.copyfile(path.join(package_dir, 'themes', 'basic', + 'static', 'basic.css'), + path.join(self.outdir, 'basic.css')) def hl(self, text, version): text = escape(text) diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index fc3efc01..c5160376 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -35,7 +35,8 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): # prepend explicit template paths if builder.config.templates_path: - chain[0:0] = builder.config.templates_path + chain[0:0] = [path.join(builder.confdir, tp) + for tp in builder.config.templates_path] # make the paths into loaders self.loaders = map(jinja2.FileSystemLoader, chain) -- cgit v1.2.1 From cd95e96150ea161c144180a55dd4b2195454b102 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 10 Jan 2009 22:32:54 +0100 Subject: Clean up tests conf.py, no need to include comments. --- tests/root/conf.py | 142 ++--------------------------------------------------- 1 file changed, 4 insertions(+), 138 deletions(-) diff --git a/tests/root/conf.py b/tests/root/conf.py index a2054f45..e9a6f15d 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -1,175 +1,41 @@ # -*- coding: utf-8 -*- -# -# Sphinx Tests documentation build configuration file, created by -# sphinx-quickstart on Wed Jun 4 23:49:58 2008. -# -# This file is execfile()d with the current directory set to its containing dir. -# -# All configuration values have a default value; values that are commented out -# serve to show the default value. import sys, os -# If your extensions are in another directory, add it here. If the directory -# is relative to the documentation root, use os.path.abspath to make it -# absolute, like shown here. sys.path.append(os.path.abspath('.')) -# General configuration -# --------------------- - -# Add any Sphinx extension module names here, as strings. They can be extensions -# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. extensions = ['ext', 'sphinx.ext.autodoc', 'sphinx.ext.jsmath', 'sphinx.ext.coverage', 'sphinx.ext.todo'] + jsmath_path = 'dummy.js' -# Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix of source filenames. -source_suffix = '.txt' - -# The master toctree document. master_doc = 'contents' +source_suffix = '.txt' -# General substitutions. project = 'Sphinx <Tests>' copyright = '2008, Georg Brandl & Team' - -# The default replacements for |version| and |release|, also used in various -# other places throughout the built documents. -# -# The short X.Y version. -version = '0.4' -# The full version, including alpha/beta/rc tags. -release = '0.4alpha1' - -# 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. +version = '0.6' +release = '0.6alpha1' today_fmt = '%B %d, %Y' - -# List of documents that shouldn't be included in the build. #unused_docs = [] - -# List of directories, relative to source directories, that shouldn't be -# searched for source files. exclude_trees = ['_build'] - keep_warnings = True - -# If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True - -# If true, the current module name will be prepended to all description -# unit titles (such as .. function::). -#add_module_names = True - -# If true, sectionauthor and moduleauthor directives will be shown in the -# output. They are ignored by default. -#show_authors = False - -# The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' - -# Options for HTML output -# ----------------------- - -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. html_style = 'default.css' - -# The name for this set of Sphinx documents. If None, it defaults to -# "<project> v<release> documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (within the static path) to place at the top of -# the sidebar. -#html_logo = None - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -#html_sidebars = {} - -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -#html_use_modindex = True - -# If false, no index is generated. -#html_use_index = True - -# If true, the reST sources are included in the HTML build as _sources/<name>. -#html_copy_source = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a <link> tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = '' - html_context = {'hckey': 'hcval'} -# Output file base name for HTML help builder. htmlhelp_basename = 'SphinxTestsdoc' - -# Options for LaTeX output -# ------------------------ - -# The paper size ('letter' or 'a4'). -#latex_paper_size = 'letter' - -# The font size ('10pt', '11pt' or '12pt'). -#latex_font_size = '10pt' - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, author, documentclass [howto/manual]). latex_documents = [ ('contents', 'SphinxTests.tex', 'Sphinx Tests Documentation', 'Georg Brandl', 'manual'), ] -# The name of an image file (relative to this directory) to place at the top of -# the title page. -#latex_logo = None - -# For "manual" documents, if this is true, then toplevel headings are parts, -# not chapters. -#latex_use_parts = False - -# Additional stuff for the LaTeX preamble. -#latex_preamble = '' - -# Documents to append as an appendix to all manuals. -#latex_appendices = [] - -# If false, no module index is generated. -#latex_use_modindex = True - value_from_conf_py = 84 coverage_c_path = ['special/*.h'] -- cgit v1.2.1 From 66957f00d356e9b1a4c4b7e905330a9d039bbe62 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 11 Jan 2009 14:28:34 +0100 Subject: Fix the serializing builder. --- sphinx/builders/html.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 52854559..13cb8554 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -64,6 +64,7 @@ class StandaloneHTMLBuilder(Builder): def init(self): self.init_templates() + self.init_highlighter() self.init_translator_class() if self.config.html_file_suffix: self.out_suffix = self.config.html_file_suffix @@ -79,6 +80,7 @@ class StandaloneHTMLBuilder(Builder): if path.isfile(jsfile): self.script_files.append('_static/translations.js') + def init_highlighter(self): # determine Pygments style and create the highlighter if self.config.pygments_style is not None: style = self.config.pygments_style @@ -600,6 +602,7 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): def init(self): self.init_translator_class() + self.init_highlighter() self.templates = None # no template bridge necessary def get_target_uri(self, docname, typ=None): -- cgit v1.2.1 From 10375e47856fccee00bebc38b692541ea7315feb Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 14 Jan 2009 00:06:56 +0100 Subject: fix --- sphinx/util/__init__.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 08e619ee..edfb31d8 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -366,6 +366,7 @@ def force_decode(string, encoding): def movefile(source, dest): # move a file, removing the destination if it exists if os.path.exists(dest): + try: os.unlink(dest) except OSError: pass -- cgit v1.2.1 From 5710e17396814dee22169f8dbc340c30d90fe6ea Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 14 Jan 2009 00:30:34 +0100 Subject: Give <pre> blocks a uniform line-height. --- sphinx/static/default.css | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/static/default.css b/sphinx/static/default.css index 005caa1f..3a4ad73a 100644 --- a/sphinx/static/default.css +++ b/sphinx/static/default.css @@ -528,6 +528,7 @@ pre { padding: 5px; background-color: #efc; color: #333; + line-height: 120%; border: 1px solid #ac9; border-left: none; border-right: none; -- cgit v1.2.1 From 25bcacb4a61db2f265bf8bf38db1cd7cb0ff5abe Mon Sep 17 00:00:00 2001 From: mitsuhiko <devnull@localhost> Date: Sat, 17 Jan 2009 01:21:47 +0100 Subject: Autodoc can document classes as functions now if explicitly marked with `autofunction`. --- CHANGES | 3 +++ sphinx/ext/autodoc.py | 13 ++++++++++++- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 6f0ecbd0..600224a6 100644 --- a/CHANGES +++ b/CHANGES @@ -78,6 +78,9 @@ New features added - Autodoc now handles inner classes and their methods. + - Autodoc can document classes as functions now if explicitly + marked with `autofunction`. + - There is now a ``Sphinx.add_lexer()`` method to be able to use custom Pygments lexers easily. diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index d0512f2b..79443859 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -324,7 +324,18 @@ class RstGenerator(object): # can never get arguments of a C function or method getargs = False if getargs: - argspec = inspect.getargspec(obj) + try: + argspec = inspect.getargspec(obj) + except TypeError: + # if a class should be documented as function (yay duck + # typing) we try to use the constructor signature as function + # signature without the first argument. + try: + argspec = inspect.getargspec(obj.__new__) + except TypeError: + argspec = inspect.getargspec(obj.__init__) + if argspec[0]: + del argspec[0][0] if what in ('class', 'method', 'staticmethod', 'classmethod') and argspec[0] and \ argspec[0][0] in ('cls', 'self'): -- cgit v1.2.1 From 8e829b5beeabab928a75289e09f12cdf121e3f89 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 18 Jan 2009 14:41:47 +0100 Subject: Italian translation update. --- sphinx/locale/cs/LC_MESSAGES/sphinx.js | 2 +- sphinx/locale/cs/LC_MESSAGES/sphinx.mo | Bin 9018 -> 8268 bytes sphinx/locale/de/LC_MESSAGES/sphinx.mo | Bin 7839 -> 7111 bytes sphinx/locale/es/LC_MESSAGES/sphinx.mo | Bin 7341 -> 6617 bytes sphinx/locale/fr/LC_MESSAGES/sphinx.mo | Bin 8054 -> 7324 bytes sphinx/locale/it/LC_MESSAGES/sphinx.js | 2 +- sphinx/locale/it/LC_MESSAGES/sphinx.mo | Bin 8415 -> 7944 bytes sphinx/locale/it/LC_MESSAGES/sphinx.po | 43 +++++++++++++----------------- sphinx/locale/ja/LC_MESSAGES/sphinx.mo | Bin 8216 -> 7345 bytes sphinx/locale/nl/LC_MESSAGES/sphinx.mo | Bin 7599 -> 6882 bytes sphinx/locale/pl/LC_MESSAGES/sphinx.mo | Bin 7665 -> 6982 bytes sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo | Bin 7998 -> 7280 bytes sphinx/locale/sl/LC_MESSAGES/sphinx.mo | Bin 7674 -> 7016 bytes sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo | Bin 8033 -> 7368 bytes 14 files changed, 20 insertions(+), 27 deletions(-) diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.js b/sphinx/locale/cs/LC_MESSAGES/sphinx.js index 0684899d..42fa9abd 100644 --- a/sphinx/locale/cs/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "cs", "plural_expr": "(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"module, in ": "modul, v", "Preparing search...": "Připravuji hledání...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Nenalezli jsme žádný dokument. Ujistěte se prosím, že všechna slova jsou správně.", "Search finished, found %s page(s) matching the search query.": "Vyhledávání skončilo, nalezeno %s stran.", ", in ": ", v", "Permalink to this headline": "Trvalý odkaz na tento nadpis", "Searching": "Hledám", "Permalink to this definition": "Trvalý odkaz na tuto definici", "Hide Search Matches": "Skrýt výsledky hledání", "Search Results": "Výsledky hledání"}}); +Documentation.addTranslations({"locale": "cs", "plural_expr": "(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"module, in ": "modul, v", "Preparing search...": "P\u0159ipravuji vyhled\u00e1v\u00e1n\u00ed....", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Nenalezli jsme \u017e\u00e1dn\u00fd dokument. Ujist\u011bte se pros\u00edm, \u017ee v\u0161echna slova jsou spr\u00e1vn\u011b a \u017ee jste vybral dostatek kategori\u00ed.", "Search finished, found %s page(s) matching the search query.": "Vyhled\u00e1v\u00e1n\u00ed skon\u010dilo, nalezeno %s stran.", ", in ": ", v", "Permalink to this headline": "Trval\u00fd odkaz na tento nadpis", "Searching": "Hled\u00e1m", "Permalink to this definition": "Trval\u00fd odkaz na tuto definici", "Hide Search Matches": "Skr\u00fdt v\u00fdsledky vyhled\u00e1v\u00e1n\u00ed", "Search Results": "V\u00fdsledky hled\u00e1n\u00ed"}}); \ No newline at end of file diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo index fd97a57e..9178448d 100644 Binary files a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo and b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/de/LC_MESSAGES/sphinx.mo b/sphinx/locale/de/LC_MESSAGES/sphinx.mo index 462f7c7f..981da26a 100644 Binary files a/sphinx/locale/de/LC_MESSAGES/sphinx.mo and b/sphinx/locale/de/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/es/LC_MESSAGES/sphinx.mo b/sphinx/locale/es/LC_MESSAGES/sphinx.mo index d1ddb079..dcc8bbc2 100644 Binary files a/sphinx/locale/es/LC_MESSAGES/sphinx.mo and b/sphinx/locale/es/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/fr/LC_MESSAGES/sphinx.mo b/sphinx/locale/fr/LC_MESSAGES/sphinx.mo index 158e964a..32633296 100644 Binary files a/sphinx/locale/fr/LC_MESSAGES/sphinx.mo and b/sphinx/locale/fr/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.js b/sphinx/locale/it/LC_MESSAGES/sphinx.js index c2c8be7b..91a939a6 100644 --- a/sphinx/locale/it/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/it/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "it", "plural_expr": "(n != 1)", "messages": {"module, in ": "modulo, in", "Preparing search...": "Preparazione della ricerca", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "La tua ricerca non ha trovato alcun risultato. Controlla la corettezzadei termini di ricerca e di avere selezionato un numero sufficiente di categorie", "Search finished, found %s page(s) matching the search query.": "Ricera terminata, trovate %s pagine corrispondenti alla ricerca.", ", in ": ", in ", "Permalink to this headline": "link permanente per questa inestazione", "Searching": "Ricerca in corso", "Permalink to this definition": "link permanente per questa definizione", "Hide Search Matches": "Nascondi i risultati della ricerca", "Search Results": "Risultati della ricerca"}}); \ No newline at end of file +Documentation.addTranslations({"locale": "it", "plural_expr": "(n != 1)", "messages": {"module, in ": "modulo, in", "Preparing search...": "Preparazione della ricerca", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "La tua ricerca non ha trovato alcun risultato. Controlla la correttezza dei termini di ricerca e di avere selezionato un numero sufficiente di categorie", "Search finished, found %s page(s) matching the search query.": "Ricerca terminata, trovate %s pagine corrispondenti alla ricerca.", ", in ": ", in ", "Permalink to this headline": "link permanente per questa intestazione", "Searching": "Ricerca in corso", "Permalink to this definition": "link permanente per questa definizione", "Hide Search Matches": "Nascondi i risultati della ricerca", "Search Results": "Risultati della ricerca"}}); \ No newline at end of file diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.mo b/sphinx/locale/it/LC_MESSAGES/sphinx.mo index 7818e876..3aa570de 100644 Binary files a/sphinx/locale/it/LC_MESSAGES/sphinx.mo and b/sphinx/locale/it/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.po b/sphinx/locale/it/LC_MESSAGES/sphinx.po index 4545f4a8..73c88e2b 100644 --- a/sphinx/locale/it/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/it/LC_MESSAGES/sphinx.po @@ -2,19 +2,19 @@ # Copyright (C) 2008 ORGANIZATION # This file is distributed under the same license as the Sphinx project. # Sandro Dentella <sandro@e-den.it>, 2008. -# msgid "" msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-11-27 18:39+0100\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" -"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" -"Language-Team: it <LL@li.org>\n" -"Plural-Forms: nplurals=2; plural=(n != 1)\n" +"PO-Revision-Date: 2009-01-06 17:38+0200\n" +"Last-Translator: Sandro Dentella <sandro@e-den.it>\n" +"Language-Team: <sphinx-dev@googlegroups.com>\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" +"Plural-Forms: nplurals=2; plural=(n != 1)\n" +"X-Generator: Virtaal 0.2\n" "Generated-By: Babel 0.9.3\n" #: sphinx/environment.py:103 sphinx/writers/latex.py:170 @@ -41,7 +41,7 @@ msgstr "Cerca" #: sphinx/roles.py:53 sphinx/directives/desc.py:564 #, python-format msgid "environment variable; %s" -msgstr "variabile dámbiente, %s" +msgstr "variabile d'ambiente, %s" #: sphinx/roles.py:60 #, python-format @@ -155,7 +155,7 @@ msgstr "%s (%s attributo)" #: sphinx/directives/desc.py:74 #, python-format msgid "%s (C function)" -msgstr "%s (functione C)" +msgstr "%s (funzione C)" #: sphinx/directives/desc.py:76 #, python-format @@ -194,7 +194,6 @@ msgid "Return type" msgstr "Tipo di ritorno" #: sphinx/directives/desc.py:201 -#, fuzzy msgid "Parameter" msgstr "Parametri" @@ -235,7 +234,7 @@ msgstr "Vedi anche" #: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 #, python-format msgid "alias of :class:`%s`" -msgstr "" +msgstr "alias per :class:`%s`" #: sphinx/ext/todo.py:31 msgid "Todo" @@ -335,7 +334,7 @@ msgstr "funzione built-in" #: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 msgid "Permalink to this headline" -msgstr "link permanente per questa inestazione" +msgstr "link permanente per questa intestazione" #: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 msgid "Permalink to this definition" @@ -370,14 +369,13 @@ msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." msgstr "" -"La tua ricerca non ha trovato alcun risultato. Controlla la corettezzadei" -" termini di ricerca e di avere selezionato un numero sufficiente di " -"categorie" +"La tua ricerca non ha trovato alcun risultato. Controlla la correttezza dei " +"termini di ricerca e di avere selezionato un numero sufficiente di categorie" #: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." -msgstr "Ricera terminata, trovate %s pagine corrispondenti alla ricerca." +msgstr "Ricerca terminata, trovate %s pagine corrispondenti alla ricerca." #: sphinx/templates/defindex.html:2 msgid "Overview" @@ -432,7 +430,7 @@ msgstr "Navigazione" #: sphinx/templates/layout.html:40 msgid "Table Of Contents" -msgstr "Tablella dei contenuti" +msgstr "Tabella dei contenuti" #: sphinx/templates/layout.html:46 msgid "Previous topic" @@ -467,9 +465,8 @@ msgid "Go" msgstr "Vai" #: sphinx/templates/layout.html:73 -#, fuzzy msgid "Enter search terms or a module, class or function name." -msgstr "Inserisci un modulo, classe o nome di funzione" +msgstr "Inserisci un termine di ricerca un modulo, classe o nome di funzione" #: sphinx/templates/layout.html:106 #, python-format @@ -529,10 +526,8 @@ msgid "" " function will automatically search for all of the words. Pages\n" " containing fewer words won't appear in the result list." msgstr "" -"Puoi effettuare una ricerca in questi documenti. Immetti le parole chiave" -" \n" -" della tua ricerca nel riquadro sottostante \"search\". Nota che la " -"funzione\n" +"Puoi effettuare una ricerca in questi documenti. Immetti le parole chiave \n" +" della tua ricerca nel riquadro sottostante \"cerca\". Nota che la funzione\n" " di ricerca cerca automaticamente per tutte le parole. Le pagine\n" " che contendono meno parole non compariranno nei risultati di ricerca." @@ -562,18 +557,17 @@ msgstr "Lista delle modifiche generata automaticamente nella versione %(version) #: sphinx/templates/changes/versionchanges.html:18 msgid "Library changes" -msgstr "Modifiche nela libreria" +msgstr "Modifiche nella libreria" #: sphinx/templates/changes/versionchanges.html:23 msgid "C API changes" -msgstr "Modifche nelle API C" +msgstr "Modifiche nelle API C" #: sphinx/templates/changes/versionchanges.html:25 msgid "Other changes" msgstr "Altre modifiche" #: sphinx/writers/latex.py:173 -#, fuzzy msgid "Release" msgstr "Release" @@ -609,4 +603,3 @@ msgstr "[immagine]" #~ "non più valido. Abbiamo provato a " #~ "ridirigerti verso il nuovo indirizzo, ma" #~ " potrebbe non essere quello giusto" - diff --git a/sphinx/locale/ja/LC_MESSAGES/sphinx.mo b/sphinx/locale/ja/LC_MESSAGES/sphinx.mo index 66b1aa9d..85f6f8cc 100644 Binary files a/sphinx/locale/ja/LC_MESSAGES/sphinx.mo and b/sphinx/locale/ja/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/nl/LC_MESSAGES/sphinx.mo b/sphinx/locale/nl/LC_MESSAGES/sphinx.mo index 583a2993..2b6ac75e 100644 Binary files a/sphinx/locale/nl/LC_MESSAGES/sphinx.mo and b/sphinx/locale/nl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/pl/LC_MESSAGES/sphinx.mo b/sphinx/locale/pl/LC_MESSAGES/sphinx.mo index ec1f3602..b08244bf 100644 Binary files a/sphinx/locale/pl/LC_MESSAGES/sphinx.mo and b/sphinx/locale/pl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo index 647d4405..3044318a 100644 Binary files a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo and b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/sl/LC_MESSAGES/sphinx.mo b/sphinx/locale/sl/LC_MESSAGES/sphinx.mo index d5282768..e0936704 100644 Binary files a/sphinx/locale/sl/LC_MESSAGES/sphinx.mo and b/sphinx/locale/sl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo index 4412f12f..bd4acf00 100644 Binary files a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo and b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo differ -- cgit v1.2.1 From a7bb180ba708ffef173d0741a56ea41b8de1de06 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 18 Jan 2009 14:43:29 +0100 Subject: add Sqlkit and Reteisi. --- EXAMPLES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/EXAMPLES b/EXAMPLES index d3ac299c..e81947a3 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -36,9 +36,11 @@ included, please mail to `the Google group * Pylons: http://docs.pylonshq.com/ * Pysparse: http://pysparse.sourceforge.net/ * Python: http://docs.python.org/dev/ +* Reteisi: http://docs.argolinux.org/reteisi/ * Satchmo: http://www.satchmoproject.com/docs/svn/ * Sphinx: http://sphinx.pocoo.org/ * SQLAlchemy: http://www.sqlalchemy.org/docs/ +* Sqlkit: http://sqlkit.argolinux.org/ * SymPy: http://docs.sympy.org/ * tinyTiM: http://tinytim.sourceforge.net/docs/2.0/ * TurboGears: http://turbogears.org/2.0/docs/ -- cgit v1.2.1 From 58b27d1b50c0988e844af168669164a4f93629a2 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Thu, 22 Jan 2009 19:44:40 +0100 Subject: Add python-apt. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index e81947a3..ca4b9eca 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -36,6 +36,7 @@ included, please mail to `the Google group * Pylons: http://docs.pylonshq.com/ * Pysparse: http://pysparse.sourceforge.net/ * Python: http://docs.python.org/dev/ +* python-apt: http://people.debian.org/~jak/python-apt-doc/ * Reteisi: http://docs.argolinux.org/reteisi/ * Satchmo: http://www.satchmoproject.com/docs/svn/ * Sphinx: http://sphinx.pocoo.org/ -- cgit v1.2.1 From d599ad60aa2ada2bf3bcf5f908ca7c7a9d47b041 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Thu, 22 Jan 2009 20:01:01 +0100 Subject: Add add_generic_role(). --- CHANGES | 3 +++ doc/ext/appapi.rst | 7 +++++++ sphinx/application.py | 3 +++ 3 files changed, 13 insertions(+) diff --git a/CHANGES b/CHANGES index 6f0ecbd0..fb068d00 100644 --- a/CHANGES +++ b/CHANGES @@ -81,6 +81,9 @@ New features added - There is now a ``Sphinx.add_lexer()`` method to be able to use custom Pygments lexers easily. + - There is now ``Sphinx.add_generic_rol()`` to mirror the docutils' + own function. + * Other changes: - Config overrides for single dict keys can now be given on the diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 3dd5282b..00fd2e58 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -86,6 +86,13 @@ the following public API: source, *role* the role function (see the `Docutils documentation <http://docutils.sourceforge.net/docs/howto/rst-roles.html>`_ on details). +.. method:: Sphinx.add_generic_role(name, nodeclass) + + Register a Docutils role that does nothing but wrap its contents in the + node given by *nodeclass*. + + .. versionadded:: 0.6 + .. method:: Sphinx.add_description_unit(directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None) This method is a very convenient way to add a new type of information that diff --git a/sphinx/application.py b/sphinx/application.py index 1ad7823f..6840629d 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -279,6 +279,9 @@ class Sphinx(object): def add_role(self, name, role): roles.register_canonical_role(name, role) + def add_generic_role(self, name, nodeclass): + roles.register_generic_role(name, nodeclass) + def add_description_unit(self, directivename, rolename, indextemplate='', parse_node=None, ref_nodeclass=None): additional_xref_types[directivename] = (rolename, indextemplate, parse_node) -- cgit v1.2.1 From 147100cbc068e1bd7896c4cc7eedffc802558dbe Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Thu, 22 Jan 2009 20:12:40 +0100 Subject: Prevent encoding errors when filenames are non-ASCII. --- sphinx/ext/autodoc.py | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index d0512f2b..3ca92e86 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -449,7 +449,10 @@ class RstGenerator(object): # add content from attribute documentation if analyzer: - sourcename = '%s:docstring of %s' % (analyzer.srcname, fullname) + # prevent encoding errors when the file name is non-ASCII + srcname = unicode(analyzer.srcname, + sys.getfilesystemencoding(), 'replace') + sourcename = u'%s:docstring of %s' % (srcname, fullname) attr_docs = analyzer.find_attr_docs() if what in ('data', 'attribute'): key = ('.'.join(objpath[:-1]), objpath[-1]) @@ -460,7 +463,7 @@ class RstGenerator(object): fullname, todoc)): self.result.append(indent + line, sourcename, i) else: - sourcename = 'docstring of %s' % fullname + sourcename = u'docstring of %s' % fullname attr_docs = {} # add content from docstrings -- cgit v1.2.1 From 0c25a7d8c2cb52fa2cca4710281c72409944045e Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Thu, 22 Jan 2009 20:29:38 +0100 Subject: add doctest quickstart target. --- sphinx/quickstart.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index b1e44d38..52bbf719 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -257,7 +257,7 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) %(rsrcdir)s -.PHONY: help clean html pickle json htmlhelp qthelp latex changes linkcheck +.PHONY: help clean html pickle json htmlhelp qthelp latex changes linkcheck doctest help: \t@echo "Please use \\`make <target>' where <target> is one of" @@ -269,6 +269,7 @@ help: \t@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" \t@echo " changes to make an overview over all changed/added/deprecated items" \t@echo " linkcheck to check all external links for integrity" +\t@echo " doctest to run all doctests embedded in the documentation (if enabled)" clean: \t-rm -rf %(rbuilddir)s/* @@ -320,6 +321,11 @@ linkcheck: \t@echo \t@echo "Link check complete; look for any errors in the above output " \\ \t "or in %(rbuilddir)s/linkcheck/output.txt." + +doctest: +\t$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) %(rbuilddir)s/doctest +\t@echo "Testing of doctests in the sources finished, look at the " \\ +\t "results in %(rbuilddir)s/doctest/output.txt." ''' BATCHFILE = '''\ @@ -346,6 +352,7 @@ if "%%1" == "help" ( \techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter \techo. changes to make an overview over all changed/added/deprecated items \techo. linkcheck to check all external links for integrity +\techo. doctest to run all doctests embedded in the documentation (if enabled) \tgoto end ) @@ -417,6 +424,14 @@ or in %(rbuilddir)s/linkcheck/output.txt. \tgoto end ) +if "%%1" == "doctest" ( +\t%%SPHINXBUILD%% -b doctest %%ALLSPHINXOPTS%% %(rbuilddir)s/doctest +\techo. +\techo.Testing of doctests in the sources finished, look at the ^ +results in %(rbuilddir)s/doctest/output.txt. +\tgoto end +) + :end ''' -- cgit v1.2.1 From 98ee517f439d5705ac9fc875026c7cfaa816aea5 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Thu, 22 Jan 2009 20:31:09 +0100 Subject: add VOR-cycling.be --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index ca4b9eca..9359121f 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -45,6 +45,7 @@ included, please mail to `the Google group * SymPy: http://docs.sympy.org/ * tinyTiM: http://tinytim.sourceforge.net/docs/2.0/ * TurboGears: http://turbogears.org/2.0/docs/ +* VOR: http://www.vor-cycling.be/ * WFront: http://discorporate.us/projects/WFront/ * Zope 3: e.g. http://docs.carduner.net/z3c-tutorial/ * zc.async: http://packages.python.org/zc.async/1.5.0/ -- cgit v1.2.1 From 8c57da52ee409a7797c5abff0e74418fafb971fb Mon Sep 17 00:00:00 2001 From: Luc Saffre <luc.saffre@mail.ee> Date: Fri, 23 Jan 2009 06:49:42 -0300 Subject: make.bat failed on MS Windows XP Home --- sphinx/quickstart.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 52bbf719..73be0fdc 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -352,7 +352,7 @@ if "%%1" == "help" ( \techo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter \techo. changes to make an overview over all changed/added/deprecated items \techo. linkcheck to check all external links for integrity -\techo. doctest to run all doctests embedded in the documentation (if enabled) +\techo. doctest to run all doctests embedded in the documentation if enabled \tgoto end ) -- cgit v1.2.1 From 9989294db857fbf9a8be56ac2ab6b22d2de6718b Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 24 Jan 2009 18:44:29 +0000 Subject: Update catalog and German translations. --- sphinx/locale/cs/LC_MESSAGES/sphinx.po | 332 ++++++++++++++++-------------- sphinx/locale/de/LC_MESSAGES/sphinx.po | 167 +++++++-------- sphinx/locale/es/LC_MESSAGES/sphinx.po | 142 ++++++------- sphinx/locale/fr/LC_MESSAGES/sphinx.po | 143 ++++++------- sphinx/locale/it/LC_MESSAGES/sphinx.po | 154 +++++++------- sphinx/locale/ja/LC_MESSAGES/sphinx.po | 140 ++++++------- sphinx/locale/nl/LC_MESSAGES/sphinx.po | 143 ++++++------- sphinx/locale/pl/LC_MESSAGES/sphinx.po | 141 ++++++------- sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po | 142 ++++++------- sphinx/locale/sl/LC_MESSAGES/sphinx.po | 141 ++++++------- sphinx/locale/sphinx.pot | 121 ++++++----- sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po | 137 ++++++------ 12 files changed, 896 insertions(+), 1007 deletions(-) diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.po b/sphinx/locale/cs/LC_MESSAGES/sphinx.po index 0d11dded..7d727399 100644 --- a/sphinx/locale/cs/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/cs/LC_MESSAGES/sphinx.po @@ -8,107 +8,38 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-11-27 18:39+0100\n" -"PO-Revision-Date: 2008-12-25 05:59+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Pavel Kosina <pavel.kosina@gmail.com>\n" "Language-Team: Pavel Kosina <pavel.kosina@gmail.com>\n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n" "MIME-Version: 1.0\n" -"Content-Type: text/plain; charset=UTF-8\n" +"Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" -"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n" -"Generated-By: Babel 0.9.4\n" -"X-Poedit-Language: Czech\n" -"X-Poedit-Country: CZECH REPUBLIC\n" +"Generated-By: Babel 0.9.3\n" -#: sphinx/builder.py:408 -#, python-format -msgid "%b %d, %Y" -msgstr "%d.%m.%Y" - -#: sphinx/builder.py:427 -#: sphinx/templates/defindex.html:21 -msgid "General Index" -msgstr "Rejstřík indexů" - -#: sphinx/builder.py:427 -msgid "index" -msgstr "index" - -#: sphinx/builder.py:429 -#: sphinx/htmlhelp.py:156 -#: sphinx/templates/defindex.html:19 -#: sphinx/templates/modindex.html:2 -#: sphinx/templates/modindex.html:13 -msgid "Global Module Index" -msgstr "Celkový rejstřík modulů" - -#: sphinx/builder.py:429 -msgid "modules" -msgstr "moduly" - -#: sphinx/builder.py:466 -msgid "next" -msgstr "další" - -#: sphinx/builder.py:473 -msgid "previous" -msgstr "předchozí" - -#: sphinx/builder.py:1054 -msgid " (in " -msgstr "(v" - -#: sphinx/builder.py:1129 -msgid "Builtins" -msgstr "Vestavěné funkce " - -#: sphinx/builder.py:1131 -msgid "Module level" -msgstr "Úroveň modulů" - -#: sphinx/environment.py:102 -#: sphinx/latexwriter.py:169 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d.%m.%Y" -#: sphinx/environment.py:291 -#: sphinx/latexwriter.py:175 -#: sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 -#: sphinx/templates/genindex-split.html:5 -#: sphinx/templates/genindex.html:2 -#: sphinx/templates/genindex.html:5 -#: sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:130 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Index" -#: sphinx/environment.py:292 -#: sphinx/latexwriter.py:174 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Rejstřík modulů " -#: sphinx/environment.py:293 -#: sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Vyhledávací stránka" -#: sphinx/htmlwriter.py:79 -#: sphinx/static/doctools.js:145 -msgid "Permalink to this definition" -msgstr "Trvalý odkaz na tuto definici" - -#: sphinx/htmlwriter.py:399 -#: sphinx/static/doctools.js:139 -msgid "Permalink to this headline" -msgstr "Trvalý odkaz na tento nadpis" - -#: sphinx/latexwriter.py:172 -msgid "Release" -msgstr "Vydání" - -#: sphinx/roles.py:53 -#: sphinx/directives/desc.py:537 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "promměná prostředí, %s" @@ -118,22 +49,55 @@ msgstr "promměná prostředí, %s" msgid "Python Enhancement Proposals!PEP %s" msgstr "Python Enhancement Proposals!PEP %s" -#: sphinx/textwriter.py:166 +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Vestavěné funkce " + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Úroveň modulů" + +#: sphinx/builders/html.py:118 #, python-format -msgid "Platform: %s" -msgstr "Platforma: %s" +msgid "%b %d, %Y" +msgstr "%d.%m.%Y" -#: sphinx/textwriter.py:422 -msgid "[image]" -msgstr "[obrázek]" +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Rejstřík indexů" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "index" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Celkový rejstřík modulů" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "moduly" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "další" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "předchozí" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "(v" #: sphinx/directives/desc.py:25 #, python-format msgid "%s() (built-in function)" msgstr "%s() (vestavěná funkce)" -#: sphinx/directives/desc.py:26 -#: sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 #: sphinx/directives/desc.py:54 #, python-format msgid "%s() (in module %s)" @@ -144,8 +108,7 @@ msgstr "%s() (v modulu %s)" msgid "%s (built-in variable)" msgstr "%s() (vestavěná proměnná)" -#: sphinx/directives/desc.py:30 -#: sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s() (v modulu %s)" @@ -180,62 +143,67 @@ msgstr "%s() (statická metoda %s.%s)" msgid "%s() (%s static method)" msgstr "%s() (statická metoda %s)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s() (atribut %s.%s)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s() (atribut %s)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C funkce)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (člen C)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C makro)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C typ)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C proměnná)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Vyvolá" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Proměnná" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Vrací" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Typ navrácené hodnoty" -#: sphinx/directives/desc.py:143 +#: sphinx/directives/desc.py:213 +#, fuzzy +msgid "Parameter" +msgstr "Parametry" + +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parametry" -#: sphinx/directives/desc.py:423 +#: sphinx/directives/desc.py:465 #, python-format msgid "%scommand line option; %s" msgstr "%s parametry příkazového řádku; %s" @@ -261,10 +229,20 @@ msgstr "Autor modulu: " msgid "Author: " msgstr "Autor: " -#: sphinx/directives/other.py:246 +#: sphinx/directives/other.py:249 msgid "See also" msgstr "Viz také" +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + #: sphinx/ext/todo.py:31 msgid "Todo" msgstr "Todo" @@ -361,6 +339,14 @@ msgstr "příkaz" msgid "built-in function" msgstr "vestavěná funkce" +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Trvalý odkaz na tento nadpis" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Trvalý odkaz na tuto definici" + #: sphinx/static/doctools.js:174 msgid "Hide Search Matches" msgstr "Skrýt výsledky vyhledávání" @@ -381,16 +367,19 @@ msgstr "modul, v" msgid ", in " msgstr ", v" -#: sphinx/static/searchtools.js:447 -#: sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Výsledky hledání" -#: sphinx/static/searchtools.js:449 -msgid "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories." -msgstr "Nenalezli jsme žádný dokument. Ujistěte se prosím, že všechna slova jsou správně a že jste vybral dostatek kategorií." +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" +"Nenalezli jsme žádný dokument. Ujistěte se prosím, že všechna slova jsou " +"správně a že jste vybral dostatek kategorií." -#: sphinx/static/searchtools.js:451 +#: sphinx/static/searchtools.js:457 #, python-format msgid "Search finished, found %s page(s) matching the search query." msgstr "Vyhledávání skončilo, nalezeno %s stran." @@ -430,8 +419,7 @@ msgstr "Index – %(key)s" #: sphinx/templates/genindex-single.html:44 #: sphinx/templates/genindex-split.html:14 -#: sphinx/templates/genindex-split.html:27 -#: sphinx/templates/genindex.html:54 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 msgid "Full index on one page" msgstr "Plný index na jedné stránce" @@ -455,28 +443,23 @@ msgstr "Obsah" msgid "Previous topic" msgstr "Přechozí téma" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "předchozí kapitola" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Další téma" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "další kapitola" -#: sphinx/templates/layout.html:55 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Tato stránka" -#: sphinx/templates/layout.html:59 -msgid "Suggest Change" -msgstr "Návrh změnu" - -#: sphinx/templates/layout.html:60 -#: sphinx/templates/layout.html:62 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Ukázat zdroj" @@ -484,66 +467,58 @@ msgstr "Ukázat zdroj" msgid "Quick search" msgstr "Rychlé vyhledávání" -#: sphinx/templates/layout.html:71 -msgid "Keyword search" -msgstr "Hledání dle klíče" - -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "hledej" #: sphinx/templates/layout.html:78 -msgid "Enter a module, class or function name." +#, fuzzy +msgid "Enter search terms or a module, class or function name." msgstr "Zadej jméno modulu, třídy nebo funkce." -#: sphinx/templates/layout.html:119 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Hledání uvnitř %(docstitle)s" -#: sphinx/templates/layout.html:128 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "O těchto dokumentech" -#: sphinx/templates/layout.html:131 -#: sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Hledání" -#: sphinx/templates/layout.html:133 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Veškerá práva vyhrazena" -#: sphinx/templates/layout.html:178 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:180 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:183 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Aktualizováno dne %(last_updated)s." -#: sphinx/templates/layout.html:186 +#: sphinx/templates/layout.html:182 #, python-format -msgid "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> %(sphinx_version)s." -msgstr "Vytvořeno pomocí <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> %(sphinx_version)s." - -#: sphinx/templates/modindex.html:15 -msgid "Most popular modules:" -msgstr "Nejpopulárnější moduly:" - -#: sphinx/templates/modindex.html:24 -msgid "Show modules only available on these platforms" -msgstr "Zobrazit moduly dostupné na této platformě" +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr "" +"Vytvořeno pomocí <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." -#: sphinx/templates/modindex.html:56 +#: sphinx/templates/modindex.html:36 msgid "Deprecated" msgstr "Zastaralé" @@ -552,25 +527,29 @@ msgstr "Zastaralé" msgid "Search %(docstitle)s" msgstr "Prohledat %(docstitle)s" -#: sphinx/templates/page.html:8 -msgid "<strong>Note:</strong> You requested an out-of-date URL from this server. We've tried to redirect you to the new location of this page, but it may not be the right one." -msgstr "<strong>Poznámka:</strong> Stránka, kterou hledáte, neexistuje.<br>Snažili jsme se najít nové umístění této stránky, ale nepovedlo se." +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:14 msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" " containing fewer words won't appear in the result list." msgstr "" -"Toto je vyhledávací stránka. Zadejte klíčová slova a klikněte na \"hledej\". \n" -"Vyhledávání hledá automaticky všechna slova. Nebudou tedy nalezeny stránky, obsahující méně slov." +"Toto je vyhledávací stránka. Zadejte klíčová slova a klikněte na " +"\"hledej\". \n" +"Vyhledávání hledá automaticky všechna slova. Nebudou tedy nalezeny " +"stránky, obsahující méně slov." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "hledej" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Nic jsme nenašli." @@ -602,3 +581,40 @@ msgstr "Změny API" msgid "Other changes" msgstr "Ostatní změny" +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Vydání" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Platforma: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "[obrázek]" + +#~ msgid "Suggest Change" +#~ msgstr "Návrh změnu" + +#~ msgid "Keyword search" +#~ msgstr "Hledání dle klíče" + +#~ msgid "Most popular modules:" +#~ msgstr "Nejpopulárnější moduly:" + +#~ msgid "Show modules only available on these platforms" +#~ msgstr "Zobrazit moduly dostupné na této platformě" + +#~ msgid "" +#~ "<strong>Note:</strong> You requested an " +#~ "out-of-date URL from this server. " +#~ "We've tried to redirect you to the" +#~ " new location of this page, but " +#~ "it may not be the right one." +#~ msgstr "" +#~ "<strong>Poznámka:</strong> Stránka, kterou hledáte," +#~ " neexistuje.<br>Snažili jsme se najít nové" +#~ " umístění této stránky, ale nepovedlo " +#~ "se." + diff --git a/sphinx/locale/de/LC_MESSAGES/sphinx.po b/sphinx/locale/de/LC_MESSAGES/sphinx.po index 2fac78d9..a830aeef 100644 --- a/sphinx/locale/de/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/de/LC_MESSAGES/sphinx.po @@ -7,7 +7,7 @@ msgstr "" "Project-Id-Version: PROJECT VERSION\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-08-07 21:40+0200\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:43+0000\n" "Last-Translator: Horst Gutmann <zerok@zerokspot.com>\n" "Language-Team: de <LL@li.org>\n" "Plural-Forms: nplurals=2; plural=(n != 1)\n" @@ -16,28 +16,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d. %m. %Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Stichwortverzeichnis" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Modulindex" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Suche" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "Umgebungsvariable; %s" @@ -55,40 +55,40 @@ msgstr "Builtins" msgid "Module level" msgstr "Modulebene" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%d. %m. %Y" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "Allgemeiner Index" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "Index" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "Globaler Modulindex" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "Module" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "weiter" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "zurück" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " -msgstr "" +msgstr " (in " #: sphinx/directives/desc.py:25 #, python-format @@ -106,7 +106,7 @@ msgstr "%s() (in Modul %s)" msgid "%s (built-in variable)" msgstr "%s (eingebaute Variable)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (in Modul %s)" @@ -141,67 +141,66 @@ msgstr "%s() (statische Methode von %s.%s)" msgid "%s() (%s static method)" msgstr "%s() (statische Methode von %s)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (Attribut von %s.%s)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (Attribut von %s)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C-Funktion)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (C-Member)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C-Makro)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C-Typ)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C-Variable)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Verursacht:" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variable" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Rückgabe" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Rückgabetyp" -#: sphinx/directives/desc.py:201 -#, fuzzy +#: sphinx/directives/desc.py:213 msgid "Parameter" msgstr "Parameter" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parameter" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, python-format msgid "%scommand line option; %s" msgstr "%sKommandozeilenoption; %s" @@ -231,23 +230,28 @@ msgstr "Autor: " msgid "See also" msgstr "Siehe auch" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr " Basisklassen: %s" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" -msgstr "" +msgstr "Alias von :class:`%s`" #: sphinx/ext/todo.py:31 msgid "Todo" -msgstr "" +msgstr "Zu tun" #: sphinx/ext/todo.py:75 #, python-format msgid "(The original entry is located in %s, line %d and can be found " -msgstr "" +msgstr "(Der Eintrag steht in %s, Zeile %s, siehe " #: sphinx/ext/todo.py:81 msgid "here" -msgstr "" +msgstr "hier" #: sphinx/locale/__init__.py:15 msgid "Attention" @@ -332,7 +336,7 @@ msgstr "Statement" msgid "built-in function" msgstr "eingebaute Funktion" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "Permalink zu dieser Überschrift" @@ -358,9 +362,9 @@ msgstr "Modul, in " #: sphinx/static/searchtools.js:347 msgid ", in " -msgstr "" +msgstr ", in " -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Suchergebnisse" @@ -436,73 +440,72 @@ msgstr "Inhalt" msgid "Previous topic" msgstr "Vorheriges Thema" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "vorheriges Kapitel" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Nächstes Thema" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "nächstes Kapitel" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Diese Seite" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Quelltext anzeigen" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Schnellsuche" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Los" -#: sphinx/templates/layout.html:73 -#, fuzzy +#: sphinx/templates/layout.html:78 msgid "Enter search terms or a module, class or function name." -msgstr "Gib einen Modul-, Klassen- oder Funktionsnamen an." +msgstr "Geben Sie einen Modul-, Klassen- oder Funktionsnamen einn." -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Suche in %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "Über diese Dokumentation" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Suche" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Zuletzt aktualisiert am %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -520,25 +523,25 @@ msgstr "Veraltet" msgid "Search %(docstitle)s" msgstr "Suche in %(docstitle)s" -#: sphinx/templates/search.html:7 -#, fuzzy +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "Bitte aktivieren Sie JavaScript, wenn Sie die Suchfunktion nutzen wollen." + +#: sphinx/templates/search.html:14 msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" " containing fewer words won't appear in the result list." -msgstr "" -"Von hier aus kannst du die Dokumentation durchsuchen. Gib deine " -"Suchbegriffe in das untenstehende Feld ein und klicke auf \"suchen\". " -"Bitte beachte, dass die Suchfunktion automatisch nach all diesen Worten " -"suchen wird. Seiten, die nicht alle Worte enthalten, werden nicht in der " -"Ergebnisliste erscheinen." +msgstr "Von hier aus können Sie die Dokumentation durchsuchen. Geben Sie Ihre Suchbegriffe in das untenstehende Feld ein und klicken Sie auf \"Suchen\". Bitte beachten Sie, dass die Suchfunktion automatisch nach all diesen Worten suchen wird. Seiten, die nicht alle Worte enthalten, werden nicht in der Ergebnisliste erscheinen." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "suchen" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Deine Suche ergab leider keine Treffer." @@ -583,29 +586,3 @@ msgstr "Plattform: %s" msgid "[image]" msgstr "[Bild]" -#~ msgid "Suggest Change" -#~ msgstr "Änderung vorschlagen" - -#~ msgid "Keyword search" -#~ msgstr "Stichwortsuche" - -#~ msgid "Most popular modules:" -#~ msgstr "Beliebteste Module:" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "Zeige nur Module, die auf diesen Plattformen verfügbar sind" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>Anmerkung:</strong> Du hast eine nicht" -#~ " länger gültige URL von diesem Server" -#~ " angefragt. Wir haben versucht dich " -#~ "auf die neue Adresse dieser Seite " -#~ "umzuleiten, aber dies muss nicht die " -#~ "richtige Seite sein." - diff --git a/sphinx/locale/es/LC_MESSAGES/sphinx.po b/sphinx/locale/es/LC_MESSAGES/sphinx.po index f50a34cc..09ebda8b 100644 --- a/sphinx/locale/es/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/es/LC_MESSAGES/sphinx.po @@ -8,7 +8,7 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: guillem@torroja.dmt.upm.es\n" "POT-Creation-Date: 2008-09-11 23:58+0200\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Guillem Borrell <guillem@torroja.dmt.upm.es>\n" "Language-Team: es <LL@li.org>\n" "Plural-Forms: nplurals=2; plural=(n != 1)\n" @@ -17,28 +17,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, fuzzy, python-format msgid "%B %d, %Y" msgstr "%d de %B de %Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Índice" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Índice de Módulos" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Página de Búsqueda" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "variables de entorno; %s" @@ -58,38 +58,38 @@ msgstr "Funciones de base" msgid "Module level" msgstr "Módulos" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%d %b, %Y" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "Índice General" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "índice" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "Índice Global de Módulos" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "módulos" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "siguiente" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "anterior" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr "" @@ -109,7 +109,7 @@ msgstr "%s() (en el módulo %s)" msgid "%s (built-in variable)" msgstr "%s (variable de base)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (en el módulo %s)" @@ -144,68 +144,68 @@ msgstr "%s() (%s.%s método estático)" msgid "%s() (%s static method)" msgstr "%s() (%s método estático)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s atributo)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s atributo)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (función C)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (miembro C)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (macro C)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (tipo C)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (variable C)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Muestra" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variable" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Devuelve" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 #, fuzzy msgid "Return type" msgstr "Tipo del argumento devuelto" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 #, fuzzy msgid "Parameter" msgstr "Parámetros" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parámetros" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, fuzzy, python-format msgid "%scommand line option; %s" msgstr "%sOpciones en línea de comandos; %s" @@ -235,7 +235,12 @@ msgstr "Autor:" msgid "See also" msgstr "Ver también" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -337,7 +342,7 @@ msgstr "sentencia" msgid "built-in function" msgstr "función de base" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "Enlazar permanentemente con este título" @@ -367,7 +372,7 @@ msgstr "módulo" msgid ", in " msgstr "" -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Resultados de la búsqueda" @@ -446,73 +451,73 @@ msgstr "Contenidos" msgid "Previous topic" msgstr "Tema anterior" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "Capítulo anterior" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Próximo tema" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "Próximo capítulo" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Esta página" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Enseñar el código" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Búsqueda rápida" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Ir a" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 #, fuzzy msgid "Enter search terms or a module, class or function name." msgstr "Introducir en nombre de un módulo, clase o función" -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Buscar en %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "Sobre este documento" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Búsqueda" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\\\"%(path)s\\\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Actualizado por última vez en %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -530,7 +535,13 @@ msgstr "Obsoleto" msgid "Search %(docstitle)s" msgstr "Buscar en %(docstitle)s" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 #, fuzzy msgid "" "From here you can search these documents. Enter your search\n" @@ -543,11 +554,11 @@ msgstr "" " las palabras. Las páginas que contengan menos palabras no aparecerán en" " la lista de resultados." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "buscar" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Tu consulta no obtuvo ningún resultado" @@ -593,28 +604,3 @@ msgstr "Plataforma: %s" msgid "[image]" msgstr "[imagen]" -#~ msgid "Suggest Change" -#~ msgstr "Sugerir una modificación" - -#~ msgid "Keyword search" -#~ msgstr "Búsqueda por palabras clave" - -#~ msgid "Most popular modules:" -#~ msgstr "Módulos más comunes:" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "Mostrar sólo los módulos disponibles en estas plataformas" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>Nota:</strong> Has solicitado una " -#~ "dirección desactualizada a este servidor. " -#~ "Hemos intentado redirigirte a la nueva" -#~ " dirección de la misma página pero" -#~ " puede no ser la correcta." - diff --git a/sphinx/locale/fr/LC_MESSAGES/sphinx.po b/sphinx/locale/fr/LC_MESSAGES/sphinx.po index c715e626..bd6ea6ec 100644 --- a/sphinx/locale/fr/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/fr/LC_MESSAGES/sphinx.po @@ -9,7 +9,7 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: larlet@gmail.com\n" "POT-Creation-Date: 2008-08-08 12:39+0000\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Sébastien Douche <sdouche@gmail.com>\n" "Language-Team: French Translation Team <sphinx-dev@googlegroups.com>\n" "Plural-Forms: nplurals=2; plural=(n > 1)\n" @@ -18,28 +18,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d %B %Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Index" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Index du module" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Page de recherche" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "variable d'environnement; %s" @@ -57,38 +57,38 @@ msgstr "Fonctions de base" msgid "Module level" msgstr "Module" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%d %b %Y" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "Index général" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "index" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "Index général des modules" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "modules" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "suivant" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "précédent" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr "(dans" @@ -108,7 +108,7 @@ msgstr "%s() (dans le module %s)" msgid "%s (built-in variable)" msgstr "%s (variable de base)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (dans le module %s)" @@ -143,67 +143,67 @@ msgstr "%s() (méthode statique %s.%s)" msgid "%s() (%s static method)" msgstr "%s() (méthode statique %s)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (attribut %s.%s)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (attribut %s)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (fonction C)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (membre C)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (macro C)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (type C)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (variable C)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Lève" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variable" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Retourne" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Type retourné" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 #, fuzzy msgid "Parameter" msgstr "Paramètres" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Paramètres" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, python-format msgid "%scommand line option; %s" msgstr "%soption de ligne de commande; %s" @@ -233,7 +233,12 @@ msgstr "Auteur : " msgid "See also" msgstr "Voir aussi" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -334,7 +339,7 @@ msgstr "état" msgid "built-in function" msgstr "fonction de base" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "Lien permanent vers ce titre" @@ -362,7 +367,7 @@ msgstr "module, dans" msgid ", in " msgstr ", dans" -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Résultats de la recherche" @@ -439,73 +444,73 @@ msgstr "Table des matières" msgid "Previous topic" msgstr "Sujet précédent" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "Chapitre précédent" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Sujet suivant" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "Chapitre suivant" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Cette page" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Montrer la source" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Recherche rapide" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Go" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 #, fuzzy msgid "Enter search terms or a module, class or function name." msgstr "Saisissez un nom de module, classe ou fonction." -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Recherchez dans %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "À propos de ces documents" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Recherche" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Mis à jour le %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -523,7 +528,13 @@ msgstr "Obsolète" msgid "Search %(docstitle)s" msgstr "Rechercher %(docstitle)s" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 #, fuzzy msgid "" "From here you can search these documents. Enter your search\n" @@ -539,11 +550,11 @@ msgstr "" " contenant moins de mots n'apparaîtront pas dans la liste des " "résultats." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "rechercher" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Votre recherche n'a retourné aucun résultat" @@ -588,29 +599,3 @@ msgstr "Plateforme : %s" msgid "[image]" msgstr "[image]" -#~ msgid "Suggest Change" -#~ msgstr "Suggérer une modification" - -#~ msgid "Keyword search" -#~ msgstr "Recherche par mot-clé" - -#~ msgid "Most popular modules:" -#~ msgstr "Modules les plus utilisés :" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "N'afficher que les modules disponibles sur ces plateformes" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>Note :</strong> Vous tentez d'accéder" -#~ " à une ancienne URL de ce " -#~ "serveur. Nous avons essayé de vous " -#~ "rediriger vers la nouvelle adresse de" -#~ " cette page, mais ce n'est peut-être" -#~ " pas la bonne." - diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.po b/sphinx/locale/it/LC_MESSAGES/sphinx.po index 73c88e2b..c6db1830 100644 --- a/sphinx/locale/it/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/it/LC_MESSAGES/sphinx.po @@ -7,38 +7,37 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-11-27 18:39+0100\n" -"PO-Revision-Date: 2009-01-06 17:38+0200\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Sandro Dentella <sandro@e-den.it>\n" "Language-Team: <sphinx-dev@googlegroups.com>\n" +"Plural-Forms: nplurals=2; plural=(n != 1)\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf-8\n" "Content-Transfer-Encoding: 8bit\n" -"Plural-Forms: nplurals=2; plural=(n != 1)\n" -"X-Generator: Virtaal 0.2\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d %B %Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Indice" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Indice dei Moduli" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Cerca" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "variabile d'ambiente, %s" @@ -56,38 +55,38 @@ msgstr "Builtin" msgid "Module level" msgstr "Modulo" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%d/%b/%Y" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "Indice generale" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "indice" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "Indice dei moduli" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "moduli" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "successivo" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "precedente" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr " (in " @@ -107,7 +106,7 @@ msgstr "%s() (nel modulo %s)" msgid "%s (built-in variable)" msgstr "%s (variabile built-in)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (nel modulo %s)" @@ -142,66 +141,66 @@ msgstr "%s() (%s.%s metodo statico)" msgid "%s() (%s static method)" msgstr "%s() (%s metodo statico)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s attributo)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s attributo)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (funzione C)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (membro C )" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (macro C)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (tipo C)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (variabile C)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Solleva" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variabile" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Ritorna" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Tipo di ritorno" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 msgid "Parameter" msgstr "Parametri" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parametri" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, python-format msgid "%scommand line option; %s" msgstr "%sopzione di linea di comando; %s" @@ -231,7 +230,12 @@ msgstr "Autore: " msgid "See also" msgstr "Vedi anche" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "alias per :class:`%s`" @@ -332,7 +336,7 @@ msgstr "statement" msgid "built-in function" msgstr "funzione built-in" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "link permanente per questa intestazione" @@ -360,7 +364,7 @@ msgstr "modulo, in" msgid ", in " msgstr ", in " -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Risultati della ricerca" @@ -369,8 +373,9 @@ msgid "" "Your search did not match any documents. Please make sure that all words " "are spelled correctly and that you've selected enough categories." msgstr "" -"La tua ricerca non ha trovato alcun risultato. Controlla la correttezza dei " -"termini di ricerca e di avere selezionato un numero sufficiente di categorie" +"La tua ricerca non ha trovato alcun risultato. Controlla la correttezza " +"dei termini di ricerca e di avere selezionato un numero sufficiente di " +"categorie" #: sphinx/static/searchtools.js:457 #, python-format @@ -436,72 +441,72 @@ msgstr "Tabella dei contenuti" msgid "Previous topic" msgstr "Argomento precedente" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "capitolo precedente" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Argomento successivo" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "capitolo successivo" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Questa pagina" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Mostra sorgente" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Ricerca veloce" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Vai" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 msgid "Enter search terms or a module, class or function name." msgstr "Inserisci un termine di ricerca un modulo, classe o nome di funzione" -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Cerca in %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "A proposito di questi documenti" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Cerca" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Ultimo Aggiornamento on %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -519,23 +524,31 @@ msgstr "Deprecato" msgid "Search %(docstitle)s" msgstr "Cerca %(docstitle)s" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" " function will automatically search for all of the words. Pages\n" " containing fewer words won't appear in the result list." msgstr "" -"Puoi effettuare una ricerca in questi documenti. Immetti le parole chiave \n" -" della tua ricerca nel riquadro sottostante \"cerca\". Nota che la funzione\n" +"Puoi effettuare una ricerca in questi documenti. Immetti le parole chiave" +" \n" +" della tua ricerca nel riquadro sottostante \"cerca\". Nota che la " +"funzione\n" " di ricerca cerca automaticamente per tutte le parole. Le pagine\n" " che contendono meno parole non compariranno nei risultati di ricerca." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "cerca" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "La tua ricerca non ha ottenuto risultati" @@ -580,26 +593,3 @@ msgstr "Piattaforma: %s" msgid "[image]" msgstr "[immagine]" -#~ msgid "Suggest Change" -#~ msgstr "Suggerisci una modifica" - -#~ msgid "Keyword search" -#~ msgstr "Ricerca per parola chiave" - -#~ msgid "Most popular modules:" -#~ msgstr "Moduli più utilizzati" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "Mostra solo i moduli disponibili su questa piattaforma" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>Nota:</strong> Hai chiesto un URL " -#~ "non più valido. Abbiamo provato a " -#~ "ridirigerti verso il nuovo indirizzo, ma" -#~ " potrebbe non essere quello giusto" diff --git a/sphinx/locale/ja/LC_MESSAGES/sphinx.po b/sphinx/locale/ja/LC_MESSAGES/sphinx.po index a2c65446..307a8700 100644 --- a/sphinx/locale/ja/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/ja/LC_MESSAGES/sphinx.po @@ -8,7 +8,7 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-09-11 23:58+0200\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Yasushi MASUDA <whosaysni@gmail.com>\n" "Language-Team: ja <LL@li.org>\n" "Plural-Forms: nplurals=1; plural=0\n" @@ -17,28 +17,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%Y 年 %m 月 %d 日" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "索引" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "モジュール索引" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "検索ページ" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "環境変数; %s" @@ -56,38 +56,38 @@ msgstr "組み込み" msgid "Module level" msgstr "モジュールレベル" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%Y 年 %m 月 %d 日" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "総合索引" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "索引" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "モジュール総索引" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "モジュール" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "次へ" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "前へ" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr "" @@ -107,7 +107,7 @@ msgstr "%s() (%s モジュール)" msgid "%s (built-in variable)" msgstr "%s (組み込み変数)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (%s モジュール)" @@ -142,67 +142,67 @@ msgstr "%s() (%s.%s の静的メソッド)" msgid "%s() (%s static method)" msgstr "%s() (%s の静的メソッド)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s の属性)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s の属性)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C の関数)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (C のメンバ変数)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C のマクロ)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C のデータ型)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C の変数)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "例外" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "変数" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "戻り値" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "戻り値の型" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 #, fuzzy msgid "Parameter" msgstr "パラメタ" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "パラメタ" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, fuzzy, python-format msgid "%scommand line option; %s" msgstr "%sコマンドラインオプション; %s" @@ -232,7 +232,12 @@ msgstr "作者: " msgid "See also" msgstr "参考" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -333,7 +338,7 @@ msgstr "文" msgid "built-in function" msgstr "組み込み関数" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "このヘッドラインへのパーマリンク" @@ -362,7 +367,7 @@ msgstr "モジュール" msgid ", in " msgstr "" -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "検索結果" @@ -436,73 +441,73 @@ msgstr "目次" msgid "Previous topic" msgstr "前のトピックへ" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "前の章へ" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "次のトピックへ" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "次の章へ" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "このページ" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "ソースコードを表示" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "クイック検索" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "検索" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 #, fuzzy msgid "Enter search terms or a module, class or function name." msgstr "モジュール、クラス、または関数名を入力してください" -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "%(docstitle)s 内を検索" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "このドキュメントについて" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "検索" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "著作権" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "最終更新: %(last_updated)s" -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -520,7 +525,13 @@ msgstr "撤廃" msgid "Search %(docstitle)s" msgstr "%(docstitle)s 内を検索" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 #, fuzzy msgid "" "From here you can search these documents. Enter your search\n" @@ -529,11 +540,11 @@ msgid "" " containing fewer words won't appear in the result list." msgstr "このページからドキュメントを検索できます。キーワードを下のボックスに入力して、「検索」をクリックしてください。入力された全てのキーワードを含むページが検索されます。一部のキーワードしか含まないページは検索結果に表示されないので注意してください。" -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "検索" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "検索条件に一致する項目がありませんでした。" @@ -578,26 +589,3 @@ msgstr "プラットフォーム: %s" msgid "[image]" msgstr "[画像]" -#~ msgid "Suggest Change" -#~ msgstr "変更のサジェスト" - -#~ msgid "Keyword search" -#~ msgstr "キーワード検索" - -#~ msgid "Most popular modules:" -#~ msgstr "よく参照されているモジュール:" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "このプラットフォームで利用可能なモジュールだけを表示する" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>注意:</strong> あなたが表示しようとしているのは古い URL " -#~ "です。このページに対応する新しい URL " -#~ "へのリダイレクトを試みますが、適切なリダイレクト先でないかもしれないので注意してください。" - diff --git a/sphinx/locale/nl/LC_MESSAGES/sphinx.po b/sphinx/locale/nl/LC_MESSAGES/sphinx.po index fe6a4556..1dbc4399 100644 --- a/sphinx/locale/nl/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/nl/LC_MESSAGES/sphinx.po @@ -7,7 +7,7 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-09-11 23:58+0200\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: nl <LL@li.org>\n" "Plural-Forms: nplurals=2; plural=(n != 1)\n" @@ -16,28 +16,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d. %B %Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Index" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Module-index" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Zoekpagina" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "Omgevingsvariabele; %s" @@ -55,38 +55,38 @@ msgstr "Builtins" msgid "Module level" msgstr "Moduleniveau" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%d.%b.%Y" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "Algemene index" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "Index" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "Globale Module-index" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "modules" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "volgende" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "vorige" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr "" @@ -106,7 +106,7 @@ msgstr "%s() (in module %s)" msgid "%s (built-in variable)" msgstr "%s (geïntegreerde variabele)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (in module %s)" @@ -141,67 +141,67 @@ msgstr "%s() (%s.%s statische methode)" msgid "%s() (%s static method)" msgstr "%s() (%s statische methode)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s attribuut)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s attribuut)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C-functie)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (C member)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C-macro)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C type)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C-variabele)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Veroorzaakt" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variabele" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Returns" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Return type" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 #, fuzzy msgid "Parameter" msgstr "Parameters" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parameters" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, fuzzy, python-format msgid "%scommand line option; %s" msgstr "%scommandolijn optie; %s" @@ -231,7 +231,12 @@ msgstr "Auteur: " msgid "See also" msgstr "Zie ook" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -332,7 +337,7 @@ msgstr "statement" msgid "built-in function" msgstr "geïntegreerde functie" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "Permanente link naar deze titel" @@ -361,7 +366,7 @@ msgstr "module" msgid ", in " msgstr "" -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Zoekresultaten" @@ -437,73 +442,73 @@ msgstr "Inhoudstafel" msgid "Previous topic" msgstr "Vorig onderwerp" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "Vorig hoofdstuk" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Volgend onderwerp" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "volgend hoofdstuk" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Deze Pagina" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Broncode weergeven" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Snel zoeken" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Go" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 #, fuzzy msgid "Enter search terms or a module, class or function name." msgstr "Geef de naam van een module, klasse of functie." -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Zoeken in %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "Over deze documenten" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Zoeken" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Laatste aanpassing op %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -521,7 +526,13 @@ msgstr "Verouderd" msgid "Search %(docstitle)s" msgstr "Zoeken %(docstitle)s" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 #, fuzzy msgid "" "From here you can search these documents. Enter your search\n" @@ -536,11 +547,11 @@ msgstr "" "\n" " zullen niet tussen de resultaten verschijnen." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "zoeken" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Uw zoekopdracht leverde geen resultaten op." @@ -585,29 +596,3 @@ msgstr "Platform: %s" msgid "[image]" msgstr "[afbeelding]" -#~ msgid "Suggest Change" -#~ msgstr "Wijziging Voorstellen" - -#~ msgid "Keyword search" -#~ msgstr "Trefwoord opzoeken" - -#~ msgid "Most popular modules:" -#~ msgstr "Populairste modules:" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "Enkel modules weergeven die op deze platformen beschikbaar zijn" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>Opgelet:</strong> U heeft een " -#~ "verouderde URL aangevraagd op deze " -#~ "server. Wij hebben probeerd u door " -#~ "te verwijzen naar de nieuwe locatie " -#~ "van deze pagina, maar dat is " -#~ "misschien niet gelukt." - diff --git a/sphinx/locale/pl/LC_MESSAGES/sphinx.po b/sphinx/locale/pl/LC_MESSAGES/sphinx.po index fdd14ca3..990c8e38 100644 --- a/sphinx/locale/pl/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/pl/LC_MESSAGES/sphinx.po @@ -4,7 +4,7 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-08-10 11:43+0000\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Michał Kandulski <Michal.Kandulski@poczta.onet.pl>\n" "Language-Team: \n" "Plural-Forms: nplurals=3; plural=(n==1 ? 0 : n%10>=2 && n%10<=4 && " @@ -14,28 +14,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%B %d %Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Indeks" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Indeks modułów" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Wyszukiwanie" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "zmienna środowiskowa; %s" @@ -53,38 +53,38 @@ msgstr "Wbudowane" msgid "Module level" msgstr "Poziom modułu" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%b %d %Y" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "Indeks ogólny" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "indeks" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "Indeks modułów" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "moduły" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "dalej" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "wstecz" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr "" @@ -104,7 +104,7 @@ msgstr "%s() (w module %s)" msgid "%s (built-in variable)" msgstr "%s (zmienna wbudowana)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (w module %s)" @@ -139,67 +139,67 @@ msgstr "%s() (%s.%s statyczna metoda)" msgid "%s() (%s static method)" msgstr "%s() (%s statyczna metoda)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s atrybut)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s atrybut)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (funkcja C)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (pole C)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (makro C)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (typ C)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (zmienna C)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Wyrzuca" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Zmienna" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Zwraca" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Typ zwracany" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 #, fuzzy msgid "Parameter" msgstr "Parametry" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parametry" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, fuzzy, python-format msgid "%scommand line option; %s" msgstr "%sopcja linii komend; %s" @@ -229,7 +229,12 @@ msgstr "Autor: " msgid "See also" msgstr "Zobacz także" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -330,7 +335,7 @@ msgstr "instrukcja" msgid "built-in function" msgstr "funkcja wbudowana" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "Stały odnośnik do tego nagłówka" @@ -359,7 +364,7 @@ msgstr "moduł" msgid ", in " msgstr "" -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Wyniki wyszukiwania" @@ -435,73 +440,73 @@ msgstr "Spis treści" msgid "Previous topic" msgstr "Poprzedni temat" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "poprzedni rozdział" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Następny temat" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "następny rozdział" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Ta strona" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Pokaż źródło" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Szybkie wyszukiwanie" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Szukaj" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 #, fuzzy msgid "Enter search terms or a module, class or function name." msgstr "Wprowadź nazwę modułu, klasy lub funkcji." -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Szukaj pośród %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "O tych dokumentach" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Szukaj" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Ostatnia modyfikacja %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -519,7 +524,13 @@ msgstr "Niezalecane" msgid "Search %(docstitle)s" msgstr "Przeszukaj %(docstitle)s" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 #, fuzzy msgid "" "From here you can search these documents. Enter your search\n" @@ -533,11 +544,11 @@ msgstr "" "Strony nie zawierające wszystkich słów nie znajdą się na wynikowej " "liście." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "Szukaj" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Nie znaleziono żadnych pasujących stron." @@ -582,27 +593,3 @@ msgstr "Platforma: %s" msgid "[image]" msgstr "[obrazek]" -#~ msgid "Suggest Change" -#~ msgstr "Zasugeruj zmianę" - -#~ msgid "Keyword search" -#~ msgstr "Szukanie wg słowa kluczowego" - -#~ msgid "Most popular modules:" -#~ msgstr "Najbardziej popularne moduły:" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "Pokaż moduły dostępne tylko na tych platformach" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>Uwaga:</strong> Zażądano przedawnionego " -#~ "URL'a z tego serwera. Nastąpiła próba" -#~ " przekierowania do nowej lokalizacji, ale" -#~ " może ona być niewłaściwa." - diff --git a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po index d3144c25..48ee96db 100644 --- a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.po @@ -8,7 +8,7 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: roger.demetrescu@gmail.com\n" "POT-Creation-Date: 2008-11-09 19:46+0100\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Roger Demetrescu <roger.demetrescu@gmail.com>\n" "Language-Team: pt_BR <roger.demetrescu@gmail.com>\n" "Plural-Forms: nplurals=2; plural=(n > 1)\n" @@ -17,28 +17,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d/%m/%Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Índice" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Índice do Módulo" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Página de Pesquisa" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "váriavel de ambiente; %s" @@ -56,38 +56,38 @@ msgstr "Internos" msgid "Module level" msgstr "Módulo" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%d/%m/%Y" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "Índice Geral" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "índice" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "Índice Global de Módulos" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "módulos" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "próximo" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "anterior" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr " (em " @@ -107,7 +107,7 @@ msgstr "%s() (no módulo %s)" msgid "%s (built-in variable)" msgstr "%s (variável interna)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (no módulo %s)" @@ -142,67 +142,67 @@ msgstr "%s() (método estático %s.%s)" msgid "%s() (%s static method)" msgstr "%s() (método estático %s)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (atributo %s.%s)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (atributo %s)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (função C)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (membro C)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (macro C)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (tipo C)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (variável C)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Levanta" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Variável" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Retorna" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Tipo de retorno" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 #, fuzzy msgid "Parameter" msgstr "Parâmetros" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parâmetros" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, python-format msgid "%scommand line option; %s" msgstr "%sopção de linha de comando; %s" @@ -232,7 +232,12 @@ msgstr "Autor: " msgid "See also" msgstr "Veja também" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -333,7 +338,7 @@ msgstr "comando" msgid "built-in function" msgstr "função interna" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "Link permanente para este título" @@ -361,7 +366,7 @@ msgstr "módulo, em " msgid ", in " msgstr ", em " -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Resultados da Pesquisa" @@ -440,73 +445,73 @@ msgstr "Tabela de Conteúdo" msgid "Previous topic" msgstr "Tópico anterior" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "capítulo anterior" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Próximo tópico" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "próximo capítulo" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Esta Página" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Exibir Fonte" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Pesquisa rápida" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Ir" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 #, fuzzy msgid "Enter search terms or a module, class or function name." msgstr "Informe o nome de um módulo, classe ou função." -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Pesquisar dentro de %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "Sobre estes documentos" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Pesquisar" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Copyright" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Copyright %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Última atualização em %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -524,7 +529,13 @@ msgstr "Obsoleto" msgid "Search %(docstitle)s" msgstr "Pesquisar em %(docstitle)s" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 #, fuzzy msgid "" "From here you can search these documents. Enter your search\n" @@ -539,11 +550,11 @@ msgstr "" " Páginas contendo menos palavras não irão aparecer na lista de " "resultado." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "pesquisar" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Sua pesquisa não encontrou nenhum resultado." @@ -588,28 +599,3 @@ msgstr "Plataforma: %s" msgid "[image]" msgstr "[imagem]" -#~ msgid "Suggest Change" -#~ msgstr "Sugerir Alteração" - -#~ msgid "Keyword search" -#~ msgstr "Pesquisa de palavras-chave" - -#~ msgid "Most popular modules:" -#~ msgstr "Módulos mais populares:" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "Exibir somente módulos disponíveis nestas plataformas" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>Nota:</strong> Você requisitou uma URL" -#~ " desatualizada deste servidor. Tentamos " -#~ "redirecioná-lo para um novo endereço " -#~ "desta página, porém é possível que " -#~ "o mesmo não seja o correto." - diff --git a/sphinx/locale/sl/LC_MESSAGES/sphinx.po b/sphinx/locale/sl/LC_MESSAGES/sphinx.po index b08c75c9..f980ee1b 100644 --- a/sphinx/locale/sl/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/sl/LC_MESSAGES/sphinx.po @@ -4,7 +4,7 @@ msgstr "" "Project-Id-Version: Sphinx\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-09-11 23:58+0200\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Rok Garbas <rok.garbas@gmail.com>\n" "Language-Team: Rok Garbas <rok.garbas@gmail.com>\n" "Plural-Forms: nplurals=1; plural=0\n" @@ -13,28 +13,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%d %B, %Y" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "Abecedni seznam" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "Seznam modulov" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "Iskalna stran" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "globalna spremenljivka; %s" @@ -52,38 +52,38 @@ msgstr "Vgrajeni deli" msgid "Module level" msgstr "Nivo modula" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%d %b, %Y" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "Splošni abecedni seznam" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "abecedni seznam" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "Splošen Seznam Modulov" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "Moduli" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "naprej" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "nazaj" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr "(v " @@ -103,7 +103,7 @@ msgstr "%s() (v modulu %s)" msgid "%s (built-in variable)" msgstr "%s (vgrajene spremenljivke)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s (v modulu %s)" @@ -138,67 +138,67 @@ msgstr "%s() (%s.%s statična metoda)" msgid "%s() (%s static method)" msgstr "%s() (%s statična metoda)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s atribut)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s atribut)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C funkcija)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (C član)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C makro)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C tip)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C spremenljivka)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "Javi" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "Spremenljivka" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "Vrne" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "Vrne tip" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 #, fuzzy msgid "Parameter" msgstr "Parametri" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "Parametri" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, python-format msgid "%scommand line option; %s" msgstr "%sopcija komandne linije; %s" @@ -228,7 +228,12 @@ msgstr "Avtor:" msgid "See also" msgstr "Poglej tudi" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -329,7 +334,7 @@ msgstr "izjava" msgid "built-in function" msgstr "vgrajene funkcije" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "Povezava na naslov" @@ -357,7 +362,7 @@ msgstr "modul, v " msgid ", in " msgstr ", v " -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "Rezultati Iskanja" @@ -433,73 +438,73 @@ msgstr "Seznam Vsebine" msgid "Previous topic" msgstr "Prejšnja tema" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "prejšnje poglavje" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "Naslednja tema" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "naslednje poglavje" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "Ta stran" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "Prikaži izvorno kodo" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "Hitro iskanje" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "Potrdi" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 #, fuzzy msgid "Enter search terms or a module, class or function name." msgstr "Vnesi ime mudla, razreda ali funkcije." -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "Išči med %(docstitle)s" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "O teh dokumentih" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "Išči" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "Vse pravice pridržane" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "© <a href=\"%(path)s\">Vse pravice pridržane</a> %(copyright)s." -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "© Vse pravice pridržane %(copyright)s." -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "Zadnjič posodobljeno na %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -517,7 +522,13 @@ msgstr "Zastarelo" msgid "Search %(docstitle)s" msgstr "Išči %(docstitle)s" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 #, fuzzy msgid "" "From here you can search these documents. Enter your search\n" @@ -530,11 +541,11 @@ msgstr "" " bo iskalo po vseh besedah v iskalnem nizu. Strani, ki ne\n" " vsebujejo vseh besed ne bodo prikazane na seznamu rezultatov." -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "išči" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "Vaše iskanje ni imelo nobenega zadetka." @@ -579,27 +590,3 @@ msgstr "Platforma: %s" msgid "[image]" msgstr "[slika]" -#~ msgid "Suggest Change" -#~ msgstr "Predlagaj spremembo" - -#~ msgid "Keyword search" -#~ msgstr "Iskanje po ključniih besedah" - -#~ msgid "Most popular modules:" -#~ msgstr "Najbolj popularni moduli:" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "Prikaži module na razpolago na platformah" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" -#~ "<strong>Opomba:</strong> Vaš zahtevek za URL" -#~ " s tega streznika je zastaral. " -#~ "Poskušali smo vas preusmeriti na novo" -#~ " lokacijo, vendar utegne biti napačna." - diff --git a/sphinx/locale/sphinx.pot b/sphinx/locale/sphinx.pot index bcaee360..657f5df1 100644 --- a/sphinx/locale/sphinx.pot +++ b/sphinx/locale/sphinx.pot @@ -1,14 +1,14 @@ # Translations template for Sphinx. -# Copyright (C) 2008 ORGANIZATION +# Copyright (C) 2009 ORGANIZATION # This file is distributed under the same license as the Sphinx project. -# FIRST AUTHOR <EMAIL@ADDRESS>, 2008. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2009. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: Sphinx 0.6\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" -"POT-Creation-Date: 2008-12-28 23:40+0100\n" +"POT-Creation-Date: 2009-01-24 18:39+0000\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n" "Language-Team: LANGUAGE <LL@li.org>\n" @@ -17,28 +17,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "" @@ -56,38 +56,38 @@ msgstr "" msgid "Module level" msgstr "" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr "" @@ -107,7 +107,7 @@ msgstr "" msgid "%s (built-in variable)" msgstr "" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "" @@ -142,66 +142,66 @@ msgstr "" msgid "%s() (%s static method)" msgstr "" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 msgid "Parameter" msgstr "" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, python-format msgid "%scommand line option; %s" msgstr "" @@ -231,7 +231,12 @@ msgstr "" msgid "See also" msgstr "" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -332,7 +337,7 @@ msgstr "" msgid "built-in function" msgstr "" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "" @@ -360,7 +365,7 @@ msgstr "" msgid ", in " msgstr "" -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "" @@ -434,72 +439,72 @@ msgstr "" msgid "Previous topic" msgstr "" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 msgid "Enter search terms or a module, class or function name." msgstr "" -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "" -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "" -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "" -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -515,7 +520,13 @@ msgstr "" msgid "Search %(docstitle)s" msgstr "" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" @@ -523,11 +534,11 @@ msgid "" " containing fewer words won't appear in the result list." msgstr "" -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "" diff --git a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po index 0e27e947..9dc3c8ea 100644 --- a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po +++ b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.po @@ -8,7 +8,7 @@ msgstr "" "Project-Id-Version: Sphinx 0.5\n" "Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" "POT-Creation-Date: 2008-11-09 19:46+0100\n" -"PO-Revision-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-24 18:39+0000\n" "Last-Translator: Fred Lin <gasolin@gmail.com>\n" "Language-Team: tw <LL@li.org>\n" "Plural-Forms: nplurals=1; plural=0\n" @@ -17,28 +17,28 @@ msgstr "" "Content-Transfer-Encoding: 8bit\n" "Generated-By: Babel 0.9.3\n" -#: sphinx/environment.py:103 sphinx/writers/latex.py:170 +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 #, python-format msgid "%B %d, %Y" msgstr "%Y 年 %m 月 %d 日" -#: sphinx/environment.py:293 sphinx/templates/genindex-single.html:2 +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 #: sphinx/templates/genindex-split.html:2 #: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 #: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 -#: sphinx/templates/layout.html:117 sphinx/writers/latex.py:176 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 msgid "Index" msgstr "索引" -#: sphinx/environment.py:294 sphinx/writers/latex.py:175 +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 msgid "Module Index" msgstr "模組索引" -#: sphinx/environment.py:295 sphinx/templates/defindex.html:16 +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 msgid "Search Page" msgstr "搜尋頁面" -#: sphinx/roles.py:53 sphinx/directives/desc.py:564 +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 #, python-format msgid "environment variable; %s" msgstr "環境變數; %s" @@ -56,38 +56,38 @@ msgstr "" msgid "Module level" msgstr "" -#: sphinx/builders/html.py:115 +#: sphinx/builders/html.py:118 #, python-format msgid "%b %d, %Y" msgstr "%Y 年 %m 月 %d 日" -#: sphinx/builders/html.py:134 sphinx/templates/defindex.html:21 +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 msgid "General Index" msgstr "總索引" -#: sphinx/builders/html.py:134 +#: sphinx/builders/html.py:137 msgid "index" msgstr "索引" -#: sphinx/builders/html.py:136 sphinx/builders/htmlhelp.py:180 -#: sphinx/builders/qthelp.py:129 sphinx/templates/defindex.html:19 +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 #: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 msgid "Global Module Index" msgstr "" -#: sphinx/builders/html.py:136 +#: sphinx/builders/html.py:139 msgid "modules" msgstr "模組" -#: sphinx/builders/html.py:175 +#: sphinx/builders/html.py:179 msgid "next" msgstr "下一頁" -#: sphinx/builders/html.py:182 +#: sphinx/builders/html.py:186 msgid "previous" msgstr "上一頁" -#: sphinx/builders/latex.py:155 +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 msgid " (in " msgstr "" @@ -107,7 +107,7 @@ msgstr "%s() (在 %s 模組中)" msgid "%s (built-in variable)" msgstr "%s (內建變數)" -#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:66 +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 #, python-format msgid "%s (in module %s)" msgstr "%s() (在 %s 模組中)" @@ -142,67 +142,67 @@ msgstr "%s() (%s.%s 靜態方法)" msgid "%s() (%s static method)" msgstr "%s() (%s 靜態方法)" -#: sphinx/directives/desc.py:70 +#: sphinx/directives/desc.py:82 #, python-format msgid "%s (%s.%s attribute)" msgstr "%s (%s.%s 屬性)" -#: sphinx/directives/desc.py:72 +#: sphinx/directives/desc.py:84 #, python-format msgid "%s (%s attribute)" msgstr "%s (%s 屬性)" -#: sphinx/directives/desc.py:74 +#: sphinx/directives/desc.py:86 #, python-format msgid "%s (C function)" msgstr "%s (C 函式)" -#: sphinx/directives/desc.py:76 +#: sphinx/directives/desc.py:88 #, python-format msgid "%s (C member)" msgstr "%s (C 成員)" -#: sphinx/directives/desc.py:78 +#: sphinx/directives/desc.py:90 #, python-format msgid "%s (C macro)" msgstr "%s (C 巨集)" -#: sphinx/directives/desc.py:80 +#: sphinx/directives/desc.py:92 #, python-format msgid "%s (C type)" msgstr "%s (C 類別)" -#: sphinx/directives/desc.py:82 +#: sphinx/directives/desc.py:94 #, python-format msgid "%s (C variable)" msgstr "%s (C 變數)" -#: sphinx/directives/desc.py:100 +#: sphinx/directives/desc.py:112 msgid "Raises" msgstr "" -#: sphinx/directives/desc.py:104 +#: sphinx/directives/desc.py:116 msgid "Variable" msgstr "變數" -#: sphinx/directives/desc.py:107 +#: sphinx/directives/desc.py:119 msgid "Returns" msgstr "返回" -#: sphinx/directives/desc.py:116 +#: sphinx/directives/desc.py:128 msgid "Return type" msgstr "返回類別" -#: sphinx/directives/desc.py:201 +#: sphinx/directives/desc.py:213 #, fuzzy msgid "Parameter" msgstr "參數" -#: sphinx/directives/desc.py:205 +#: sphinx/directives/desc.py:217 msgid "Parameters" msgstr "參數" -#: sphinx/directives/desc.py:450 +#: sphinx/directives/desc.py:465 #, python-format msgid "%scommand line option; %s" msgstr "%s命令列選項; %s" @@ -232,7 +232,12 @@ msgstr "作者：" msgid "See also" msgstr "" -#: sphinx/ext/autodoc.py:576 sphinx/ext/autodoc.py:590 +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 #, python-format msgid "alias of :class:`%s`" msgstr "" @@ -333,7 +338,7 @@ msgstr "" msgid "built-in function" msgstr "內建函式" -#: sphinx/static/doctools.js:139 sphinx/writers/html.py:415 +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 msgid "Permalink to this headline" msgstr "" @@ -361,7 +366,7 @@ msgstr "" msgid ", in " msgstr "" -#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:18 +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 msgid "Search Results" msgstr "搜尋結果" @@ -435,73 +440,73 @@ msgstr "內容目錄" msgid "Previous topic" msgstr "上一個主題" -#: sphinx/templates/layout.html:47 +#: sphinx/templates/layout.html:48 msgid "previous chapter" msgstr "上一章" -#: sphinx/templates/layout.html:50 +#: sphinx/templates/layout.html:51 msgid "Next topic" msgstr "下一個主題" -#: sphinx/templates/layout.html:51 +#: sphinx/templates/layout.html:53 msgid "next chapter" msgstr "下一章" -#: sphinx/templates/layout.html:56 +#: sphinx/templates/layout.html:58 msgid "This Page" msgstr "本頁" -#: sphinx/templates/layout.html:58 +#: sphinx/templates/layout.html:61 msgid "Show Source" msgstr "顯示原始碼" -#: sphinx/templates/layout.html:67 +#: sphinx/templates/layout.html:71 msgid "Quick search" msgstr "快速搜尋" -#: sphinx/templates/layout.html:69 +#: sphinx/templates/layout.html:74 msgid "Go" msgstr "" -#: sphinx/templates/layout.html:73 +#: sphinx/templates/layout.html:78 #, fuzzy msgid "Enter search terms or a module, class or function name." msgstr "輸入一個模組、類別、或是函式名稱." -#: sphinx/templates/layout.html:106 +#: sphinx/templates/layout.html:115 #, python-format msgid "Search within %(docstitle)s" msgstr "在 %(docstitle)s 中搜尋" -#: sphinx/templates/layout.html:115 +#: sphinx/templates/layout.html:124 msgid "About these documents" msgstr "" -#: sphinx/templates/layout.html:118 sphinx/templates/search.html:2 +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 #: sphinx/templates/search.html:5 msgid "Search" msgstr "搜尋" -#: sphinx/templates/layout.html:120 +#: sphinx/templates/layout.html:129 msgid "Copyright" msgstr "版權所有" -#: sphinx/templates/layout.html:165 +#: sphinx/templates/layout.html:174 #, python-format msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." msgstr "" -#: sphinx/templates/layout.html:167 +#: sphinx/templates/layout.html:176 #, python-format msgid "© Copyright %(copyright)s." msgstr "" -#: sphinx/templates/layout.html:170 +#: sphinx/templates/layout.html:179 #, python-format msgid "Last updated on %(last_updated)s." msgstr "最後更新日期是 %(last_updated)s." -#: sphinx/templates/layout.html:173 +#: sphinx/templates/layout.html:182 #, python-format msgid "" "Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " @@ -517,7 +522,13 @@ msgstr "已移除" msgid "Search %(docstitle)s" msgstr "搜尋 %(docstitle)s" -#: sphinx/templates/search.html:7 +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "" + +#: sphinx/templates/search.html:14 msgid "" "From here you can search these documents. Enter your search\n" " words into the box below and click \"search\". Note that the search\n" @@ -525,11 +536,11 @@ msgid "" " containing fewer words won't appear in the result list." msgstr "" -#: sphinx/templates/search.html:14 +#: sphinx/templates/search.html:21 msgid "search" msgstr "搜尋" -#: sphinx/templates/search.html:20 +#: sphinx/templates/search.html:27 msgid "Your search did not match any results." msgstr "" @@ -574,23 +585,3 @@ msgstr "平台：%s" msgid "[image]" msgstr "[圖片]" -#~ msgid "Suggest Change" -#~ msgstr "" - -#~ msgid "Keyword search" -#~ msgstr "關鍵字搜尋" - -#~ msgid "Most popular modules:" -#~ msgstr "" - -#~ msgid "Show modules only available on these platforms" -#~ msgstr "" - -#~ msgid "" -#~ "<strong>Note:</strong> You requested an " -#~ "out-of-date URL from this server. " -#~ "We've tried to redirect you to the" -#~ " new location of this page, but " -#~ "it may not be the right one." -#~ msgstr "" - -- cgit v1.2.1 From 85c813f7699de4b68eef7f4ce4ba04f2ae62388c Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 24 Jan 2009 20:55:16 +0000 Subject: fix classmethoddesc environment --- sphinx/texinputs/sphinx.sty | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index bb247664..364b571e 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -454,13 +454,7 @@ % class method ---------------------------------------------------------- % \begin{classmethoddesc}[classname]{methodname}{args} \newcommand{\classmethodline}[3][\@undefined]{ - \classmethodlineni{#2}{#3} - \ifx\@undefined#1\relax - \index{#2@{\py@idxcode{#2()}} (\py@thisclass\ class method)} - \else - \index{#2@{\py@idxcode{#2()}} (#1 class method)} - \fi -} + \py@sigline{class \bfcode{#2}}{#3}} \newenvironment{classmethoddesc}[3][\@undefined]{ \begin{fulllineitems} \ifx\@undefined#1\relax @@ -471,15 +465,6 @@ \fi }{\end{fulllineitems}} -% similar to {classmethoddesc}, but doesn't add to the index -% (never actually uses the optional argument) -\newcommand{\classmethodlineni}[3][\py@classbadkey]{% - \py@sigline{class \bfcode{#2}}{#3}} -\newenvironment{classmethoddescni}[3][\py@classbadkey]{ - \begin{fulllineitems} - \classmethodlineni{#2}{#3} -}{\end{fulllineitems}} - % object data attribute -------------------------------------------------- % \begin{memberdesc}[classname]{membername} \newcommand{\memberline}[2][\py@classbadkey]{% -- cgit v1.2.1 From 521007bfd65b1301b231e37da919569ebd84305a Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 26 Jan 2009 19:56:14 +0100 Subject: Add Selflanguage.org. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 9359121f..f1bf1141 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -39,6 +39,7 @@ included, please mail to `the Google group * python-apt: http://people.debian.org/~jak/python-apt-doc/ * Reteisi: http://docs.argolinux.org/reteisi/ * Satchmo: http://www.satchmoproject.com/docs/svn/ +* Self: http://selflanguage.org/ * Sphinx: http://sphinx.pocoo.org/ * SQLAlchemy: http://www.sqlalchemy.org/docs/ * Sqlkit: http://sqlkit.argolinux.org/ -- cgit v1.2.1 From 21cccbd98405e026150fe6aa91ff4d397ae7702b Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 26 Jan 2009 20:08:02 +0100 Subject: Add WTForms. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index f1bf1141..1f71ea93 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -48,5 +48,6 @@ included, please mail to `the Google group * TurboGears: http://turbogears.org/2.0/docs/ * VOR: http://www.vor-cycling.be/ * WFront: http://discorporate.us/projects/WFront/ +* WTForms: http://wtforms.simplecodes.com/docs/ * Zope 3: e.g. http://docs.carduner.net/z3c-tutorial/ * zc.async: http://packages.python.org/zc.async/1.5.0/ -- cgit v1.2.1 From a1deea1a040a612e262b34717b73674b5bc423ce Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 26 Jan 2009 21:57:15 +0100 Subject: Added a toctree variable to the templates, and the ability to include external links in toctrees. Patch by Stefan Seefeld. --- AUTHORS | 1 + CHANGES | 3 +++ doc/concepts.rst | 5 ++++- doc/templating.rst | 23 +++++++++++++++++++-- sphinx/builders/html.py | 2 ++ sphinx/directives/other.py | 19 +++++++++++++----- sphinx/environment.py | 50 ++++++++++++++++++++++++++++++---------------- 7 files changed, 78 insertions(+), 25 deletions(-) diff --git a/AUTHORS b/AUTHORS index 6750dad9..c13d267e 100644 --- a/AUTHORS +++ b/AUTHORS @@ -12,6 +12,7 @@ Other contributors, listed alphabetically, are: * Dave Kuhlman -- original LaTeX writer * Thomas Lamb -- linkcheck builder * Benjamin Peterson -- unittests +* Stefan Seefeld -- toctree improvements * Antonio Valentino -- qthelp builder * Pauli Virtanen -- autodoc improvements * Sebastian Wiesner -- image handling, distutils support diff --git a/CHANGES b/CHANGES index 38a0c9e9..15239fd0 100644 --- a/CHANGES +++ b/CHANGES @@ -49,6 +49,9 @@ New features added - #23: Added a ``classmethod`` directive along with ``method`` and ``staticmethod``. + - Added a toctree variable to the templates, and the ability to + include external links in toctrees. + * Configuration: - The new ``html_add_permalinks`` config value can be used to diff --git a/doc/concepts.rst b/doc/concepts.rst index 379888ff..23725b10 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -71,6 +71,9 @@ tables of contents. The ``toctree`` directive is the central element. The second line above will link to the ``strings`` document, but will use the title "All about strings" instead of the title of the ``strings`` document. + You can also add external links, by giving an HTTP URL instead of a document + name. + You can use "globbing" in toctree directives, by giving the ``glob`` flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically. Example:: @@ -113,7 +116,7 @@ tables of contents. The ``toctree`` directive is the central element. Added "globbing" option. .. versionchanged:: 0.6 - Added "hidden" option. + Added "hidden" option and external links. Special names diff --git a/doc/templating.rst b/doc/templating.rst index ff4bdd51..20c61ce0 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -221,8 +221,12 @@ in the future. .. data:: builder - The name of the builder (for builtin builders, ``html``, ``htmlhelp``, or - ``web``). + The name of the builder (e.g. ``html`` or ``htmlhelp``). + +.. data:: embedded + + True if the built HTML is supposed to be embedded in some application that + handles navigation, e.g. HTML Help or Qt Help. .. data:: next @@ -239,3 +243,18 @@ in the future. .. data:: prev Like :data:`next`, but for the previous page. + + +In documents that are created from source files (as opposed to +automatically-generated files like the module index, or documents that already +are in HTML form), these variables are also available: + +.. data:: toc + + The local table of contents for the current page, rendered as HTML bullet + lists. + +.. data:: toctree + + The global TOC tree containing the current page, rendered as HTML bullet + lists. diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index fa802613..660e63ca 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -219,6 +219,8 @@ class StandaloneHTMLBuilder(Builder): metatags = metatags, rellinks = rellinks, sourcename = sourcename, + toctree = self.render_partial(self.env.get_toctree_for( + docname, self))['fragment'], toc = self.render_partial(self.env.get_toc_for(docname))['fragment'], # only display a TOC if there's more than one item to show display_toc = (self.env.toc_num_entries[docname] > 1), diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index cbf548be..0c1e29f9 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -27,6 +27,9 @@ def toctree_directive(name, arguments, options, content, lineno, glob = 'glob' in options ret = [] + # (title, ref) pairs, where ref may be a document, or an external link, + # and title may be None if the document's title is to be used + entries = [] includefiles = [] includetitles = {} all_docnames = env.found_docs.copy() @@ -39,33 +42,39 @@ def toctree_directive(name, arguments, options, content, lineno, # look for explicit titles and documents ("Some Title <document>"). m = caption_ref_re.match(entry) if m: - docname = m.group(2) - includetitles[docname] = m.group(1) + ref = m.group(2) + title = m.group(1) + docname = ref else: - docname = entry + ref = docname = entry + title = None # remove suffixes (backwards compatibility) if docname.endswith(suffix): docname = docname[:-len(suffix)] # absolutize filenames docname = docname_join(env.docname, docname) - if docname not in env.found_docs: + if ref.startswith('http://'): # FIXME: generalize to arbitrary xrefs + entries.append((title, ref)) + elif docname not in env.found_docs: ret.append(state.document.reporter.warning( 'toctree references unknown document %r' % docname, line=lineno)) else: + entries.append((title, ref)) includefiles.append(docname) else: patname = docname_join(env.docname, entry) docnames = sorted(patfilter(all_docnames, patname)) for docname in docnames: all_docnames.remove(docname) # don't include it again + entries.append((None, docname)) includefiles.append(docname) if not docnames: ret.append(state.document.reporter.warning( 'toctree glob pattern %r didn\'t match any documents' % entry, line=lineno)) subnode = addnodes.toctree() + subnode['entries'] = entries subnode['includefiles'] = includefiles - subnode['includetitles'] = includetitles subnode['maxdepth'] = options.get('maxdepth', -1) subnode['glob'] = glob subnode['hidden'] = 'hidden' in options diff --git a/sphinx/environment.py b/sphinx/environment.py index cf69ced9..799495db 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -828,6 +828,17 @@ class BuildEnvironment: node['refuri'] = node['anchorname'] return toc + def get_toctree_for(self, docname, builder): + """Return the global TOC nodetree.""" + + # XXX why master_doc? + doctree = self.get_doctree(self.config.master_doc) + for toctreenode in doctree.traverse(addnodes.toctree): + result = self.resolve_toctree(docname, builder, toctreenode, + prune=True) + if result is not None: + return result + # ------- # these are called from docutils directives and therefore use self.docname # @@ -912,35 +923,46 @@ class BuildEnvironment: if toctree.get('hidden', False): return None - def _walk_depth(node, depth, maxdepth, titleoverrides): + def _walk_depth(node, depth, maxdepth): """Utility: Cut a TOC at a specified depth.""" for subnode in node.children[:]: if isinstance(subnode, (addnodes.compact_paragraph, nodes.list_item)): subnode['classes'].append('toctree-l%d' % (depth-1)) - _walk_depth(subnode, depth, maxdepth, titleoverrides) + _walk_depth(subnode, depth, maxdepth) elif isinstance(subnode, nodes.bullet_list): if maxdepth > 0 and depth > maxdepth: subnode.parent.replace(subnode, []) else: - _walk_depth(subnode, depth+1, maxdepth, titleoverrides) + _walk_depth(subnode, depth+1, maxdepth) def _entries_from_toctree(toctreenode, separate=False, subtree=False): """Return TOC entries for a toctree node.""" - includefiles = map(str, toctreenode['includefiles']) - + refs = [(e[0], str(e[1])) for e in toctreenode['entries']] entries = [] - for includefile in includefiles: + for (title, ref) in refs: try: - toc = self.tocs[includefile].deepcopy() + if ref.startswith('http://'): # FIXME: (see directives/other.py) + reference = nodes.reference('', '', refuri=ref, anchorname='', + *[nodes.Text(title)]) + para = addnodes.compact_paragraph('', '', reference) + item = nodes.list_item('', para) + toc = nodes.bullet_list('', item) + else: + toc = self.tocs[ref].deepcopy() + if title and toc.children and len(toc.children) == 1: + for refnode in toc.children[0].traverse(nodes.reference): + if refnode['refuri'] == ref and not refnode['anchorname']: + refnode.children = [nodes.Text(title)] if not toc.children: # empty toc means: no titles will show up in the toctree self.warn(docname, 'toctree contains reference to document ' '%r that doesn\'t have a title: no link will be ' - 'generated' % includefile) + 'generated' % ref) + except KeyError: # this is raised if the included file does not exist self.warn(docname, 'toctree contains reference to nonexisting ' - 'document %r' % includefile) + 'document %r' % ref) else: # if titles_only is given, only keep the main title and # sub-toctrees @@ -969,7 +991,6 @@ class BuildEnvironment: return entries maxdepth = maxdepth or toctree.get('maxdepth', -1) - titleoverrides = toctree.get('includetitles', {}) # NOTE: previously, this was separate=True, but that leads to artificial # separation when two or more toctree entries form a logical unit, so @@ -981,14 +1002,9 @@ class BuildEnvironment: newnode = addnodes.compact_paragraph('', '', *tocentries) newnode['toctree'] = True # prune the tree to maxdepth and replace titles, also set level classes - _walk_depth(newnode, 1, prune and maxdepth or 0, titleoverrides) - # replace titles, if needed, and set the target paths in the - # toctrees (they are not known at TOC generation time) + _walk_depth(newnode, 1, prune and maxdepth or 0) + # set the target paths in the toctrees (they are not known at TOC generation time) for refnode in newnode.traverse(nodes.reference): - if titleoverrides and not refnode['anchorname'] \ - and refnode['refuri'] in titleoverrides: - newtitle = titleoverrides[refnode['refuri']] - refnode.children = [nodes.Text(newtitle)] refnode['refuri'] = builder.get_relative_uri( docname, refnode['refuri']) + refnode['anchorname'] return newnode -- cgit v1.2.1 From 173590214ef97785c71d257f3324528d61293256 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 26 Jan 2009 22:04:29 +0100 Subject: Add a minimal test for external toctree links and fix a small bug found by it. --- sphinx/environment.py | 5 +++-- tests/root/contents.txt | 2 ++ tests/test_build.py | 1 + 3 files changed, 6 insertions(+), 2 deletions(-) diff --git a/sphinx/environment.py b/sphinx/environment.py index 799495db..a654cb77 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -1005,8 +1005,9 @@ class BuildEnvironment: _walk_depth(newnode, 1, prune and maxdepth or 0) # set the target paths in the toctrees (they are not known at TOC generation time) for refnode in newnode.traverse(nodes.reference): - refnode['refuri'] = builder.get_relative_uri( - docname, refnode['refuri']) + refnode['anchorname'] + if not refnode['refuri'].startswith('http://'): # FIXME: see above + refnode['refuri'] = builder.get_relative_uri( + docname, refnode['refuri']) + refnode['anchorname'] return newnode descroles = frozenset(('data', 'exc', 'func', 'class', 'const', 'attr', 'obj', diff --git a/tests/root/contents.txt b/tests/root/contents.txt index 61646f62..c87a2d8e 100644 --- a/tests/root/contents.txt +++ b/tests/root/contents.txt @@ -18,6 +18,8 @@ Contents: math autodoc + Python <http://python.org/> + Indices and tables ================== diff --git a/tests/test_build.py b/tests/test_build.py index 9999abd0..ed2d9982 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -95,6 +95,7 @@ HTML_XPATH = { ".//li[@class='toctree-l2']/a": 'Admonitions', ".//title": 'Sphinx <Tests>', ".//div[@class='footer']": 'Georg Brandl & Team', + ".//a[@href='http://python.org/']": '', }, } -- cgit v1.2.1 From f5e2ccd6c0728861b0eaf9794b021ca498f51896 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 26 Jan 2009 22:35:56 +0100 Subject: don't error out in search index building if there are documents without titles containing referenced stuff --- sphinx/search.py | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/sphinx/search.py b/sphinx/search.py index f39d3674..fe20c24a 100644 --- a/sphinx/search.py +++ b/sphinx/search.py @@ -134,13 +134,16 @@ class IndexBuilder(object): def get_modules(self, fn2index): rv = {} for name, (doc, _, _, _) in self.env.modules.iteritems(): - rv[name] = fn2index[doc] + if doc in fn2index: + rv[name] = fn2index[doc] return rv def get_descrefs(self, fn2index): rv = {} dt = self._desctypes for fullname, (doc, desctype) in self.env.descrefs.iteritems(): + if doc not in fn2index: + continue prefix, name = rpartition(fullname, '.') pdict = rv.setdefault(prefix, {}) try: @@ -156,9 +159,10 @@ class IndexBuilder(object): for k, v in self._mapping.iteritems(): if len(v) == 1: fn, = v - rv[k] = fn2index[fn] + if fn in fn2index: + rv[k] = fn2index[fn] else: - rv[k] = [fn2index[fn] for fn in v] + rv[k] = [fn2index[fn] for fn in v if fn in fn2index] return rv def freeze(self): -- cgit v1.2.1 From c03931c45ac7033dab16a329edf968dffd5352cc Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 26 Jan 2009 23:36:10 +0100 Subject: Use full path in new toctree entries. --- sphinx/directives/other.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 0c1e29f9..a7cdd904 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -59,7 +59,7 @@ def toctree_directive(name, arguments, options, content, lineno, ret.append(state.document.reporter.warning( 'toctree references unknown document %r' % docname, line=lineno)) else: - entries.append((title, ref)) + entries.append((title, docname)) includefiles.append(docname) else: patname = docname_join(env.docname, entry) -- cgit v1.2.1 From cca9de484189cbf76b47a18831993a9bc077bbf1 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 26 Jan 2009 23:38:02 +0100 Subject: The new ``trim_footnote_reference_space`` config value mirrors the docutils config value of the same name and removes the space before a footnote reference that is necessary for reST to recognize the reference. --- CHANGES | 5 +++++ doc/config.rst | 7 +++++++ sphinx/config.py | 1 + sphinx/environment.py | 4 +++- 4 files changed, 16 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index e37afeda..4b28899b 100644 --- a/CHANGES +++ b/CHANGES @@ -64,6 +64,11 @@ New features added - The default value for ``htmlhelp_basename`` is now the project title, cleaned up as a filename. + - The new ``trim_footnote_reference_space`` config value mirrors + the docutils config value of the same name and removes the + space before a footnote reference that is necessary for reST + to recognize the reference. + * Builders: - New builder for Qt help collections, by Antonio Valentino. diff --git a/doc/config.rst b/doc/config.rst index dd25cf22..8fc7978c 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -261,7 +261,14 @@ Project information A boolean that decides whether :dir:`moduleauthor` and :dir:`sectionauthor` directives produce any output in the built files. +.. confval:: trim_footnote_reference_space + Trim spaces before footnote references that are necessary for the reST parser + to recognize the footnote, but do not look too nice in the output. + + .. versionadded:: 0.6 + + .. _html-options: Options for HTML output diff --git a/sphinx/config.py b/sphinx/config.py index e1eb8ec8..a3de68f5 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -45,6 +45,7 @@ class Config(object): default_role = (None, True), add_function_parentheses = (True, True), add_module_names = (True, True), + trim_footnote_reference_space = (False, True), show_authors = (False, True), pygments_style = ('sphinx', False), highlight_language = ('python', False), diff --git a/sphinx/environment.py b/sphinx/environment.py index a654cb77..991fab72 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -59,7 +59,7 @@ default_settings = { # This is increased every time an environment attribute is added # or changed to properly invalidate pickle files. -ENV_VERSION = 27 +ENV_VERSION = 28 default_substitutions = set([ @@ -517,6 +517,8 @@ class BuildEnvironment: self.docname = docname self.settings['input_encoding'] = self.config.source_encoding + self.settings['trim_footnote_reference_space'] = \ + self.config.trim_footnote_reference_space class SphinxSourceClass(FileInput): def read(self): -- cgit v1.2.1 From e2b244180db9af84867a4c49c6b21be3bc46223b Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Thu, 5 Feb 2009 12:47:02 +0100 Subject: Add Roundup. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 1f71ea93..d5f477cc 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -38,6 +38,7 @@ included, please mail to `the Google group * Python: http://docs.python.org/dev/ * python-apt: http://people.debian.org/~jak/python-apt-doc/ * Reteisi: http://docs.argolinux.org/reteisi/ +* Roundup: http://www.roundup-tracker.org/ * Satchmo: http://www.satchmoproject.com/docs/svn/ * Self: http://selflanguage.org/ * Sphinx: http://sphinx.pocoo.org/ -- cgit v1.2.1 From c59edf8861c48613880224897df7e593def93332 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Thu, 5 Feb 2009 13:26:50 +0100 Subject: Add Pyevolve. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index d5f477cc..90e91ff3 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -31,6 +31,7 @@ included, please mail to `the Google group * Paver: http://www.blueskyonmars.com/projects/paver/ * Py on Windows: http://timgolden.me.uk/python-on-windows/ * PyEphem: http://rhodesmill.org/pyephem/ +* Pyevolve: http://pyevolve.sourceforge.net/ * PyPubSub: http://pubsub.sourceforge.net/ * PyUblas: http://tiker.net/doc/pyublas/ * Pylons: http://docs.pylonshq.com/ -- cgit v1.2.1 From 4a1a34b1ae1492a834d7ab652a6783b716ae8af0 Mon Sep 17 00:00:00 2001 From: mitsuhiko <devnull@localhost> Date: Thu, 5 Feb 2009 13:28:46 +0100 Subject: attribute documentation now overrides non attribute documentation. This makes it possible to document aliased methods and other things:: def foo(self): pass #: an alias for foo() foo_alias = foo Also attribute documentation can contain paragraphs now. --- sphinx/ext/autodoc.py | 30 +++++++++++++++++++----------- sphinx/util/docstrings.py | 8 ++++++-- 2 files changed, 25 insertions(+), 13 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index a817e343..2727fd6c 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -359,7 +359,7 @@ class RstGenerator(object): return '' def generate(self, what, name, members, add_content, indent=u'', check_module=False, - no_docstring=False): + no_docstring=False, real_module=None): """ Generate reST for the object in self.result. """ @@ -388,9 +388,17 @@ class RstGenerator(object): (what, str(fullname), err)) return + # if there is no real-module defined figure out which to use. The real module + # is used in the module analyzer to look up the module where the attribute + # documentation would actually be found in. + # This is used for situations where you have a module that collects the + # functions and classes of internal submodules. + if real_module is None: + real_module = getattr(todoc, '__module__', None) or mod + # try to also get a source code analyzer for attribute docs try: - analyzer = ModuleAnalyzer.for_module(mod) + analyzer = ModuleAnalyzer.for_module(real_module) # parse right now, to get PycodeErrors on parsing analyzer.parse() except PycodeError, err: @@ -465,14 +473,13 @@ class RstGenerator(object): sys.getfilesystemencoding(), 'replace') sourcename = u'%s:docstring of %s' % (srcname, fullname) attr_docs = analyzer.find_attr_docs() - if what in ('data', 'attribute'): - key = ('.'.join(objpath[:-1]), objpath[-1]) - if key in attr_docs: - no_docstring = True - docstrings = [attr_docs[key]] - for i, line in enumerate(self.process_doc(docstrings, what, - fullname, todoc)): - self.result.append(indent + line, sourcename, i) + key = ('.'.join(objpath[:-1]), objpath[-1]) + if key in attr_docs: + no_docstring = True + docstrings = [attr_docs[key]] + for i, line in enumerate(self.process_doc(docstrings, what, + fullname, todoc)): + self.result.append(indent + line, sourcename, i) else: sourcename = u'docstring of %s' % fullname attr_docs = {} @@ -605,7 +612,8 @@ class RstGenerator(object): full_membername = mod + '::' + '.'.join(objpath + [membername]) self.generate(memberwhat, full_membername, ['__all__'], add_content=content, no_docstring=bool(content), - indent=indent, check_module=members_check_module) + indent=indent, check_module=members_check_module, + real_module=real_module) self.env.autodoc_current_module = None self.env.autodoc_current_class = None diff --git a/sphinx/util/docstrings.py b/sphinx/util/docstrings.py index 1b0a599a..ea03340a 100644 --- a/sphinx/util/docstrings.py +++ b/sphinx/util/docstrings.py @@ -49,8 +49,12 @@ def prepare_commentdoc(s): result = [] lines = [line.strip() for line in s.expandtabs().splitlines()] for line in lines: - if line.startswith('#: '): - result.append(line[3:]) + if line.startswith('#:'): + line = line[2:] + # the first space after the comment is ignored + if line and line[0] == ' ': + line = line[1:] + result.append(line) if result and result[-1]: result.append('') return result -- cgit v1.2.1 From d4879916e33c21ff8f888f2e71ff3868bf9a1766 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Fri, 6 Feb 2009 17:41:41 +0100 Subject: Fix #97: redundant wording. --- doc/concepts.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/concepts.rst b/doc/concepts.rst index 23725b10..a748acad 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -57,8 +57,8 @@ tables of contents. The ``toctree`` directive is the central element. chapter", "previous chapter" and "parent chapter" links. Document titles in the :dir:`toctree` will be automatically read from the - title of the referenced document. If that isn't what you want, you can give - the specify an explicit title and target using a similar syntax to reST + title of the referenced document. If that isn't what you want, you can + specify an explicit title and target using a similar syntax to reST hyperlinks (and Sphinx's :ref:`cross-referencing syntax <xref-syntax>`). This looks like:: -- cgit v1.2.1 From 183ab534dc2ca0319eb4441bd6e69c1cd208cce6 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Fri, 6 Feb 2009 17:50:24 +0100 Subject: Add Ukrainian translation, by Stoune. --- CHANGES | 2 + doc/config.rst | 1 + sphinx/locale/uk_UA/LC_MESSAGES/sphinx.js | 1 + sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo | Bin 0 -> 9801 bytes sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po | 595 ++++++++++++++++++++++++++++++ 5 files changed, 599 insertions(+) create mode 100644 sphinx/locale/uk_UA/LC_MESSAGES/sphinx.js create mode 100644 sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo create mode 100644 sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po diff --git a/CHANGES b/CHANGES index 3ef35a5e..f390afcb 100644 --- a/CHANGES +++ b/CHANGES @@ -80,6 +80,8 @@ New features added - Italian by Sandro Dentella. + - Ukrainian by Stoune. + * Extensions and API: - Autodoc now handles documented attributes. diff --git a/doc/config.rst b/doc/config.rst index 8fc7978c..c59ea01a 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -210,6 +210,7 @@ Project information * ``pl`` -- Polish * ``pt_BR`` -- Brazilian Portuguese * ``sl`` -- Slovenian + * ``uk_UA`` -- Ukrainian * ``zh_TW`` -- Traditional Chinese .. confval:: today diff --git a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.js b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.js new file mode 100644 index 00000000..d1089bf1 --- /dev/null +++ b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "uk_UA", "plural_expr": "(n%10==1 && n%100!=11 ? 0 : n%10>=2 && n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)", "messages": {"module, in ": "\u043c\u043e\u0434\u0443\u043b\u044c, \u0432 ", "Preparing search...": "\u041f\u0456\u0434\u0433\u043e\u0442\u043e\u0432\u043a\u0430 \u0434\u043e \u043f\u043e\u0448\u0443\u043a\u0443...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "\u0412\u0430\u0448 \u043f\u043e\u0448\u0443\u043a \u043d\u0435 \u0432\u0438\u044f\u0432\u0438\u0432 \u0436\u043e\u0434\u043d\u043e\u0433\u043e \u0441\u043f\u0456\u0432\u043f\u0430\u0434\u0456\u043d\u043d\u044f. \u0411\u0443\u0434\u044c-\u043b\u0430\u0441\u043a\u0430 \u043f\u0435\u0440\u0435\u043a\u043e\u043d\u0430\u0439\u0442\u0435\u0441\u044f \u0449\u043e \u0432\u0441\u0456 \u0441\u043b\u043e\u0432\u0430 \u043d\u0430\u0431\u0440\u0430\u043d\u0456 \u043f\u0440\u0430\u0432\u0438\u043b\u044c\u043d\u043e \u0456 \u0432\u0438 \u043e\u0431\u0440\u0430\u043b\u0438 \u0434\u043e\u0441\u0442\u0430\u0442\u043d\u044c\u043e \u043a\u0430\u0442\u0435\u0433\u043e\u0440\u0456\u0439.", "Search finished, found %s page(s) matching the search query.": "\u041f\u043e\u0448\u0443\u043a \u0437\u0430\u043a\u0456\u043d\u0447\u0435\u043d\u043e, \u0437\u043d\u0430\u0439\u0434\u0435\u043d\u043e %s \u0441\u0442\u043e\u0440\u0456\u043d\u043e\u043a \u044f\u043a\u0456 \u0441\u043f\u0456\u0432\u043f\u0430\u043b\u0438 \u0437 \u043f\u043e\u0448\u0443\u043a\u043e\u0432\u0438\u043c \u0437\u0430\u043f\u0438\u0442\u043e\u043c.", ", in ": ", \u0432 ", "Permalink to this headline": "\u041f\u043e\u0441\u0442\u0456\u0439\u043d\u0435 \u043f\u043e\u0441\u0438\u043b\u0430\u043d\u043d\u044f \u043d\u0430 \u0446\u0435\u0439 \u0437\u0430\u0433\u043e\u043b\u043e\u0432\u043e\u043a", "Searching": "\u0428\u0443\u043a\u0430\u044e", "Permalink to this definition": "\u041f\u043e\u0441\u0442\u0456\u0439\u043d\u0435 \u043f\u043e\u0441\u0438\u043b\u0430\u043d\u043d\u044f \u043d\u0430 \u0446\u0435 \u0432\u0438\u0437\u043d\u0430\u0447\u0435\u043d\u043d\u044f", "Hide Search Matches": "\u041f\u0440\u0438\u0445\u043e\u0432\u0430\u0442\u0438 \u0441\u043f\u0456\u0432\u043f\u0430\u0434\u0456\u043d\u043d\u044f \u043f\u043e\u0448\u0443\u043a\u0443", "Search Results": "\u0420\u0435\u0437\u0443\u043b\u044c\u0442\u0430\u0442\u0438 \u043f\u043e\u0448\u0443\u043a\u0443"}}); \ No newline at end of file diff --git a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo new file mode 100644 index 00000000..6677bc57 Binary files /dev/null and b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po new file mode 100644 index 00000000..9f6992f0 --- /dev/null +++ b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.po @@ -0,0 +1,595 @@ +# Ukrainian (Ukraine) translations for Sphinx. +# Copyright (C) 2009 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# Petro Sasnyk <petro@sasnyk.name>, 2009. +# +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.6\n" +"Report-Msgid-Bugs-To: EMAIL@ADDRESS\n" +"POT-Creation-Date: 2008-12-28 23:40+0100\n" +"PO-Revision-Date: 2009-01-14 17:34+0200\n" +"Last-Translator: Petro Sasnyk <petro@sasnyk.name>\n" +"Language-Team: uk_UA <LL@li.org>\n" +"Plural-Forms: nplurals=3; plural=(n%10==1 && n%100!=11 ? 0 : n%10>=2 && " +"n%10<=4 && (n%100<10 || n%100>=20) ? 1 : 2)\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.4\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "Індекс" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Індекс модулів" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Сторінка пошуку" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "змінна оточення; %s" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "Python Enhancement Proposals!PEP %s" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "Вбудовані елементи" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Рівень модуля" + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%b %d, %Y" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Загальний індекс" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "індекс" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Загальний індекс модулів" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "модулі" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr "наступний" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "попередній" + +#: sphinx/builders/latex.py:155 +msgid " (in " +msgstr " (в " + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "%s() (вбудована функція)" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "%s() (в модулі %s)" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "%s (вбудована змінна)" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "%s (в модулі %s)" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "%s (вбудований клас)" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "%s (клас в %s)" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "%s() (%s.%s метод)" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "%s() (%s метод)" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "%s() (%s.%s статичний метод)" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "%s() (%s статичний метод)" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "%s (%s.%s атрибут)" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "%s (%s атрибут)" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "%s (С функція)" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "%s (C член)" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "%s (C макрос)" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "%s (C тип)" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "%s (C змінна)" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "Викликає" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "Змінна" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "Повертає" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "Тип повернення" + +#: sphinx/directives/desc.py:213 +msgid "Parameter" +msgstr "Параметр" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "Параметри" + +#: sphinx/directives/desc.py:465 +#, python-format +msgid "%scommand line option; %s" +msgstr "%sопція командного рядка; %s" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Платформи: " + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (модуль)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Автор секції: " + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Автор модуля: " + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Автор: " + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "Дивись також" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr " Базовий: %s" + +#: sphinx/ext/autodoc.py:563 sphinx/ext/autodoc.py:580 +#, python-format +msgid "alias of :class:`%s`" +msgstr "синонім :class:`%s`" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Доробити" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "(Початкове входження знаходиться в %s, рядок %d і може бути знайдений " + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "тут" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Увага" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Застереження" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Небезпека" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Помилка" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Підказка" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Важливо" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Примітка" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Дивись також" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Порада" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Попередження" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Нове в версії %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Змінено в версії %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Застаріло починаючи з версії %s" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "модуль" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "ключове слово" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "оператор" + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "об'єкт" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "виняткова ситуація" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "вираз" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "вбудована функція" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "Постійне посилання на цей заголовок" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "Постійне посилання на це визначення" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Приховати співпадіння пошуку" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Шукаю" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Підготовка до пошуку..." + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "модуль, в " + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr ", в " + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "Результати пошуку" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "" +"Ваш пошук не виявив жодного співпадіння. Будь-ласка переконайтеся що всі " +"слова набрані правильно і ви обрали достатньо категорій." + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "Пошук закінчено, знайдено %s сторінок які співпали з пошуковим запитом." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Огляд" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "Індекси та таблиці:" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "Повний Зміст" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "перелічити всі секції та підсекції" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "шукати цю документацію" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "швидкий доступ до всіх модулів" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "всі функції, класи, терміни" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "Індекс – %(key)" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Повний індекс на одній сторінці" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Індексні сторінки по символам" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "може бути величезним" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Навігація" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Зміст" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "Попередній розділ" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "Попередній розділ" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr "Наступна тема" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr "наступний розділ" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "Ця сторінка" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "Відобразити вихідний текст" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Швидкий пошук" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "Вперед" + +#: sphinx/templates/layout.html:78 +msgid "Enter search terms or a module, class or function name." +msgstr "Введіть пошуковий термін, модуль, клас чи назву функції." + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "Шукати в %(docstitle)s" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "Про ці документи" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Пошук" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "Авторські права" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "© Copyright %(copyright)s." + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "Востаннє оновлено %(last_updated)s." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr "" +"Створено з використанням <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "Застарілий" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "Пошук %(docstitle)s" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "Будь-ласка вімкніть підтримку JavaScript, щоб ввікнути\n" +" пошук." + +#: sphinx/templates/search.html:14 +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "" +"Звідси ви можете шукати ці документи. Введіть ваші пошукові\n" +" слова в поле нижче та натисніть \"пошук\". Зауважте що функція\n" +" пошуку автоматично шукатиме за всіма словами. Сторінки\n" +" що містять менше слів не з'являться в результуючому списку." + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "пошук" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "Ваш пошук не виявив жодних співпадінь." + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Зміни в Версії %(version)s — %(docstitle)" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "%(filename) — %(docstitle)" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Автоматичного згенерований список змін в версії %(version)" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "Зміни в бібліотеці" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "зміни C API" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "Інші зміни" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "Реліз" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Platform: %s" +msgstr "Платформа: %s" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "" + -- cgit v1.2.1 From 376ef7c9cb923f0922b4510670110c5423ce8b6e Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Fri, 6 Feb 2009 19:04:14 +0100 Subject: Add several projects. --- EXAMPLES | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/EXAMPLES b/EXAMPLES index 90e91ff3..625e113e 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -7,8 +7,10 @@ included, please mail to `the Google group <http://groups.google.com/group/sphinx-dev>`_. * APSW: http://apsw.googlecode.com/svn/publish/index.html +* boostmpi: http://documen.tician.de/boostmpi/ * Calibre: http://calibre.kovidgoyal.net/user_manual/ * Chaco: http://code.enthought.com/projects/chaco/docs/html/ +* CodePy: http://documen.tician.de/codepy/ * Cython: http://docs.cython.org/ * Director: http://packages.python.org/director/ * Django: http://docs.djangoproject.com/ @@ -16,11 +18,13 @@ included, please mail to `the Google group * GeoDjango: http://geodjango.org/docs/ * Glashammer: http://glashammer.org/ * Grok: http://grok.zope.org/doc/current/ +* Hedge: http://documen.tician.de/hedge/ * IFM: http://fluffybunny.memebot.com/ifm-docs/index.html * Jinja: http://jinja.pocoo.org/2/documentation/ * MapServer: http://mapserver.osgeo.org/ * Matplotlib: http://matplotlib.sourceforge.net/ * Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi +* MeshPy: http://documen.tician.de/meshpy/ * Mixin.com: http://dev.mixin.com/ * mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html * NetworkX: http://networkx.lanl.gov/ @@ -30,14 +34,17 @@ included, please mail to `the Google group * Paste: http://pythonpaste.org/script/ * Paver: http://www.blueskyonmars.com/projects/paver/ * Py on Windows: http://timgolden.me.uk/python-on-windows/ +* PyCuda: http://documen.tician.de/pycuda/ * PyEphem: http://rhodesmill.org/pyephem/ * Pyevolve: http://pyevolve.sourceforge.net/ -* PyPubSub: http://pubsub.sourceforge.net/ -* PyUblas: http://tiker.net/doc/pyublas/ +* Pylo: http://documen.tician.de/pylo/ * Pylons: http://docs.pylonshq.com/ +* PyPubSub: http://pubsub.sourceforge.net/ +* pyrticle: http://documen.tician.de/pyrticle/ * Pysparse: http://pysparse.sourceforge.net/ * Python: http://docs.python.org/dev/ * python-apt: http://people.debian.org/~jak/python-apt-doc/ +* PyUblas: http://documen.tician.de/pyublas/ * Reteisi: http://docs.argolinux.org/reteisi/ * Roundup: http://www.roundup-tracker.org/ * Satchmo: http://www.satchmoproject.com/docs/svn/ -- cgit v1.2.1 From 522308f342b09a297981f4b3377aecd5f67a5d47 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Fri, 6 Feb 2009 22:18:16 +0100 Subject: Skip pygments-related tests if it is not installed. --- sphinx/environment.py | 2 -- tests/test_build.py | 27 ++++++++++++++++++--------- tests/test_highlighting.py | 15 +++++++++++---- 3 files changed, 29 insertions(+), 15 deletions(-) diff --git a/sphinx/environment.py b/sphinx/environment.py index 991fab72..4aa32ed0 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -832,8 +832,6 @@ class BuildEnvironment: def get_toctree_for(self, docname, builder): """Return the global TOC nodetree.""" - - # XXX why master_doc? doctree = self.get_doctree(self.config.master_doc) for toctreenode in doctree.traverse(addnodes.toctree): result = self.resolve_toctree(docname, builder, toctreenode, diff --git a/tests/test_build.py b/tests/test_build.py index ed2d9982..21d829cb 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -20,6 +20,11 @@ from subprocess import Popen, PIPE from util import * from etree13 import ElementTree as ET +try: + import pygments +except ImportError: + pygments = None + from sphinx.builders.html import StandaloneHTMLBuilder from sphinx.builders.latex import LaTeXBuilder from sphinx.writers.latex import LaTeXTranslator @@ -58,18 +63,9 @@ HTML_XPATH = { ".//img[@src='../_images/img1.png']": '', }, 'includes.html': { - ".//pre/span[@class='s']": u'üöä', ".//pre": u'Max Strauß', ".//a[@href='_downloads/img.png']": '', ".//a[@href='_downloads/img1.png']": '', - ".//div[@class='inc-pyobj1 highlight-text']/div/pre": - r'^class Foo:\n pass\n\s*$', - ".//div[@class='inc-pyobj2 highlight-text']/div/pre": - r'^ def baz\(\):\n pass\n\s*$', - ".//div[@class='inc-lines highlight-text']/div/pre": - r'^class Foo:\n pass\nclass Bar:\n$', - ".//div[@class='inc-startend highlight-text']/div/pre": - ur'^foo = u"Including Unicode characters: üöä"\n$', }, 'autodoc.html': { ".//dt[@id='test_autodoc.Class']": '', @@ -99,6 +95,19 @@ HTML_XPATH = { }, } +if pygments: + HTML_XPATH['includes.html'].update({ + ".//pre/span[@class='s']": u'üöä', + ".//div[@class='inc-pyobj1 highlight-text']/div/pre": + r'^class Foo:\n pass\n\s*$', + ".//div[@class='inc-pyobj2 highlight-text']/div/pre": + r'^ def baz\(\):\n pass\n\s*$', + ".//div[@class='inc-lines highlight-text']/div/pre": + r'^class Foo:\n pass\nclass Bar:\n$', + ".//div[@class='inc-startend highlight-text']/div/pre": + ur'^foo = u"Including Unicode characters: üöä"\n$', + }) + class NslessParser(ET.XMLParser): """XMLParser that throws away namespaces in tag names.""" diff --git a/tests/test_highlighting.py b/tests/test_highlighting.py index 198f7a0a..ea1f25f1 100644 --- a/tests/test_highlighting.py +++ b/tests/test_highlighting.py @@ -11,6 +11,12 @@ from util import * +try: + import pygments +except ImportError: + from nose.plugins.skip import SkipTest + raise SkipTest('pygments not available') + from pygments.lexer import RegexLexer from pygments.token import Text, Name from pygments.formatters.html import HtmlFormatter @@ -28,16 +34,17 @@ class MyLexer(RegexLexer): ], } -class ComplainOnUnhighlighted(PygmentsBridge): - - def unhighlighted(self, source): - raise AssertionError("should highlight %r" % source) class MyFormatter(HtmlFormatter): def format(self, tokensource, outfile): outfile.write('test') +class ComplainOnUnhighlighted(PygmentsBridge): + def unhighlighted(self, source): + raise AssertionError("should highlight %r" % source) + + @with_app() def test_add_lexer(app): app.add_lexer('test', MyLexer()) -- cgit v1.2.1 From 0743857bed5894a95ebe4134b0c5fc1c0e714455 Mon Sep 17 00:00:00 2001 From: mitsuhiko <devnull@localhost> Date: Fri, 6 Feb 2009 22:25:39 +0100 Subject: Fixed a bug in autodoc that caused a lot of headaches to the testsuite. --- sphinx/ext/autodoc.py | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 2727fd6c..aecf343c 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -473,13 +473,14 @@ class RstGenerator(object): sys.getfilesystemencoding(), 'replace') sourcename = u'%s:docstring of %s' % (srcname, fullname) attr_docs = analyzer.find_attr_docs() - key = ('.'.join(objpath[:-1]), objpath[-1]) - if key in attr_docs: - no_docstring = True - docstrings = [attr_docs[key]] - for i, line in enumerate(self.process_doc(docstrings, what, - fullname, todoc)): - self.result.append(indent + line, sourcename, i) + if objpath: + key = ('.'.join(objpath[:-1]), objpath[-1]) + if key in attr_docs: + no_docstring = True + docstrings = [attr_docs[key]] + for i, line in enumerate(self.process_doc(docstrings, what, + fullname, todoc)): + self.result.append(indent + line, sourcename, i) else: sourcename = u'docstring of %s' % fullname attr_docs = {} -- cgit v1.2.1 From 63617c4daa54abf96305e7afdf75972ffd299713 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 7 Feb 2009 13:32:47 +0100 Subject: Patch from Stefan Seefeld: make local toctree collapsible. --- sphinx/builders/html.py | 7 +++++-- sphinx/config.py | 1 + sphinx/directives/other.py | 4 ++-- sphinx/environment.py | 33 +++++++++++++++++++++++++++------ sphinx/util/__init__.py | 2 +- 5 files changed, 36 insertions(+), 11 deletions(-) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 660e63ca..0b2946ae 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -164,6 +164,10 @@ class StandaloneHTMLBuilder(Builder): ) self.globalcontext.update(self.config.html_context) + def _get_local_toctree(self, docname): + return self.render_partial(self.env.get_toctree_for( + docname, self, self.config.html_collapse_toctree))['fragment'] + def get_doc_context(self, docname, body, metatags): """Collect items for the template context of a page.""" # find out relations @@ -219,8 +223,6 @@ class StandaloneHTMLBuilder(Builder): metatags = metatags, rellinks = rellinks, sourcename = sourcename, - toctree = self.render_partial(self.env.get_toctree_for( - docname, self))['fragment'], toc = self.render_partial(self.env.get_toc_for(docname))['fragment'], # only display a TOC if there's more than one item to show display_toc = (self.env.toc_num_entries[docname] > 1), @@ -474,6 +476,7 @@ class StandaloneHTMLBuilder(Builder): ctx['pathto'] = pathto ctx['hasdoc'] = lambda name: name in self.env.all_docs ctx['customsidebar'] = self.config.html_sidebars.get(pagename) + ctx['toctree'] = self._get_local_toctree(pagename) ctx.update(addctx) self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) diff --git a/sphinx/config.py b/sphinx/config.py index a3de68f5..24c3e83f 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -66,6 +66,7 @@ class Config(object): html_use_smartypants = (True, False), html_translator_class = (None, False), html_sidebars = ({}, False), + html_collapse_toctree = (False, False), html_additional_pages = ({}, False), html_use_modindex = (True, False), html_add_permalinks = (True, False), diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index a7cdd904..ab98ee61 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -14,7 +14,7 @@ from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.locale import pairindextypes -from sphinx.util import patfilter, ws_re, caption_ref_re, docname_join +from sphinx.util import patfilter, ws_re, caption_ref_re, url_re, docname_join from sphinx.util.compat import make_admonition @@ -53,7 +53,7 @@ def toctree_directive(name, arguments, options, content, lineno, docname = docname[:-len(suffix)] # absolutize filenames docname = docname_join(env.docname, docname) - if ref.startswith('http://'): # FIXME: generalize to arbitrary xrefs + if url_re.match(ref): entries.append((title, ref)) elif docname not in env.found_docs: ret.append(state.document.reporter.warning( diff --git a/sphinx/environment.py b/sphinx/environment.py index 4aa32ed0..aa5eede6 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -44,7 +44,7 @@ from docutils.transforms.parts import ContentsFilter from sphinx import addnodes from sphinx.util import movefile, get_matching_docs, SEP, ustrftime, \ - docname_join, FilenameUniqDict + docname_join, FilenameUniqDict, url_re from sphinx.directives import additional_xref_types default_settings = { @@ -830,12 +830,12 @@ class BuildEnvironment: node['refuri'] = node['anchorname'] return toc - def get_toctree_for(self, docname, builder): + def get_toctree_for(self, docname, builder, collapse): """Return the global TOC nodetree.""" doctree = self.get_doctree(self.config.master_doc) for toctreenode in doctree.traverse(addnodes.toctree): result = self.resolve_toctree(docname, builder, toctreenode, - prune=True) + prune=True, collapse=collapse) if result is not None: return result @@ -909,7 +909,7 @@ class BuildEnvironment: return doctree def resolve_toctree(self, docname, builder, toctree, prune=True, maxdepth=0, - titles_only=False): + titles_only=False, collapse=False): """ Resolve a *toctree* node into individual bullet lists with titles as items, returning None (if no containing titles are found) or @@ -919,6 +919,8 @@ class BuildEnvironment: to the value of the *maxdepth* option on the *toctree* node. If *titles_only* is True, only toplevel document titles will be in the resulting tree. + If *collapse* is True, all branches not containing docname will + be collapsed. """ if toctree.get('hidden', False): return None @@ -935,13 +937,30 @@ class BuildEnvironment: else: _walk_depth(subnode, depth+1, maxdepth) + # cull sub-entries whose parents aren't 'current' + if (collapse and + depth > 1 and + 'current' not in subnode.parent['classes']): + subnode.parent.remove(subnode) + + elif isinstance(subnode, nodes.reference): + # Identify the toc entry pointing to the current document. + if subnode['refuri'] == docname and not subnode['anchorname']: + # tag the whole branch as 'current' + # (We can't use traverse here as 'ascend' un-intuitively + # implies 'siblings'.) + p = subnode + while p: + p['classes'].append('current') + p = p.parent + def _entries_from_toctree(toctreenode, separate=False, subtree=False): """Return TOC entries for a toctree node.""" refs = [(e[0], str(e[1])) for e in toctreenode['entries']] entries = [] for (title, ref) in refs: try: - if ref.startswith('http://'): # FIXME: (see directives/other.py) + if url_re.match(ref): reference = nodes.reference('', '', refuri=ref, anchorname='', *[nodes.Text(title)]) para = addnodes.compact_paragraph('', '', reference) @@ -1001,11 +1020,13 @@ class BuildEnvironment: newnode = addnodes.compact_paragraph('', '', *tocentries) newnode['toctree'] = True + # prune the tree to maxdepth and replace titles, also set level classes _walk_depth(newnode, 1, prune and maxdepth or 0) + # set the target paths in the toctrees (they are not known at TOC generation time) for refnode in newnode.traverse(nodes.reference): - if not refnode['refuri'].startswith('http://'): # FIXME: see above + if not url_re.match(refnode['refuri']): refnode['refuri'] = builder.get_relative_uri( docname, refnode['refuri']) + refnode['anchorname'] return newnode diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index edfb31d8..6b64483d 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -23,7 +23,7 @@ from os import path # Generally useful regular expressions. ws_re = re.compile(r'\s+') caption_ref_re = re.compile(r'^([^<]+?)\s*<(.+)>$') - +url_re = re.compile(r'(?P<schema>.+)://.*') # SEP separates path elements in the canonical file names # -- cgit v1.2.1 From 5c0d8eece2669cd349cd149d55deafd04eb7383a Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 7 Feb 2009 14:13:13 +0100 Subject: Added a ``toctree`` variable to the templates, and the ability to The new ``html_collapse_toctree`` config value can be used to "collapse" the generated toctree given to the templates. --- CHANGES | 5 ++++- doc/conf.py | 2 ++ doc/config.rst | 8 ++++++++ 3 files changed, 14 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index f390afcb..48e54fda 100644 --- a/CHANGES +++ b/CHANGES @@ -49,7 +49,7 @@ New features added - #23: Added a ``classmethod`` directive along with ``method`` and ``staticmethod``. - - Added a toctree variable to the templates, and the ability to + - Added a ``toctree`` variable to the templates, and the ability to include external links in toctrees. * Configuration: @@ -61,6 +61,9 @@ New features added - The new ``html_show_sourcelink`` config value can be used to switch off the links to the reST sources in the sidebar. + - The new ``html_collapse_toctree`` config value can be used to + "collapse" the generated toctree given to the templates. + - The default value for ``htmlhelp_basename`` is now the project title, cleaned up as a filename. diff --git a/doc/conf.py b/doc/conf.py index 709d6f75..c0f8f9a5 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -82,6 +82,8 @@ html_style = 'sphinxdoc.css' # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +html_collapse_toctree = True + # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = '%b %d, %Y' diff --git a/doc/config.rst b/doc/config.rst index c59ea01a..4b184b7a 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -462,6 +462,14 @@ that use Sphinx' HTMLWriter class. .. versionadded:: 0.4 +.. confval:: html_collapse_toctree + + If true, the toctree given to the templates as ``toctree`` will be collapsed, + i.e. only the subitems that contain the current page are visible. Default is + ``False``. + + .. versionadded:: 0.6 + .. confval:: htmlhelp_basename Output file base name for HTML help builder. Default is ``'pydoc'``. -- cgit v1.2.1 From ae2b21615eb49fd63be01d360be0a8f33a35fbca Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 7 Feb 2009 19:35:53 +0100 Subject: Revert accidental debugging leftover. --- doc/conf.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index c0f8f9a5..709d6f75 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -82,8 +82,6 @@ html_style = 'sphinxdoc.css' # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] -html_collapse_toctree = True - # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. html_last_updated_fmt = '%b %d, %Y' -- cgit v1.2.1 From 3c5d3068a185b5a31fbb5735eb887bb910a5e45c Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 7 Feb 2009 19:41:10 +0100 Subject: Add a rst_epilog setting, usable for global substitutions. --- CHANGES | 4 ++++ doc/config.rst | 16 ++++++++++++++++ sphinx/config.py | 1 + sphinx/environment.py | 9 ++++++--- tests/root/conf.py | 3 +++ tests/root/markup.txt | 2 ++ tests/test_build.py | 1 + 7 files changed, 33 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index 48e54fda..002740ec 100644 --- a/CHANGES +++ b/CHANGES @@ -54,6 +54,10 @@ New features added * Configuration: + - The new config value ``rst_epilog`` can contain reST that is + appended to each source file that is read. This is the right + place for global substitutions. + - The new ``html_add_permalinks`` config value can be used to switch off the generated "paragraph sign" permalinks for each heading and definition environment. diff --git a/doc/config.rst b/doc/config.rst index 4b184b7a..92557bed 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -141,8 +141,24 @@ General configuration instance is then used to render HTML documents, and possibly the output of other builders (currently the changes builder). +.. confval:: rst_epilog + + .. index:: pair: global; substitutions + + A string of reStructuredText that will be included at the end of every source + file that is read. This is the right place to add substitutions that should + be available in every file. An example:: + + rest_preamble = """ + .. |psf| replace:: Python Software Foundation + """ + + .. versionadded:: 0.6 + .. confval:: default_role + .. index:: default; role + The name of a reST role (builtin or Sphinx extension) to use as the default role, that is, for text marked up ```like this```. This can be set to ``'obj'`` to make ```filter``` a cross-reference to the function "filter". diff --git a/sphinx/config.py b/sphinx/config.py index 24c3e83f..910069f0 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -52,6 +52,7 @@ class Config(object): templates_path = ([], False), template_bridge = (None, False), keep_warnings = (False, True), + rst_epilog = (None, True), # HTML options html_title = (lambda self: '%s v%s documentation' % diff --git a/sphinx/environment.py b/sphinx/environment.py index aa5eede6..fccecf07 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -521,13 +521,16 @@ class BuildEnvironment: self.config.trim_footnote_reference_space class SphinxSourceClass(FileInput): - def read(self): - data = FileInput.read(self) + def read(self_): + data = FileInput.read(self_) if app: arg = [data] app.emit('source-read', docname, arg) data = arg[0] - return data + if self.config.rst_epilog: + return data + '\n' + self.config.rst_epilog + '\n' + else: + return data # publish manually pub = Publisher(reader=SphinxStandaloneReader(), diff --git a/tests/root/conf.py b/tests/root/conf.py index 12951d03..8f67a450 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -77,6 +77,9 @@ keep_warnings = True # The name of the Pygments (syntax highlighting) style to use. pygments_style = 'sphinx' +# Global substitutions +rst_epilog = '.. |subst| replace:: global substitution' + # Options for HTML output # ----------------------- diff --git a/tests/root/markup.txt b/tests/root/markup.txt index 777fbd2f..e01d2152 100644 --- a/tests/root/markup.txt +++ b/tests/root/markup.txt @@ -11,6 +11,8 @@ Testing various markup :author: Me :keywords: docs, sphinx +A |subst|. + .. _label: :: diff --git a/tests/test_build.py b/tests/test_build.py index 21d829cb..9c8698c4 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -78,6 +78,7 @@ HTML_XPATH = { ".//a[@href='contents.html#ref1']": '', ".//div[@id='label']": '', ".//span[@class='option']": '--help', + ".//p": 'A global substitution.', }, 'desc.html': { ".//dt[@id='mod.Cls.meth1']": '', -- cgit v1.2.1 From d4ffd4a6786546b3f03d771abc94217dcfa3a297 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 7 Feb 2009 20:38:56 +0100 Subject: Clarify what needs to be added to extensions. --- doc/ext/math.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/ext/math.rst b/doc/ext/math.rst index f2664dfe..87ea220d 100644 --- a/doc/ext/math.rst +++ b/doc/ext/math.rst @@ -17,8 +17,9 @@ if possible, reuse that support too. .. note:: - :mod:`sphinx.ext.mathbase` does not need to be added to the - :confval:`extensions` config value. + :mod:`sphinx.ext.mathbase` is not meant to be added to the + :confval:`extensions` config value, instead, use either + :mod:`sphinx.ext.pngmath` or :mod:`sphinx.ext.jsmath` as described below. The input language for mathematics is LaTeX markup. This is the de-facto standard for plain-text math notation and has the added advantage that no -- cgit v1.2.1 From e3fc28cbaa37b8c4746a1b23b21935adca5e61dc Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Thu, 12 Feb 2009 12:50:42 +0100 Subject: Add FAQ, to be expanded. --- doc/contents.rst | 3 ++- doc/faq.rst | 20 ++++++++++++++++++++ 2 files changed, 22 insertions(+), 1 deletion(-) create mode 100644 doc/faq.rst diff --git a/doc/contents.rst b/doc/contents.rst index 6ddbcbcb..c4fb107b 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -14,7 +14,8 @@ Sphinx documentation contents config templating extensions - + + faq glossary changes examples diff --git a/doc/faq.rst b/doc/faq.rst new file mode 100644 index 00000000..d447602f --- /dev/null +++ b/doc/faq.rst @@ -0,0 +1,20 @@ +.. _faq: + +Sphinx FAQ +========== + +This is a list of Frequently Asked Questions about Sphinx. Feel free to +suggest new entries! + +How do I... +----------- + +... add global substitutions? + Add them in the :confval:`rst_epilog` config value. + +... use Sphinx with Epydoc? + There's a third-party extension providing an `api role`_ which refers to + Epydoc's API docs for a given identifier. + + +.. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py -- cgit v1.2.1 From d906311bb4281b54535cb8a1209645b373a6b5fb Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 11:38:28 +0100 Subject: Fix handling of "docname" and target names in LaTeX builder. --- sphinx/builders/latex.py | 18 +++++++++++------- sphinx/writers/latex.py | 4 ++-- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index 3b7b0c19..395ccd9d 100644 --- a/sphinx/builders/latex.py +++ b/sphinx/builders/latex.py @@ -52,6 +52,10 @@ class LaTeXBuilder(Builder): else: return '%' + docname + def get_relative_uri(self, from_, to, typ=None): + # ignore source path + return self.get_target_uri(to, typ) + def init_document_data(self): preliminary_document_data = map(list, self.config.latex_documents) if not preliminary_document_data: @@ -72,11 +76,6 @@ class LaTeXBuilder(Builder): self.titles.append((docname, entry[2])) def write(self, *ignored): - # first, assemble the "appendix" docs that are in every PDF - appendices = [] - for fname in self.config.latex_appendices: - appendices.append(self.env.get_doctree(fname)) - docwriter = LaTeXWriter(self) docsettings = OptionParser( defaults=self.env.settings, @@ -94,7 +93,8 @@ class LaTeXBuilder(Builder): encoding='utf-8') self.info("processing " + targetname + "... ", nonl=1) doctree = self.assemble_doctree(docname, toctree_only, - appendices=(docclass == 'manual') and appendices or []) + appendices=((docclass == 'manual') and + self.config.latex_appendices or [])) self.post_process_images(doctree) self.info("writing... ", nonl=1) doctree.settings = docsettings @@ -140,7 +140,11 @@ class LaTeXBuilder(Builder): new_sect += node tree = new_tree largetree = process_tree(indexfile, tree) - largetree.extend(appendices) + largetree['docname'] = indexfile + for docname in appendices: + appendix = self.env.get_doctree(docname) + appendix['docname'] = docname + largetree.append(appendix) self.info() self.info("resolving references...") self.env.resolve_references(largetree, indexfile, self) diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index e1fbea13..057e229b 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -239,7 +239,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_document(self, node): self.footnotestack.append(self.collect_footnotes(node)) - self.curfilestack.append(node['file']) + self.curfilestack.append(node['docname']) if self.first_document == 1: # the first document is all the regular content ... self.body.append(BEGIN_DOC % self.elements) @@ -274,7 +274,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.footnotestack.append(self.collect_footnotes(node)) # also add a document target self.body.append('\\hypertarget{--doc-%s}{}' % node['docname']) - self.curfilestack.append(node['file']) + self.curfilestack.append(node['docname']) def collect_footnotes(self, node): fnotes = {} -- cgit v1.2.1 From 1f61a0bac545320b464668a13528c755a9b10d48 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 13:05:36 +0100 Subject: Make the "toctree" context item a callable. --- sphinx/builders/html.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 3b3abaa8..59cadde2 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -477,7 +477,7 @@ class StandaloneHTMLBuilder(Builder): ctx['pathto'] = pathto ctx['hasdoc'] = lambda name: name in self.env.all_docs ctx['customsidebar'] = self.config.html_sidebars.get(pagename) - ctx['toctree'] = self._get_local_toctree(pagename) + ctx['toctree'] = lambda: self._get_local_toctree(pagename) ctx.update(addctx) self.app.emit('html-page-context', pagename, templatename, ctx, event_arg) -- cgit v1.2.1 From 99397e86fa053df850f851147b00bec5665282b6 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 13:38:09 +0100 Subject: Make builds 20-25% faster by supplying custom versions of node.traverse(). --- sphinx/util/__init__.py | 36 ++++++++++++++++++++++++++++++++++++ sphinx/writers/latex.py | 2 +- 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 6b64483d..75707d89 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -13,6 +13,7 @@ import os import re import sys import time +import types import fnmatch import tempfile import posixpath @@ -371,3 +372,38 @@ def movefile(source, dest): except OSError: pass os.rename(source, dest) + + +# monkey-patch Node.traverse + +def _all_traverse(self): + """Version of Node.traverse() that doesn't need a condition.""" + result = [] + result.append(self) + for child in self.children: + result.extend(child._all_traverse()) + return result + +def _fast_traverse(self, cls): + """Version of Node.traverse() that only supports instance checks.""" + result = [] + if isinstance(self, cls): + result.append(self) + for child in self.children: + result.extend(child._fast_traverse(cls)) + return result + +def _new_traverse(self, condition=None, + include_self=1, descend=1, siblings=0, ascend=0): + if include_self and descend and not siblings and not ascend: + if condition is None: + return self._all_traverse() + elif isinstance(condition, (types.ClassType, type)): + return self._fast_traverse(condition) + return self._old_traverse(condition, include_self, descend, siblings, ascend) + +import docutils.nodes +docutils.nodes.Node._old_traverse = docutils.nodes.Node.traverse +docutils.nodes.Node._all_traverse = _all_traverse +docutils.nodes.Node._fast_traverse = _fast_traverse +docutils.nodes.Node.traverse = _new_traverse diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 057e229b..7fa21fc6 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -239,7 +239,7 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_document(self, node): self.footnotestack.append(self.collect_footnotes(node)) - self.curfilestack.append(node['docname']) + self.curfilestack.append(node.get('docname', '')) if self.first_document == 1: # the first document is all the regular content ... self.body.append(BEGIN_DOC % self.elements) -- cgit v1.2.1 From d72d177988ad1ae330498616d144961dbc1d3e31 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 13:48:07 +0100 Subject: Warn if a static path dir doesn't exist. --- sphinx/builders/html.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 59cadde2..d2bd5e01 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -392,6 +392,9 @@ class StandaloneHTMLBuilder(Builder): [path.join(self.confdir, spath) for spath in self.config.html_static_path] for staticdirname in staticdirnames: + if not path.isdir(staticdirname): + self.warn('static directory %r does not exist' % staticdirname) + continue for filename in os.listdir(staticdirname): if filename.startswith('.'): continue -- cgit v1.2.1 From 9a88cb6a696a962c19711a067ef070e47c7dd19c Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 15:09:45 +0100 Subject: Add Finnish translation by Jukka Inkeri. --- CHANGES | 4 +- doc/config.rst | 1 + sphinx/locale/cs/LC_MESSAGES/sphinx.mo | Bin 8268 -> 7816 bytes sphinx/locale/de/LC_MESSAGES/sphinx.js | 2 +- sphinx/locale/de/LC_MESSAGES/sphinx.mo | Bin 7111 -> 8058 bytes sphinx/locale/es/LC_MESSAGES/sphinx.mo | Bin 6617 -> 6809 bytes sphinx/locale/fi/LC_MESSAGES/sphinx.js | 1 + sphinx/locale/fi/LC_MESSAGES/sphinx.mo | Bin 0 -> 7537 bytes sphinx/locale/fi/LC_MESSAGES/sphinx.po | 600 ++++++++++++++++++++++++++++++ sphinx/locale/fr/LC_MESSAGES/sphinx.mo | Bin 7324 -> 7516 bytes sphinx/locale/it/LC_MESSAGES/sphinx.mo | Bin 7944 -> 8136 bytes sphinx/locale/ja/LC_MESSAGES/sphinx.mo | Bin 7345 -> 7537 bytes sphinx/locale/nl/LC_MESSAGES/sphinx.mo | Bin 6882 -> 7074 bytes sphinx/locale/pl/LC_MESSAGES/sphinx.mo | Bin 6982 -> 7174 bytes sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo | Bin 7280 -> 7472 bytes sphinx/locale/sl/LC_MESSAGES/sphinx.mo | Bin 7016 -> 7208 bytes sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo | Bin 9801 -> 9801 bytes sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo | Bin 7368 -> 7560 bytes 18 files changed, 606 insertions(+), 2 deletions(-) create mode 100644 sphinx/locale/fi/LC_MESSAGES/sphinx.js create mode 100644 sphinx/locale/fi/LC_MESSAGES/sphinx.mo create mode 100644 sphinx/locale/fi/LC_MESSAGES/sphinx.po diff --git a/CHANGES b/CHANGES index 7209b3b5..d0ff30d5 100644 --- a/CHANGES +++ b/CHANGES @@ -87,7 +87,9 @@ New features added - Italian by Sandro Dentella. - - Ukrainian by Stoune. + - Ukrainian by Petro Sasnyk. + + - Finnish by Jukka Inkeri. * Extensions and API: diff --git a/doc/config.rst b/doc/config.rst index 92557bed..a0151dda 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -220,6 +220,7 @@ Project information * ``de`` -- German * ``en`` -- English * ``es`` -- Spanish + * ``fi`` -- Finnish * ``fr`` -- French * ``it`` -- Italian * ``nl`` -- Dutch diff --git a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo index 9178448d..3dccc2b9 100644 Binary files a/sphinx/locale/cs/LC_MESSAGES/sphinx.mo and b/sphinx/locale/cs/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/de/LC_MESSAGES/sphinx.js b/sphinx/locale/de/LC_MESSAGES/sphinx.js index 98aa5c12..542c094f 100644 --- a/sphinx/locale/de/LC_MESSAGES/sphinx.js +++ b/sphinx/locale/de/LC_MESSAGES/sphinx.js @@ -1 +1 @@ -Documentation.addTranslations({"locale": "de", "plural_expr": "(n != 1)", "messages": {"module, in ": "Modul, in ", "Preparing search...": "Suche wird vorbereitet...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Es wurden keine Dokumente gefunden. Haben Sie alle Suchworte richtig geschrieben und gen\u00fcgend Kategorien ausgew\u00e4hlt?", "Search finished, found %s page(s) matching the search query.": "Suche beendet, %s Seite(n) mit Ergebnissen wurden gefunden.", ", in ": "", "Permalink to this headline": "Permalink zu dieser \u00dcberschrift", "Searching": "Suchen...", "Permalink to this definition": "Permalink zu dieser Definition", "Hide Search Matches": "Suchergebnisse ausblenden", "Search Results": "Suchergebnisse"}}); \ No newline at end of file +Documentation.addTranslations({"locale": "de", "plural_expr": "(n != 1)", "messages": {"module, in ": "Modul, in ", "Preparing search...": "Suche wird vorbereitet...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Es wurden keine Dokumente gefunden. Haben Sie alle Suchworte richtig geschrieben und gen\u00fcgend Kategorien ausgew\u00e4hlt?", "Search finished, found %s page(s) matching the search query.": "Suche beendet, %s Seite(n) mit Ergebnissen wurden gefunden.", ", in ": ", in ", "Permalink to this headline": "Permalink zu dieser \u00dcberschrift", "Searching": "Suchen...", "Permalink to this definition": "Permalink zu dieser Definition", "Hide Search Matches": "Suchergebnisse ausblenden", "Search Results": "Suchergebnisse"}}); \ No newline at end of file diff --git a/sphinx/locale/de/LC_MESSAGES/sphinx.mo b/sphinx/locale/de/LC_MESSAGES/sphinx.mo index 981da26a..1f8f8d2d 100644 Binary files a/sphinx/locale/de/LC_MESSAGES/sphinx.mo and b/sphinx/locale/de/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/es/LC_MESSAGES/sphinx.mo b/sphinx/locale/es/LC_MESSAGES/sphinx.mo index dcc8bbc2..2989194c 100644 Binary files a/sphinx/locale/es/LC_MESSAGES/sphinx.mo and b/sphinx/locale/es/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/fi/LC_MESSAGES/sphinx.js b/sphinx/locale/fi/LC_MESSAGES/sphinx.js new file mode 100644 index 00000000..f654e7e1 --- /dev/null +++ b/sphinx/locale/fi/LC_MESSAGES/sphinx.js @@ -0,0 +1 @@ +Documentation.addTranslations({"locale": "fi", "plural_expr": "(n != 1)", "messages": {"module, in ": "", "Preparing search...": "Valmistellaan etsint\u00e4\u00e4...", "Your search did not match any documents. Please make sure that all words are spelled correctly and that you've selected enough categories.": "Ei l\u00f6ytynyt yht\u00e4\u00e4n. Tarkista hakuehdot, sanahaku, ei sen osia", "Search finished, found %s page(s) matching the search query.": "Etsint\u00e4 tehty, l\u00f6ydetty %s sivu(a).", ", in ": "", "Permalink to this headline": "", "Searching": "Etsit\u00e4\u00e4n", "Permalink to this definition": "", "Hide Search Matches": "Piilota l\u00f6ydetyt", "Search Results": "Etsinn\u00e4n tulos"}}); \ No newline at end of file diff --git a/sphinx/locale/fi/LC_MESSAGES/sphinx.mo b/sphinx/locale/fi/LC_MESSAGES/sphinx.mo new file mode 100644 index 00000000..3207b738 Binary files /dev/null and b/sphinx/locale/fi/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/fi/LC_MESSAGES/sphinx.po b/sphinx/locale/fi/LC_MESSAGES/sphinx.po new file mode 100644 index 00000000..7bbe636e --- /dev/null +++ b/sphinx/locale/fi/LC_MESSAGES/sphinx.po @@ -0,0 +1,600 @@ +# Finnish translations for Sphinx. +# Copyright (C) 2009 ORGANIZATION +# This file is distributed under the same license as the Sphinx project. +# FIRST AUTHOR <EMAIL@ADDRESS>, 2009. +# +msgid "" +msgstr "" +"Project-Id-Version: Sphinx 0.6\n" +"Report-Msgid-Bugs-To: sphinx@awot.fi\n" +"POT-Creation-Date: 2009-01-24 18:39+0000\n" +"PO-Revision-Date: 2009-02-11 11:21+0200\n" +"Last-Translator: Jukka Inkeri <sphinx@awot.fi>\n" +"Language-Team: fi <sphinx@awot.fi>\n" +"Plural-Forms: nplurals=2; plural=(n != 1)\n" +"MIME-Version: 1.0\n" +"Content-Type: text/plain; charset=utf-8\n" +"Content-Transfer-Encoding: 8bit\n" +"Generated-By: Babel 0.9.4\n" + +#: sphinx/environment.py:104 sphinx/writers/latex.py:170 +#, python-format +msgid "%B %d, %Y" +msgstr "%d.%m.%Y" + +#: sphinx/environment.py:300 sphinx/templates/genindex-single.html:2 +#: sphinx/templates/genindex-split.html:2 +#: sphinx/templates/genindex-split.html:5 sphinx/templates/genindex.html:2 +#: sphinx/templates/genindex.html:5 sphinx/templates/genindex.html:48 +#: sphinx/templates/layout.html:126 sphinx/writers/latex.py:176 +msgid "Index" +msgstr "Sisällysluettelo" + +#: sphinx/environment.py:301 sphinx/writers/latex.py:175 +msgid "Module Index" +msgstr "Moduuli sisällysluettelo" + +#: sphinx/environment.py:302 sphinx/templates/defindex.html:16 +msgid "Search Page" +msgstr "Etsi sivu" + +#: sphinx/roles.py:53 sphinx/directives/desc.py:580 +#, python-format +msgid "environment variable; %s" +msgstr "" + +#: sphinx/roles.py:60 +#, python-format +msgid "Python Enhancement Proposals!PEP %s" +msgstr "" + +#: sphinx/builders/changes.py:64 +msgid "Builtins" +msgstr "" + +#: sphinx/builders/changes.py:66 +msgid "Module level" +msgstr "Moduulitaso" + + +#: sphinx/builders/html.py:118 +#, python-format +msgid "%b %d, %Y" +msgstr "%d.%m.%Y" + +#: sphinx/builders/html.py:137 sphinx/templates/defindex.html:21 +msgid "General Index" +msgstr "Yleinen sisällysluettelo" + +#: sphinx/builders/html.py:137 +msgid "index" +msgstr "hakemisto" + +#: sphinx/builders/html.py:139 sphinx/builders/htmlhelp.py:182 +#: sphinx/builders/qthelp.py:131 sphinx/templates/defindex.html:19 +#: sphinx/templates/modindex.html:2 sphinx/templates/modindex.html:13 +msgid "Global Module Index" +msgstr "Yleinen moduulien sisällysluettelo" + +#: sphinx/builders/html.py:139 +msgid "modules" +msgstr "moduulit" +#msgstr "osat" + +#: sphinx/builders/html.py:179 +msgid "next" +msgstr ">" + +#: sphinx/builders/html.py:186 +msgid "previous" +msgstr "<" + +#: sphinx/builders/latex.py:155 sphinx/builders/pdf.py:162 +msgid " (in " +msgstr "" + +#: sphinx/directives/desc.py:25 +#, python-format +msgid "%s() (built-in function)" +msgstr "" + +#: sphinx/directives/desc.py:26 sphinx/directives/desc.py:42 +#: sphinx/directives/desc.py:54 +#, python-format +msgid "%s() (in module %s)" +msgstr "" + +#: sphinx/directives/desc.py:29 +#, python-format +msgid "%s (built-in variable)" +msgstr "" + +#: sphinx/directives/desc.py:30 sphinx/directives/desc.py:78 +#, python-format +msgid "%s (in module %s)" +msgstr "" + +#: sphinx/directives/desc.py:33 +#, python-format +msgid "%s (built-in class)" +msgstr "" + +#: sphinx/directives/desc.py:34 +#, python-format +msgid "%s (class in %s)" +msgstr "" + +#: sphinx/directives/desc.py:46 +#, python-format +msgid "%s() (%s.%s method)" +msgstr "" + +#: sphinx/directives/desc.py:48 +#, python-format +msgid "%s() (%s method)" +msgstr "" + +#: sphinx/directives/desc.py:58 +#, python-format +msgid "%s() (%s.%s static method)" +msgstr "" + +#: sphinx/directives/desc.py:60 +#, python-format +msgid "%s() (%s static method)" +msgstr "" + +#: sphinx/directives/desc.py:82 +#, python-format +msgid "%s (%s.%s attribute)" +msgstr "" + +#: sphinx/directives/desc.py:84 +#, python-format +msgid "%s (%s attribute)" +msgstr "" + +#: sphinx/directives/desc.py:86 +#, python-format +msgid "%s (C function)" +msgstr "" + +#: sphinx/directives/desc.py:88 +#, python-format +msgid "%s (C member)" +msgstr "" + +#: sphinx/directives/desc.py:90 +#, python-format +msgid "%s (C macro)" +msgstr "" + +#: sphinx/directives/desc.py:92 +#, python-format +msgid "%s (C type)" +msgstr "" + +#: sphinx/directives/desc.py:94 +#, python-format +msgid "%s (C variable)" +msgstr "" + +#: sphinx/directives/desc.py:112 +msgid "Raises" +msgstr "" + +#: sphinx/directives/desc.py:116 +msgid "Variable" +msgstr "" + +#: sphinx/directives/desc.py:119 +msgid "Returns" +msgstr "" + +#: sphinx/directives/desc.py:128 +msgid "Return type" +msgstr "" + +#: sphinx/directives/desc.py:213 +msgid "Parameter" +msgstr "" + +#: sphinx/directives/desc.py:217 +msgid "Parameters" +msgstr "" + +#: sphinx/directives/desc.py:465 +#, python-format +msgid "%scommand line option; %s" +msgstr "" + +#: sphinx/directives/other.py:101 +msgid "Platforms: " +msgstr "Ympäristö" + +#: sphinx/directives/other.py:106 +#, python-format +msgid "%s (module)" +msgstr "%s (moduuli)" + +#: sphinx/directives/other.py:146 +msgid "Section author: " +msgstr "Luvun kirjoittaja: " + +#: sphinx/directives/other.py:148 +msgid "Module author: " +msgstr "Moduulin kirjoittaja: " + +#: sphinx/directives/other.py:150 +msgid "Author: " +msgstr "Tekijä: " + +#: sphinx/directives/other.py:249 +msgid "See also" +msgstr "Katso myös" + +#: sphinx/ext/autodoc.py:442 +#, python-format +msgid " Bases: %s" +msgstr "" + +#: sphinx/ext/autodoc.py:566 sphinx/ext/autodoc.py:583 +#, python-format +msgid "alias of :class:`%s`" +msgstr "" + +#: sphinx/ext/todo.py:31 +msgid "Todo" +msgstr "Tehtävä vielä" + +#: sphinx/ext/todo.py:75 +#, python-format +msgid "(The original entry is located in %s, line %d and can be found " +msgstr "" + +#: sphinx/ext/todo.py:81 +msgid "here" +msgstr "tässä" + +#: sphinx/locale/__init__.py:15 +msgid "Attention" +msgstr "Huom" + +#: sphinx/locale/__init__.py:16 +msgid "Caution" +msgstr "Varoitus" + +#: sphinx/locale/__init__.py:17 +msgid "Danger" +msgstr "Vaara" + +#: sphinx/locale/__init__.py:18 +msgid "Error" +msgstr "Virhe" + +#: sphinx/locale/__init__.py:19 +msgid "Hint" +msgstr "Vihje" + +#: sphinx/locale/__init__.py:20 +msgid "Important" +msgstr "Tärkeä" + +#: sphinx/locale/__init__.py:21 +msgid "Note" +msgstr "Muista" + +#: sphinx/locale/__init__.py:22 +msgid "See Also" +msgstr "Katso myös" + +#: sphinx/locale/__init__.py:23 +msgid "Tip" +msgstr "Vihje" + +#: sphinx/locale/__init__.py:24 +msgid "Warning" +msgstr "Varoitus" + +#: sphinx/locale/__init__.py:28 +#, python-format +msgid "New in version %s" +msgstr "Uusi versiossa %s" + +#: sphinx/locale/__init__.py:29 +#, python-format +msgid "Changed in version %s" +msgstr "Muutettu versiossa %s" + +#: sphinx/locale/__init__.py:30 +#, python-format +msgid "Deprecated since version %s" +msgstr "Poistettu versiosta %s alkaen" + +#: sphinx/locale/__init__.py:34 +msgid "module" +msgstr "moduuli" +#msgstr "osa" + +#: sphinx/locale/__init__.py:35 +msgid "keyword" +msgstr "" +#msgstr "avainsana" + +#: sphinx/locale/__init__.py:36 +msgid "operator" +msgstr "" +#msgstr "operaattori" + + +#: sphinx/locale/__init__.py:37 +msgid "object" +msgstr "" +#msgstr "objekti" + +#: sphinx/locale/__init__.py:38 +msgid "exception" +msgstr "" +#msgstr "poikkeus" + +#: sphinx/locale/__init__.py:39 +msgid "statement" +msgstr "" + +#: sphinx/locale/__init__.py:40 +msgid "built-in function" +msgstr "" + +#: sphinx/static/doctools.js:139 sphinx/writers/html.py:425 +msgid "Permalink to this headline" +msgstr "" + +#: sphinx/static/doctools.js:145 sphinx/writers/html.py:80 +msgid "Permalink to this definition" +msgstr "" + +#: sphinx/static/doctools.js:174 +msgid "Hide Search Matches" +msgstr "Piilota löydetyt" + +#: sphinx/static/searchtools.js:274 +msgid "Searching" +msgstr "Etsitään" + +#: sphinx/static/searchtools.js:279 +msgid "Preparing search..." +msgstr "Valmistellaan etsintää..." + +#: sphinx/static/searchtools.js:338 +msgid "module, in " +msgstr "" + +#: sphinx/static/searchtools.js:347 +msgid ", in " +msgstr "" + +#: sphinx/static/searchtools.js:453 sphinx/templates/search.html:25 +msgid "Search Results" +msgstr "Etsinnän tulos" + +#: sphinx/static/searchtools.js:455 +msgid "" +"Your search did not match any documents. Please make sure that all words " +"are spelled correctly and that you've selected enough categories." +msgstr "Ei löytynyt yhtään. Tarkista hakuehdot, sanahaku, ei sen osia" + +#: sphinx/static/searchtools.js:457 +#, python-format +msgid "Search finished, found %s page(s) matching the search query." +msgstr "Etsintä tehty, löydetty %s sivu(a)." + +#: sphinx/templates/defindex.html:2 +msgid "Overview" +msgstr "Yhteenveto" + +#: sphinx/templates/defindex.html:11 +msgid "Indices and tables:" +msgstr "" + +#: sphinx/templates/defindex.html:14 +msgid "Complete Table of Contents" +msgstr "" + +#: sphinx/templates/defindex.html:15 +msgid "lists all sections and subsections" +msgstr "" + +#: sphinx/templates/defindex.html:17 +msgid "search this documentation" +msgstr "" + +#: sphinx/templates/defindex.html:20 +msgid "quick access to all modules" +msgstr "" + +#: sphinx/templates/defindex.html:22 +msgid "all functions, classes, terms" +msgstr "" + +#: sphinx/templates/genindex-single.html:5 +#, python-format +msgid "Index – %(key)s" +msgstr "" + +#: sphinx/templates/genindex-single.html:44 +#: sphinx/templates/genindex-split.html:14 +#: sphinx/templates/genindex-split.html:27 sphinx/templates/genindex.html:54 +msgid "Full index on one page" +msgstr "Hakemisto yhtenä luettelona" + +#: sphinx/templates/genindex-split.html:7 +msgid "Index pages by letter" +msgstr "Hakemisto aakkostus sivuttain" + +#: sphinx/templates/genindex-split.html:15 +msgid "can be huge" +msgstr "voi olla iso" + +#: sphinx/templates/layout.html:9 +msgid "Navigation" +msgstr "Navikointi" + +#: sphinx/templates/layout.html:40 +msgid "Table Of Contents" +msgstr "Sisällysluettelo" + +#: sphinx/templates/layout.html:46 +msgid "Previous topic" +msgstr "<<" + +#: sphinx/templates/layout.html:48 +msgid "previous chapter" +msgstr "<<" + +#: sphinx/templates/layout.html:51 +msgid "Next topic" +msgstr ">>" + +#: sphinx/templates/layout.html:53 +msgid "next chapter" +msgstr ">>" + +#: sphinx/templates/layout.html:58 +msgid "This Page" +msgstr "Tämä sivu" + +#: sphinx/templates/layout.html:61 +msgid "Show Source" +msgstr "Näytä lähdekoodina" + +#: sphinx/templates/layout.html:71 +msgid "Quick search" +msgstr "Pikahaku" + +#: sphinx/templates/layout.html:74 +msgid "Go" +msgstr "Siirry" + +#: sphinx/templates/layout.html:78 +msgid "Enter search terms or a module, class or function name." +msgstr "Anna etsittävä termi tai moduuli, luokka tai funktio" + +#: sphinx/templates/layout.html:115 +#, python-format +msgid "Search within %(docstitle)s" +msgstr "" + +#: sphinx/templates/layout.html:124 +msgid "About these documents" +msgstr "Tietoja tästä documentistä" + +#: sphinx/templates/layout.html:127 sphinx/templates/search.html:2 +#: sphinx/templates/search.html:5 +msgid "Search" +msgstr "Etsi" + +#: sphinx/templates/layout.html:129 +msgid "Copyright" +msgstr "" +#msgstr "(c)" + +#: sphinx/templates/layout.html:174 +#, python-format +msgid "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +msgstr "" +#msgstr "© <a href=\"%(path)s\">Copyright</a> %(copyright)s." +#msgstr "© <a href=\"%(path)s\">kaikki pidätetään</A> %(copyright)." + +#: sphinx/templates/layout.html:176 +#, python-format +msgid "© Copyright %(copyright)s." +msgstr "" +##msgstr "© Copyright %(copyright)s." +#msgstr "© %(copyright)." + +#: sphinx/templates/layout.html:179 +#, python-format +msgid "Last updated on %(last_updated)s." +msgstr "" +#msgstr "Viimeksi muutettu %(last_updated)." + +#: sphinx/templates/layout.html:182 +#, python-format +msgid "" +"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> " +"%(sphinx_version)s." +msgstr """ +#msgstr "Tehty <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> %(sphinx_version)" + +#: sphinx/templates/modindex.html:36 +msgid "Deprecated" +msgstr "Poistettu" + +#: sphinx/templates/opensearch.xml:4 +#, python-format +msgid "Search %(docstitle)s" +msgstr "" + +#: sphinx/templates/search.html:9 +msgid "" +"Please activate JavaScript to enable the search\n" +" functionality." +msgstr "Javascript pitää olla sallittu, jotta etsintä toimii." + +#: sphinx/templates/search.html:14 +msgid "" +"From here you can search these documents. Enter your search\n" +" words into the box below and click \"search\". Note that the search\n" +" function will automatically search for all of the words. Pages\n" +" containing fewer words won't appear in the result list." +msgstr "Anna hakusanat kokonaan, osasanoilla ei haeta." + +#: sphinx/templates/search.html:21 +msgid "search" +msgstr "etsi" + +#: sphinx/templates/search.html:27 +msgid "Your search did not match any results." +msgstr "Ei löytynyt ko. ehdoilla yhtään." + +#: sphinx/templates/changes/frameset.html:5 +#: sphinx/templates/changes/versionchanges.html:12 +#, python-format +msgid "Changes in Version %(version)s — %(docstitle)s" +msgstr "Muutos versiosta %(version) — %(docstitle)" + +#: sphinx/templates/changes/rstsource.html:5 +#, python-format +msgid "%(filename)s — %(docstitle)s" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:17 +#, python-format +msgid "Automatically generated list of changes in version %(version)s" +msgstr "Automaattisesti luotu muutoshistoria alkaen versiosta %(version)" + +#: sphinx/templates/changes/versionchanges.html:18 +msgid "Library changes" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:23 +msgid "C API changes" +msgstr "" + +#: sphinx/templates/changes/versionchanges.html:25 +msgid "Other changes" +msgstr "" + +#: sphinx/writers/latex.py:173 +msgid "Release" +msgstr "" + +#: sphinx/writers/text.py:166 +#, python-format +msgid "Ympäristö: %s" +msgstr "" + +#: sphinx/writers/text.py:427 +msgid "[image]" +msgstr "" + diff --git a/sphinx/locale/fr/LC_MESSAGES/sphinx.mo b/sphinx/locale/fr/LC_MESSAGES/sphinx.mo index 32633296..c7b2474d 100644 Binary files a/sphinx/locale/fr/LC_MESSAGES/sphinx.mo and b/sphinx/locale/fr/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/it/LC_MESSAGES/sphinx.mo b/sphinx/locale/it/LC_MESSAGES/sphinx.mo index 3aa570de..4f95d152 100644 Binary files a/sphinx/locale/it/LC_MESSAGES/sphinx.mo and b/sphinx/locale/it/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/ja/LC_MESSAGES/sphinx.mo b/sphinx/locale/ja/LC_MESSAGES/sphinx.mo index 85f6f8cc..36735ab5 100644 Binary files a/sphinx/locale/ja/LC_MESSAGES/sphinx.mo and b/sphinx/locale/ja/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/nl/LC_MESSAGES/sphinx.mo b/sphinx/locale/nl/LC_MESSAGES/sphinx.mo index 2b6ac75e..035fd0e3 100644 Binary files a/sphinx/locale/nl/LC_MESSAGES/sphinx.mo and b/sphinx/locale/nl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/pl/LC_MESSAGES/sphinx.mo b/sphinx/locale/pl/LC_MESSAGES/sphinx.mo index b08244bf..93fd9f94 100644 Binary files a/sphinx/locale/pl/LC_MESSAGES/sphinx.mo and b/sphinx/locale/pl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo index 3044318a..7c470e4f 100644 Binary files a/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo and b/sphinx/locale/pt_BR/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/sl/LC_MESSAGES/sphinx.mo b/sphinx/locale/sl/LC_MESSAGES/sphinx.mo index e0936704..e8cc5a6e 100644 Binary files a/sphinx/locale/sl/LC_MESSAGES/sphinx.mo and b/sphinx/locale/sl/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo index 6677bc57..db1ce221 100644 Binary files a/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo and b/sphinx/locale/uk_UA/LC_MESSAGES/sphinx.mo differ diff --git a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo index bd4acf00..f0576ccd 100644 Binary files a/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo and b/sphinx/locale/zh_TW/LC_MESSAGES/sphinx.mo differ -- cgit v1.2.1 From ad6d8fd2dc90935a10d98d27c2da6fb5f9fcb304 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 15:11:25 +0100 Subject: Fix example. --- doc/config.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/config.rst b/doc/config.rst index a0151dda..e35ca696 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -149,7 +149,7 @@ General configuration file that is read. This is the right place to add substitutions that should be available in every file. An example:: - rest_preamble = """ + rst_epilog = """ .. |psf| replace:: Python Software Foundation """ -- cgit v1.2.1 From 110f358852854b38ba252706cd0c7d8f28e998a8 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 15:29:18 +0100 Subject: Image paths can now be absolute (like ``/images/foo.png``). They are treated as relative to the top source directory. --- CHANGES | 7 +++++-- sphinx/environment.py | 6 +++++- tests/root/subdir/images.txt | 2 ++ tests/test_build.py | 1 + 4 files changed, 13 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index d0ff30d5..bdb141f0 100644 --- a/CHANGES +++ b/CHANGES @@ -37,6 +37,9 @@ New features added the directive -- this allows you to define your document structure, but place the links yourself. + - Image paths can now be absolute (like ``/images/foo.png``). + They are treated as relative to the top source directory. + - #52: There is now a ``hlist`` directive, creating a compact list by placing distributing items into multiple columns. @@ -49,8 +52,8 @@ New features added - #23: Added a ``classmethod`` directive along with ``method`` and ``staticmethod``. - - Added a ``toctree`` variable to the templates, and the ability to - include external links in toctrees. + - Added a ``toctree`` callable to the templates, and the ability + to include external links in toctrees. * Configuration: diff --git a/sphinx/environment.py b/sphinx/environment.py index 36009f80..d49356d1 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -647,7 +647,11 @@ class BuildEnvironment: candidates['?'] = imguri continue # imgpath is the image path *from srcdir* - imgpath = path.normpath(path.join(docdir, imguri)) + if imguri.startswith('/') or imguri.startswith(os.sep): + # absolute path (= relative to srcdir) + imgpath = path.normpath(imguri[1:]) + else: + imgpath = path.normpath(path.join(docdir, imguri)) # set imgpath as default URI node['uri'] = imgpath if imgpath.endswith(os.extsep + '*'): diff --git a/tests/root/subdir/images.txt b/tests/root/subdir/images.txt index 33adf5b5..f2adf88d 100644 --- a/tests/root/subdir/images.txt +++ b/tests/root/subdir/images.txt @@ -2,3 +2,5 @@ Image including source in subdir ================================ .. image:: img.* + +.. image:: /rimg.png diff --git a/tests/test_build.py b/tests/test_build.py index 9c8698c4..6e8c5c24 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -61,6 +61,7 @@ HTML_XPATH = { }, 'subdir/images.html': { ".//img[@src='../_images/img1.png']": '', + ".//img[@src='../_images/rimg.png']": '', }, 'includes.html': { ".//pre": u'Max Strauß', -- cgit v1.2.1 From 7459cd7767c7c6716b930e84593d4cb44c3c49c9 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 15:32:41 +0100 Subject: Add docs for absolute image paths feature. --- doc/rest.rst | 15 +++++++++++---- 1 file changed, 11 insertions(+), 4 deletions(-) diff --git a/doc/rest.rst b/doc/rest.rst index d7ef5c7b..e6dfe0de 100644 --- a/doc/rest.rst +++ b/doc/rest.rst @@ -212,10 +212,14 @@ reST supports an image directive, used like so:: .. image:: gnu.png (options) -When used within Sphinx, the file name given (here ``gnu.png``) must be relative -to the source file, and Sphinx will automatically copy image files over to a -subdirectory of the output directory on building (e.g. the ``_static`` directory -for HTML output.) +When used within Sphinx, the file name given (here ``gnu.png``) must either be +relative to the source file, or absolute which means that they are relative to +the top source directory. For example, the file ``sketch/spam.rst`` could refer +to the image ``images/spam.png`` as ``../images/spam.png`` or +``/images/spam.png``. + +Sphinx will automatically copy image files over to a subdirectory of the output +directory on building (e.g. the ``_static`` directory for HTML output.) Interpretation of image size options (``width`` and ``height``) is as follows: if the size has no unit or the unit is pixels, the given size will only be @@ -236,6 +240,9 @@ the former, while the HTML builder would prefer the latter. .. versionchanged:: 0.4 Added the support for file names ending in an asterisk. +.. versionchanged:: 0.6 + Image paths can now be absolute. + Footnotes --------- -- cgit v1.2.1 From ede7b9ea692eae47c5b353c411f836cbdd81282c Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 19:05:26 +0100 Subject: Add SimPy and openWNS. --- EXAMPLES | 2 ++ 1 file changed, 2 insertions(+) diff --git a/EXAMPLES b/EXAMPLES index 625e113e..dec3c3ef 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -31,6 +31,7 @@ included, please mail to `the Google group * NumPy: http://docs.scipy.org/doc/numpy/reference/ * ObjectListView: http://objectlistview.sourceforge.net/python * OpenLayers: http://docs.openlayers.org/ +* openWNS: http://docs.openwns.org/ * Paste: http://pythonpaste.org/script/ * Paver: http://www.blueskyonmars.com/projects/paver/ * Py on Windows: http://timgolden.me.uk/python-on-windows/ @@ -49,6 +50,7 @@ included, please mail to `the Google group * Roundup: http://www.roundup-tracker.org/ * Satchmo: http://www.satchmoproject.com/docs/svn/ * Self: http://selflanguage.org/ +* SimPy: http://simpy.sourceforge.net/ * Sphinx: http://sphinx.pocoo.org/ * SQLAlchemy: http://www.sqlalchemy.org/docs/ * Sqlkit: http://sqlkit.argolinux.org/ -- cgit v1.2.1 From f7e898ef2a9b94037b315d6966c113cf3f462fdf Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 19:48:07 +0100 Subject: Add missing file. --- tests/root/rimg.png | Bin 0 -> 67861 bytes 1 file changed, 0 insertions(+), 0 deletions(-) create mode 100644 tests/root/rimg.png diff --git a/tests/root/rimg.png b/tests/root/rimg.png new file mode 100644 index 00000000..72c12d13 Binary files /dev/null and b/tests/root/rimg.png differ -- cgit v1.2.1 From ce2ba430878a8bfbcbfe7769d5ccff68885e9956 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sat, 14 Feb 2009 23:14:33 +0100 Subject: Make it more probable for docutils to report the correct source for content generated by autodoc. --- sphinx/directives/desc.py | 3 ++- sphinx/directives/other.py | 4 ++++ sphinx/ext/autodoc.py | 3 +++ sphinx/util/__init__.py | 12 ++++++++---- 4 files changed, 17 insertions(+), 5 deletions(-) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index 3ffe048b..2b741803 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -428,6 +428,7 @@ def desc_directive(desctype, arguments, options, content, lineno, env = state.document.settings.env inode = addnodes.index(entries=[]) node = addnodes.desc() + node.document = state.document node['desctype'] = desctype noindex = ('noindex' in options) @@ -520,6 +521,7 @@ def desc_directive(desctype, arguments, options, content, lineno, inode['entries'].append(('single', indextext, fullname, fullname)) subnode = addnodes.desc_content() + node.append(subnode) # needed for automatic qualification of members clsname_set = False if desctype in ('class', 'exception') and names: @@ -537,7 +539,6 @@ def desc_directive(desctype, arguments, options, content, lineno, if clsname_set: env.currclass = None env.currdesc = None - node.append(subnode) return [inode, node] desc_directive.content = 1 diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index ab98ee61..a5ba589a 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -228,6 +228,7 @@ directives.register_directive('index', index_directive) def version_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): node = addnodes.versionmodified() + node.document = state.document node['type'] = name node['version'] = arguments[0] if len(arguments) == 2: @@ -333,6 +334,7 @@ def glossary_directive(name, arguments, options, content, lineno, """Glossary with cross-reference targets for :term: roles.""" env = state.document.settings.env node = addnodes.glossary() + node.document = state.document state.nested_parse(content, content_offset, node) # the content should be definition lists @@ -381,6 +383,7 @@ directives.register_directive('centered', centered_directive) def acks_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): node = addnodes.acks() + node.document = state.document state.nested_parse(content, content_offset, node) if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): return [state.document.reporter.warning('.. acks content is not a list', @@ -396,6 +399,7 @@ def hlist_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): ncolumns = options.get('columns', 2) node = nodes.paragraph() + node.document = state.document state.nested_parse(content, content_offset, node) if len(node.children) != 1 or not isinstance(node.children[0], nodes.bullet_list): return [state.document.reporter.warning('.. hlist content is not a list', diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index aecf343c..0cb2b14b 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -652,9 +652,12 @@ def _auto_directive(dirname, arguments, options, content, lineno, state.memo.reporter = AutodocReporter(generator.result, state.memo.reporter) if dirname == 'automodule': node = nodes.section() + node.document = state.document # necessary so that the child nodes + # get the right source/line set nested_parse_with_titles(state, generator.result, node) else: node = nodes.paragraph() + node.document = state.document state.nested_parse(generator.result, 0, node) state.memo.reporter = old_reporter return generator.warnings + node.children diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 75707d89..944aa8d4 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -281,9 +281,11 @@ def nested_parse_with_titles(state, content, node): surrounding_section_level = state.memo.section_level state.memo.title_styles = [] state.memo.section_level = 0 - state.nested_parse(content, 0, node, match_titles=1) - state.memo.title_styles = surrounding_title_styles - state.memo.section_level = surrounding_section_level + try: + return state.nested_parse(content, 0, node, match_titles=1) + finally: + state.memo.title_styles = surrounding_title_styles + state.memo.section_level = surrounding_section_level def ustrftime(format, *args): @@ -374,7 +376,9 @@ def movefile(source, dest): os.rename(source, dest) -# monkey-patch Node.traverse +# monkey-patch Node.traverse to get more speed +# traverse() is called so many times during a build that it saves +# on average 20-25% overall build time! def _all_traverse(self): """Version of Node.traverse() that doesn't need a condition.""" -- cgit v1.2.1 From bbffb7d7d75c8f8440c57afe8efe6ad38fe12b74 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 00:07:05 +0100 Subject: Support theme zipfiles. --- sphinx/application.py | 1 + sphinx/builders/__init__.py | 5 +++++ sphinx/builders/html.py | 7 +++--- sphinx/jinja2glue.py | 2 +- sphinx/theming.py | 54 +++++++++++++++++++++++++++++++++++++++++---- 5 files changed, 61 insertions(+), 8 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 7b8462c0..856f9108 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -149,6 +149,7 @@ class Sphinx(object): raise else: self.emit('build-finished', None) + self.builder.cleanup() def warn(self, message): self._warncount += 1 diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index ee13947e..46054460 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -344,6 +344,11 @@ class Builder(object): """ pass + def cleanup(self): + """ + Cleanup any resources. The default implementation does nothing. + """ + BUILTIN_BUILDERS = { 'html': ('html', 'StandaloneHTMLBuilder'), diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index da8faed6..57105d16 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -237,8 +237,6 @@ class StandaloneHTMLBuilder(Builder): # local TOC and global TOC tree toc = self.render_partial(self.env.get_toc_for(docname))['fragment'] - toctree = self.render_partial( - self.env.get_toctree_for(docname, self))['fragment'] return dict( parents = parents, @@ -251,7 +249,6 @@ class StandaloneHTMLBuilder(Builder): rellinks = rellinks, sourcename = sourcename, toc = toc, - toctree = toctree, # only display a TOC if there's more than one item to show display_toc = (self.env.toc_num_entries[docname] > 1), ) @@ -477,6 +474,10 @@ class StandaloneHTMLBuilder(Builder): # dump the search index self.handle_finish() + def cleanup(self): + # clean up theme stuff + self.theme.cleanup() + def get_outdated_docs(self): if self.templates: template_mtime = self.templates.newest_template_mtime() diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index c5160376..c7c163aa 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -52,7 +52,7 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): return self.environment.get_template(template).render(context) def newest_template_mtime(self): - return max(mtimes_of_files(self.theme.themepath, '.html')) + return max(mtimes_of_files(self.theme.get_dirchain(), '.html')) # Loader interface diff --git a/sphinx/theming.py b/sphinx/theming.py index d0727c98..cdfe314a 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -10,6 +10,9 @@ """ import os +import shutil +import zipfile +import tempfile import ConfigParser from os import path @@ -41,16 +44,47 @@ class Theme(object): if not path.isdir(themedir): continue for theme in os.listdir(themedir): - if not path.isfile(path.join(themedir, theme, THEMECONF)): - continue - cls.themes[theme] = path.join(themedir, theme) + if theme.lower().endswith('.zip'): + try: + zfile = zipfile.ZipFile(path.join(themedir, theme)) + if THEMECONF not in zfile.namelist(): + continue + tname = theme[:-4] + tinfo = zfile + except Exception: + builder.warn('File %r on theme path is not a valid ' + 'zipfile or contains no theme' % theme) + continue + else: + if not path.isfile(path.join(themedir, theme, THEMECONF)): + continue + tname = theme + tinfo = None + cls.themes[tname] = (path.join(themedir, theme), tinfo) def __init__(self, name): if name not in self.themes: raise ThemeError('no theme named %r found ' '(missing theme.conf?)' % name) self.name = name - self.themedir = self.themes[name] + + tdir, tinfo = self.themes[name] + if tinfo is None: + # already a directory, do nothing + self.themedir = tdir + self.themedir_created = False + else: + # extract the theme to a temp directory + self.themedir = tempfile.mkdtemp('sxt') + self.themedir_created = True + for name in tinfo.namelist(): + if name.endswith('/'): continue + dirname = path.dirname(name) + if not path.isdir(path.join(self.themedir, dirname)): + os.makedirs(path.join(self.themedir, dirname)) + fp = open(path.join(self.themedir, name), 'w') + fp.write(tinfo.read(name)) + fp.close() self.themeconf = ConfigParser.RawConfigParser() self.themeconf.read(path.join(self.themedir, THEMECONF)) @@ -94,3 +128,15 @@ class Theme(object): chain.append(base.themedir) base = base.base return chain + + def cleanup(self): + """ + Remove temporary directories. + """ + if self.themedir_created: + try: + shutil.rmtree(self.themedir) + except Exception: + pass + if self.base: + self.base.cleanup() -- cgit v1.2.1 From abd62c95a0cbccf1a1b0dd865c7cdf83adbe7a8c Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 01:43:10 +0100 Subject: * Add support for theme options. * Make the right-/stickysidebar alternatives for the default design options. * Add theme-related options to quickstart. --- doc/_templates/layout.html | 4 ++-- sphinx/builders/html.py | 3 +++ sphinx/config.py | 1 + sphinx/jinja2glue.py | 11 ++++++++++- sphinx/quickstart.py | 15 +++++++++++---- sphinx/themes/basic/layout.html | 12 ++++++------ sphinx/themes/basic/theme.conf | 3 +++ sphinx/themes/default/layout.html | 12 ++++++++++++ sphinx/themes/default/static/rightsidebar.css | 6 ++---- sphinx/themes/default/static/stickysidebar.css | 13 ++++++++----- sphinx/themes/default/theme.conf | 4 ++++ sphinx/theming.py | 23 ++++++++++++++++++++++- 12 files changed, 84 insertions(+), 23 deletions(-) create mode 100644 sphinx/themes/default/layout.html diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index e8970899..2c370dbd 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -1,8 +1,8 @@ {% extends "!layout.html" %} {% block rootrellink %} - <li><a href="{{ pathto('index') }}">Sphinx home </a> | </li> - <li><a href="{{ pathto('contents') }}">Documentation </a> »</li> + <li><a href="{{ pathto('index') }}">Sphinx home</a>  | </li> + <li><a href="{{ pathto('contents') }}">Documentation</a> »</li> {% endblock %} {% block header %} diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 57105d16..a2414164 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -179,6 +179,9 @@ class StandaloneHTMLBuilder(Builder): logo = logo, favicon = favicon, ) + self.globalcontext.update( + ('theme_' + key, val) for (key, val) in + self.theme.get_options(self.config.html_theme_options).iteritems()) self.globalcontext.update(self.config.html_context) def _get_local_toctree(self, docname): diff --git a/sphinx/config.py b/sphinx/config.py index 2cba96a3..79f3ce8a 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -58,6 +58,7 @@ class Config(object): # HTML options html_theme = ('default', False), html_theme_path = ([], False), + html_theme_options = ({}, False), html_title = (lambda self: '%s v%s documentation' % (self.project, self.release), False), diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index c7c163aa..9fc9ba3a 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -18,6 +18,12 @@ from sphinx.util import mtimes_of_files from sphinx.application import TemplateBridge +def _tobool(val): + if isinstance(val, basestring): + return val.lower() in ('true', '1', 'yes', 'on') + return bool(val) + + class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): """ Interfaces the rendering environment of jinja2 for use in Sphinx. @@ -38,6 +44,8 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): chain[0:0] = [path.join(builder.confdir, tp) for tp in builder.config.templates_path] + self.pathchain = chain + # make the paths into loaders self.loaders = map(jinja2.FileSystemLoader, chain) @@ -45,6 +53,7 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): extensions = use_i18n and ['jinja2.ext.i18n'] or [] self.environment = jinja2.Environment(loader=self, extensions=extensions) + self.environment.filters['tobool'] = _tobool if use_i18n: self.environment.install_gettext_translations(builder.translator) @@ -52,7 +61,7 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): return self.environment.get_template(template).render(context) def newest_template_mtime(self): - return max(mtimes_of_files(self.theme.get_dirchain(), '.html')) + return max(mtimes_of_files(self.pathchain, '.html')) # Loader interface diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index c7bf92f6..d2a1c62d 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -114,10 +114,17 @@ pygments_style = 'sphinx' # -- Options for HTML output --------------------------------------------------- -# The style sheet to use for HTML and HTML Help pages. A file of that name -# must exist either in Sphinx' static/ path, or in one of the custom paths -# given in html_static_path. -html_style = 'default.css' +# The theme to use for HTML and HTML Help pages. Major themes that come with +# Sphinx are currently 'default' and 'sphinxdoc'. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] # The name for this set of Sphinx documents. If None, it defaults to # "<project> v<release> documentation". diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html index b4b1e7c5..dda18343 100644 --- a/sphinx/themes/basic/layout.html +++ b/sphinx/themes/basic/layout.html @@ -27,7 +27,7 @@ {%- endmacro %} {%- macro sidebar() %} - {%- if not embedded %} + {%- if not embedded %}{% if not theme_nosidebar|tobool %} <div class="sphinxsidebar"> <div class="sphinxsidebarwrapper"> {%- block sidebarlogo %} @@ -86,7 +86,7 @@ {%- endblock %} </div> </div> - {%- endif %} + {%- endif %}{% endif %} {%- endmacro %} <html xmlns="http://www.w3.org/1999/xhtml"> @@ -155,15 +155,15 @@ {%- block document %} <div class="document"> <div class="documentwrapper"> - {%- if not embedded %} + {%- if not embedded %}{% if not theme_nosidebar|tobool %} <div class="bodywrapper"> - {%- endif %} + {%- endif %}{% endif %} <div class="body"> {% block body %} {% endblock %} </div> - {%- if not embedded %} + {%- if not embedded %}{% if not theme_nosidebar|tobool %} </div> - {%- endif %} + {%- endif %}{% endif %} </div> {%- endblock %} diff --git a/sphinx/themes/basic/theme.conf b/sphinx/themes/basic/theme.conf index 3157eac5..d1fe6d1f 100644 --- a/sphinx/themes/basic/theme.conf +++ b/sphinx/themes/basic/theme.conf @@ -2,3 +2,6 @@ inherit = none stylesheet = basic.css pygments_style = none + +[options] +nosidebar = false diff --git a/sphinx/themes/default/layout.html b/sphinx/themes/default/layout.html new file mode 100644 index 00000000..9a909b0b --- /dev/null +++ b/sphinx/themes/default/layout.html @@ -0,0 +1,12 @@ +{% extends "basic/layout.html" %} +{% block extrahead %} +{%- if theme_rightsidebar|tobool %} + <link rel="stylesheet" href="{{ pathto('_static/rightsidebar.css', 1) }}" + type="text/css" /> +{%- endif %} +{%- if theme_stickysidebar|tobool %} + <link rel="stylesheet" href="{{ pathto('_static/stickysidebar.css', 1) }}" + type="text/css" /> +{%- endif %} +{{ super() }} +{% endblock %} diff --git a/sphinx/themes/default/static/rightsidebar.css b/sphinx/themes/default/static/rightsidebar.css index bc604a89..d21eb096 100644 --- a/sphinx/themes/default/static/rightsidebar.css +++ b/sphinx/themes/default/static/rightsidebar.css @@ -1,10 +1,8 @@ -/** - * Sphinx Doc Design -- Right Side Bar Overrides - */ - +/* rightsidebar overrides for default design */ div.sphinxsidebar { float: right; + right: 0; /* for sticky sidebar */ } div.bodywrapper { diff --git a/sphinx/themes/default/static/stickysidebar.css b/sphinx/themes/default/static/stickysidebar.css index dfc99c77..01450853 100644 --- a/sphinx/themes/default/static/stickysidebar.css +++ b/sphinx/themes/default/static/stickysidebar.css @@ -1,15 +1,17 @@ -/** - * Sphinx Doc Design -- Sticky sidebar Overrides - */ +/* stickysidebar overrides for default design */ div.sphinxsidebar { top: 30px; - left: 0px; + height: 100%; + overflow: auto; position: fixed; margin: 0; - float: none; + background-color: #1c4e63; } +/* this is nice, but it it leads to hidden headings when jumping + to an anchor */ +/* div.related { position: fixed; } @@ -17,3 +19,4 @@ div.related { div.documentwrapper { margin-top: 30px; } +*/ diff --git a/sphinx/themes/default/theme.conf b/sphinx/themes/default/theme.conf index 1f513206..f3d4d5ea 100644 --- a/sphinx/themes/default/theme.conf +++ b/sphinx/themes/default/theme.conf @@ -2,3 +2,7 @@ inherit = basic stylesheet = default.css pygments_style = sphinx + +[options] +rightsidebar = false +stickysidebar = false diff --git a/sphinx/theming.py b/sphinx/theming.py index cdfe314a..c6e4f4ce 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -108,7 +108,7 @@ class Theme(object): """ try: return self.themeconf.get(section, name) - except ConfigParser.NoOptionError: + except (ConfigParser.NoOptionError, ConfigParser.NoSectionError): if self.base is not None: return self.base.get_confstr(section, name) if default is NODEFAULT: @@ -117,6 +117,27 @@ class Theme(object): else: return default + def get_options(self, overrides): + """ + Return a dictionary of theme options and their values. + """ + chain = [self.themeconf] + base = self.base + while base is not None: + chain.append(base.themeconf) + base = base.base + options = {} + for conf in reversed(chain): + try: + options.update(conf.items('options')) + except ConfigParser.NoSectionError: + pass + for option, value in overrides.iteritems(): + if option not in options: + raise ThemeError('unsupported theme option %r given' % option) + options[option] = value + return options + def get_dirchain(self): """ Return a list of theme directories, beginning with this theme's, -- cgit v1.2.1 From 9ffe88706068d587576856dbce47aa97e13d725a Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 02:30:12 +0100 Subject: Update Python docs URL. --- EXAMPLES | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXAMPLES b/EXAMPLES index dec3c3ef..87c69173 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -43,7 +43,7 @@ included, please mail to `the Google group * PyPubSub: http://pubsub.sourceforge.net/ * pyrticle: http://documen.tician.de/pyrticle/ * Pysparse: http://pysparse.sourceforge.net/ -* Python: http://docs.python.org/dev/ +* Python: http://docs.python.org/ * python-apt: http://people.debian.org/~jak/python-apt-doc/ * PyUblas: http://documen.tician.de/pyublas/ * Reteisi: http://docs.argolinux.org/reteisi/ -- cgit v1.2.1 From 66a8c8ac80e7d8df9e233f2e8f03edde76eda924 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 02:49:08 +0100 Subject: Use well-named IDs before auto-named IDs. --- sphinx/environment.py | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/sphinx/environment.py b/sphinx/environment.py index de04b0f8..2e6c6817 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -134,6 +134,19 @@ class HandleCodeBlocks(Transform): nodes.doctest_block): node.replace_self(node.children[0]) + +class SortIds(Transform): + """ + Sort secion IDs so that the "id[0-9]+" one comes last. + """ + default_priority = 261 + + def apply(self): + for node in self.document.traverse(nodes.section): + if len(node['ids']) > 1 and node['ids'][0].startswith('id'): + node['ids'] = node['ids'][1:] + [node['ids'][0]] + + class CitationReferences(Transform): """ Handle citation references before the default docutils transform does. @@ -154,7 +167,7 @@ class SphinxStandaloneReader(standalone.Reader): Add our own transforms. """ transforms = [CitationReferences, DefaultSubstitutions, MoveModuleTargets, - HandleCodeBlocks] + HandleCodeBlocks, SortIds] def get_transforms(self): return standalone.Reader.get_transforms(self) + self.transforms @@ -167,7 +180,6 @@ class SphinxDummyWriter(UnfilteredWriter): pass - class SphinxContentsFilter(ContentsFilter): """ Used with BuildEnvironment.add_toc_from() to discard cross-file links -- cgit v1.2.1 From 6e4173a520f83ee6c58448243ba678b207ecf0bf Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 07:55:30 +0100 Subject: Small template adjustment. --- sphinx/themes/basic/layout.html | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html index dda18343..53b9b8b1 100644 --- a/sphinx/themes/basic/layout.html +++ b/sphinx/themes/basic/layout.html @@ -165,11 +165,10 @@ </div> {%- endif %}{% endif %} </div> -{%- endblock %} - -{%- block sidebar2 %}{{ sidebar() }}{% endblock %} + {%- block sidebar2 %}{{ sidebar() }}{% endblock %} <div class="clearer"></div> </div> +{%- endblock %} {%- block relbar2 %}{{ relbar() }}{% endblock %} -- cgit v1.2.1 From e24658da95db788a38f55f62fdcb3580247f8c14 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 07:19:48 +0100 Subject: Add support for templated static files. --- sphinx/application.py | 11 +++++++++-- sphinx/builders/html.py | 11 ++++++++++- sphinx/jinja2glue.py | 4 ++++ 3 files changed, 23 insertions(+), 3 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 856f9108..0d87c493 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -350,7 +350,14 @@ class TemplateBridge(object): def render(self, template, context): """ - Called by the builder to render a *template* with a specified - context (a Python dictionary). + Called by the builder to render a template given as a filename with a + specified context (a Python dictionary). + """ + raise NotImplementedError('must be implemented in subclasses') + + def render_string(self, template, context): + """ + Called by the builder to render a template given as a string with a + specified context (a Python dictionary). """ raise NotImplementedError('must be implemented in subclasses') diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index a2414164..3332aa14 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -460,7 +460,16 @@ class StandaloneHTMLBuilder(Builder): fullname = path.join(staticdirname, filename) targetname = path.join(self.outdir, '_static', filename) if path.isfile(fullname): - shutil.copyfile(fullname, targetname) + if fullname.lower().endswith('_t'): + # templated! + fsrc = open(fullname, 'rb') + fdst = open(targetname[:-2], 'wb') + fdst.write(self.templates.render_string( + fsrc.read(), self.globalcontext)) + fsrc.close() + fdst.close() + else: + shutil.copyfile(fullname, targetname) elif path.isdir(fullname): if filename in self.config.exclude_dirnames: continue diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index 9fc9ba3a..b7f99e6f 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -44,6 +44,7 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): chain[0:0] = [path.join(builder.confdir, tp) for tp in builder.config.templates_path] + # store it for use in newest_template_mtime self.pathchain = chain # make the paths into loaders @@ -60,6 +61,9 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): def render(self, template, context): return self.environment.get_template(template).render(context) + def render_string(self, source, context): + return self.environment.from_string(source).render(context) + def newest_template_mtime(self): return max(mtimes_of_files(self.pathchain, '.html')) -- cgit v1.2.1 From d45786e63f1c185b799c727de81d7237d0031e90 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 09:35:54 +0100 Subject: Make the default theme color-customizable. --- sphinx/themes/default/static/default.css | 197 ----------------------------- sphinx/themes/default/static/default.css_t | 197 +++++++++++++++++++++++++++++ sphinx/themes/default/theme.conf | 16 +++ 3 files changed, 213 insertions(+), 197 deletions(-) delete mode 100644 sphinx/themes/default/static/default.css create mode 100644 sphinx/themes/default/static/default.css_t diff --git a/sphinx/themes/default/static/default.css b/sphinx/themes/default/static/default.css deleted file mode 100644 index 40b1f152..00000000 --- a/sphinx/themes/default/static/default.css +++ /dev/null @@ -1,197 +0,0 @@ -/** - * Sphinx stylesheet -- default theme - * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - */ - -@import url("basic.css"); - -/* -- page layout ----------------------------------------------------------- */ - -body { - font-family: sans-serif; - font-size: 100%; - background-color: #11303d; - color: #000; - margin: 0; - padding: 0; -} - -div.document { - background-color: #1c4e63; -} - -div.body { - background-color: white; - padding: 0 20px 30px 20px; -} - -div.footer { - color: #fff; - width: 100%; - padding: 9px 0 9px 0; - text-align: center; - font-size: 75%; -} - -div.footer a { - color: #fff; - text-decoration: underline; -} - -div.related { - background-color: #133f52; - line-height: 30px; - color: #fff; -} - -div.related a { - color: white; -} - -div.sphinxsidebar h3 { - font-family: 'Trebuchet MS', sans-serif; - color: white; - font-size: 1.4em; - font-weight: normal; - margin: 0; - padding: 0; -} - -div.sphinxsidebar h3 a { - color: white; -} - -div.sphinxsidebar h4 { - font-family: 'Trebuchet MS', sans-serif; - color: white; - font-size: 1.3em; - font-weight: normal; - margin: 5px 0 0 0; - padding: 0; -} - -div.sphinxsidebar p { - color: white; -} - -div.sphinxsidebar p.topless { - margin: 5px 10px 10px 10px; -} - -div.sphinxsidebar ul { - margin: 10px; - padding: 0; - color: white; -} - -div.sphinxsidebar a { - color: #98dbcc; -} - -div.sphinxsidebar input { - border: 1px solid #98dbcc; - font-family: sans-serif; - font-size: 1em; -} - -/* -- body styles ----------------------------------------------------------- */ - -a { - color: #355f7c; - text-decoration: none; -} - -a:hover { - text-decoration: underline; -} - -div.body p, div.body dd, div.body li { - text-align: justify; - line-height: 130%; -} - -div.body h1, -div.body h2, -div.body h3, -div.body h4, -div.body h5, -div.body h6 { - font-family: 'Trebuchet MS', sans-serif; - background-color: #f2f2f2; - font-weight: normal; - color: #20435c; - border-bottom: 1px solid #ccc; - margin: 20px -20px 10px -20px; - padding: 3px 0 3px 10px; -} - -div.body h1 { margin-top: 0; font-size: 200%; } -div.body h2 { font-size: 160%; } -div.body h3 { font-size: 140%; } -div.body h4 { font-size: 120%; } -div.body h5 { font-size: 110%; } -div.body h6 { font-size: 100%; } - -a.headerlink { - color: #c60f0f; - font-size: 0.8em; - padding: 0 4px 0 4px; - text-decoration: none; -} - -a.headerlink:hover { - background-color: #c60f0f; - color: white; -} - -div.body p, div.body dd, div.body li { - text-align: justify; - line-height: 130%; -} - -div.admonition p.admonition-title + p { - display: inline; -} - -div.note { - background-color: #eee; - border: 1px solid #ccc; -} - -div.seealso { - background-color: #ffc; - border: 1px solid #ff6; -} - -div.topic { - background-color: #eee; -} - -div.warning { - background-color: #ffe4e4; - border: 1px solid #f66; -} - -p.admonition-title { - display: inline; -} - -p.admonition-title:after { - content: ":"; -} - -pre { - padding: 5px; - background-color: #efc; - color: #333; - line-height: 120%; - border: 1px solid #ac9; - border-left: none; - border-right: none; -} - -tt { - background-color: #ecf0f3; - padding: 0 1px 0 1px; - font-size: 0.95em; -} diff --git a/sphinx/themes/default/static/default.css_t b/sphinx/themes/default/static/default.css_t new file mode 100644 index 00000000..b1feb252 --- /dev/null +++ b/sphinx/themes/default/static/default.css_t @@ -0,0 +1,197 @@ +/** + * Sphinx stylesheet -- default theme + * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + */ + +@import url("basic.css"); + +/* -- page layout ----------------------------------------------------------- */ + +body { + font-family: {{ theme_bodyfont }}; + font-size: 100%; + background-color: {{ theme_footerbgcolor }}; + color: #000; + margin: 0; + padding: 0; +} + +div.document { + background-color: {{ theme_sidebarbgcolor }}; +} + +div.body { + background-color: white; + padding: 0 20px 30px 20px; +} + +div.footer { + color: {{ theme_footertextcolor }}; + width: 100%; + padding: 9px 0 9px 0; + text-align: center; + font-size: 75%; +} + +div.footer a { + color: {{ theme_footertextcolor }}; + text-decoration: underline; +} + +div.related { + background-color: {{ theme_relbarbgcolor }}; + line-height: 30px; + color: {{ theme_relbartextcolor }}; +} + +div.related a { + color: {{ theme_relbarlinkcolor }}; +} + +div.sphinxsidebar h3 { + font-family: {{ theme_headfont }}; + color: {{ theme_sidebartextcolor }}; + font-size: 1.4em; + font-weight: normal; + margin: 0; + padding: 0; +} + +div.sphinxsidebar h3 a { + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar h4 { + font-family: {{ theme_headfont }}; + color: {{ theme_sidebartextcolor }}; + font-size: 1.3em; + font-weight: normal; + margin: 5px 0 0 0; + padding: 0; +} + +div.sphinxsidebar p { + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar p.topless { + margin: 5px 10px 10px 10px; +} + +div.sphinxsidebar ul { + margin: 10px; + padding: 0; + color: {{ theme_sidebartextcolor }}; +} + +div.sphinxsidebar a { + color: {{ theme_sidebarlinkcolor }}; +} + +div.sphinxsidebar input { + border: 1px solid {{ theme_sidebarlinkcolor }}; + font-family: sans-serif; + font-size: 1em; +} + +/* -- body styles ----------------------------------------------------------- */ + +a { + color: {{ theme_linkcolor }}; + text-decoration: none; +} + +a:hover { + text-decoration: underline; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.body h1, +div.body h2, +div.body h3, +div.body h4, +div.body h5, +div.body h6 { + font-family: {{ theme_headfont }}; + background-color: #f2f2f2; + font-weight: normal; + color: {{ theme_headcolor }}; + border-bottom: 1px solid #ccc; + margin: 20px -20px 10px -20px; + padding: 3px 0 3px 10px; +} + +div.body h1 { margin-top: 0; font-size: 200%; } +div.body h2 { font-size: 160%; } +div.body h3 { font-size: 140%; } +div.body h4 { font-size: 120%; } +div.body h5 { font-size: 110%; } +div.body h6 { font-size: 100%; } + +a.headerlink { + color: #c60f0f; + font-size: 0.8em; + padding: 0 4px 0 4px; + text-decoration: none; +} + +a.headerlink:hover { + background-color: #c60f0f; + color: white; +} + +div.body p, div.body dd, div.body li { + text-align: justify; + line-height: 130%; +} + +div.admonition p.admonition-title + p { + display: inline; +} + +div.note { + background-color: #eee; + border: 1px solid #ccc; +} + +div.seealso { + background-color: #ffc; + border: 1px solid #ff6; +} + +div.topic { + background-color: #eee; +} + +div.warning { + background-color: #ffe4e4; + border: 1px solid #f66; +} + +p.admonition-title { + display: inline; +} + +p.admonition-title:after { + content: ":"; +} + +pre { + padding: 5px; + background-color: {{ theme_codebgcolor }}; + color: {{ theme_codecolor }}; + line-height: 120%; + border: 1px solid #ac9; + border-left: none; + border-right: none; +} + +tt { + background-color: #ecf0f3; + padding: 0 1px 0 1px; + font-size: 0.95em; +} diff --git a/sphinx/themes/default/theme.conf b/sphinx/themes/default/theme.conf index f3d4d5ea..5c1f13ac 100644 --- a/sphinx/themes/default/theme.conf +++ b/sphinx/themes/default/theme.conf @@ -6,3 +6,19 @@ pygments_style = sphinx [options] rightsidebar = false stickysidebar = false + +footerbgcolor = #11303d +footertextcolor = #ffffff +sidebarbgcolor = #1c4e63 +sidebartextcolor = #ffffff +sidebarlinkcolor = #98dbcc +relbarbgcolor = #133f52 +relbartextcolor = #ffffff +relbarlinkcolor = #ffffff +headcolor = #20435c +linkcolor = #355f7c +codebgcolor = #eeffcc +codecolor = #333333 + +bodyfont = sans-serif +headfont = 'Trebuchet MS', sans-serif -- cgit v1.2.1 From 60b16073391c89a574e345f5e652f6b0c81db00b Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 10:25:39 +0100 Subject: Make the relbar and sidebar fonts a bit larger. --- sphinx/themes/sphinxdoc/static/sphinxdoc.css | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/sphinx/themes/sphinxdoc/static/sphinxdoc.css b/sphinx/themes/sphinxdoc/static/sphinxdoc.css index df8c4e02..1d11e8b9 100644 --- a/sphinx/themes/sphinxdoc/static/sphinxdoc.css +++ b/sphinx/themes/sphinxdoc/static/sphinxdoc.css @@ -46,6 +46,10 @@ div.body { padding: 0.5em 20px 20px 20px; } +div.related { + font-size: 1em; +} + div.related ul { background-image: url(navigation.png); height: 2em; @@ -85,6 +89,7 @@ div.sphinxsidebar { padding: 0.5em 15px 15px 0; width: 210px; float: right; + font-size: 1em; text-align: left; } -- cgit v1.2.1 From 7c126bab2dd6aac2dca713e6fbe5723f270f5110 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 10:25:55 +0100 Subject: Make body colors customizable. --- sphinx/themes/default/static/default.css_t | 5 +++-- sphinx/themes/default/theme.conf | 4 +++- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/sphinx/themes/default/static/default.css_t b/sphinx/themes/default/static/default.css_t index b1feb252..2f4b4d86 100644 --- a/sphinx/themes/default/static/default.css_t +++ b/sphinx/themes/default/static/default.css_t @@ -21,7 +21,8 @@ div.document { } div.body { - background-color: white; + background-color: {{ theme_bgcolor }}; + color: {{ theme_textcolor }}; padding: 0 20px 30px 20px; } @@ -183,7 +184,7 @@ p.admonition-title:after { pre { padding: 5px; background-color: {{ theme_codebgcolor }}; - color: {{ theme_codecolor }}; + color: {{ theme_codetextcolor }}; line-height: 120%; border: 1px solid #ac9; border-left: none; diff --git a/sphinx/themes/default/theme.conf b/sphinx/themes/default/theme.conf index 5c1f13ac..9a24b978 100644 --- a/sphinx/themes/default/theme.conf +++ b/sphinx/themes/default/theme.conf @@ -15,10 +15,12 @@ sidebarlinkcolor = #98dbcc relbarbgcolor = #133f52 relbartextcolor = #ffffff relbarlinkcolor = #ffffff +bgcolor = #ffffff +textcolor = #000000 headcolor = #20435c linkcolor = #355f7c codebgcolor = #eeffcc -codecolor = #333333 +codetextcolor = #333333 bodyfont = sans-serif headfont = 'Trebuchet MS', sans-serif -- cgit v1.2.1 From 32c59d15b976d1c6900e173fffab2df37d07b880 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 10:31:52 +0100 Subject: Handle sidebar options directly in the stylesheet. --- sphinx/themes/default/layout.html | 12 --------- sphinx/themes/default/static/default.css_t | 36 ++++++++++++++++++++++++++ sphinx/themes/default/static/rightsidebar.css | 14 ---------- sphinx/themes/default/static/stickysidebar.css | 22 ---------------- 4 files changed, 36 insertions(+), 48 deletions(-) delete mode 100644 sphinx/themes/default/layout.html delete mode 100644 sphinx/themes/default/static/rightsidebar.css delete mode 100644 sphinx/themes/default/static/stickysidebar.css diff --git a/sphinx/themes/default/layout.html b/sphinx/themes/default/layout.html deleted file mode 100644 index 9a909b0b..00000000 --- a/sphinx/themes/default/layout.html +++ /dev/null @@ -1,12 +0,0 @@ -{% extends "basic/layout.html" %} -{% block extrahead %} -{%- if theme_rightsidebar|tobool %} - <link rel="stylesheet" href="{{ pathto('_static/rightsidebar.css', 1) }}" - type="text/css" /> -{%- endif %} -{%- if theme_stickysidebar|tobool %} - <link rel="stylesheet" href="{{ pathto('_static/stickysidebar.css', 1) }}" - type="text/css" /> -{%- endif %} -{{ super() }} -{% endblock %} diff --git a/sphinx/themes/default/static/default.css_t b/sphinx/themes/default/static/default.css_t index 2f4b4d86..77307084 100644 --- a/sphinx/themes/default/static/default.css_t +++ b/sphinx/themes/default/static/default.css_t @@ -26,6 +26,12 @@ div.body { padding: 0 20px 30px 20px; } +{%- if theme_rightsidebar|tobool %} +div.bodywrapper { + margin: 0 230px 0 0; +} +{%- endif %} + div.footer { color: {{ theme_footertextcolor }}; width: 100%; @@ -49,6 +55,36 @@ div.related a { color: {{ theme_relbarlinkcolor }}; } +div.sphinxsidebar { + {%- if theme_stickysidebar|tobool %} + top: 30px; + margin: 0; + position: fixed; + overflow: auto; + height: 100%; + {%- endif %} + {%- if theme_rightsidebar|tobool %} + float: right; + {%- if theme_stickysidebar|tobool %} + right: 0; + {%- endif %} + {%- endif %} +} + +{%- if theme_stickysidebar|tobool %} +/* this is nice, but it it leads to hidden headings when jumping + to an anchor */ +/* +div.related { + position: fixed; +} + +div.documentwrapper { + margin-top: 30px; +} +*/ +{%- endif %} + div.sphinxsidebar h3 { font-family: {{ theme_headfont }}; color: {{ theme_sidebartextcolor }}; diff --git a/sphinx/themes/default/static/rightsidebar.css b/sphinx/themes/default/static/rightsidebar.css deleted file mode 100644 index d21eb096..00000000 --- a/sphinx/themes/default/static/rightsidebar.css +++ /dev/null @@ -1,14 +0,0 @@ -/* rightsidebar overrides for default design */ - -div.sphinxsidebar { - float: right; - right: 0; /* for sticky sidebar */ -} - -div.bodywrapper { - margin: 0 230px 0 0; -} - -div.inlinecomments { - right: 250px; -} diff --git a/sphinx/themes/default/static/stickysidebar.css b/sphinx/themes/default/static/stickysidebar.css deleted file mode 100644 index 01450853..00000000 --- a/sphinx/themes/default/static/stickysidebar.css +++ /dev/null @@ -1,22 +0,0 @@ -/* stickysidebar overrides for default design */ - -div.sphinxsidebar { - top: 30px; - height: 100%; - overflow: auto; - position: fixed; - margin: 0; - background-color: #1c4e63; -} - -/* this is nice, but it it leads to hidden headings when jumping - to an anchor */ -/* -div.related { - position: fixed; -} - -div.documentwrapper { - margin-top: 30px; -} -*/ -- cgit v1.2.1 From da34a553fef2c92961ea8ac3ef1b19428f0cb2c6 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 10:45:46 +0100 Subject: Theming docs, part 1. --- CHANGES | 2 ++ doc/config.rst | 30 ++++++++++++++-- doc/contents.rst | 1 + doc/theming.rst | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 137 insertions(+), 3 deletions(-) create mode 100644 doc/theming.rst diff --git a/CHANGES b/CHANGES index addc3e73..2d4342bc 100644 --- a/CHANGES +++ b/CHANGES @@ -20,6 +20,8 @@ New features added if name.startswith('_'): return True +* Theming support. + * Markup: - Due to popular demand, added a ``:doc:`` role which directly diff --git a/doc/config.rst b/doc/config.rst index e5ec3810..c55f4a8e 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -305,6 +305,29 @@ Options for HTML output These options influence HTML as well as HTML Help output, and other builders that use Sphinx' HTMLWriter class. +.. confval:: html_theme + + The "theme" that the HTML output should use. See the :doc:`section about + theming <theming>`. The default is ``'default'``. + + .. versionadded:: 0.6 + +.. confval:: html_theme_options + + A dictionary of options that influence the look and feel of the selected + theme. These are theme-specific. For the options understood by the builtin + themes, see :ref:`this section <builtin-themes>`. + + .. versionadded:: 0.6 + +.. confval:: html_theme_path + + A list of paths that contain custom themes, either as subdirectories or as + zip files. Relative paths are taken as relative to the configuration + directory. + + .. versionadded:: 0.6 + .. confval:: html_title The "title" for HTML documentation generated with Sphinx' own templates. @@ -325,7 +348,8 @@ that use Sphinx' HTMLWriter class. The style sheet to use for HTML pages. A file of that name must exist either in Sphinx' :file:`static/` path, or in one of the custom paths given in - :confval:`html_static_path`. Default is ``'default.css'``. + :confval:`html_static_path`. Default is the stylesheet given by the selected + theme. .. confval:: html_logo @@ -350,8 +374,8 @@ that use Sphinx' HTMLWriter class. A list of paths that contain custom static files (such as style sheets or script files). Relative paths are taken as relative to the configuration - directory. They are copied to the output directory after the builtin static - files, so a file named :file:`default.css` will overwrite the builtin + directory. They are copied to the output directory after the theme's static + files, so a file named :file:`default.css` will overwrite the theme's :file:`default.css`. .. versionchanged:: 0.4 diff --git a/doc/contents.rst b/doc/contents.rst index c4fb107b..1f3860ea 100644 --- a/doc/contents.rst +++ b/doc/contents.rst @@ -12,6 +12,7 @@ Sphinx documentation contents markup/index builders config + theming templating extensions diff --git a/doc/theming.rst b/doc/theming.rst new file mode 100644 index 00000000..b3721248 --- /dev/null +++ b/doc/theming.rst @@ -0,0 +1,107 @@ +.. highlightlang:: python + +HTML theming support +==================== + +.. versionadded:: 0.6 + +Sphinx supports changing the appearance of its HTML output via *themes*. A +theme is a collection of HTML templates, stylesheet(s) and other static files. +Additionally, it has a configuration file which specifies from which theme to +inherit, which highlighting style to use, and what options exist for customizing +the theme's look and feel. + +Themes are meant to be project-unaware, so they can be used for different +projects without change. + + +Using a theme +------------- + +Using an existing theme is easy. If the theme is builtin to Sphinx, you only +need to set the :confval:`html_theme` config value. With the +:confval:`html_theme_options` config value you can set theme-specific options +that change the look and feel. For example, you could have the following in +your :file:`conf.py`:: + + html_theme = "default" + html_theme_options = { + "rightsidebar": "true", + "relbarbgcolor: "black" + } + +That would give you the default theme, but with a sidebar on the right side and +a black background for the relation bar (the bar with the navigation links at +the page's top and bottom). + +If the theme does not come with Sphinx, it can be in two forms: either a +directory (containing :file:`theme.conf` and other needed files), or a zip file +with the same contents. Either of them must be put where Sphinx can find it; +for this there is the config value :confval:`html_theme_path`. It gives a list +of directories, relative to the directory containing :file:`conf.py`, that can +contain theme directories or zip files. For example, if you have a theme in the +file :file:`blue.zip`, you can put it right in the directory containing +:file:`conf.py` and use this configuration:: + + html_theme = "blue" + html_theme_path = ["."] + + +.. _builtin-themes: + +Builtin themes +-------------- + +Sphinx comes with a selection of themes to choose from: + +* **basic** -- This is a basically unstyled layout used as the base for the + *default* and *sphinxdoc* themes, and usable as the base for custom themes as + well. The HTML contains all important elements like sidebar and relation bar. + There is one option (which is inherited by *default* and *sphinxdoc*): + + - **nosidebar** (true or false): Don't include the sidebar. Defaults to + false. + +* **default** -- This is the default theme. It can be customized via these + options: + + - **rightsidebar** (true or false): Put the sidebar on the right side. + Defaults to false. + + - **stickysidebar** (true or false): Make the sidebar "fixed" so that it + doesn't scroll out of view for long body content. This may not work well + with all browsers. Defaults to false. + + There are also various color and font options that can change the color scheme + without having to write a custom stylesheet: + + - **footerbgcolor** (CSS color): Background color for the footer line. + - **footertextcolor** (CSS color): Text color for the footer line. + - **sidebarbgcolor** (CSS color): Background color for the sidebar. + - **sidebartextcolor** (CSS color): Text color for the sidebar. + - **sidebarlinkcolor** (CSS color): Link color for the sidebar. + - **relbarbgcolor** (CSS color): Background color for the relation bar. + - **relbartextcolor** (CSS color): Text color for the relation bar. + - **relbarlinkcolor** (CSS color): Link color for the relation bar. + - **bgcolor** (CSS color): Body background color. + - **textcolor** (CSS color): Body text color. + - **linkcolor** (CSS color): Body link color. + - **headcolor** (CSS color): Text color for headings. + - **codebgcolor** (CSS color): Background color for code blocks. + - **codetextcolor** (CSS color): Default text color for code blocks, if not + set differently by the highlighting style. + + - **bodyfont** (CSS font-family): Font for normal text. + - **headfont** (CSS font-family): Font for headings. + +* **sphinxdoc** -- The theme used for this documentation. It features a sidebar + on the right side. There are currently no options beyond *nosidebar*. + +.. + * option specs + * zipfiles + * old config values work + * static/ + * theme.conf + * _t templates + -- cgit v1.2.1 From 7f87c67ccded0036793a2f9cc20120ea3678dcc4 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 11:03:16 +0100 Subject: Theming docs, part 2. --- doc/config.rst | 22 +++++++++--------- doc/theming.rst | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++------ 2 files changed, 74 insertions(+), 17 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index c55f4a8e..efa1fa85 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -131,15 +131,16 @@ General configuration .. confval:: templates_path A list of paths that contain extra templates (or templates that overwrite - builtin templates). Relative paths are taken as relative to the - configuration directory. + builtin/theme-specific templates). Relative paths are taken as relative to + the configuration directory. .. confval:: template_bridge A string with the fully-qualified name of a callable (or simply a class) that returns an instance of :class:`~sphinx.application.TemplateBridge`. This instance is then used to render HTML documents, and possibly the output of - other builders (currently the changes builder). + other builders (currently the changes builder). (Note that the template + bridge must be made theme-aware if HTML themes are to be used.) .. confval:: rst_epilog @@ -328,6 +329,14 @@ that use Sphinx' HTMLWriter class. .. versionadded:: 0.6 +.. confval:: html_style + + The style sheet to use for HTML pages. A file of that name must exist either + in Sphinx' :file:`static/` path, or in one of the custom paths given in + :confval:`html_static_path`. Default is the stylesheet given by the selected + theme. If you only want to add or override a few things compared to the + theme's stylesheet, use CSS ``@import`` to import the theme's stylesheet. + .. confval:: html_title The "title" for HTML documentation generated with Sphinx' own templates. @@ -344,13 +353,6 @@ that use Sphinx' HTMLWriter class. .. versionadded:: 0.4 -.. confval:: html_style - - The style sheet to use for HTML pages. A file of that name must exist either - in Sphinx' :file:`static/` path, or in one of the custom paths given in - :confval:`html_static_path`. Default is the stylesheet given by the selected - theme. - .. confval:: html_logo If given, this must be the name of an image file that is the logo of the diff --git a/doc/theming.rst b/doc/theming.rst index b3721248..9f7786fb 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -97,11 +97,66 @@ Sphinx comes with a selection of themes to choose from: * **sphinxdoc** -- The theme used for this documentation. It features a sidebar on the right side. There are currently no options beyond *nosidebar*. -.. - * option specs - * zipfiles - * old config values work - * static/ - * theme.conf - * _t templates + +Creating themes +--------------- + +As said, themes are either a directory or a zipfile (whose name is the theme +name), containing the following: + +* A :file:`theme.conf` file, see below. +* HTML templates, if needed. +* A ``static/`` directory containing any static files that will be copied to the + output statid directory on build. These can be images, styles, script files. + +The :file:`theme.conf` file is in INI format [1]_ (readable by the standard +Python :mod:`ConfigParser` module) and has the following structure:: + + [theme] + inherit = base theme + stylesheet = main CSS name + pygments_style = stylename + + [options] + variable = default value + +* The **inherit** setting gives the name of a "base theme", or ``none``. The + base theme will be used to locate missing templates, its options will be + inherited, and all of its static files will be used as well. + +* The **stylesheet** setting gives the name of a CSS file which will be + referenced in the HTML header. If you need more than one CSS file, either + include one from the other via CSS' ``@import``, or use a custom HTML template + that adds ``<link rel="stylesheet">`` tags as necessary. Setting the + :confval:`html_style` config value will override this setting. + +* The **pygments_style** setting gives the name of a Pygments style to use for + highlighting. This can be overridden by the user in the + :confval:`pygments_style` config value. + +* The **options** section contains pairs of variable names and default values. + These options can be overridden by the user in :confval:`html_theme_options` + and are accessible from all templates as ``theme_<name>``. + + +Static templates +---------------- + +Since theme options are meant for the user to configure a theme more easily, +without having to write a custom stylesheet, it is necessary to be able to +template static files as well as HTML files. Therefore, Sphinx supports +so-called "static templates", like this: + +If the name of a file in the ``static/`` directory of a theme (or in the user's +static path, for that matter) ends with ``_t``, it will be processed by the +template engine. The ``_t`` will be left from the final file name. For +example, the *default* theme has a file ``static/default.css_t`` which uses +templating to put the color options into the stylesheet. When a documentation +is built with the default theme, the output directory will contain a +``_static/default.css`` file where all template tags have been processed. + + +.. [1] It is not an executable Python file, as opposed to :file:`conf.py`, + because that would pose an unnecessary security risk if themes are + shared. -- cgit v1.2.1 From d333ec6a6c091203be3d37af4550ecdc56c14727 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 11:38:23 +0100 Subject: More templating docs. --- doc/markup/misc.rst | 2 + doc/templating.rst | 183 +++++++++++++++++++++++++++++++++++++++++----------- doc/theming.rst | 24 ++++++- 3 files changed, 168 insertions(+), 41 deletions(-) diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 98f5485e..03fbdeea 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -3,6 +3,8 @@ Miscellaneous markup ==================== +.. _metadata:: + File-wide metadata ------------------ diff --git a/doc/templating.rst b/doc/templating.rst index 20c61ce0..2ee449aa 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -1,3 +1,5 @@ +.. highlight:: html+jinja + .. _templating: Templating @@ -37,27 +39,26 @@ template, customizing it while also keeping the changes at a minimum. To customize the output of your documentation you can override all the templates (both the layout templates and the child templates) by adding files with the -same name as the original filename into the template directory of the folder the -Sphinx quickstart generated for you. +same name as the original filename into the template directory of the structure +the Sphinx quickstart generated for you. Sphinx will look for templates in the folders of :confval:`templates_path` first, and if it can't find the template it's looking for there, it falls back -to the builtin templates that come with Sphinx. +to the selected theme's templates. A template contains **variables**, which are replaced with values when the template is evaluated, **tags**, which control the logic of the template and **blocks** which are used for template inheritance. -Sphinx provides base templates with a couple of blocks it will fill with data. -The default templates are located in the :file:`templates` folder of the Sphinx -installation directory. Templates with the same name in the -:confval:`templates_path` override templates located in the builtin folder. +Sphinx' *basic* theme provides base templates with a couple of blocks it will +fill with data. These are located in the :file:`themes/basic` subdirectory of +the Sphinx installation directory, and used by all builtin Sphinx themes. +Templates with the same name in the :confval:`templates_path` override templates +supplied by the selected theme. For example, to add a new link to the template area containing related links all you have to do is to add a new template called ``layout.html`` with the -following contents: - -.. sourcecode:: html+jinja +following contents:: {% extends "!layout.html" %} {% block rootrellink %} @@ -65,16 +66,24 @@ following contents: {{ super() }} {% endblock %} -By prefixing the name of the extended template with an exclamation mark, Sphinx -will load the builtin layout template. If you override a block, you should call -``{{ super() }}`` somewhere to render the block's content in the extended -template -- unless you don't want that content to show up. +By prefixing the name of the overridden template with an exclamation mark, +Sphinx will load the layout template from the underlying HTML theme. + +**Important**: If you override a block, call ``{{ super() }}`` somewhere to +render the block's content in the extended template -- unless you don't want +that content to show up. + +Working the the builtin templates +--------------------------------- + +The builtin **basic** theme supplies the templates that all builtin Sphinx +themes are based on. It has the following elements you can override or use: Blocks ~~~~~~ -The following blocks exist in the ``layout`` template: +The following blocks exist in the ``layout.html`` template: `doctype` The doctype of the output format. By default this is XHTML 1.0 Transitional @@ -92,11 +101,11 @@ The following blocks exist in the ``layout`` template: add references to JavaScript or extra CSS files. `relbar1` / `relbar2` - This block contains the list of related links (the parent documents on the - left, and the links to index, modules etc. on the right). `relbar1` appears - before the document, `relbar2` after the document. By default, both blocks - are filled; to show the relbar only before the document, you would override - `relbar2` like this:: + This block contains the *relation bar*, the list of related links (the + parent documents on the left, and the links to index, modules etc. on the + right). `relbar1` appears before the document, `relbar2` after the + document. By default, both blocks are filled; to show the relbar only + before the document, you would override `relbar2` like this:: {% block relbar2 %}{% endblock %} @@ -109,7 +118,8 @@ The following blocks exist in the ``layout`` template: the :data:`reldelim1`. `document` - The contents of the document itself. + The contents of the document itself. It contains the block "body" where the + individual content is put by subtemplates like ``page.html``. `sidebar1` / `sidebar2` A possible location for a sidebar. `sidebar1` appears before the document @@ -166,13 +176,17 @@ using the ``{% set %}`` tag: defaults to ``' |'``. Each item except of the last one in the related bar ends with the value of this variable. -Overriding works like this: - -.. sourcecode:: html+jinja +Overriding works like this:: {% extends "!layout.html" %} {% set reldelim1 = ' >' %} +.. data:: script_files + + Add additional script files here, like this:: + + {% set script_files = script_files + [pathto("_static/myscript.js", 1)] %} + Helper Functions ~~~~~~~~~~~~~~~~ @@ -200,7 +214,7 @@ them to generate links or output multiply used elements. .. function:: relbar() - Return the rendered relbar. + Return the rendered relation bar. Global Variables @@ -210,45 +224,138 @@ These global variables are available in every template and are safe to use. There are more, but most of them are an implementation detail and might change in the future. +.. data:: builder + + The name of the builder (e.g. ``html`` or ``htmlhelp``). + +.. data:: copyright + + The value of :confval:`copyright`. + .. data:: docstitle The title of the documentation (the value of :confval:`html_title`). -.. data:: sourcename +.. data:: embedded - The name of the copied source file for the current document. This is only - nonempty if the :confval:`html_copy_source` value is true. + True if the built HTML is meant to be embedded in some viewing application + that handles navigation, not the web browser, such as for HTML help or Qt + help formats. In this case, the sidebar is not included. -.. data:: builder +.. data:: favicon - The name of the builder (e.g. ``html`` or ``htmlhelp``). + The path to the HTML favicon in the static path, or ``''``. -.. data:: embedded +.. data:: file_suffix + + The value of the builder's :attr:`out_suffix` attribute, i.e. the file name + extension that the output files will get. For a standard HTML builder, this + is usually ``.html``. + +.. data:: has_source - True if the built HTML is supposed to be embedded in some application that - handles navigation, e.g. HTML Help or Qt Help. + True if the reST document sources are copied (if :confval:`html_copy_source` + is true). + +.. data:: last_updated + + The build date. + +.. data:: logo + + The path to the HTML logo image in the static path, or ``''``. + +.. data:: master_doc + + The value of :confval:`master_doc`, for usage with :func:`pathto`. .. data:: next The next document for the navigation. This variable is either false or has two attributes `link` and `title`. The title contains HTML markup. For - example, to generate a link to the next page, you can use this snippet: - - .. sourcecode:: html+jinja + example, to generate a link to the next page, you can use this snippet:: {% if next %} <a href="{{ next.link|e }}">{{ next.title }}</a> {% endif %} +.. data:: pagename + + The "page name" of the current file, i.e. either the document name if the + file is generated from a reST source, or the equivalent hierarchical name + relative to the output directory (``[directory/]filename_without_extension``). + +.. data:: parents + + A list of parent documents for navigation, structured like the :data:`next` + item. + .. data:: prev Like :data:`next`, but for the previous page. +.. data:: project + + The value of :confval:`project`. + +.. data:: release + + The value of :confval:`release`. + +.. data:: rellinks + + A list of links to put at the left side of the relbar, next to "next" and + "prev". This usually contains links to the index and the modindex. If you + add something yourself, it must be a tuple ``(pagename, link title, + accesskey, link text)``. + +.. data:: shorttitle + + The value of :confval:`html_short_title`. + +.. data:: show_source + + True if :confval:`html_show_sourcelink` is true. + +.. data:: sphinx_version + + The version of Sphinx used to build. + +.. data:: style + + The name of the main stylesheet, as given by the theme or + :confval:`html_style`. +.. data:: title + + The title of the current document, as used in the ``<title>`` tag. + +.. data:: use_opensearch + + The value of :confval:`html_use_opensearch`. + +.. data:: version + + The value of :confval:`version`. + + +In addition to these values, there are also all **theme options** available +(prefixed by ``theme_``), as well as the values given by the user in +:confval:`html_context`. + In documents that are created from source files (as opposed to automatically-generated files like the module index, or documents that already are in HTML form), these variables are also available: +.. data:: meta + + Document metadata, see :ref:`metadata`. + +.. data:: sourcename + + The name of the copied source file for the current document. This is only + nonempty if the :confval:`html_copy_source` value is true. + .. data:: toc The local table of contents for the current page, rendered as HTML bullet @@ -256,5 +363,5 @@ are in HTML form), these variables are also available: .. data:: toctree - The global TOC tree containing the current page, rendered as HTML bullet - lists. + A callable yielding the global TOC tree containing the current page, rendered + as HTML bullet lists. diff --git a/doc/theming.rst b/doc/theming.rst index 9f7786fb..bc150f4c 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -121,8 +121,9 @@ Python :mod:`ConfigParser` module) and has the following structure:: variable = default value * The **inherit** setting gives the name of a "base theme", or ``none``. The - base theme will be used to locate missing templates, its options will be - inherited, and all of its static files will be used as well. + base theme will be used to locate missing templates (most themes will not have + to supply most templates if they use ``basic`` as the base theme), its options + will be inherited, and all of its static files will be used as well. * The **stylesheet** setting gives the name of a CSS file which will be referenced in the HTML header. If you need more than one CSS file, either @@ -139,8 +140,25 @@ Python :mod:`ConfigParser` module) and has the following structure:: and are accessible from all templates as ``theme_<name>``. +Templating +~~~~~~~~~~ + +The :doc:`guide to templating <templating>` is helpful if you want to write your +own templates. What is important to keep in mind is the order in which Sphinx +searches for templates: + +* First, in the user's ``templates_path`` directories. +* Then, in the selected theme. +* Then, in its base theme, its base's base theme, etc. + +From all of these levels, you can inherit templates from the lowernext level by +prefixing the template name with an exclamation mark in the ``extends`` tag, or +(in the case of theme templates) giving an explicit path, like +``basic/layout.html``. + + Static templates ----------------- +~~~~~~~~~~~~~~~~ Since theme options are meant for the user to configure a theme more easily, without having to write a custom stylesheet, it is necessary to be able to -- cgit v1.2.1 From 07098c9f40bde13fb724a4ac0d44d10b6d58a379 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 12:35:05 +0100 Subject: Add language-binding.net. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 87c69173..32c4b54e 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -12,6 +12,7 @@ included, please mail to `the Google group * Chaco: http://code.enthought.com/projects/chaco/docs/html/ * CodePy: http://documen.tician.de/codepy/ * Cython: http://docs.cython.org/ +* C\\C++ Python language binding project: http://language-binding.net/index.html * Director: http://packages.python.org/director/ * Django: http://docs.djangoproject.com/ * F2py: http://www.f2py.org/html/ -- cgit v1.2.1 From 6d60b52591dd394484769c37879a21e7a3fd1fbd Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 12:44:10 +0100 Subject: Fix test suite. --- tests/test_config.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_config.py b/tests/test_config.py index 6343a364..b3aa4eea 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -36,7 +36,7 @@ def test_core_config(app): # complex default values assert 'html_title' not in cfg.__dict__ - assert cfg.html_title == 'Sphinx <Tests> v0.4alpha1 documentation' + assert cfg.html_title == 'Sphinx <Tests> v0.6alpha1 documentation' # complex default values mustn't raise for valuename in cfg.config_values: -- cgit v1.2.1 From 34fcbfcd18e95bd948f971d977166b9e1f8863b0 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 16:10:10 +0100 Subject: Add theming test suite, fix a few bugs and doc problems. --- doc/theming.rst | 11 +++-- sphinx/config.py | 1 - sphinx/jinja2glue.py | 5 ++- sphinx/theming.py | 2 +- tests/root/_templates/layout.html | 1 + tests/root/conf.py | 4 ++ tests/root/rimg.png | Bin 67861 -> 218 bytes tests/root/testtheme/layout.html | 5 +++ tests/root/testtheme/static/staticimg.png | Bin 0 -> 218 bytes tests/root/testtheme/static/statictmpl.html_t | 2 + tests/root/testtheme/theme.conf | 7 ++++ tests/root/ziptheme.zip | Bin 0 -> 1039 bytes tests/test_build.py | 6 +++ tests/test_theming.py | 56 ++++++++++++++++++++++++++ 14 files changed, 92 insertions(+), 8 deletions(-) create mode 100644 tests/root/testtheme/layout.html create mode 100644 tests/root/testtheme/static/staticimg.png create mode 100644 tests/root/testtheme/static/statictmpl.html_t create mode 100644 tests/root/testtheme/theme.conf create mode 100644 tests/root/ziptheme.zip create mode 100644 tests/test_theming.py diff --git a/doc/theming.rst b/doc/theming.rst index bc150f4c..b2448198 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -97,6 +97,9 @@ Sphinx comes with a selection of themes to choose from: * **sphinxdoc** -- The theme used for this documentation. It features a sidebar on the right side. There are currently no options beyond *nosidebar*. +* **traditional** -- A theme resembling the old Python documentation. There are + currently no options beyond *nosidebar*. + Creating themes --------------- @@ -151,10 +154,10 @@ searches for templates: * Then, in the selected theme. * Then, in its base theme, its base's base theme, etc. -From all of these levels, you can inherit templates from the lowernext level by -prefixing the template name with an exclamation mark in the ``extends`` tag, or -(in the case of theme templates) giving an explicit path, like -``basic/layout.html``. +When extending a template in the base theme with the same name, use the theme +name as an explicit directory: ``{% extends "basic/layout.html" %}``. From a +user ``templates_path`` template, you can still use the "exclamation mark" +syntax as described in the templating document. Static templates diff --git a/sphinx/config.py b/sphinx/config.py index 79f3ce8a..474ddc23 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -133,7 +133,6 @@ class Config(object): config.setdefault(realvalname, {})[key] = value else: config[valname] = value - config.update(self.overrides) for name in config: if name in self.values: self.__dict__[name] = config[name] diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index b7f99e6f..d7ad328d 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -40,6 +40,7 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): chain.extend(self.theme.themepath) # prepend explicit template paths + self.templatepathlen = len(builder.config.templates_path) if builder.config.templates_path: chain[0:0] = [path.join(builder.confdir, tp) for tp in builder.config.templates_path] @@ -71,9 +72,9 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): def get_source(self, environment, template): loaders = self.loaders - # exclamation mark starts search from base + # exclamation mark starts search from theme if template.startswith('!'): - loaders = loaders[1:] + loaders = loaders[self.templatepathlen:] template = template[1:] for loader in loaders: try: diff --git a/sphinx/theming.py b/sphinx/theming.py index c6e4f4ce..d9fde636 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -110,7 +110,7 @@ class Theme(object): return self.themeconf.get(section, name) except (ConfigParser.NoOptionError, ConfigParser.NoSectionError): if self.base is not None: - return self.base.get_confstr(section, name) + return self.base.get_confstr(section, name, default) if default is NODEFAULT: raise ThemeError('setting %s.%s occurs in none of the ' 'searched theme configs' % (section, name)) diff --git a/tests/root/_templates/layout.html b/tests/root/_templates/layout.html index 1f4688e6..e8920025 100644 --- a/tests/root/_templates/layout.html +++ b/tests/root/_templates/layout.html @@ -1,4 +1,5 @@ {% extends "!layout.html" %} {% block extrahead %} <meta name="hc" content="{{ hckey }}" /> +{{ super() }} {% endblock %} diff --git a/tests/root/conf.py b/tests/root/conf.py index 1a169f30..ace6ac6c 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -26,6 +26,10 @@ pygments_style = 'sphinx' rst_epilog = '.. |subst| replace:: global substitution' +html_theme = 'testtheme' +html_theme_path = ['.'] +html_theme_options = {'testopt': 'testoverride'} + html_style = 'default.css' html_static_path = ['_static'] html_last_updated_fmt = '%b %d, %Y' diff --git a/tests/root/rimg.png b/tests/root/rimg.png index 72c12d13..1081dc14 100644 Binary files a/tests/root/rimg.png and b/tests/root/rimg.png differ diff --git a/tests/root/testtheme/layout.html b/tests/root/testtheme/layout.html new file mode 100644 index 00000000..81372be0 --- /dev/null +++ b/tests/root/testtheme/layout.html @@ -0,0 +1,5 @@ +{% extends "basic/layout.html" %} +{% block extrahead %} +<meta name="testopt" content="{{ theme_testopt }}" /> +{{ super() }} +{% endblock %} diff --git a/tests/root/testtheme/static/staticimg.png b/tests/root/testtheme/static/staticimg.png new file mode 100644 index 00000000..1081dc14 Binary files /dev/null and b/tests/root/testtheme/static/staticimg.png differ diff --git a/tests/root/testtheme/static/statictmpl.html_t b/tests/root/testtheme/static/statictmpl.html_t new file mode 100644 index 00000000..4ab292b4 --- /dev/null +++ b/tests/root/testtheme/static/statictmpl.html_t @@ -0,0 +1,2 @@ +<!-- testing static templates --> +<html><project>{{ project|e }}</project></html> diff --git a/tests/root/testtheme/theme.conf b/tests/root/testtheme/theme.conf new file mode 100644 index 00000000..a8776737 --- /dev/null +++ b/tests/root/testtheme/theme.conf @@ -0,0 +1,7 @@ +[theme] +inherit = basic +stylesheet = default.css +pygments_style = emacs + +[options] +testopt = optdefault diff --git a/tests/root/ziptheme.zip b/tests/root/ziptheme.zip new file mode 100644 index 00000000..8a246ed9 Binary files /dev/null and b/tests/root/ziptheme.zip differ diff --git a/tests/test_build.py b/tests/test_build.py index 207ae280..a8934b82 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -89,6 +89,7 @@ HTML_XPATH = { }, 'contents.html': { ".//meta[@name='hc'][@content='hcval']": '', + ".//meta[@name='testopt'][@content='testoverride']": '', ".//td[@class='label']": r'\[Ref1\]', ".//li[@class='toctree-l1']/a": 'Testing various markup', ".//li[@class='toctree-l2']/a": 'Admonitions', @@ -96,6 +97,9 @@ HTML_XPATH = { ".//div[@class='footer']": 'Georg Brandl & Team', ".//a[@href='http://python.org/']": '', }, + '_static/statictmpl.html': { + ".//project": 'Sphinx <Tests>', + }, } if pygments: @@ -141,6 +145,8 @@ def test_html(app): etree = ET.parse(os.path.join(app.outdir, fname), parser) for path, check in paths.iteritems(): nodes = list(etree.findall(path)) + if not nodes: + import pdb; pdb.set_trace() assert nodes != [] if hasattr(check, '__call__'): check(nodes) diff --git a/tests/test_theming.py b/tests/test_theming.py new file mode 100644 index 00000000..349a9ce4 --- /dev/null +++ b/tests/test_theming.py @@ -0,0 +1,56 @@ +# -*- coding: utf-8 -*- +""" + test_theming + ~~~~~~~~~~~~ + + Test the Theme class. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import zipfile + +from util import * + +from sphinx.theming import Theme, ThemeError + + +@with_app(confoverrides={'html_theme': 'ziptheme', + 'html_theme_options.testopt': 'foo'}) +def test_theme_api(app): + cfg = app.config + + # test Theme class API + assert set(Theme.themes.keys()) == \ + set(['basic', 'default', 'sphinxdoc', 'traditional', + 'testtheme', 'ziptheme']) + assert Theme.themes['testtheme'][1] is None + assert isinstance(Theme.themes['ziptheme'][1], zipfile.ZipFile) + + # test Theme instance API + theme = app.builder.theme + assert theme.name == 'ziptheme' + assert theme.themedir_created + themedir = theme.themedir + assert theme.base.name == 'basic' + assert len(theme.get_dirchain()) == 2 + + # direct setting + assert theme.get_confstr('theme', 'stylesheet') == 'custom.css' + # inherited setting + assert theme.get_confstr('options', 'nosidebar') == 'false' + # nonexisting setting + assert theme.get_confstr('theme', 'foobar', 'def') == 'def' + raises(ThemeError, theme.get_confstr, 'theme', 'foobar') + + # options API + raises(ThemeError, theme.get_options, {'nonexisting': 'foo'}) + options = theme.get_options(cfg.html_theme_options) + assert options['testopt'] == 'foo' + assert options['nosidebar'] == 'false' + + # cleanup temp directories + theme.cleanup() + assert not os.path.exists(themedir) -- cgit v1.2.1 From a7a6b7a145648978ca914a24c2e0477b2c9b0e0f Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 18:52:28 +0100 Subject: Fix #93: note that show-inheritance works with automodule. --- doc/ext/autodoc.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index ccaf7ca8..00fafdb7 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -115,9 +115,11 @@ directive. .. versionadded:: 0.4 - * The :dir:`autoclass` and :dir:`autoexception` directives also support a - flag option called ``show-inheritance``. When given, a list of base - classes will be inserted just below the class signature. + * The :dir:`automodule`, :dir:`autoclass` and :dir:`autoexception` directives + also support a flag option called ``show-inheritance``. When given, a list + of base classes will be inserted just below the class signature (when used + with :dir:`automodule`, this will be inserted for every class that is + documented in the module). .. versionadded:: 0.4 -- cgit v1.2.1 From c9b7d87c4b5bbca5df288f59873c959bf60716f7 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Sun, 15 Feb 2009 20:08:31 +0100 Subject: Fix target. --- doc/markup/misc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 03fbdeea..5bff00dc 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -3,7 +3,7 @@ Miscellaneous markup ==================== -.. _metadata:: +.. _metadata: File-wide metadata ------------------ -- cgit v1.2.1 From fe73fee37cbf5d9fa9992160b546715247aa403e Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 16 Feb 2009 00:02:36 +0100 Subject: Add Sprox. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 32c4b54e..0562a7f2 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -53,6 +53,7 @@ included, please mail to `the Google group * Self: http://selflanguage.org/ * SimPy: http://simpy.sourceforge.net/ * Sphinx: http://sphinx.pocoo.org/ +* Sprox: http://sprox.org/ * SQLAlchemy: http://www.sqlalchemy.org/docs/ * Sqlkit: http://sqlkit.argolinux.org/ * SymPy: http://docs.sympy.org/ -- cgit v1.2.1 From 70b27cb2c654f41f5ab56fe46ffb79c15eaf5b3d Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 16 Feb 2009 00:08:08 +0100 Subject: Change html_collapse_toctree setting to an argument of the toctree() callable. --- CHANGES | 7 +++---- doc/config.rst | 8 -------- doc/templating.rst | 3 ++- sphinx/builders/html.py | 10 +++++----- sphinx/config.py | 1 - 5 files changed, 10 insertions(+), 19 deletions(-) diff --git a/CHANGES b/CHANGES index 2d4342bc..80a27910 100644 --- a/CHANGES +++ b/CHANGES @@ -55,7 +55,9 @@ New features added and ``staticmethod``. - Added a ``toctree`` callable to the templates, and the ability - to include external links in toctrees. + to include external links in toctrees. The 'collapse' keyword argument + indicates whether or not to only display subitems of the current page. + (Defaults to True.) * Configuration: @@ -70,9 +72,6 @@ New features added - The new ``html_show_sourcelink`` config value can be used to switch off the links to the reST sources in the sidebar. - - The new ``html_collapse_toctree`` config value can be used to - "collapse" the generated toctree given to the templates. - - The default value for ``htmlhelp_basename`` is now the project title, cleaned up as a filename. diff --git a/doc/config.rst b/doc/config.rst index efa1fa85..2c9e09d0 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -515,14 +515,6 @@ that use Sphinx' HTMLWriter class. .. versionadded:: 0.4 -.. confval:: html_collapse_toctree - - If true, the toctree given to the templates as ``toctree`` will be collapsed, - i.e. only the subitems that contain the current page are visible. Default is - ``False``. - - .. versionadded:: 0.6 - .. confval:: htmlhelp_basename Output file base name for HTML help builder. Default is ``'pydoc'``. diff --git a/doc/templating.rst b/doc/templating.rst index 2ee449aa..bccdd689 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -364,4 +364,5 @@ are in HTML form), these variables are also available: .. data:: toctree A callable yielding the global TOC tree containing the current page, rendered - as HTML bullet lists. + as HTML bullet lists. If the optional keyword argument ``collapse`` is true, + all TOC entries that are not ancestors of the current page are collapsed. diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 3332aa14..1bbf359f 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -184,10 +184,6 @@ class StandaloneHTMLBuilder(Builder): self.theme.get_options(self.config.html_theme_options).iteritems()) self.globalcontext.update(self.config.html_context) - def _get_local_toctree(self, docname): - return self.render_partial(self.env.get_toctree_for( - docname, self, self.config.html_collapse_toctree))['fragment'] - def get_doc_context(self, docname, body, metatags): """Collect items for the template context of a page.""" # find out relations @@ -535,6 +531,10 @@ class StandaloneHTMLBuilder(Builder): if self.indexer is not None and title: self.indexer.feed(pagename, title, doctree) + def _get_local_toctree(self, docname, collapse=True): + return self.render_partial(self.env.get_toctree_for( + docname, self, collapse))['fragment'] + # --------- these are overwritten by the serialization builder def get_target_uri(self, docname, typ=None): @@ -554,7 +554,7 @@ class StandaloneHTMLBuilder(Builder): ctx['pathto'] = pathto ctx['hasdoc'] = lambda name: name in self.env.all_docs ctx['customsidebar'] = self.config.html_sidebars.get(pagename) - ctx['toctree'] = lambda: self._get_local_toctree(pagename) + ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw) ctx.update(addctx) self.app.emit('html-page-context', pagename, templatename, diff --git a/sphinx/config.py b/sphinx/config.py index 474ddc23..d5bb6471 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -72,7 +72,6 @@ class Config(object): html_use_smartypants = (True, False), html_translator_class = (None, False), html_sidebars = ({}, False), - html_collapse_toctree = (False, False), html_additional_pages = ({}, False), html_use_modindex = (True, False), html_add_permalinks = (True, False), -- cgit v1.2.1 From fd55c93fdd30b99b1bd220993997b747efe90174 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 16 Feb 2009 09:06:54 +0100 Subject: Fix templating inconsistency. --- sphinx/themes/basic/layout.html | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html index 53b9b8b1..7a2d5859 100644 --- a/sphinx/themes/basic/layout.html +++ b/sphinx/themes/basic/layout.html @@ -152,8 +152,8 @@ {%- block sidebar1 %} {# possible location for sidebar #} {% endblock %} -{%- block document %} <div class="document"> +{%- block document %} <div class="documentwrapper"> {%- if not embedded %}{% if not theme_nosidebar|tobool %} <div class="bodywrapper"> @@ -165,10 +165,11 @@ </div> {%- endif %}{% endif %} </div> - {%- block sidebar2 %}{{ sidebar() }}{% endblock %} +{%- endblock %} + +{%- block sidebar2 %}{{ sidebar() }}{% endblock %} <div class="clearer"></div> </div> -{%- endblock %} {%- block relbar2 %}{{ relbar() }}{% endblock %} -- cgit v1.2.1 From 4397c3f6b8247bf969056fd35777ef71aec55dd1 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Mon, 16 Feb 2009 09:13:49 +0100 Subject: Note incompatibility about the document block. --- CHANGES | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/CHANGES b/CHANGES index 80a27910..cfb56130 100644 --- a/CHANGES +++ b/CHANGES @@ -11,6 +11,11 @@ New features added is largely the same, very few fixes should be necessary in custom templates. + - The "document" div tag has been moved out of the ``layout.html`` + template's "document" block, because the closing tag was already + outside. If you overwrite this block, you need to remove your + "document" div tag as well. + - The ``autodoc_skip_member`` event now also gets to decide whether to skip members whose name starts with underscores. Previously, these members were always automatically skipped. -- cgit v1.2.1 From fe956651a0b4e346278c5cde98b551a968c1d63c Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 12:20:09 +0100 Subject: Use INI lexer. --- doc/theming.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/doc/theming.rst b/doc/theming.rst index b2448198..7c3ae709 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -113,7 +113,9 @@ name), containing the following: output statid directory on build. These can be images, styles, script files. The :file:`theme.conf` file is in INI format [1]_ (readable by the standard -Python :mod:`ConfigParser` module) and has the following structure:: +Python :mod:`ConfigParser` module) and has the following structure: + +.. sourcecode:: ini [theme] inherit = base theme -- cgit v1.2.1 From 79c547d3bea993cf3074aba40465c4d6cabf6906 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 16:36:30 +0100 Subject: Refactor autodoc so that it gets easy to add support for custom types of objects. --- sphinx/application.py | 22 +- sphinx/ext/autodoc.py | 1175 +++++++++++++++++++++++++++++-------------------- sphinx/util/compat.py | 63 ++- 3 files changed, 775 insertions(+), 485 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 0d87c493..9bb276f1 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -56,6 +56,7 @@ from sphinx.builders import BUILTIN_BUILDERS from sphinx.directives import desc_directive, target_directive, \ additional_xref_types from sphinx.environment import SphinxStandaloneReader +from sphinx.util.compat import Directive, directive_dwim from sphinx.util.console import bold @@ -282,11 +283,17 @@ class Sphinx(object): if depart: setattr(translator, 'depart_'+node.__name__, depart) - def add_directive(self, name, func, content, arguments, **options): - func.content = content - func.arguments = arguments - func.options = options - directives.register_directive(name, func) + def add_directive(self, name, obj, content=None, arguments=None, **options): + if isinstance(obj, Directive): + if content or arguments or options: + raise ExtensionError('when adding directive classes, no ' + 'additional arguments may be given') + directives.register_directive(name, directive_dwim(obj)) + else: + obj.content = content + obj.arguments = arguments + obj.options = options + directives.register_directive(name, obj) def add_role(self, name, role): roles.register_canonical_role(name, role) @@ -325,6 +332,11 @@ class Sphinx(object): return lexers[alias] = lexer + def add_autodocumenter(self, cls): + from sphinx.ext import autodoc + autodoc.add_documenter(cls) + self.add_directive('auto' + cls.objtype, autodoc.AutoDirective) + class TemplateBridge(object): """ diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 662682f3..b8e048e8 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -14,18 +14,20 @@ import re import sys import inspect -import linecache -from types import FunctionType, BuiltinFunctionType, MethodType, ClassType +from types import ModuleType, FunctionType, BuiltinFunctionType, MethodType, \ + ClassType from docutils import nodes -from docutils.parsers.rst import directives +from docutils.utils import assemble_option_dict from docutils.statemachine import ViewList from sphinx.util import rpartition, nested_parse_with_titles, force_decode from sphinx.pycode import ModuleAnalyzer, PycodeError +from sphinx.application import ExtensionError +from sphinx.util.compat import Directive from sphinx.util.docstrings import prepare_docstring -clstypes = (type, ClassType) + try: base_exception = BaseException except NameError: @@ -42,22 +44,39 @@ py_ext_sig_re = re.compile( ''', re.VERBOSE) -class Options(object): - pass +class DefDict(dict): + def __init__(self, default): + dict.__init__(self) + self.default = default + def __getitem__(self, key): + try: + return dict.__getitem__(self, key) + except KeyError: + return self.default + def __nonzero__(self): + # docutils check "if option_spec" + return True +identity = lambda x: x -def get_method_type(obj): - """ - Return the method type for an object: method, staticmethod or classmethod. - """ - if isinstance(obj, classmethod) or \ - (isinstance(obj, MethodType) and obj.im_self is not None): - return 'classmethod' - elif isinstance(obj, FunctionType) or \ - (isinstance(obj, BuiltinFunctionType) and obj.__self__ is not None): - return 'staticmethod' - else: - return 'method' + +class Options(dict): + def __getattr__(self, name): + try: + return self[name.replace('_', '-')] + except KeyError: + return False + + +ALL = object() + +def members_option(arg): + if arg is None: + return ALL + return [x.strip() for x in arg.split(',')] + +def bool_option(arg): + return True class AutodocReporter(object): @@ -171,229 +190,327 @@ def isdescriptor(x): return False -class RstGenerator(object): - def __init__(self, options, document, lineno): - self.options = options - self.env = document.settings.env - self.reporter = document.reporter - self.lineno = lineno - self.filename_set = set() - self.warnings = [] - self.result = ViewList() - - def warn(self, msg): - self.warnings.append(self.reporter.warning(msg, line=self.lineno)) - - def get_doc(self, what, obj, encoding=None): - """Decode and return lines of the docstring(s) for the object.""" - docstrings = [] - - # add the regular docstring if present - if getattr(obj, '__doc__', None): - docstrings.append(obj.__doc__) - - # skip some lines in module docstrings if configured (deprecated!) - if what == 'module' and self.env.config.automodule_skip_lines \ - and docstrings: - docstrings[0] = '\n'.join(docstrings[0].splitlines() - [self.env.config.automodule_skip_lines:]) - - # for classes, what the "docstring" is can be controlled via an option - if what in ('class', 'exception'): - content = self.env.config.autoclass_content - if content in ('both', 'init'): - initdocstring = getattr(obj, '__init__', None).__doc__ - # for new-style classes, no __init__ means default __init__ - if initdocstring == object.__init__.__doc__: - initdocstring = None - if initdocstring: - if content == 'init': - docstrings = [initdocstring] - else: - docstrings.append(initdocstring) - # the default is only the class docstring - - # make sure we have Unicode docstrings, then sanitize and split - # into lines - return [prepare_docstring(force_decode(docstring, encoding)) - for docstring in docstrings] - - def process_doc(self, docstrings, what, name, obj): - """Let the user process the docstrings.""" - for docstringlines in docstrings: - if self.env.app: - # let extensions preprocess docstrings - self.env.app.emit('autodoc-process-docstring', - what, name, obj, self.options, docstringlines) - for line in docstringlines: - yield line - - def resolve_name(self, what, name): +class Documenter(object): + # name by which the directive is called (auto...) and the default + # generated directive name + objtype = 'object' + # indentation by which to indent the directive content + content_indent = u' ' + # priority if multiple documenters return True from can_document_member + priority = 0 + + option_spec = {'noindex': bool_option} + + special_attrgetters = {} + + @classmethod + def get_attr(cls, obj, name, *defargs): + """getattr() override for types such as Zope interfaces.""" + for typ, func in cls.special_attrgetters.iteritems(): + if isinstance(obj, typ): + return func(obj, name, *defargs) + return getattr(obj, name, *defargs) + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + """Called to see if a member can be documented by this documenter.""" + raise NotImplementedError('must be implemented in subclasses') + + def __init__(self, directive, name, indent=u''): + self.directive = directive + self.env = directive.env + self.options = directive.genopt + self.name = name + self.indent = indent + # the module and object path within the module, and the fully + # qualified name (all set after resolve_name succeeds) + self.modname = None + self.module = None + self.objpath = None + self.fullname = None + # extra signature items (arguments and return annotation, + # also set after resolve_name succeeds) + self.args = None + self.retann = None + # the object to document (set after import_object succeeds) + self.object = None + # the module analyzer to get at attribute docs, or None + self.analyzer = None + + def add_line(self, line, source, *lineno): + self.directive.result.append(self.indent + line, source, *lineno) + + def resolve_name(self, modname, parents, path, base): + raise NotImplementedError('must be implemented in subclasses') + + def parse_name(self): """ Determine what module to import and what attribute to document. - Returns a tuple of: the full name, the module name, a path of - names to get via getattr, the signature and return annotation. + Returns True if parsing and resolving was successful. """ # first, parse the definition -- auto directives for classes and # functions can contain a signature which is then used instead of # an autogenerated one try: - mod, path, base, args, retann = py_ext_sig_re.match(name).groups() - except: - self.warn('invalid signature for auto%s (%r)' % (what, name)) - return None, [], None, None + explicit_modname, path, base, args, retann = \ + py_ext_sig_re.match(self.name).groups() + except AttributeError: + self.directive.warn('invalid signature for auto%s (%r)' % + (self.objtype, self.name)) + return False # support explicit module and class name separation via :: - if mod is not None: - mod = mod[:-2] + if explicit_modname is not None: + modname = explicit_modname[:-2] parents = path and path.rstrip('.').split('.') or [] else: + modname = None parents = [] - if what == 'module': - if mod is not None: - self.warn('"::" in automodule name doesn\'t make sense') - if args or retann: - self.warn('ignoring signature arguments and return annotation ' - 'for automodule %s' % name) - return (path or '') + base, [], None, None - - elif what in ('exception', 'function', 'class', 'data'): - if mod is None: - if path: - mod = path.rstrip('.') - else: - # if documenting a toplevel object without explicit module, - # it can be contained in another auto directive ... - if hasattr(self.env, 'autodoc_current_module'): - mod = self.env.autodoc_current_module - # ... or in the scope of a module directive - if not mod: - mod = self.env.currmodule - return mod, parents + [base], args, retann + self.modname, self.objpath = \ + self.resolve_name(modname, parents, path, base) - else: - if mod is None: - if path: - mod_cls = path.rstrip('.') - else: - mod_cls = None - # if documenting a class-level object without path, - # there must be a current class, either from a parent - # auto directive ... - if hasattr(self.env, 'autodoc_current_class'): - mod_cls = self.env.autodoc_current_class - # ... or from a class directive - if mod_cls is None: - mod_cls = self.env.currclass - # ... if still None, there's no way to know - if mod_cls is None: - return None, [], None, None - mod, cls = rpartition(mod_cls, '.') - parents = [cls] - # if the module name is still missing, get it like above - if not mod and hasattr(self.env, 'autodoc_current_module'): - mod = self.env.autodoc_current_module - if not mod: - mod = self.env.currmodule - return mod, parents + [base], args, retann - - def format_signature(self, what, name, obj, args, retann): - """ - Return the signature of the object, formatted for display. - """ - if what not in ('class', 'method', 'staticmethod', 'classmethod', - 'function'): - return '' + self.args = args + self.retann = retann + self.fullname = self.modname + (self.objpath and + '.' + '.'.join(self.objpath) or '') + return True + def import_object(self): + try: + __import__(self.modname) + obj = self.module = sys.modules[self.modname] + for part in self.objpath: + obj = self.get_attr(obj, part) + self.object = obj + return True + except (ImportError, AttributeError), err: + self.directive.warn( + 'autodoc can\'t import/find %s %r, it reported error: ' + '"%s", please check your spelling and sys.path' % + (self.objtype, str(self.fullname), err)) + return False + + def get_real_modname(self): + return self.get_attr(self.object, '__module__', None) or self.modname + + def check_module(self): + modname = self.get_attr(self.object, '__module__', None) + if modname and modname != self.modname: + return False + return True + + def format_args(self): + return None + + def format_signature(self): err = None - if args is not None: + if self.args is not None: # signature given explicitly - args = "(%s)" % args + args = "(%s)" % self.args else: # try to introspect the signature try: - args = None - getargs = True - if what == 'class': - # for classes, the relevant signature is the - # __init__ method's - obj = getattr(obj, '__init__', None) - # classes without __init__ method, default __init__ or - # __init__ written in C? - if obj is None or obj is object.__init__ or not \ - (inspect.ismethod(obj) or inspect.isfunction(obj)): - getargs = False - elif inspect.isbuiltin(obj) or inspect.ismethoddescriptor(obj): - # can never get arguments of a C function or method - getargs = False - if getargs: - try: - argspec = inspect.getargspec(obj) - except TypeError: - # if a class should be documented as function (yay duck - # typing) we try to use the constructor signature as function - # signature without the first argument. - try: - argspec = inspect.getargspec(obj.__new__) - except TypeError: - argspec = inspect.getargspec(obj.__init__) - if argspec[0]: - del argspec[0][0] - if what in ('class', 'method', 'staticmethod', - 'classmethod') and argspec[0] and \ - argspec[0][0] in ('cls', 'self'): - del argspec[0][0] - args = inspect.formatargspec(*argspec) + args = self.format_args() except Exception, e: args = None err = e + if args is None: + return '' + retann = self.retann result = self.env.app.emit_firstresult( - 'autodoc-process-signature', what, name, obj, - self.options, args, retann) + 'autodoc-process-signature', self.objtype, self.fullname, + self.object, self.options, args, retann) if result: args, retann = result if args is not None: - return '%s%s' % (args, retann and (' -> %s' % retann) or '') + return args + (retann and (' -> %s' % retann) or '') elif err: # re-raise the error for perusal of the handler in generate() raise RuntimeError(err) else: return '' - def generate(self, what, name, members, add_content, indent=u'', - check_module=False, no_docstring=False, real_module=None): - """ - Generate reST for the object in self.result. - """ - mod, objpath, args, retann = self.resolve_name(what, name) - if not mod: + def add_directive_header(self, sig): + directive = getattr(self, 'directivetype', self.objtype) + # the name to put into the generated directive -- doesn't contain + # the module (except for module directive of course) + name_in_directive = '.'.join(self.objpath) or self.modname + self.add_line(u'.. %s:: %s%s' % (directive, name_in_directive, sig), + '<autodoc>') + if self.options.noindex: + self.add_line(u' :noindex:', '<autodoc>') + if self.objpath: + # Be explicit about the module, this is necessary since .. class:: + # etc. don't support a prepended module name + self.add_line(u' :module: %s' % self.modname, '<autodoc>') + + def get_doc(self, encoding=None): + """Decode and return lines of the docstring(s) for the object.""" + docstring = self.get_attr(self.object, '__doc__', None) + if docstring: + # make sure we have Unicode docstrings, then sanitize and split + # into lines + return [prepare_docstring(force_decode(docstring, encoding))] + return [] + + def process_doc(self, docstrings): + """Let the user process the docstrings.""" + for docstringlines in docstrings: + if self.env.app: + # let extensions preprocess docstrings + self.env.app.emit('autodoc-process-docstring', + self.objtype, self.fullname, self.object, + self.options, docstringlines) + for line in docstringlines: + yield line + + def add_content(self, more_content, no_docstring=False): + # set sourcename and add content from attribute documentation + if self.analyzer: + # prevent encoding errors when the file name is non-ASCII + filename = unicode(self.analyzer.srcname, + sys.getfilesystemencoding(), 'replace') + sourcename = u'%s:docstring of %s' % (filename, self.fullname) + + attr_docs = self.analyzer.find_attr_docs() + if self.objpath: + key = ('.'.join(self.objpath[:-1]), self.objpath[-1]) + if key in attr_docs: + no_docstring = True + docstrings = [attr_docs[key]] + for i, line in enumerate(self.process_doc(docstrings)): + self.add_line(line, sourcename, i) + else: + sourcename = u'docstring of %s' % self.fullname + + # add content from docstrings + if not no_docstring: + encoding = self.analyzer and self.analyzer.encoding + docstrings = self.get_doc(encoding) + for i, line in enumerate(self.process_doc(docstrings)): + self.add_line(line, sourcename, i) + + # add additional content (e.g. from document), if present + if more_content: + for line, src in zip(more_content.data, more_content.items): + self.add_line(line, src[0], src[1]) + + def get_object_members(self, members=ALL): + if members is not ALL: + # specific members given + ret = [] + for mname in members: + try: + ret.append((mname, self.get_attr(self.object, mname))) + except AttributeError: + self.directive.warn('missing attribute %s in object %s: ' + % (mname, self.fullname)) + return False, ret + elif self.options.inherited_members: + # getmembers() uses dir() which pulls in members from all + # base classes + return False, inspect.getmembers(self.object) + else: + # __dict__ contains only the members directly defined in + # the class + return False, sorted(self.object.__dict__.iteritems()) + + def filter_members(self, members, want_all): + ret = [] + + # search for members in source code too + namespace = '.'.join(self.objpath) # will be empty for modules + + if self.analyzer: + attr_docs = self.analyzer.find_attr_docs() + else: + attr_docs = {} + + # process members and determine which to skip + for (membername, member) in members: + # if isattr is True, the member is documented as an attribute + isattr = False + + if want_all and membername.startswith('_'): + # ignore members whose name starts with _ by default + skip = True + elif (namespace, membername) in attr_docs: + # keep documented attributes + skip = False + isattr = True + else: + # ignore undocumented members if :undoc-members: + # is not given + doc = self.get_attr(member, '__doc__', None) + skip = not self.options.undoc_members and not doc + + # give the user a chance to decide whether this member + # should be skipped + if self.env.app: + # let extensions preprocess docstrings + skip_user = self.env.app.emit_firstresult( + 'autodoc-skip-member', self.objtype, membername, member, + skip, self.options) + if skip_user is not None: + skip = skip_user + if skip: + continue + + ret.append((membername, member, isattr)) + + return ret + + def document_members(self, all_members=False): + # set current namespace for finding members + self.env.autodoc_current_module = self.modname + if self.objpath: + self.env.autodoc_current_class = self.objpath[0] + + want_all = all_members or self.options.inherited_members or \ + self.options.members is ALL + # find out which members are documentable + members_check_module, members = self.get_object_members(want_all) + + # document non-skipped members + for (mname, member, isattr) in self.filter_members(members, want_all): + classes = [cls for cls in AutoDirective._registry.itervalues() + if cls.can_document_member(member, mname, isattr, self)] + if not classes: + # don't know how to document this member + continue + # prefer the documenter with the highest priority + classes.sort(lambda cls: cls.priority) + # give explicitly separated module name, so that members + # of inner classes can be documented + full_mname = self.modname + '::' + \ + '.'.join(self.objpath + [mname]) + memberdocmtr = classes[-1](self.directive, full_mname, + self.indent) + memberdocmtr.generate(all_members=True, + real_modname=self.real_modname, + check_module=members_check_module) + + # reset current objects + self.env.autodoc_current_module = None + self.env.autodoc_current_class = None + + def generate(self, more_content=None, real_modname=None, + check_module=False, all_members=False): + if not self.parse_name(): # need a module to import - self.warn('don\'t know which module to import for autodocumenting ' - '%r (try placing a "module" or "currentmodule" directive ' - 'in the document, or giving an explicit module name)' - % name) + self.directive.warn( + 'don\'t know which module to import for autodocumenting ' + '%r (try placing a "module" or "currentmodule" directive ' + 'in the document, or giving an explicit module name)' + % self.name) return - # fully-qualified name - fullname = mod + (objpath and '.' + '.'.join(objpath) or '') - - # the name to put into the generated directive -- doesn't contain - # the module - name_in_directive = '.'.join(objpath) or mod # now, import the module and get object to document - try: - __import__(mod) - todoc = module = sys.modules[mod] - for part in objpath: - todoc = getattr(todoc, part) - except (ImportError, AttributeError), err: - self.warn('autodoc can\'t import/find %s %r, it reported error: ' - '"%s", please check your spelling and sys.path' % - (what, str(fullname), err)) + if not self.import_object(): return # If there is no real module defined, figure out which to use. @@ -401,327 +518,427 @@ class RstGenerator(object): # where the attribute documentation would actually be found in. # This is used for situations where you have a module that collects the # functions and classes of internal submodules. - if real_module is None: - real_module = getattr(todoc, '__module__', None) or mod + self.real_modname = real_modname or self.get_real_modname() # try to also get a source code analyzer for attribute docs try: - analyzer = ModuleAnalyzer.for_module(real_module) + self.analyzer = ModuleAnalyzer.for_module(self.real_modname) # parse right now, to get PycodeErrors on parsing - analyzer.parse() + self.analyzer.parse() except PycodeError, err: # no source file -- e.g. for builtin and C modules - analyzer = None + self.analyzer = None else: - self.filename_set.add(analyzer.srcname) + self.directive.filename_set.add(self.analyzer.srcname) - # check __module__ of object for members not given explicitly + # check __module__ of object (for members not given explicitly) if check_module: - if hasattr(todoc, '__module__'): - if todoc.__module__ != mod: - return + if not self.check_module(): + return # make sure that the result starts with an empty line. This is # necessary for some situations where another directive preprocesses # reST and no starting newline is present - self.result.append(u'', '') + self.add_line(u'', '') # format the object's signature, if any try: - sig = self.format_signature(what, fullname, todoc, args, retann) + sig = self.format_signature() except Exception, err: - self.warn('error while formatting signature for %s: %s' % - (fullname, err)) + self.directive.warn('error while formatting signature for ' + '%s: %s' % (self.fullname, err)) sig = '' - # now, create the directive header - if what == 'method': - directive = get_method_type(todoc) - else: - directive = what - self.result.append(indent + u'.. %s:: %s%s' % - (directive, name_in_directive, sig), '<autodoc>') - if what == 'module': - # Add some module-specific options - if self.options.synopsis: - self.result.append(indent + u' :synopsis: ' + - self.options.synopsis, '<autodoc>') - if self.options.platform: - self.result.append(indent + u' :platform: ' + - self.options.platform, '<autodoc>') - if self.options.deprecated: - self.result.append(indent + u' :deprecated:', '<autodoc>') - else: - # Be explicit about the module, this is necessary since .. class:: - # doesn't support a prepended module name - self.result.append(indent + u' :module: %s' % mod, '<autodoc>') - if self.options.noindex: - self.result.append(indent + u' :noindex:', '<autodoc>') - self.result.append(u'', '<autodoc>') + # generate the directive header and options, if applicable + self.add_directive_header(sig) + self.add_line(u'', '<autodoc>') + + # e.g. the module directive doesn't have content + self.indent += self.content_indent + + # add all content (from docstrings, attribute docs etc.) + self.add_content(more_content) + + # document members, if possible + self.document_members(all_members) + + +class ModuleDocumenter(Documenter): + option_spec = { + 'members': members_option, 'undoc-members': bool_option, + 'noindex': bool_option, 'inherited-members': bool_option, + 'show-inheritance': bool_option, 'synopsis': identity, + 'platform': identity, 'deprecated': bool_option, + } + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, ModuleType) + + def resolve_name(self, modname, parents, path, base): + if modname is not None: + self.directive.warn('"::" in automodule name doesn\'t make sense') + return (path or '') + base, [] + + def parse_name(self): + ret = Documenter.parse_name(self) + if self.args or self.retann: + self.directive.warn('signature arguments or return annotation ' + 'given for automodule %s' % self.fullname) + return ret + + def add_directive_header(self, sig): + Documenter.add_directive_header(self, sig) + + # add some module-specific options + if self.options.synopsis: + self.add_line( + u' :synopsis: ' + self.options.synopsis, '<autodoc>') + if self.options.platform: + self.add_line( + u' :platform: ' + self.options.platform, '<autodoc>') + if self.options.deprecated: + self.add_line(u' :deprecated:', '<autodoc>') + + def get_object_members(self, members=None): + if members is ALL or not hasattr(self.object, '__all__'): + # for implicit module members, check __module__ to avoid + # documenting imported objects + return True, inspect.getmembers(self.object) + ret = [] + for mname in (members or self.object.__all__): + try: + ret.append((mname, getattr(self.object, mname))) + except AttributeError: + self.directive.warn('missing attribute mentioned in :members: ' + 'or __all__: module %s, attribute %s' % + (self.object.__name__, mname)) + return False, ret + + +class ModuleLevelDocumenter(Documenter): + def resolve_name(self, modname, parents, path, base): + if modname is None: + if path: + modname = path.rstrip('.') + else: + # if documenting a toplevel object without explicit module, + # it can be contained in another auto directive ... + if hasattr(self.env, 'autodoc_current_module'): + modname = self.env.autodoc_current_module + # ... or in the scope of a module directive + if not modname: + modname = self.env.currmodule + # ... else, it stays None, which means invalid + return modname, parents + [base] + + +class ClassLevelDocumenter(Documenter): + def resolve_name(self, modname, parents, path, base): + if modname is None: + if path: + mod_cls = path.rstrip('.') + else: + mod_cls = None + # if documenting a class-level object without path, + # there must be a current class, either from a parent + # auto directive ... + if hasattr(self.env, 'autodoc_current_class'): + mod_cls = self.env.autodoc_current_class + # ... or from a class directive + if mod_cls is None: + mod_cls = self.env.currclass + # ... if still None, there's no way to know + if mod_cls is None: + return None, [] + modname, cls = rpartition(mod_cls, '.') + parents = [cls] + # if the module name is still missing, get it like above + if not modname and hasattr(self.env, 'autodoc_current_module'): + modname = self.env.autodoc_current_module + if not modname: + modname = self.env.currmodule + # ... else, it stays None, which means invalid + return modname, parents + [base] + + +class FunctionDocumenter(ModuleLevelDocumenter): + objtype = 'function' + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, (FunctionType, BuiltinFunctionType)) + + def format_args(self): + if inspect.isbuiltin(self.object) or \ + inspect.ismethoddescriptor(self.object): + # can never get arguments of a C function or method + return None + try: + argspec = inspect.getargspec(self.object) + except TypeError: + # if a class should be documented as function (yay duck + # typing) we try to use the constructor signature as function + # signature without the first argument. + try: + argspec = inspect.getargspec(self.object.__new__) + except TypeError: + argspec = inspect.getargspec(self.object.__init__) + if argspec[0]: + del argspec[0][0] + return inspect.formatargspec(*argspec) + + def document_members(self, all_members=False): + pass + + +class ClassDocumenter(ModuleLevelDocumenter): + objtype = 'class' + option_spec = { + 'members': members_option, 'undoc-members': bool_option, + 'noindex': bool_option, 'inherited-members': bool_option, + 'show-inheritance': bool_option, + } + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, (type, ClassType)) + + def import_object(self): + ModuleLevelDocumenter.import_object(self) + + # if the class is documented under another name, document it + # as data/attribute + self.doc_as_attr = (self.objpath[-1] != self.object.__name__) + + def format_args(self): + args = None + # for classes, the relevant signature is the __init__ method's + initmeth = self.get_attr(self.object, '__init__', None) + # classes without __init__ method, default __init__ or + # __init__ written in C? + if initmeth is None or initmeth is object.__init__ or not \ + (inspect.ismethod(initmeth) or inspect.isfunction(initmeth)): + return None + argspec = inspect.getargspec(initmeth) + if argspec[0] and argspec[0][0] in ('cls', 'self'): + del argspec[0][0] + return inspect.formatargspec(*argspec) + + def format_signature(self): + if self.doc_as_attr: + return '' + return ModuleLevelDocumenter.format_signature(self) + + def add_directive_header(self, sig): + if self.doc_as_attr: + self.directivetype = 'attribute' + Documenter.add_directive_header(self, sig) # add inheritance info, if wanted - if self.options.show_inheritance and what in ('class', 'exception'): - if len(todoc.__bases__): + if not self.doc_as_attr and self.options.show_inheritance: + self.add_line(u'', '<autodoc>') + if len(self.object.__bases__): bases = [b.__module__ == '__builtin__' and u':class:`%s`' % b.__name__ or u':class:`%s.%s`' % (b.__module__, b.__name__) - for b in todoc.__bases__] - self.result.append(indent + _(u' Bases: %s') % - ', '.join(bases), - '<autodoc>') - self.result.append(u'', '<autodoc>') - - # the module directive doesn't have content - if what != 'module': - indent += u' ' - - # add content from attribute documentation - if analyzer: - # prevent encoding errors when the file name is non-ASCII - srcname = unicode(analyzer.srcname, - sys.getfilesystemencoding(), 'replace') - sourcename = u'%s:docstring of %s' % (srcname, fullname) - attr_docs = analyzer.find_attr_docs() - if objpath: - key = ('.'.join(objpath[:-1]), objpath[-1]) - if key in attr_docs: - no_docstring = True - docstrings = [attr_docs[key]] - for i, line in enumerate(self.process_doc(docstrings, what, - fullname, todoc)): - self.result.append(indent + line, sourcename, i) - else: - sourcename = u'docstring of %s' % fullname - attr_docs = {} + for b in self.object.__bases__] + self.add_line(_(u' Bases: %s') % ', '.join(bases), + '<autodoc>') - # add content from docstrings - if not no_docstring: - encoding = analyzer and analyzer.encoding - docstrings = self.get_doc(what, todoc, encoding) - for i, line in enumerate(self.process_doc(docstrings, what, - fullname, todoc)): - self.result.append(indent + line, sourcename, i) + def get_doc(self, encoding=None): + content = self.env.config.autoclass_content - # add additional content (e.g. from document), if present - if add_content: - for line, src in zip(add_content.data, add_content.items): - self.result.append(indent + line, src[0], src[1]) + docstrings = [] + docstring = self.get_attr(self.object, '__doc__', None) + if docstring: + docstrings.append(docstring) + + # for classes, what the "docstring" is can be controlled via a + # config value; the default is only the class docstring + if content in ('both', 'init'): + initdocstring = self.get_attr( + self.get_attr(self.object, '__init__', None), '__doc__') + # for new-style classes, no __init__ means default __init__ + if initdocstring == object.__init__.__doc__: + initdocstring = None + if initdocstring: + if content == 'init': + docstrings = [initdocstring] + else: + docstrings.append(initdocstring) - # document members? - if not members or what in ('function', 'method', 'staticmethod', - 'classmethod', 'data', 'attribute'): - return + return [prepare_docstring(force_decode(docstring, encoding)) + for docstring in docstrings] - # set current namespace for finding members - self.env.autodoc_current_module = mod - if objpath: - self.env.autodoc_current_class = objpath[0] - - # look for members to include - want_all_members = members == ['__all__'] - members_check_module = False - if want_all_members: - # unqualified :members: given - if what == 'module': - if hasattr(todoc, '__all__'): - members_check_module = False - all_members = [] - for mname in todoc.__all__: - try: - all_members.append((mname, getattr(todoc, mname))) - except AttributeError: - self.warn('missing attribute mentioned in __all__: ' - 'module %s, attribute %s' % - (todoc.__name__, mname)) - else: - # for implicit module members, check __module__ to avoid - # documenting imported objects - members_check_module = True - all_members = inspect.getmembers(todoc) - else: - if self.options.inherited_members: - # getmembers() uses dir() which pulls in members from all - # base classes - all_members = inspect.getmembers(todoc) - else: - # __dict__ contains only the members directly defined - # in the class - all_members = sorted(todoc.__dict__.iteritems()) + def add_content(self, more_content, no_docstring=False): + if self.doc_as_attr: + content = ViewList( + [_('alias of :class:`%s`') % self.object.__name__], source='') + ModuleLevelDocumenter.add_content(self, content, no_docstring=True) else: - all_members = [(mname, getattr(todoc, mname)) for mname in members] + ModuleLevelDocumenter.add_content(self, more_content) - # search for members in source code too - namespace = '.'.join(objpath) # will be empty for modules - for (membername, member) in all_members: - # if isattr is True, the member is documented as an attribute - isattr = False - # if content is not None, no extra content from docstrings - # will be added - content = None +class ExceptionDocumenter(ClassDocumenter): + objtype = 'exception' - if want_all_members and membername.startswith('_'): - # ignore members whose name starts with _ by default - skip = True - else: - if (namespace, membername) in attr_docs: - # keep documented attributes - skip = False - isattr = True - else: - # ignore undocumented members if :undoc-members: - # is not given - doc = getattr(member, '__doc__', None) - skip = not self.options.undoc_members and not doc + # needs a higher priority than ClassDocumenter + priority = 10 - # give the user a chance to decide whether this member - # should be skipped - if self.env.app: - # let extensions preprocess docstrings - skip_user = self.env.app.emit_firstresult( - 'autodoc-skip-member', what, membername, member, - skip, self.options) - if skip_user is not None: - skip = skip_user - if skip: - continue + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, (type, ClassType)) and \ + issubclass(member, base_exception) - # determine member type - if what == 'module': - if isinstance(member, (FunctionType, BuiltinFunctionType)): - memberwhat = 'function' - elif isattr: - memberwhat = 'attribute' - elif isinstance(member, clstypes): - if member.__name__ != membername: - # assume it's aliased - memberwhat = 'data' - content = ViewList( - [_('alias of :class:`%s`') % member.__name__], - source='') - elif issubclass(member, base_exception): - memberwhat = 'exception' - else: - memberwhat = 'class' - else: - continue - else: - if inspect.isroutine(member): - memberwhat = 'method' - elif isattr: - memberwhat = 'attribute' - elif isinstance(member, clstypes): - if member.__name__ != membername: - # assume it's aliased - memberwhat = 'attribute' - content = ViewList( - [_('alias of :class:`%s`') % member.__name__], - source='') - else: - memberwhat = 'class' - elif isdescriptor(member): - memberwhat = 'attribute' - else: - continue - # give explicitly separated module name, so that members - # of inner classes can be documented - full_membername = mod + '::' + '.'.join(objpath + [membername]) - self.generate(memberwhat, full_membername, ['__all__'], - add_content=content, no_docstring=bool(content), - indent=indent, check_module=members_check_module, - real_module=real_module) +class DataDocumenter(ModuleLevelDocumenter): + objtype = 'data' - self.env.autodoc_current_module = None - self.env.autodoc_current_class = None + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(parent, ModuleDocumenter) and isattr + def document_members(self, all_members=False): + pass -def _auto_directive(dirname, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - what = dirname[4:] # strip "auto" - name = arguments[0] - genopt = Options() - members = options.get('members', []) - genopt.inherited_members = 'inherited-members' in options - if genopt.inherited_members and not members: - # :inherited-members: implies :members: - members = ['__all__'] - genopt.undoc_members = 'undoc-members' in options - genopt.show_inheritance = 'show-inheritance' in options - genopt.noindex = 'noindex' in options - genopt.synopsis = options.get('synopsis', '') - genopt.platform = options.get('platform', '') - genopt.deprecated = 'deprecated' in options - - generator = RstGenerator(genopt, state.document, lineno) - generator.generate(what, name, members, content) - if not generator.result: - return generator.warnings - - # record all filenames as dependencies -- this will at least partially make - # automatic invalidation possible - for fn in generator.filename_set: - state.document.settings.env.note_dependency(fn) - - # use a custom reporter that correctly assigns lines to source and lineno - old_reporter = state.memo.reporter - state.memo.reporter = AutodocReporter(generator.result, state.memo.reporter) - if dirname == 'automodule': - node = nodes.section() - node.document = state.document # necessary so that the child nodes - # get the right source/line set - nested_parse_with_titles(state, generator.result, node) - else: - node = nodes.paragraph() - node.document = state.document - state.nested_parse(generator.result, 0, node) - state.memo.reporter = old_reporter - return generator.warnings + node.children - -def auto_directive(*args, **kwds): - return _auto_directive(*args, **kwds) - -def automodule_directive(*args, **kwds): - return _auto_directive(*args, **kwds) - -def autoclass_directive(*args, **kwds): - return _auto_directive(*args, **kwds) +class MethodDocumenter(ClassLevelDocumenter): + objtype = 'method' -def members_option(arg): - if arg is None: - return ['__all__'] - return [x.strip() for x in arg.split(',')] + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + # other attributes are recognized via the module analyzer + return inspect.isroutine(member) and \ + not isinstance(parent, ModuleDocumenter) + + def format_args(self): + if inspect.isbuiltin(self.object) or \ + inspect.ismethoddescriptor(self.object): + # can never get arguments of a C function or method + return None + argspec = inspect.getargspec(self.object) + if argspec[0] and argspec[0][0] in ('cls', 'self'): + del argspec[0][0] + return inspect.formatargspec(*argspec) + + def document_members(self, all_members=False): + pass + + +class ClassmethodDocumenter(MethodDocumenter): + objtype = 'classmethod' + + priority = 10 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return inspect.isroutine(member) and \ + not isinstance(parent, ModuleDocumenter) and \ + (isinstance(member, classmethod) or + (isinstance(member, MethodType) and member.im_self is not None)) + + +class StaticmethodDocumenter(MethodDocumenter): + objtype = 'staticmethod' + + priority = 10 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return inspect.isroutine(member) and \ + not isinstance(parent, ModuleDocumenter) and \ + (isinstance(member, FunctionType) or + (isinstance(member, BuiltinFunctionType) and + member.__self__ is not None)) + + +class AttributeDocumenter(ClassLevelDocumenter): + objtype = 'attribute' + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isdescriptor(member) or \ + (not isinstance(parent, ModuleDocumenter) and isattr) + + def document_members(self, all_members=False): + pass + + +class AutoDirective(Directive): + # a registry of objtype -> documenter class + _registry = {} + + # standard docutils directive settings + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + # allow any options to be passed; the options are parsed further + # by the selected Documenter + option_spec = DefDict(identity) + + def warn(self, msg): + self.warnings.append(self.reporter.warning(msg, line=self.lineno)) + + def run(self): + self.filename_set = set() # a set of dependent filenames + self.reporter = self.state.document.reporter + self.env = self.state.document.settings.env + self.warnings = [] + self.result = ViewList() + + # find out what documenter to call + objtype = self.name[4:] + doc_class = self._registry[objtype] + # process the options with the selected documenter's option_spec + self.genopt = Options(assemble_option_dict( + self.options.items(), doc_class.option_spec)) + # generate the output + documenter = doc_class(self, self.arguments[0]) + documenter.generate(more_content=self.content) + if not self.result: + return self.warnings + + # use a custom reporter that correctly assigns lines to source + # filename/description and lineno + old_reporter = self.state.memo.reporter + self.state.memo.reporter = AutodocReporter(self.result, + self.state.memo.reporter) + if self.name == 'automodule': + node = nodes.section() + # necessary so that the child nodes get the right source/line set + node.document = self.state.document + nested_parse_with_titles(self.state, self.result, node) + else: + node = nodes.paragraph() + node.document = self.state.document + self.state.nested_parse(self.result, 0, node) + self.state.memo.reporter = old_reporter + return self.warnings + node.children + + +def add_documenter(cls): + if not issubclass(cls, Documenter): + raise ExtensionError('autodoc documenter %r must be a subclass ' + 'of Documenter' % cls) + if cls.objtype in AutoDirective._registry: + raise ExtensionError('autodoc documenter for %r is already ' + 'registered' % cls.objtype) + AutoDirective._registry[cls.objtype] = cls def setup(app): - mod_options = { - 'members': members_option, 'undoc-members': directives.flag, - 'noindex': directives.flag, 'inherited-members': directives.flag, - 'show-inheritance': directives.flag, 'synopsis': lambda x: x, - 'platform': lambda x: x, 'deprecated': directives.flag - } - cls_options = { - 'members': members_option, 'undoc-members': directives.flag, - 'noindex': directives.flag, 'inherited-members': directives.flag, - 'show-inheritance': directives.flag - } - app.add_directive('automodule', automodule_directive, - 1, (1, 0, 1), **mod_options) - app.add_directive('autoclass', autoclass_directive, - 1, (1, 0, 1), **cls_options) - app.add_directive('autoexception', autoclass_directive, - 1, (1, 0, 1), **cls_options) - app.add_directive('autodata', auto_directive, 1, (1, 0, 1), - noindex=directives.flag) - app.add_directive('autofunction', auto_directive, 1, (1, 0, 1), - noindex=directives.flag) - app.add_directive('automethod', auto_directive, 1, (1, 0, 1), - noindex=directives.flag) - app.add_directive('autoattribute', auto_directive, 1, (1, 0, 1), - noindex=directives.flag) - # deprecated: remove in some future version. - app.add_config_value('automodule_skip_lines', 0, True) + app.add_autodocumenter(ModuleDocumenter) + app.add_autodocumenter(ClassDocumenter) + app.add_autodocumenter(ExceptionDocumenter) + app.add_autodocumenter(DataDocumenter) + app.add_autodocumenter(FunctionDocumenter) + app.add_autodocumenter(MethodDocumenter) + app.add_autodocumenter(ClassmethodDocumenter) + app.add_autodocumenter(StaticmethodDocumenter) + app.add_autodocumenter(AttributeDocumenter) + app.add_config_value('autoclass_content', 'class', True) app.add_event('autodoc-process-docstring') app.add_event('autodoc-process-signature') diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py index 56ac9e80..3ef3debd 100644 --- a/sphinx/util/compat.py +++ b/sphinx/util/compat.py @@ -11,7 +11,6 @@ from docutils import nodes - # function missing in 0.5 SVN def make_admonition(node_class, name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -35,3 +34,65 @@ def make_admonition(node_class, name, arguments, options, content, lineno, state.nested_parse(content, content_offset, admonition_node) return [admonition_node] + +# support the class-style Directive interface even when using docutils 0.4 + +try: + from docutils.parsers.rst import Directive + +except ImportError: + class Directive(object): + """ + Fake Directive class to allow Sphinx directives to be written in + class style. + """ + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = None + has_content = False + + def __init__(self, name, arguments, options, content, lineno, + content_offset, block_text, state, state_machine): + self.name = name + self.arguments = arguments + self.options = options + self.content = content + self.lineno = lineno + self.content_offset = content_offset + self.block_text = block_text + self.state = state + self.state_machine = state_machine + + def run(self): + raise NotImplementedError('Must override run() is subclass.') + + def directive_dwim(obj): + """ + Return something usable with register_directive(), regardless if + class or function. For that, we need to convert classes to a + function for docutils 0.4. + """ + if isinstance(obj, Directive): + def _class_directive(name, arguments, options, content, + lineno, content_offset, block_text, + state, state_machine): + return obj(name, arguments, options, content, + lineno, content_offset, block_text, + state, state_machine).run() + _class_directive.options = obj.option_spec + _class_directive.content = obj.has_content + _class_directive.arguments = (obj.required_arguments, + obj.optional_arguments, + obj.final_argument_whitespace) + return _class_directive + return obj + +else: + def directive_dwim(obj): + """ + Return something usable with register_directive(), regardless if + class or function. Nothing to do here, because docutils 0.5 takes + care of converting functions itself. + """ + return obj -- cgit v1.2.1 From eadf317b5720b4d80037fa15b1233f717be75e1c Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 16:57:33 +0100 Subject: Fix a few bugs in the new autodoc. --- sphinx/ext/autodoc.py | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index b8e048e8..e81c9e62 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -399,11 +399,11 @@ class Documenter(object): for line, src in zip(more_content.data, more_content.items): self.add_line(line, src[0], src[1]) - def get_object_members(self, members=ALL): - if members is not ALL: + def get_object_members(self, want_all): + if not want_all: # specific members given ret = [] - for mname in members: + for mname in self.options.members: try: ret.append((mname, self.get_attr(self.object, mname))) except AttributeError: @@ -416,8 +416,10 @@ class Documenter(object): return False, inspect.getmembers(self.object) else: # __dict__ contains only the members directly defined in - # the class - return False, sorted(self.object.__dict__.iteritems()) + # the class (but get them via getattr anyway, to e.g. get + # unbound method objects instead of function objects) + return False, sorted([(mname, self.get_attr(self.object, mname)) + for mname in self.object.__dict__]) def filter_members(self, members, want_all): ret = [] @@ -474,6 +476,7 @@ class Documenter(object): self.options.members is ALL # find out which members are documentable members_check_module, members = self.get_object_members(want_all) + print members # document non-skipped members for (mname, member, isattr) in self.filter_members(members, want_all): @@ -483,7 +486,7 @@ class Documenter(object): # don't know how to document this member continue # prefer the documenter with the highest priority - classes.sort(lambda cls: cls.priority) + classes.sort(key=lambda cls: cls.priority) # give explicitly separated module name, so that members # of inner classes can be documented full_mname = self.modname + '::' + \ @@ -705,11 +708,11 @@ class ClassDocumenter(ModuleLevelDocumenter): return isinstance(member, (type, ClassType)) def import_object(self): - ModuleLevelDocumenter.import_object(self) - + ret = ModuleLevelDocumenter.import_object(self) # if the class is documented under another name, document it # as data/attribute self.doc_as_attr = (self.objpath[-1] != self.object.__name__) + return ret def format_args(self): args = None -- cgit v1.2.1 From 413c96fd4503c65e73bf65d617f51b8caa3b725f Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 18:16:49 +0100 Subject: More small autodoc fixes. --- sphinx/ext/autodoc.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index e81c9e62..1f8a933f 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -401,6 +401,8 @@ class Documenter(object): def get_object_members(self, want_all): if not want_all: + if not self.options.members: + return False, [] # specific members given ret = [] for mname in self.options.members: @@ -476,7 +478,6 @@ class Documenter(object): self.options.members is ALL # find out which members are documentable members_check_module, members = self.get_object_members(want_all) - print members # document non-skipped members for (mname, member, isattr) in self.filter_members(members, want_all): @@ -576,7 +577,8 @@ class ModuleDocumenter(Documenter): @classmethod def can_document_member(cls, member, membername, isattr, parent): - return isinstance(member, ModuleType) + # don't document submodules automatically + return False def resolve_name(self, modname, parents, path, base): if modname is not None: -- cgit v1.2.1 From 82e105d67f7dff571676064f9d38980a8d952812 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 18:17:17 +0100 Subject: Allow "self" in toctrees, as a reference to the document containing the directive. --- sphinx/directives/other.py | 3 ++- sphinx/environment.py | 13 +++++++++++++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 12dcc83a..3d060b02 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -53,7 +53,7 @@ def toctree_directive(name, arguments, options, content, lineno, docname = docname[:-len(suffix)] # absolutize filenames docname = docname_join(env.docname, docname) - if url_re.match(ref): + if url_re.match(ref) or ref == 'self': entries.append((title, ref)) elif docname not in env.found_docs: ret.append(state.document.reporter.warning( @@ -74,6 +74,7 @@ def toctree_directive(name, arguments, options, content, lineno, 'toctree glob pattern %r didn\'t match any documents' % entry, line=lineno)) subnode = addnodes.toctree() + subnode['parent'] = env.docname subnode['entries'] = entries subnode['includefiles'] = includefiles subnode['maxdepth'] = options.get('maxdepth', -1) diff --git a/sphinx/environment.py b/sphinx/environment.py index 2a082120..d48dbad0 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -1013,6 +1013,19 @@ class BuildEnvironment: para = addnodes.compact_paragraph('', '', reference) item = nodes.list_item('', para) toc = nodes.bullet_list('', item) + elif ref == 'self': + # 'self' refers to the document from which this toctree originates. + ref = toctreenode['parent'] + if not title: + title = self.titles[ref].astext() + reference = nodes.reference('', '', + refuri=ref, + anchorname='', + *[nodes.Text(title)]) + para = addnodes.compact_paragraph('', '', reference) + item = nodes.list_item('', para) + # Don't show subitems. + toc = nodes.bullet_list('', item) else: toc = self.tocs[ref].deepcopy() if title and toc.children and len(toc.children) == 1: -- cgit v1.2.1 From 9cb11f9ae00b09e83105afb390ca1053c84ee84f Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 19:19:09 +0100 Subject: There is now a ``-W`` option for sphinx-build that turns warnings into errors. ^ --- CHANGES | 3 +++ doc/intro.rst | 4 ++++ sphinx/application.py | 11 ++++++++++- sphinx/cmdline.py | 9 ++++++--- 4 files changed, 23 insertions(+), 4 deletions(-) diff --git a/CHANGES b/CHANGES index ddecfdb0..1c0b11c5 100644 --- a/CHANGES +++ b/CHANGES @@ -131,6 +131,9 @@ New features added - Quickstart can now generate a Windows ``make.bat`` file. + - There is now a ``-W`` option for sphinx-build that turns warnings + into errors. + Release 0.5.2 (in development) ============================== diff --git a/doc/intro.rst b/doc/intro.rst index f9e23e18..782328be 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -133,6 +133,10 @@ The :program:`sphinx-build` script has several more options: Do not output anything on standard output, also suppress warnings. Only errors are written to standard error. +**-W** + Turn warnings into errors. This means that the build stops at the first + warning and ``sphinx-build`` exits with exit status 1. + **-P** (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an unhandled exception occurs while building. diff --git a/sphinx/application.py b/sphinx/application.py index 9bb276f1..70a0a823 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -28,6 +28,10 @@ class SphinxError(Exception): """ category = 'Sphinx error' +class SphinxWarning(SphinxError): + """Raised for warnings if warnings are treated as errors.""" + category = 'Warning, treated as error' + class ExtensionError(SphinxError): """Raised if something's wrong with the configuration.""" category = 'Extension error' @@ -78,7 +82,8 @@ CONFIG_FILENAME = 'conf.py' class Sphinx(object): def __init__(self, srcdir, confdir, outdir, doctreedir, buildername, - confoverrides, status, warning=sys.stderr, freshenv=False): + confoverrides, status, warning=sys.stderr, freshenv=False, + warningiserror=False): self.next_listener_id = 0 self._listeners = {} self.builderclasses = BUILTIN_BUILDERS.copy() @@ -95,11 +100,13 @@ class Sphinx(object): else: self._status = status self.quiet = False + if warning is None: self._warning = StringIO() else: self._warning = warning self._warncount = 0 + self.warningiserror = warningiserror self._events = events.copy() @@ -153,6 +160,8 @@ class Sphinx(object): self.builder.cleanup() def warn(self, message): + if self.warningiserror: + raise SphinxWarning('WARNING: %s\n' % message) self._warncount += 1 try: self._warning.write('WARNING: %s\n' % message) diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 4642b795..b4c3cc7b 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -44,6 +44,7 @@ new and changed files -N -- do not do colored output -q -- no output on stdout, just warnings on stderr -Q -- no output at all, not even warnings + -W -- turn warnings into errors -P -- run Pdb on exception Modi: * without -a and without filenames, write new and changed files. @@ -57,7 +58,7 @@ def main(argv): nocolor() try: - opts, args = getopt.getopt(argv[1:], 'ab:d:c:CD:A:NEqQP') + opts, args = getopt.getopt(argv[1:], 'ab:d:c:CD:A:NEqQWP') allopts = set(opt[0] for opt in opts) srcdir = confdir = path.abspath(args[0]) if not path.isdir(srcdir): @@ -86,7 +87,7 @@ def main(argv): return 1 buildername = all_files = None - freshenv = use_pdb = False + freshenv = warningiserror = use_pdb = False status = sys.stdout warning = sys.stderr confoverrides = {} @@ -143,13 +144,15 @@ def main(argv): elif opt == '-Q': status = None warning = None + elif opt == '-W': + warningiserror = True elif opt == '-P': use_pdb = True confoverrides['html_context'] = htmlcontext try: app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername, - confoverrides, status, warning, freshenv) + confoverrides, status, warning, freshenv, warningiserror) app.build(all_files, filenames) return app.statuscode except KeyboardInterrupt: -- cgit v1.2.1 From c422c06fc8706c27a76bcd4299e847d0411f84de Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 19:24:45 +0100 Subject: Document self-in-toctree. --- doc/concepts.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/doc/concepts.rst b/doc/concepts.rst index ff26989b..be18da9f 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -89,6 +89,10 @@ tables of contents. The ``toctree`` directive is the central element. documents in the ``recipe`` folder, then all remaining documents (except the one containing the directive, of course.) [#]_ + The special entry name ``self`` stands for the document containing the + toctree directive. This is useful if you want to generate a "sitemap" from + the toctree. + You can also give a "hidden" option to the directive, like this:: .. toctree:: @@ -99,7 +103,8 @@ tables of contents. The ``toctree`` directive is the central element. This will still notify Sphinx of the document hierarchy, but not insert links into the document at the location of the directive -- this makes sense if you - intend to insert these links yourself, in a different style. + intend to insert these links yourself, in a different style, or in the HTML + sidebar. In the end, all documents in the :term:`source directory` (or subdirectories) must occur in some ``toctree`` directive; Sphinx will emit a warning if it @@ -116,7 +121,7 @@ tables of contents. The ``toctree`` directive is the central element. Added "globbing" option. .. versionchanged:: 0.6 - Added "hidden" option and external links. + Added "hidden" option and external links, as well as support for "self". Special names -- cgit v1.2.1 From 40fdec8d86520332be78c933170f279c691c2fb4 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 19:33:46 +0100 Subject: Document changes to the app API. --- doc/ext/appapi.rst | 36 ++++++++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 218c561b..2a487845 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -60,13 +60,27 @@ the following public API: Added the support for keyword arguments giving visit functions. .. method:: Sphinx.add_directive(name, func, content, arguments, **options) + Sphinx.add_directive(name, directiveclass) Register a Docutils directive. *name* must be the prospective directive - name, *func* the directive function for details about the signature and - return value. *content*, *arguments* and *options* are set as attributes on - the function and determine whether the directive has content, arguments and - options, respectively. For their exact meaning, please consult the Docutils - documentation. + name. There are two possible ways to write a directive: + + * In the docutils 0.4 style, *func* is the directive function. *content*, + *arguments* and *options* are set as attributes on the function and + determine whether the directive has content, arguments and options, + respectively. For their exact meaning, please consult the Docutils + documentation. + + * In the docutils 0.5 style, *directiveclass* is the directive class. It + must already have attributes named *has_content*, *required_arguments*, + *optional_arguments*, *final_argument_whitespace* and *option_spec* that + correspond to the options for the function way. + + The directive class normally must inherit from the class + ``docutils.parsers.rst.Directive``. When writing a directive for usage in + a Sphinx extension, you inherit from ``sphinx.util.compat.Directive`` + instead which does the right thing even on docutils 0.4 (which doesn't + support directive classes otherwise). For example, the (already existing) :dir:`literalinclude` directive would be added like this:: @@ -78,7 +92,8 @@ the following public API: language = direcitves.unchanged, encoding = directives.encoding) - .. XXX once we target docutils 0.5, update this + .. versionchanged:: 0.6 + Docutils 0.5-style directive classes are now supported. .. method:: Sphinx.add_role(name, role) @@ -182,6 +197,15 @@ the following public API: .. versionadded:: 0.6 +.. method:: Sphinx.add_autodocumenter(cls) + + Add *cls* as a new documenter class for the :mod:`sphinx.ext.autodoc` + extension. It must be a subclass of :class:`sphinx.ext.autodoc.Documenter`. + This allows to auto-document new types of objects. See the source of the + autodoc module for examples on how to subclass :class:`Documenter`. + + .. versionadded:: 0.6 + .. method:: Sphinx.connect(event, callback) Register *callback* to be called when *event* is emitted. For details on -- cgit v1.2.1 From 2e84e88e25d02f8d95e1845a03a20c3f2ae5a45a Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 19:55:49 +0100 Subject: Unify all method types again. --- sphinx/ext/autodoc.py | 43 ++++++++++++++----------------------------- 1 file changed, 14 insertions(+), 29 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 1f8a933f..26cda61f 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -817,6 +817,20 @@ class MethodDocumenter(ClassLevelDocumenter): return inspect.isroutine(member) and \ not isinstance(parent, ModuleDocumenter) + def import_object(self): + ret = ClassLevelDocumenter.import_object(self) + if isinstance(self.object, classmethod) or \ + (isinstance(self.object, MethodType) and + self.object.im_self is not None): + self.directivetype = 'classmethod' + elif isinstance(self.object, FunctionType) or \ + (isinstance(self.object, BuiltinFunctionType) and + self.object.__self__ is not None): + self.directivetype = 'staticmethod' + else: + self.directivetype = 'method' + return ret + def format_args(self): if inspect.isbuiltin(self.object) or \ inspect.ismethoddescriptor(self.object): @@ -831,33 +845,6 @@ class MethodDocumenter(ClassLevelDocumenter): pass -class ClassmethodDocumenter(MethodDocumenter): - objtype = 'classmethod' - - priority = 10 - - @classmethod - def can_document_member(cls, member, membername, isattr, parent): - return inspect.isroutine(member) and \ - not isinstance(parent, ModuleDocumenter) and \ - (isinstance(member, classmethod) or - (isinstance(member, MethodType) and member.im_self is not None)) - - -class StaticmethodDocumenter(MethodDocumenter): - objtype = 'staticmethod' - - priority = 10 - - @classmethod - def can_document_member(cls, member, membername, isattr, parent): - return inspect.isroutine(member) and \ - not isinstance(parent, ModuleDocumenter) and \ - (isinstance(member, FunctionType) or - (isinstance(member, BuiltinFunctionType) and - member.__self__ is not None)) - - class AttributeDocumenter(ClassLevelDocumenter): objtype = 'attribute' @@ -940,8 +927,6 @@ def setup(app): app.add_autodocumenter(DataDocumenter) app.add_autodocumenter(FunctionDocumenter) app.add_autodocumenter(MethodDocumenter) - app.add_autodocumenter(ClassmethodDocumenter) - app.add_autodocumenter(StaticmethodDocumenter) app.add_autodocumenter(AttributeDocumenter) app.add_config_value('autoclass_content', 'class', True) -- cgit v1.2.1 From a35e6fdb7cb24dbf7314ecae90dcd471c15a0976 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 22:11:17 +0100 Subject: Add changelog entries. --- CHANGES | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 1c0b11c5..27fe0781 100644 --- a/CHANGES +++ b/CHANGES @@ -106,6 +106,10 @@ New features added * Extensions and API: + - Autodoc now has a reusable Python API, which can be used to + create custom types of objects to auto-document (e.g. Zope + interfaces). See also ``Sphinx.add_autodocumenter()``. + - Autodoc now handles documented attributes. - Autodoc now handles inner classes and their methods. @@ -113,11 +117,16 @@ New features added - Autodoc can document classes as functions now if explicitly marked with `autofunction`. + - The function ``Sphinx.add_directive()`` now also supports + docutils 0.5-style directive classes. If they inherit from + ``sphinx.util.compat.Directive``, they also work with + docutils 0.4. + - There is now a ``Sphinx.add_lexer()`` method to be able to use custom Pygments lexers easily. - - There is now ``Sphinx.add_generic_rol()`` to mirror the docutils' - own function. + - There is now ``Sphinx.add_generic_role()`` to mirror the + docutils' own function. * Other changes: -- cgit v1.2.1 From 25385439059c9e05da69d63dba0e5bab576dc3b4 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 23:08:26 +0100 Subject: Add examples for docnames. --- doc/concepts.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/doc/concepts.rst b/doc/concepts.rst index be18da9f..3212256d 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -16,6 +16,9 @@ directory`, the extension is stripped, and path separators are converted to slashes. All values, parameters and suchlike referring to "documents" expect such a document name. +Examples for document names are ``index``, ``library/zipfile``, or +``reference/datamodel/types``. Note that there is no leading slash. + The TOC tree ------------ -- cgit v1.2.1 From 261fdbc6a92f692215cd42ad04aeddaa4a2c7794 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Tue, 17 Feb 2009 23:55:05 +0100 Subject: Update the test_autodoc for the autodoc refactorings and fix a few remaining bugs. --- sphinx/ext/autodoc.py | 42 +++++--- sphinx/util/__init__.py | 3 + tests/test_autodoc.py | 276 ++++++++++++++++++++++++------------------------ tests/util.py | 2 + 4 files changed, 170 insertions(+), 153 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 26cda61f..585b0e25 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -271,10 +271,13 @@ class Documenter(object): self.modname, self.objpath = \ self.resolve_name(modname, parents, path, base) + if not self.modname: + return False + self.args = args self.retann = retann - self.fullname = self.modname + (self.objpath and - '.' + '.'.join(self.objpath) or '') + self.fullname = (self.modname or '') + (self.objpath and + '.' + '.'.join(self.objpath) or '') return True def import_object(self): @@ -305,17 +308,12 @@ class Documenter(object): return None def format_signature(self): - err = None if self.args is not None: # signature given explicitly args = "(%s)" % self.args else: # try to introspect the signature - try: - args = self.format_args() - except Exception, e: - args = None - err = e + args = self.format_args() if args is None: return '' retann = self.retann @@ -328,9 +326,6 @@ class Documenter(object): if args is not None: return args + (retann and (' -> %s' % retann) or '') - elif err: - # re-raise the error for perusal of the handler in generate() - raise RuntimeError(err) else: return '' @@ -568,6 +563,9 @@ class Documenter(object): class ModuleDocumenter(Documenter): + objtype = 'module' + content_indent = u'' + option_spec = { 'members': members_option, 'undoc-members': bool_option, 'noindex': bool_option, 'inherited-members': bool_option, @@ -605,13 +603,18 @@ class ModuleDocumenter(Documenter): if self.options.deprecated: self.add_line(u' :deprecated:', '<autodoc>') - def get_object_members(self, members=None): - if members is ALL or not hasattr(self.object, '__all__'): - # for implicit module members, check __module__ to avoid - # documenting imported objects - return True, inspect.getmembers(self.object) + def get_object_members(self, want_all): + if want_all: + if not hasattr(self.object, '__all__'): + # for implicit module members, check __module__ to avoid + # documenting imported objects + return True, inspect.getmembers(self.object) + else: + memberlist = self.object.__all__ + else: + memberlist = self.options.members ret = [] - for mname in (members or self.object.__all__): + for mname in memberlist: try: ret.append((mname, getattr(self.object, mname))) except AttributeError: @@ -784,6 +787,11 @@ class ClassDocumenter(ModuleLevelDocumenter): else: ModuleLevelDocumenter.add_content(self, more_content) + def document_members(self, all_members=False): + if self.doc_as_attr: + return + ModuleLevelDocumenter.document_members(self, all_members) + class ExceptionDocumenter(ClassDocumenter): objtype = 'exception' diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 944aa8d4..1978cfa4 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -41,6 +41,9 @@ def relative_uri(base, to): """Return a relative URL from ``base`` to ``to``.""" b2 = base.split(SEP) t2 = to.split(SEP) + if len(t2) > 1 and t2[0] == '': + # "to" is absolute, return it + return to # remove common segments for x, y in zip(b2, t2): if x != y: diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index d59ff304..98fe4c19 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -3,7 +3,7 @@ test_autodoc ~~~~~~~~~~~~ - Test the autodoc extension. This tests mainly the RstGenerator; the auto + Test the autodoc extension. This tests mainly the Documenters; the auto directives are tested in a test source file translated by test_build. :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. @@ -14,11 +14,13 @@ from util import * from docutils.statemachine import ViewList -from sphinx.ext.autodoc import RstGenerator, cut_lines, between +from sphinx.ext.autodoc import AutoDirective, Documenter, ModuleDocumenter, \ + ClassDocumenter, FunctionDocumenter, DataDocumenter, MethodDocumenter, \ + AttributeDocumenter, cut_lines, between, ALL def setup_module(): - global app, lid, options, gen + global app, lid, options, directive app = TestApp() app.builder.env.app = app @@ -34,27 +36,25 @@ def setup_module(): synopsis = '', platform = '', deprecated = False, + members = [], ) - gen = TestGenerator(options, app) + directive = Struct( + env = app.builder.env, + genopt = options, + result = ViewList(), + warn = warnfunc, + filename_set = set(), + ) def teardown_module(): app.cleanup() -class TestGenerator(RstGenerator): - """Generator that handles warnings without a reporter.""" - - def __init__(self, options, app): - self.options = options - self.env = app.builder.env - self.lineno = 42 - self.filename_set = set() - self.warnings = [] - self.result = ViewList() +_warnings = [] - def warn(self, msg): - self.warnings.append(msg) +def warnfunc(msg): + _warnings.append(msg) processed_docstrings = [] @@ -79,63 +79,66 @@ def skip_member(app, what, name, obj, skip, options): return True -def test_resolve_name(): - # for modules - assert gen.resolve_name('module', 'test_autodoc') == \ - ('test_autodoc', [], None, None) - assert gen.resolve_name('module', 'test.test_autodoc') == \ - ('test.test_autodoc', [], None, None) +def test_parse_name(): + def verify(objtype, name, result): + inst = AutoDirective._registry[objtype](directive, name) + assert inst.parse_name() + assert (inst.modname, inst.objpath, inst.args, inst.retann) == result - assert gen.resolve_name('module', 'test(arg)') == \ - ('test', [], None, None) - assert 'ignoring signature arguments' in gen.warnings[0] - del gen.warnings[:] + # for modules + verify('module', 'test_autodoc', ('test_autodoc', [], None, None)) + verify('module', 'test.test_autodoc', ('test.test_autodoc', [], None, None)) + verify('module', 'test(arg)', ('test', [], 'arg', None)) + assert 'signature arguments' in _warnings[0] + del _warnings[:] # for functions/classes - assert gen.resolve_name('function', 'util.raises') == \ - ('util', ['raises'], None, None) - assert gen.resolve_name('function', 'util.raises(exc) -> None') == \ - ('util', ['raises'], 'exc', 'None') - gen.env.autodoc_current_module = 'util' - assert gen.resolve_name('function', 'raises') == \ - ('util', ['raises'], None, None) - gen.env.autodoc_current_module = None - gen.env.currmodule = 'util' - assert gen.resolve_name('function', 'raises') == \ - ('util', ['raises'], None, None) - assert gen.resolve_name('class', 'TestApp') == \ - ('util', ['TestApp'], None, None) + verify('function', 'util.raises', ('util', ['raises'], None, None)) + verify('function', 'util.raises(exc) -> None', + ('util', ['raises'], 'exc', 'None')) + directive.env.autodoc_current_module = 'util' + verify('function', 'raises', ('util', ['raises'], None, None)) + directive.env.autodoc_current_module = None + directive.env.currmodule = 'util' + verify('function', 'raises', ('util', ['raises'], None, None)) + verify('class', 'TestApp', ('util', ['TestApp'], None, None)) # for members - gen.env.currmodule = 'foo' - assert gen.resolve_name('method', 'util.TestApp.cleanup') == \ - ('util', ['TestApp', 'cleanup'], None, None) - gen.env.currmodule = 'util' - gen.env.currclass = 'Foo' - gen.env.autodoc_current_class = 'TestApp' - assert gen.resolve_name('method', 'cleanup') == \ - ('util', ['TestApp', 'cleanup'], None, None) - assert gen.resolve_name('method', 'TestApp.cleanup') == \ - ('util', ['TestApp', 'cleanup'], None, None) + directive.env.currmodule = 'foo' + verify('method', 'util.TestApp.cleanup', + ('util', ['TestApp', 'cleanup'], None, None)) + directive.env.currmodule = 'util' + directive.env.currclass = 'Foo' + directive.env.autodoc_current_class = 'TestApp' + verify('method', 'cleanup', ('util', ['TestApp', 'cleanup'], None, None)) + verify('method', 'TestApp.cleanup', + ('util', ['TestApp', 'cleanup'], None, None)) # and clean up - gen.env.currmodule = None - gen.env.currclass = None - gen.env.autodoc_current_class = None + directive.env.currmodule = None + directive.env.currclass = None + directive.env.autodoc_current_class = None def test_format_signature(): + def formatsig(objtype, name, obj, args, retann): + inst = AutoDirective._registry[objtype](directive, name) + inst.fullname = name + inst.doc_as_attr = False # for class objtype + inst.object = obj + inst.args = args + inst.retann = retann + return inst.format_signature() + # no signatures for modules - assert gen.format_signature('module', 'test', None, None, None) == '' + assert formatsig('module', 'test', None, None, None) == '' # test for functions def f(a, b, c=1, **d): pass - assert gen.format_signature('function', 'f', f, None, None) == \ - '(a, b, c=1, **d)' - assert gen.format_signature('function', 'f', f, 'a, b, c, d', None) == \ - '(a, b, c, d)' - assert gen.format_signature('function', 'f', f, None, 'None') == \ + assert formatsig('function', 'f', f, None, None) == '(a, b, c=1, **d)' + assert formatsig('function', 'f', f, 'a, b, c, d', None) == '(a, b, c, d)' + assert formatsig('function', 'f', f, None, 'None') == \ '(a, b, c=1, **d) -> None' # test for classes @@ -145,16 +148,15 @@ def test_format_signature(): pass # no signature for classes without __init__ for C in (D, E): - assert gen.format_signature('class', 'D', C, None, None) == '' + assert formatsig('class', 'D', C, None, None) == '' class F: def __init__(self, a, b=None): pass class G(F, object): pass for C in (F, G): - assert gen.format_signature('class', 'C', C, None, None) == \ - '(a, b=None)' - assert gen.format_signature('class', 'C', D, 'a, b', 'X') == '(a, b) -> X' + assert formatsig('class', 'C', C, None, None) == '(a, b=None)' + assert formatsig('class', 'C', D, 'a, b', 'X') == '(a, b) -> X' # test for methods class H: @@ -162,24 +164,22 @@ def test_format_signature(): pass def foo2(b, *c): pass - assert gen.format_signature('method', 'H.foo', H.foo1, None, None) == \ - '(b, *c)' - assert gen.format_signature('method', 'H.foo', H.foo1, 'a', None) == \ - '(a)' - assert gen.format_signature('method', 'H.foo', H.foo2, None, None) == \ - '(b, *c)' + assert formatsig('method', 'H.foo', H.foo1, None, None) == '(b, *c)' + assert formatsig('method', 'H.foo', H.foo1, 'a', None) == '(a)' + assert formatsig('method', 'H.foo', H.foo2, None, None) == '(b, *c)' # test exception handling - raises(RuntimeError, gen.format_signature, - 'function', 'int', int, None, None) + raises(TypeError, formatsig, 'function', 'int', int, None, None) # test processing by event handler - assert gen.format_signature('method', 'bar', H.foo1, None, None) == '42' + assert formatsig('method', 'bar', H.foo1, None, None) == '42' def test_get_doc(): - def getdocl(*args): - ds = gen.get_doc(*args) + def getdocl(objtype, obj, encoding=None): + inst = AutoDirective._registry[objtype](directive, 'tmp') + inst.object = obj + ds = inst.get_doc(encoding) # for testing purposes, concat them and strip the empty line at the end return sum(ds, [])[:-1] @@ -222,11 +222,11 @@ def test_get_doc(): """Class docstring""" def __init__(self): """Init docstring""" - gen.env.config.autoclass_content = 'class' + directive.env.config.autoclass_content = 'class' assert getdocl('class', C) == ['Class docstring'] - gen.env.config.autoclass_content = 'init' + directive.env.config.autoclass_content = 'init' assert getdocl('class', C) == ['Init docstring'] - gen.env.config.autoclass_content = 'both' + directive.env.config.autoclass_content = 'both' assert getdocl('class', C) == ['Class docstring', '', 'Init docstring'] class D: @@ -244,8 +244,11 @@ def test_get_doc(): def test_docstring_processing(): - def process(what, name, obj): - return list(gen.process_doc(gen.get_doc(what, obj), what, name, obj)) + def process(objtype, name, obj): + inst = AutoDirective._registry[objtype](directive, name) + inst.object = obj + inst.fullname = name + return list(inst.process_doc(inst.get_doc())) class E: def __init__(self): @@ -279,122 +282,123 @@ def test_docstring_processing(): def test_generate(): - def assert_warns(warn_str, *args): - gen.generate(*args) - assert len(gen.result) == 0, gen.result - assert len(gen.warnings) == 1, gen.warnings - assert warn_str in gen.warnings[0], gen.warnings - del gen.warnings[:] - - def assert_works(*args): - gen.generate(*args) - assert gen.result - assert len(gen.warnings) == 0, gen.warnings - del gen.result[:] - - def assert_processes(items, *args): + def assert_warns(warn_str, objtype, name, **kw): + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + assert len(directive.result) == 0, directive.result + assert len(_warnings) == 1, _warnings + assert warn_str in _warnings[0], _warnings + del _warnings[:] + + def assert_works(objtype, name, **kw): + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + assert directive.result + assert len(_warnings) == 0, _warnings + del directive.result[:] + + def assert_processes(items, objtype, name, **kw): del processed_docstrings[:] del processed_signatures[:] - assert_works(*args) + assert_works(objtype, name, **kw) assert set(processed_docstrings) | set(processed_signatures) == \ set(items) - def assert_result_contains(item, *args): - gen.generate(*args) - #print '\n'.join(gen.result) - assert len(gen.warnings) == 0, gen.warnings - assert item in gen.result - del gen.result[:] + def assert_result_contains(item, objtype, name, **kw): + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + #print '\n'.join(directive.result) + assert len(_warnings) == 0, _warnings + assert item in directive.result + del directive.result[:] # no module found? assert_warns("import for autodocumenting 'foobar'", - 'function', 'foobar', None, None) + 'function', 'foobar', more_content=None) # importing assert_warns("import/find module 'test_foobar'", - 'module', 'test_foobar', None, None) + 'module', 'test_foobar', more_content=None) # attributes missing assert_warns("import/find function 'util.foobar'", - 'function', 'util.foobar', None, None) + 'function', 'util.foobar', more_content=None) # test auto and given content mixing - gen.env.currmodule = 'test_autodoc' - assert_result_contains(' Function.', 'method', 'Class.meth', [], None) + directive.env.currmodule = 'test_autodoc' + assert_result_contains(' Function.', 'method', 'Class.meth') add_content = ViewList() add_content.append('Content.', '', 0) assert_result_contains(' Function.', 'method', - 'Class.meth', [], add_content) + 'Class.meth', more_content=add_content) assert_result_contains(' Content.', 'method', - 'Class.meth', [], add_content) + 'Class.meth', more_content=add_content) # test check_module - gen.generate('function', 'raises', None, None, check_module=True) - assert len(gen.result) == 0 + inst = FunctionDocumenter(directive, 'raises') + inst.generate(check_module=True) + assert len(directive.result) == 0 # assert that exceptions can be documented - assert_works('exception', 'test_autodoc.CustomEx', ['__all__'], None) - assert_works('exception', 'test_autodoc.CustomEx', [], None) + assert_works('exception', 'test_autodoc.CustomEx', all_members=True) + assert_works('exception', 'test_autodoc.CustomEx') # test diverse inclusion settings for members should = [('class', 'test_autodoc.Class')] - assert_processes(should, 'class', 'Class', [], None) + assert_processes(should, 'class', 'Class') should.extend([('method', 'test_autodoc.Class.meth')]) - assert_processes(should, 'class', 'Class', ['meth'], None) + options.members = ['meth'] + assert_processes(should, 'class', 'Class') should.extend([('attribute', 'test_autodoc.Class.prop'), ('attribute', 'test_autodoc.Class.attr'), ('attribute', 'test_autodoc.Class.docattr'), ('attribute', 'test_autodoc.Class.udocattr')]) - assert_processes(should, 'class', 'Class', ['__all__'], None) + options.members = ALL + assert_processes(should, 'class', 'Class') options.undoc_members = True should.append(('method', 'test_autodoc.Class.undocmeth')) - assert_processes(should, 'class', 'Class', ['__all__'], None) + assert_processes(should, 'class', 'Class') options.inherited_members = True should.append(('method', 'test_autodoc.Class.inheritedmeth')) - assert_processes(should, 'class', 'Class', ['__all__'], None) + assert_processes(should, 'class', 'Class') + options.members = [] # test module flags - assert_result_contains('.. module:: test_autodoc', - 'module', 'test_autodoc', [], None) + assert_result_contains('.. module:: test_autodoc', 'module', 'test_autodoc') options.synopsis = 'Synopsis' - assert_result_contains(' :synopsis: Synopsis', - 'module', 'test_autodoc', [], None) + assert_result_contains(' :synopsis: Synopsis', 'module', 'test_autodoc') options.deprecated = True - assert_result_contains(' :deprecated:', - 'module', 'test_autodoc', [], None) + assert_result_contains(' :deprecated:', 'module', 'test_autodoc') options.platform = 'Platform' - assert_result_contains(' :platform: Platform', - 'module', 'test_autodoc', [], None) + assert_result_contains(' :platform: Platform', 'module', 'test_autodoc') # test if __all__ is respected for modules - assert_result_contains('.. class:: Class', - 'module', 'test_autodoc', ['__all__'], None) + options.members = ALL + assert_result_contains('.. class:: Class', 'module', 'test_autodoc') try: - assert_result_contains('.. exception:: CustomEx', - 'module', 'test_autodoc', ['__all__'], None) + assert_result_contains('.. exception:: CustomEx', 'module', 'test_autodoc') except AssertionError: pass else: assert False, 'documented CustomEx which is not in __all__' # test noindex flag + options.members = [] options.noindex = True - assert_result_contains(' :noindex:', 'module', 'test_autodoc', [], None) - assert_result_contains(' :noindex:', 'class', 'Base', [], None) + assert_result_contains(' :noindex:', 'module', 'test_autodoc') + assert_result_contains(' :noindex:', 'class', 'Base') # okay, now let's get serious about mixing Python and C signature stuff assert_result_contains('.. class:: CustomDict', 'class', 'CustomDict', - ['__all__'], None) + all_members=True) # test inner class handling assert_processes([('class', 'test_autodoc.Outer'), ('class', 'test_autodoc.Outer.Inner'), ('method', 'test_autodoc.Outer.Inner.meth')], - 'class', 'Outer', ['__all__'], None) + 'class', 'Outer', all_members=True) # test generation for C modules (which have no source file) - gen.env.currmodule = 'time' - assert_processes([('function', 'time.asctime')], - 'function', 'asctime', [], None) - assert_processes([('function', 'time.asctime')], - 'function', 'asctime', [], None) + directive.env.currmodule = 'time' + assert_processes([('function', 'time.asctime')], 'function', 'asctime') + assert_processes([('function', 'time.asctime')], 'function', 'asctime') # --- generate fodder ------------ diff --git a/tests/util.py b/tests/util.py index dcaf74ad..5d0b4a98 100644 --- a/tests/util.py +++ b/tests/util.py @@ -20,6 +20,7 @@ except ImportError: wraps = lambda f: (lambda w: w) from sphinx import application +from sphinx.ext.autodoc import AutoDirective from path import path @@ -141,6 +142,7 @@ class TestApp(application.Sphinx): freshenv) def cleanup(self, doctrees=False): + AutoDirective._registry.clear() for tree in self.cleanup_trees: shutil.rmtree(tree, True) -- cgit v1.2.1 From b6f5ffe058cabcf40270f6fae56724b9c4ed3a0e Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 18 Feb 2009 00:06:24 +0100 Subject: Add a test for a new documenter. --- sphinx/ext/autodoc.py | 2 +- tests/test_autodoc.py | 37 +++++++++++++++++++++++++++++++++---- 2 files changed, 34 insertions(+), 5 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 585b0e25..82e16e04 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -404,7 +404,7 @@ class Documenter(object): try: ret.append((mname, self.get_attr(self.object, mname))) except AttributeError: - self.directive.warn('missing attribute %s in object %s: ' + self.directive.warn('missing attribute %s in object %s' % (mname, self.fullname)) return False, ret elif self.options.inherited_members: diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 98fe4c19..d1da4439 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -14,9 +14,8 @@ from util import * from docutils.statemachine import ViewList -from sphinx.ext.autodoc import AutoDirective, Documenter, ModuleDocumenter, \ - ClassDocumenter, FunctionDocumenter, DataDocumenter, MethodDocumenter, \ - AttributeDocumenter, cut_lines, between, ALL +from sphinx.ext.autodoc import AutoDirective, Documenter, add_documenter, \ + ModuleLevelDocumenter, FunctionDocumenter, cut_lines, between, ALL def setup_module(): @@ -281,6 +280,33 @@ def test_docstring_processing(): app.disconnect(lid) +def test_new_documenter(): + class MyDocumenter(ModuleLevelDocumenter): + objtype = 'integer' + directivetype = 'data' + priority = 100 + + @classmethod + def can_document_member(cls, member, membername, isattr, parent): + return isinstance(member, int) + + def document_members(self, all_members=False): + return + + add_documenter(MyDocumenter) + + def assert_result_contains(item, objtype, name, **kw): + inst = AutoDirective._registry[objtype](directive, name) + inst.generate(**kw) + #print '\n'.join(directive.result) + assert len(_warnings) == 0, _warnings + assert item in directive.result + del directive.result[:] + + options.members = ['integer'] + assert_result_contains('.. data:: integer', 'module', 'test_autodoc') + + def test_generate(): def assert_warns(warn_str, objtype, name, **kw): inst = AutoDirective._registry[objtype](directive, name) @@ -312,6 +338,8 @@ def test_generate(): assert item in directive.result del directive.result[:] + options.members = [] + # no module found? assert_warns("import for autodocumenting 'foobar'", 'function', 'foobar', more_content=None) @@ -405,13 +433,14 @@ def test_generate(): __all__ = ['Class'] +integer = 1 + class CustomEx(Exception): """My custom exception.""" def f(self): """Exception method.""" - class Base(object): def inheritedmeth(self): """Inherited function.""" -- cgit v1.2.1 From 02c933497d858c20c6d138106bc76d996b17f4de Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 18 Feb 2009 00:10:32 +0100 Subject: Add more FAQ entries. --- doc/faq.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/faq.rst b/doc/faq.rst index d447602f..7e5cffd5 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -9,9 +9,15 @@ suggest new entries! How do I... ----------- +... customize the look of the built HTML files? + Use themes, see :doc:`theming`. + ... add global substitutions? Add them in the :confval:`rst_epilog` config value. +... write my own extension? + See the :ref:`extension tutorial <exttut>`. + ... use Sphinx with Epydoc? There's a third-party extension providing an `api role`_ which refers to Epydoc's API docs for a given identifier. -- cgit v1.2.1 From a3fe21ae2e9cf6554a4f3810e46c0eb5af76780e Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 18 Feb 2009 00:13:12 +0100 Subject: Add link to docutils directive docs. --- doc/ext/appapi.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index 2a487845..aad41e35 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -68,13 +68,14 @@ the following public API: * In the docutils 0.4 style, *func* is the directive function. *content*, *arguments* and *options* are set as attributes on the function and determine whether the directive has content, arguments and options, - respectively. For their exact meaning, please consult the Docutils - documentation. + respectively. * In the docutils 0.5 style, *directiveclass* is the directive class. It must already have attributes named *has_content*, *required_arguments*, *optional_arguments*, *final_argument_whitespace* and *option_spec* that - correspond to the options for the function way. + correspond to the options for the function way. See `the Docutils docs + <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ for + details. The directive class normally must inherit from the class ``docutils.parsers.rst.Directive``. When writing a directive for usage in -- cgit v1.2.1 From 255b2a1a54bdcf8c93b0badc8908ca4879934460 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 18 Feb 2009 00:17:28 +0100 Subject: Add node structure picture. --- doc/ext/tutorial.rst | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst index 85763e83..7d93817c 100644 --- a/doc/ext/tutorial.rst +++ b/doc/ext/tutorial.rst @@ -236,6 +236,22 @@ node. In the last line, the nodes that should be put into the doctree are returned: the target node and the admonition node. +The node structure that the directive returns looks like this:: + + +--------------------+ + | target node | + +--------------------+ + +--------------------+ + | todo node | + +--------------------+ + \__+--------------------+ + | admonition title | + +--------------------+ + | paragraph | + +--------------------+ + | ... | + +--------------------+ + The Event Handlers ------------------ -- cgit v1.2.1 From c5b3b76c873c751196eee26c92e2b7ac0087558e Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 18 Feb 2009 00:21:11 +0100 Subject: Dont prefer SVG before PNG until SVG is supported and its handling in Sphinx sorted out. --- sphinx/builders/html.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 1bbf359f..b03a6412 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -55,8 +55,8 @@ class StandaloneHTMLBuilder(Builder): out_suffix = '.html' link_suffix = '.html' # defaults to matching out_suffix indexer_format = js_index - supported_image_types = ['image/svg+xml', 'image/png', 'image/gif', - 'image/jpeg'] + supported_image_types = ['image/png', 'image/gif', 'image/jpeg', + 'image/svg+xml'] searchindex_filename = 'searchindex.js' add_permalinks = True embedded = False # for things like HTML help or Qt help: suppresses sidebar -- cgit v1.2.1 From a8f08275212c0ad38af49a9f4cc6e4fea19cb0a2 Mon Sep 17 00:00:00 2001 From: Sebastian Wiesner <basti.wiesner@gmx.net> Date: Tue, 25 Nov 2008 21:29:19 +0100 Subject: Scaled images are now linked to their high resulution version. --- sphinx/builders/html.py | 27 ++++++++++++++++++++++++++- sphinx/themes/basic/static/basic.css | 2 +- 2 files changed, 27 insertions(+), 2 deletions(-) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index b03a6412..15f84151 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -12,9 +12,11 @@ import os import codecs import shutil +import posixpath import cPickle as pickle from os import path +from docutils import nodes from docutils.io import DocTreeInput, StringOutput from docutils.core import publish_parts from docutils.utils import new_document @@ -253,11 +255,11 @@ class StandaloneHTMLBuilder(Builder): ) def write_doc(self, docname, doctree): - self.post_process_images(doctree) destination = StringOutput(encoding='utf-8') doctree.settings = self.docsettings self.imgpath = relative_uri(self.get_target_uri(docname), '_images') + self.post_process_images(doctree) self.dlpath = relative_uri(self.get_target_uri(docname), '_downloads') self.docwriter.write(doctree, destination) self.docwriter.assemble_parts() @@ -486,6 +488,29 @@ class StandaloneHTMLBuilder(Builder): # clean up theme stuff self.theme.cleanup() + def post_process_images(self, doctree): + """ + Pick the best candiate for an image and link down-scaled images to + their high res version. + """ + Builder.post_process_images(self, doctree) + for node in doctree.traverse(nodes.image): + if not node.has_key('scale') or \ + isinstance(node.parent, nodes.reference): + # docutils does unfortunately not preserve the + # ``target`` attribute on images, so we need to check + # the parent node here. + continue + uri = node['uri'] + reference = nodes.reference() + if uri in self.images: + reference['refuri'] = posixpath.join(self.imgpath, + self.images[uri]) + else: + reference['refuri'] = uri + node.replace_self(reference) + reference.append(node) + def get_outdated_docs(self): if self.templates: template_mtime = self.templates.newest_template_mtime() diff --git a/sphinx/themes/basic/static/basic.css b/sphinx/themes/basic/static/basic.css index 5a27fc16..ed737d3b 100644 --- a/sphinx/themes/basic/static/basic.css +++ b/sphinx/themes/basic/static/basic.css @@ -82,7 +82,7 @@ div.sphinxsidebar input { font-size: 1em; } -img.logo { +img { border: 0; } -- cgit v1.2.1 From 279d9bc7b6d20dd47e1d775b5cc2a187715df625 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 18 Feb 2009 00:33:42 +0100 Subject: Remove apparent debugging leftover. --- sphinx/writers/html.py | 1 - 1 file changed, 1 deletion(-) diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 17a22b7a..44a7c879 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -291,7 +291,6 @@ class HTMLTranslator(BaseTranslator): olduri)) except (IOError, # Source image can't be found or opened UnicodeError): # PIL doesn't like Unicode paths. - print olduri pass else: if not node.has_key('width'): -- cgit v1.2.1 From 1d6c00ff74ea59c674918d47940c8ec3602f2fe8 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 18 Feb 2009 00:35:33 +0100 Subject: Add changelog entry for r1123. --- CHANGES | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CHANGES b/CHANGES index 27fe0781..b9184841 100644 --- a/CHANGES +++ b/CHANGES @@ -59,10 +59,12 @@ New features added - #23: Added a ``classmethod`` directive along with ``method`` and ``staticmethod``. + - Scaled images now get a link to the unscaled version. + - Added a ``toctree`` callable to the templates, and the ability - to include external links in toctrees. The 'collapse' keyword argument - indicates whether or not to only display subitems of the current page. - (Defaults to True.) + to include external links in toctrees. The 'collapse' keyword + argument indicates whether or not to only display subitems of + the current page. (Defaults to True.) * Configuration: -- cgit v1.2.1 From 27e20dc5f5ea2f53ead870283aa39ce6bb525b11 Mon Sep 17 00:00:00 2001 From: Georg Brandl <georg@python.org> Date: Wed, 18 Feb 2009 00:52:12 +0100 Subject: SVG images are now supported in HTML (via ``<object>`` and ``<embed>`` tags). --- CHANGES | 3 + sphinx/writers/html.py | 20 +++++++ tests/root/images.txt | 3 + tests/root/svgimg.pdf | Bin 0 -> 141783 bytes tests/root/svgimg.svg | 158 +++++++++++++++++++++++++++++++++++++++++++++++++ tests/test_build.py | 2 + tests/test_env.py | 18 +++--- 7 files changed, 195 insertions(+), 9 deletions(-) create mode 100644 tests/root/svgimg.pdf create mode 100644 tests/root/svgimg.svg diff --git a/CHANGES b/CHANGES index b9184841..510738b4 100644 --- a/CHANGES +++ b/CHANGES @@ -61,6 +61,9 @@ New features added - Scaled images now get a link to the unscaled version. + - SVG images are now supported in HTML (via ``<object>`` and + ``<embed>`` tags). + - Added a ``toctree`` callable to the templates, and the ability to include external links in toctrees. The 'collapse' keyword argument indicates whether or not to only display subitems of diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 44a7c879..0859bae6 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -283,6 +283,26 @@ class HTMLTranslator(BaseTranslator): node['uri'] = posixpath.join(self.builder.imgpath, self.builder.images[olduri]) + if node['uri'].lower().endswith('svg') or \ + node['uri'].lower().endswith('svgz'): + atts = {'data': node['uri'], 'type': 'image/svg+xml'} + if 'width' in node: + atts['width'] = node['width'] + if 'height' in node: + atts['height'] = node['height'] + if 'align' in node: + self.body.append('<div align="%s" class="align-%s">' % + (node['align'], node['align'])) + self.context.append('</div>\n') + else: + self.context.append('') + embatts = atts.copy() + embatts['src'] = embatts.pop('data') + self.body.append(self.starttag(node, 'object', '', **atts)) + self.body.append(self.emptytag(node, 'embed', '', **embatts)) + self.body.append('</object>\n') + return + if node.has_key('scale'): if Image and not (node.has_key('width') and node.has_key('height')): diff --git a/tests/root/images.txt b/tests/root/images.txt index be868dfe..bd64d573 100644 --- a/tests/root/images.txt +++ b/tests/root/images.txt @@ -23,3 +23,6 @@ Sphinx image handling .. an image with subdir and unspecified extension .. image:: subdir/simg.* + +.. an SVG image (for HTML at least) +.. image:: svgimg.* diff --git a/tests/root/svgimg.pdf b/tests/root/svgimg.pdf new file mode 100644 index 00000000..cacbd855 Binary files /dev/null and b/tests/root/svgimg.pdf differ diff --git a/tests/root/svgimg.svg b/tests/root/svgimg.svg new file mode 100644 index 00000000..10e035b6 --- /dev/null +++ b/tests/root/svgimg.svg @@ -0,0 +1,158 @@ +<?xml version="1.0" encoding="UTF-8" standalone="no"?> +<svg + xmlns:dc="http://purl.org/dc/elements/1.1/" + xmlns:cc="http://web.resource.org/cc/" + xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" + xmlns:svg="http://www.w3.org/2000/svg" + xmlns="http://www.w3.org/2000/svg" + xmlns:xlink="http://www.w3.org/1999/xlink" + xmlns:sodipodi="http://inkscape.sourceforge.net/DTD/sodipodi-0.dtd" + xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape" + height="60" + width="60" + _SVGFile__filename="oldscale/apps/warning.svg" + version="1.0" + y="0" + x="0" + id="svg1" + sodipodi:version="0.32" + inkscape:version="0.41" + sodipodi:docname="exclamation.svg" + sodipodi:docbase="/home/danny/work/icons/primary/scalable/actions"> + <sodipodi:namedview + id="base" + pagecolor="#ffffff" + bordercolor="#666666" + borderopacity="1.0" + inkscape:pageopacity="0.0000000" + inkscape:pageshadow="2" + inkscape:zoom="7.5136000" + inkscape:cx="42.825186" + inkscape:cy="24.316071" + inkscape:window-width="1020" + inkscape:window-height="691" + inkscape:window-x="0" + inkscape:window-y="0" + inkscape:current-layer="svg1" /> + <defs + id="defs3"> + <linearGradient + id="linearGradient1160"> + <stop + style="stop-color: #000000;stop-opacity: 1.0;" + id="stop1161" + offset="0" /> + <stop + style="stop-color:#ffffff;stop-opacity:1;" + id="stop1162" + offset="1" /> + </linearGradient> + <linearGradient + xlink:href="#linearGradient1160" + id="linearGradient1163" /> + </defs> + <metadata + id="metadata12"> + <RDF + id="RDF13"> + <Work + about="" + id="Work14"> + <title + id="title15">Part of the Flat Icon Collection (Thu Aug 26 14:31:40 2004) + + + +
    • + + + + + + </Agent> + </publisher> + <creator + id="creator24"> + <Agent + about="" + id="Agent25"> + <title + id="title26">Danny Allen + + + + + Danny Allen + + + + image/svg+xml + + + + + en + + + + + image/svg+xml + + + + + + + + + + + + + diff --git a/tests/test_build.py b/tests/test_build.py index a8934b82..326a4bd6 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -59,6 +59,8 @@ HTML_XPATH = { ".//img[@src='_images/img.png']": '', ".//img[@src='_images/img1.png']": '', ".//img[@src='_images/simg.png']": '', + ".//object[@data='_images/svgimg.svg']": '', + ".//embed[@src='_images/svgimg.svg']": '', }, 'subdir/images.html': { ".//img[@src='../_images/img1.png']": '', diff --git a/tests/test_env.py b/tests/test_env.py index 32d87ebf..5d27bcfd 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -56,21 +56,21 @@ def test_images(): htmlbuilder.post_process_images(tree) assert "no matching candidate for image URI u'foo.*'" in \ app._warning.content[-1] - assert set(htmlbuilder.images.keys()) == set(['subdir/img.png', 'img.png', - 'subdir/simg.png']) - assert set(htmlbuilder.images.values()) == set(['img.png', 'img1.png', - 'simg.png']) + assert set(htmlbuilder.images.keys()) == \ + set(['subdir/img.png', 'img.png', 'subdir/simg.png', 'svgimg.svg']) + assert set(htmlbuilder.images.values()) == \ + set(['img.png', 'img1.png', 'simg.png', 'svgimg.svg']) app._warning.reset() latexbuilder = LaTeXBuilder(app, env) latexbuilder.post_process_images(tree) assert "no matching candidate for image URI u'foo.*'" in \ app._warning.content[-1] - assert set(latexbuilder.images.keys()) == set(['subdir/img.png', - 'subdir/simg.png', - 'img.png', 'img.pdf']) - assert set(latexbuilder.images.values()) == set(['img.pdf', 'img.png', - 'img1.png', 'simg.png']) + assert set(latexbuilder.images.keys()) == \ + set(['subdir/img.png', 'subdir/simg.png', 'img.png', 'img.pdf', + 'svgimg.pdf']) + assert set(latexbuilder.images.values()) == \ + set(['img.pdf', 'img.png', 'img1.png', 'simg.png', 'svgimg.pdf']) def test_second_update(): # delete, add and "edit" (change saved mtime) some files and update again -- cgit v1.2.1 From 073f2305fcc73ef80223b85fbdb61562b6afd3e5 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 18 Feb 2009 01:13:57 +0100 Subject: Fix the fix for #82. --- sphinx/environment.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sphinx/environment.py b/sphinx/environment.py index 10ceeaed..f197c8cd 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -630,6 +630,7 @@ class BuildEnvironment: Process docutils-generated dependency info. """ cwd = os.getcwd() + frompath = path.join(path.normpath(self.srcdir), 'dummy') deps = doctree.settings.record_dependencies if not deps: return @@ -637,8 +638,8 @@ class BuildEnvironment: for dep in deps.list: # the dependency path is relative to the working dir, so get # one relative to the srcdir - fullpath = path.normpath(path.join(cwd, dep)) - relpath = fullpath[len(path.normpath(self.srcdir))+len(path.sep):] + relpath = relative_path(frompath, + path.normpath(path.join(cwd, dep))) self.dependencies.setdefault(docname, set()).add(relpath) def process_downloads(self, docname, doctree): -- cgit v1.2.1 From 5695acce0110614153e4072e948ab1b5016a25ee Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 18 Feb 2009 16:11:05 +0100 Subject: Make SVG preferred again. --- sphinx/builders/html.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 15f84151..61c0c0b1 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -57,8 +57,8 @@ class StandaloneHTMLBuilder(Builder): out_suffix = '.html' link_suffix = '.html' # defaults to matching out_suffix indexer_format = js_index - supported_image_types = ['image/png', 'image/gif', 'image/jpeg', - 'image/svg+xml'] + supported_image_types = ['image/svg+xml', + 'image/png', 'image/gif', 'image/jpeg'] searchindex_filename = 'searchindex.js' add_permalinks = True embedded = False # for things like HTML help or Qt help: suppresses sidebar -- cgit v1.2.1 From 3301774150e4ea52be327c892718185e54c439e8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 18 Feb 2009 19:55:57 +0100 Subject: Convert builtin directives to classes. Refactor desc_directive so that it is easier to subclass. --- sphinx/application.py | 7 +- sphinx/directives/code.py | 284 ++++++----- sphinx/directives/desc.py | 1144 +++++++++++++++++++++++--------------------- sphinx/directives/other.py | 882 +++++++++++++++++++--------------- 4 files changed, 1253 insertions(+), 1064 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 70a0a823..f221e1c7 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -57,8 +57,7 @@ import sphinx from sphinx.roles import xfileref_role, innernodetypes from sphinx.config import Config from sphinx.builders import BUILTIN_BUILDERS -from sphinx.directives import desc_directive, target_directive, \ - additional_xref_types +from sphinx.directives import GenericDesc, Target, additional_xref_types from sphinx.environment import SphinxStandaloneReader from sphinx.util.compat import Directive, directive_dwim from sphinx.util.console import bold @@ -314,7 +313,7 @@ class Sphinx(object): parse_node=None, ref_nodeclass=None): additional_xref_types[directivename] = (rolename, indextemplate, parse_node) - directives.register_directive(directivename, desc_directive) + directives.register_directive(directivename, GenericDesc) roles.register_canonical_role(rolename, xfileref_role) if ref_nodeclass is not None: innernodetypes[rolename] = ref_nodeclass @@ -322,7 +321,7 @@ class Sphinx(object): def add_crossref_type(self, directivename, rolename, indextemplate='', ref_nodeclass=None): additional_xref_types[directivename] = (rolename, indextemplate, None) - directives.register_directive(directivename, target_directive) + directives.register_directive(directivename, Target) roles.register_canonical_role(rolename, xfileref_role) if ref_nodeclass is not None: innernodetypes[rolename] = ref_nodeclass diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 3162d557..a6694085 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -16,135 +16,159 @@ from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.util import parselinenos - - -# ------ highlight directive --------------------------------------------------- - -def highlightlang_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - if 'linenothreshold' in options: - try: - linenothreshold = int(options['linenothreshold']) - except Exception: - linenothreshold = 10 - else: - linenothreshold = sys.maxint - return [addnodes.highlightlang(lang=arguments[0].strip(), - linenothreshold=linenothreshold)] - -highlightlang_directive.content = 0 -highlightlang_directive.arguments = (1, 0, 0) -highlightlang_directive.options = {'linenothreshold': directives.unchanged} -directives.register_directive('highlight', highlightlang_directive) -# old name -directives.register_directive('highlightlang', highlightlang_directive) - - -# ------ code-block directive -------------------------------------------------- - -def codeblock_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - code = u'\n'.join(content) - literal = nodes.literal_block(code, code) - literal['language'] = arguments[0] - literal['linenos'] = 'linenos' in options - return [literal] - -codeblock_directive.content = 1 -codeblock_directive.arguments = (1, 0, 0) -codeblock_directive.options = {'linenos': directives.flag} -directives.register_directive('code-block', codeblock_directive) -directives.register_directive('sourcecode', codeblock_directive) - - -# ------ literalinclude directive ---------------------------------------------- - -def literalinclude_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Like .. include:: :literal:, but only warns if the include file is - not found.""" - if not state.document.settings.file_insertion_enabled: - return [state.document.reporter.warning('File insertion disabled', - line=lineno)] - env = state.document.settings.env - rel_fn = arguments[0] - source_dir = path.dirname(path.abspath(state_machine.input_lines.source( - lineno - state_machine.input_offset - 1))) - fn = path.normpath(path.join(source_dir, rel_fn)) - - if 'pyobject' in options and 'lines' in options: - return [state.document.reporter.warning( - 'Cannot use both "pyobject" and "lines" options', line=lineno)] - - encoding = options.get('encoding', env.config.source_encoding) - try: - f = codecs.open(fn, 'rU', encoding) - lines = f.readlines() - f.close() - except (IOError, OSError): - return [state.document.reporter.warning( - 'Include file %r not found or reading it failed' % arguments[0], - line=lineno)] - except UnicodeError: - return [state.document.reporter.warning( - 'Encoding %r used for reading included file %r seems to ' - 'be wrong, try giving an :encoding: option' % - (encoding, arguments[0]))] - - objectname = options.get('pyobject') - if objectname is not None: - from sphinx.pycode import ModuleAnalyzer - analyzer = ModuleAnalyzer.for_file(fn, '') - tags = analyzer.find_tags() - if objectname not in tags: - return [state.document.reporter.warning( - 'Object named %r not found in include file %r' % - (objectname, arguments[0]), line=lineno)] +from sphinx.util.compat import Directive + + +class Highlight(Directive): + """ + Directive to set the highlighting language for code blocks, as well + as the threshold for line numbers. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenothreshold': directives.unchanged, + } + + def run(self): + if 'linenothreshold' in self.options: + try: + linenothreshold = int(self.options['linenothreshold']) + except Exception: + linenothreshold = 10 else: - lines = lines[tags[objectname][1] - 1 : tags[objectname][2] - 1] - - linespec = options.get('lines') - if linespec is not None: + linenothreshold = sys.maxint + return [addnodes.highlightlang(lang=self.arguments[0].strip(), + linenothreshold=linenothreshold)] + + +class CodeBlock(Directive): + """ + Directive for a code block with special highlighting or line numbering + settings. + """ + + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenos': directives.flag, + } + + def run(self): + code = u'\n'.join(self.content) + literal = nodes.literal_block(code, code) + literal['language'] = self.arguments[0] + literal['linenos'] = 'linenos' in self.options + return [literal] + + +class LiteralInclude(Directive): + """ + Like ``.. include:: :literal:``, but only warns if the include file is + not found, and does not raise errors. Also has several options for + selecting what to include. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'linenos': directives.flag, + 'language': directives.unchanged_required, + 'encoding': directives.encoding, + 'pyobject': directives.unchanged_required, + 'lines': directives.unchanged_required, + 'start-after': directives.unchanged_required, + 'end-before': directives.unchanged_required, + } + + def run(self): + document = self.state.document + filename = self.arguments[0] + if not document.settings.file_insertion_enabled: + return [document.reporter.warning('File insertion disabled', + line=self.lineno)] + env = document.settings.env + rel_fn = filename + sourcename = self.state_machine.input_lines.source( + self.lineno - self.state_machine.input_offset - 1) + source_dir = path.dirname(path.abspath(sourcename)) + fn = path.normpath(path.join(source_dir, rel_fn)) + + if 'pyobject' in self.options and 'lines' in self.options: + return [document.reporter.warning( + 'Cannot use both "pyobject" and "lines" options', + line=self.lineno)] + + encoding = self.options.get('encoding', env.config.source_encoding) try: - linelist = parselinenos(linespec, len(lines)) - except ValueError, err: - return [state.document.reporter.warning(str(err), line=lineno)] - lines = [lines[i] for i in linelist] - - startafter = options.get('start-after') - endbefore = options.get('end-before') - if startafter is not None or endbefore is not None: - use = not startafter - res = [] - for line in lines: - if not use and startafter in line: - use = True - elif use and endbefore in line: - use = False - break - elif use: - res.append(line) - lines = res - - text = ''.join(lines) - retnode = nodes.literal_block(text, text, source=fn) - retnode.line = 1 - if options.get('language', ''): - retnode['language'] = options['language'] - if 'linenos' in options: - retnode['linenos'] = True - state.document.settings.env.note_dependency(rel_fn) - return [retnode] - -literalinclude_directive.options = { - 'linenos': directives.flag, - 'language': directives.unchanged_required, - 'encoding': directives.encoding, - 'pyobject': directives.unchanged_required, - 'lines': directives.unchanged_required, - 'start-after': directives.unchanged_required, - 'end-before': directives.unchanged_required, -} -literalinclude_directive.content = 0 -literalinclude_directive.arguments = (1, 0, 0) -directives.register_directive('literalinclude', literalinclude_directive) + f = codecs.open(fn, 'rU', encoding) + lines = f.readlines() + f.close() + except (IOError, OSError): + return [document.reporter.warning( + 'Include file %r not found or reading it failed' % filename, + line=self.lineno)] + except UnicodeError: + return [document.reporter.warning( + 'Encoding %r used for reading included file %r seems to ' + 'be wrong, try giving an :encoding: option' % + (encoding, filename))] + + objectname = self.options.get('pyobject') + if objectname is not None: + from sphinx.pycode import ModuleAnalyzer + analyzer = ModuleAnalyzer.for_file(fn, '') + tags = analyzer.find_tags() + if objectname not in tags: + return [document.reporter.warning( + 'Object named %r not found in include file %r' % + (objectname, filename), line=self.lineno)] + else: + lines = lines[tags[objectname][1]-1 : tags[objectname][2]-1] + + linespec = self.options.get('lines') + if linespec is not None: + try: + linelist = parselinenos(linespec, len(lines)) + except ValueError, err: + return [document.reporter.warning(str(err), line=self.lineno)] + lines = [lines[i] for i in linelist] + + startafter = self.options.get('start-after') + endbefore = self.options.get('end-before') + if startafter is not None or endbefore is not None: + use = not startafter + res = [] + for line in lines: + if not use and startafter in line: + use = True + elif use and endbefore in line: + use = False + break + elif use: + res.append(line) + lines = res + + text = ''.join(lines) + retnode = nodes.literal_block(text, text, source=fn) + retnode.line = 1 + if self.options.get('language', ''): + retnode['language'] = self.options['language'] + if 'linenos' in self.options: + retnode['linenos'] = True + document.settings.env.note_dependency(rel_fn) + return [retnode] + + +directives.register_directive('highlight', Highlight) +directives.register_directive('highlightlang', Highlight) # old name +directives.register_directive('code-block', CodeBlock) +directives.register_directive('sourcecode', CodeBlock) +directives.register_directive('literalinclude', LiteralInclude) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index dd275b74..e45042b9 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -15,124 +15,11 @@ from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.util import ws_re - - -# ------ information units ----------------------------------------------------- - -def desc_index_text(desctype, module, name, add_modules): - if desctype == 'function': - if not module: - return _('%s() (built-in function)') % name - return _('%s() (in module %s)') % (name, module) - elif desctype == 'data': - if not module: - return _('%s (built-in variable)') % name - return _('%s (in module %s)') % (name, module) - elif desctype == 'class': - if not module: - return _('%s (built-in class)') % name - return _('%s (class in %s)') % (name, module) - elif desctype == 'exception': - return name - elif desctype == 'method': - try: - clsname, methname = name.rsplit('.', 1) - except ValueError: - if module: - return _('%s() (in module %s)') % (name, module) - else: - return '%s()' % name - if module and add_modules: - return _('%s() (%s.%s method)') % (methname, module, clsname) - else: - return _('%s() (%s method)') % (methname, clsname) - elif desctype == 'staticmethod': - try: - clsname, methname = name.rsplit('.', 1) - except ValueError: - if module: - return _('%s() (in module %s)') % (name, module) - else: - return '%s()' % name - if module and add_modules: - return _('%s() (%s.%s static method)') % (methname, module, clsname) - else: - return _('%s() (%s static method)') % (methname, clsname) - elif desctype == 'classmethod': - try: - clsname, methname = name.rsplit('.', 1) - except ValueError: - if module: - return '%s() (in module %s)' % (name, module) - else: - return '%s()' % name - if module: - return '%s() (%s.%s class method)' % (methname, module, clsname) - else: - return '%s() (%s class method)' % (methname, clsname) - elif desctype == 'attribute': - try: - clsname, attrname = name.rsplit('.', 1) - except ValueError: - if module: - return _('%s (in module %s)') % (name, module) - else: - return name - if module and add_modules: - return _('%s (%s.%s attribute)') % (attrname, module, clsname) - else: - return _('%s (%s attribute)') % (attrname, clsname) - elif desctype == 'cfunction': - return _('%s (C function)') % name - elif desctype == 'cmember': - return _('%s (C member)') % name - elif desctype == 'cmacro': - return _('%s (C macro)') % name - elif desctype == 'ctype': - return _('%s (C type)') % name - elif desctype == 'cvar': - return _('%s (C variable)') % name - else: - raise ValueError('unhandled descenv: %s' % desctype) - - -# ------ make field lists (like :param foo:) in desc bodies prettier - -_ = lambda x: x # make gettext extraction in constants possible - -doc_fields_with_arg = { - 'param': '%param', - 'parameter': '%param', - 'arg': '%param', - 'argument': '%param', - 'keyword': '%param', - 'kwarg': '%param', - 'kwparam': '%param', - 'type': '%type', - 'raises': _('Raises'), - 'raise': 'Raises', - 'exception': 'Raises', - 'except': 'Raises', - 'var': _('Variable'), - 'ivar': 'Variable', - 'cvar': 'Variable', - 'returns': _('Returns'), - 'return': 'Returns', -} - -doc_fields_with_linked_arg = ('raises', 'raise', 'exception', 'except') - -doc_fields_without_arg = { - 'returns': 'Returns', - 'return': 'Returns', - 'rtype': _('Return type'), -} - -del _ +from sphinx.util.compat import Directive def _is_only_paragraph(node): - # determine if the node only contains one paragraph (and system messages) + """True if the node only contains one paragraph (and system messages).""" if len(node) == 0: return False elif len(node) > 1: @@ -144,89 +31,7 @@ def _is_only_paragraph(node): return False -def handle_doc_fields(node, env): - # don't traverse, only handle field lists that are immediate children - for child in node.children: - if not isinstance(child, nodes.field_list): - continue - params = [] - pfield = None - param_nodes = {} - param_types = {} - new_list = nodes.field_list() - for field in child: - fname, fbody = field - try: - typ, obj = fname.astext().split(None, 1) - typdesc = _(doc_fields_with_arg[typ]) - if _is_only_paragraph(fbody): - children = fbody.children[0].children - else: - children = fbody.children - if typdesc == '%param': - if not params: - # add the field that later gets all the parameters - pfield = nodes.field() - new_list += pfield - dlitem = nodes.list_item() - dlpar = nodes.paragraph() - dlpar += nodes.emphasis(obj, obj) - dlpar += nodes.Text(' -- ', ' -- ') - dlpar += children - param_nodes[obj] = dlpar - dlitem += dlpar - params.append(dlitem) - elif typdesc == '%type': - typenodes = fbody.children - if _is_only_paragraph(fbody): - typenodes = [nodes.Text(' (')] + \ - typenodes[0].children + [nodes.Text(')')] - param_types[obj] = typenodes - else: - fieldname = typdesc + ' ' - nfield = nodes.field() - nfieldname = nodes.field_name(fieldname, fieldname) - nfield += nfieldname - node = nfieldname - if typ in doc_fields_with_linked_arg: - node = addnodes.pending_xref(obj, reftype='obj', - refcaption=False, - reftarget=obj, - modname=env.currmodule, - classname=env.currclass) - nfieldname += node - node += nodes.Text(obj, obj) - nfield += nodes.field_body() - nfield[1] += fbody.children - new_list += nfield - except (KeyError, ValueError): - fnametext = fname.astext() - try: - typ = _(doc_fields_without_arg[fnametext]) - except KeyError: - # at least capitalize the field name - typ = fnametext.capitalize() - fname[0] = nodes.Text(typ) - new_list += field - if params: - if len(params) == 1: - pfield += nodes.field_name('', _('Parameter')) - pfield += nodes.field_body() - pfield[1] += params[0][0] - else: - pfield += nodes.field_name('', _('Parameters')) - pfield += nodes.field_body() - pfield[1] += nodes.bullet_list() - pfield[1][0].extend(params) - - for param, type in param_types.iteritems(): - if param in param_nodes: - param_nodes[param][1:1] = type - child.replace_self(new_list) - - -# ------ functions to parse a Python or C signature and create desc_* nodes. - +# REs for Python signatures py_sig_re = re.compile( r'''^ ([\w.]*\.)? # class name(s) (\w+) \s* # thing name @@ -237,84 +42,7 @@ py_sig_re = re.compile( py_paramlist_re = re.compile(r'([\[\],])') # split at '[', ']' and ',' -def parse_py_signature(signode, sig, desctype, module, env): - """ - Transform a python signature into RST nodes. - Return (fully qualified name of the thing, classname if any). - - If inside a class, the current class name is handled intelligently: - * it is stripped from the displayed name if present - * it is added to the full name (return value) if not present - """ - m = py_sig_re.match(sig) - if m is None: - raise ValueError - classname, name, arglist, retann = m.groups() - - if env.currclass: - add_module = False - if classname and classname.startswith(env.currclass): - fullname = classname + name - # class name is given again in the signature - classname = classname[len(env.currclass):].lstrip('.') - elif classname: - # class name is given in the signature, but different - # (shouldn't happen) - fullname = env.currclass + '.' + classname + name - else: - # class name is not given in the signature - fullname = env.currclass + '.' + name - else: - add_module = True - fullname = classname and classname + name or name - - if desctype == 'staticmethod': - signode += addnodes.desc_annotation('static ', 'static ') - elif desctype == 'classmethod': - signode += addnodes.desc_annotation('classmethod ', 'classmethod ') - - if classname: - signode += addnodes.desc_addname(classname, classname) - # exceptions are a special case, since they are documented in the - # 'exceptions' module. - elif add_module and env.config.add_module_names and \ - module and module != 'exceptions': - nodetext = module + '.' - signode += addnodes.desc_addname(nodetext, nodetext) - - signode += addnodes.desc_name(name, name) - if not arglist: - if desctype in ('function', 'method', 'staticmethod', 'classmethod'): - # for callables, add an empty parameter list - signode += addnodes.desc_parameterlist() - if retann: - signode += addnodes.desc_returns(retann, retann) - return fullname, classname - signode += addnodes.desc_parameterlist() - - stack = [signode[-1]] - for token in py_paramlist_re.split(arglist): - if token == '[': - opt = addnodes.desc_optional() - stack[-1] += opt - stack.append(opt) - elif token == ']': - try: - stack.pop() - except IndexError: - raise ValueError - elif not token or token == ',' or token.isspace(): - pass - else: - token = token.strip() - stack[-1] += addnodes.desc_parameter(token, token) - if len(stack) != 1: - raise ValueError - if retann: - signode += addnodes.desc_returns(retann, retann) - return fullname, classname - - +# REs for C signatures c_sig_re = re.compile( r'''^([^(]*?) # return type ([\w:]+) \s* # thing name (colon allowed for C++ class names) @@ -329,258 +57,608 @@ c_funcptr_sig_re = re.compile( ''', re.VERBOSE) c_funcptr_name_re = re.compile(r'^\(\s*\*\s*(.*?)\s*\)$') +# RE for option descriptions +option_desc_re = re.compile( + r'((?:/|-|--)[-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)') + # RE to split at word boundaries wsplit_re = re.compile(r'(\W+)') -# These C types aren't described in the reference, so don't try to create -# a cross-reference to them -stopwords = set(('const', 'void', 'char', 'int', 'long', 'FILE', 'struct')) - -def parse_c_type(node, ctype): - # add cross-ref nodes for all words - for part in filter(None, wsplit_re.split(ctype)): - tnode = nodes.Text(part, part) - if part[0] in string.ascii_letters+'_' and part not in stopwords: - pnode = addnodes.pending_xref( - '', reftype='ctype', reftarget=part, - modname=None, classname=None) - pnode += tnode - node += pnode +# RE to strip backslash escapes +strip_backslash_re = re.compile(r'\\(?=[^\\])') + + +class DescDirective(Directive): + """ + Directive to describe a class, function or similar object. + """ + + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'noindex': directives.flag, + 'module': directives.unchanged, + } + + _ = lambda x: x # make gettext extraction in constants possible + + doc_fields_with_arg = { + 'param': '%param', + 'parameter': '%param', + 'arg': '%param', + 'argument': '%param', + 'keyword': '%param', + 'kwarg': '%param', + 'kwparam': '%param', + 'type': '%type', + 'raises': _('Raises'), + 'raise': 'Raises', + 'exception': 'Raises', + 'except': 'Raises', + 'var': _('Variable'), + 'ivar': 'Variable', + 'cvar': 'Variable', + 'returns': _('Returns'), + 'return': 'Returns', + } + + doc_fields_with_linked_arg = ('raises', 'raise', 'exception', 'except') + + doc_fields_without_arg = { + 'returns': 'Returns', + 'return': 'Returns', + 'rtype': _('Return type'), + } + + def handle_doc_fields(self, node): + # don't traverse, only handle field lists that are immediate children + for child in node.children: + if not isinstance(child, nodes.field_list): + continue + params = [] + pfield = None + param_nodes = {} + param_types = {} + new_list = nodes.field_list() + for field in child: + fname, fbody = field + try: + typ, obj = fname.astext().split(None, 1) + typdesc = _(self.doc_fields_with_arg[typ]) + if _is_only_paragraph(fbody): + children = fbody.children[0].children + else: + children = fbody.children + if typdesc == '%param': + if not params: + # add the field that later gets all the parameters + pfield = nodes.field() + new_list += pfield + dlitem = nodes.list_item() + dlpar = nodes.paragraph() + dlpar += nodes.emphasis(obj, obj) + dlpar += nodes.Text(' -- ', ' -- ') + dlpar += children + param_nodes[obj] = dlpar + dlitem += dlpar + params.append(dlitem) + elif typdesc == '%type': + typenodes = fbody.children + if _is_only_paragraph(fbody): + typenodes = ([nodes.Text(' (')] + + typenodes[0].children + + [nodes.Text(')')]) + param_types[obj] = typenodes + else: + fieldname = typdesc + ' ' + nfield = nodes.field() + nfieldname = nodes.field_name(fieldname, fieldname) + nfield += nfieldname + node = nfieldname + if typ in self.doc_fields_with_linked_arg: + node = addnodes.pending_xref( + obj, reftype='obj', refcaption=False, + reftarget=obj, modname=self.env.currmodule, + classname=self.env.currclass) + nfieldname += node + node += nodes.Text(obj, obj) + nfield += nodes.field_body() + nfield[1] += fbody.children + new_list += nfield + except (KeyError, ValueError): + fnametext = fname.astext() + try: + typ = _(self.doc_fields_without_arg[fnametext]) + except KeyError: + # at least capitalize the field name + typ = fnametext.capitalize() + fname[0] = nodes.Text(typ) + new_list += field + if params: + if len(params) == 1: + pfield += nodes.field_name('', _('Parameter')) + pfield += nodes.field_body() + pfield[1] += params[0][0] + else: + pfield += nodes.field_name('', _('Parameters')) + pfield += nodes.field_body() + pfield[1] += nodes.bullet_list() + pfield[1][0].extend(params) + + for param, type in param_types.iteritems(): + if param in param_nodes: + param_nodes[param][1:1] = type + child.replace_self(new_list) + + def get_signatures(self): + # remove backslashes to support (dummy) escapes; helps Vim highlighting + return [strip_backslash_re.sub('', sig.strip()) + for sig in self.arguments[0].split('\n')] + + def parse_signature(self, sig, signode): + raise ValueError # must be implemented in subclasses + + def add_target_and_index(self, name, sig, signode): + return # do nothing by default + + def before_content(self): + pass + + def after_content(self): + pass + + def run(self): + self.desctype = self.name + self.env = self.state.document.settings.env + self.indexnode = addnodes.index(entries=[]) + + node = addnodes.desc() + node.document = self.state.document + node['desctype'] = self.desctype + node['noindex'] = noindex = ('noindex' in self.options) + + self.names = [] + signatures = self.get_signatures() + for i, sig in enumerate(signatures): + # add a signature node for each signature in the current unit + # and add a reference target for it + signode = addnodes.desc_signature(sig, '') + signode['first'] = False + node.append(signode) + try: + # name can also be a tuple, e.g. (classname, objname) + name = self.parse_signature(sig, signode) + except ValueError, err: + # signature parsing failed + signode.clear() + signode += addnodes.desc_name(sig, sig) + continue # we don't want an index entry here + if not noindex and name not in self.names: + # only add target and index entry if this is the first + # description of the object with this name in this desc block + self.names.append(name) + self.add_target_and_index(name, sig, signode) + + contentnode = addnodes.desc_content() + node.append(contentnode) + if self.names: + # needed for association of version{added,changed} directives + self.env.currdesc = self.names[0] + self.before_content() + self.state.nested_parse(self.content, self.content_offset, contentnode) + self.handle_doc_fields(contentnode) + self.env.currdesc = None + self.after_content() + return [self.indexnode, node] + + +class PythonDesc(DescDirective): + def parse_signature(self, sig, signode): + """ + Transform a python signature into RST nodes. + Return (fully qualified name of the thing, classname if any). + + If inside a class, the current class name is handled intelligently: + * it is stripped from the displayed name if present + * it is added to the full name (return value) if not present + """ + m = py_sig_re.match(sig) + if m is None: + raise ValueError + classname, name, arglist, retann = m.groups() + + if self.env.currclass: + add_module = False + if classname and classname.startswith(self.env.currclass): + fullname = classname + name + # class name is given again in the signature + classname = classname[len(self.env.currclass):].lstrip('.') + elif classname: + # class name is given in the signature, but different + # (shouldn't happen) + fullname = self.env.currclass + '.' + classname + name + else: + # class name is not given in the signature + fullname = self.env.currclass + '.' + name else: - node += tnode - -def parse_c_signature(signode, sig, desctype): - """Transform a C (or C++) signature into RST nodes.""" - # first try the function pointer signature regex, it's more specific - m = c_funcptr_sig_re.match(sig) - if m is None: - m = c_sig_re.match(sig) - if m is None: - raise ValueError('no match') - rettype, name, arglist, const = m.groups() - - signode += addnodes.desc_type('', '') - parse_c_type(signode[-1], rettype) - try: - classname, funcname = name.split('::', 1) - classname += '::' - signode += addnodes.desc_addname(classname, classname) - signode += addnodes.desc_name(funcname, funcname) - # name (the full name) is still both parts - except ValueError: + add_module = True + fullname = classname and classname + name or name + + # XXX! + if self.desctype == 'staticmethod': + signode += addnodes.desc_annotation('static ', 'static ') + elif self.desctype == 'classmethod': + signode += addnodes.desc_annotation('classmethod ', 'classmethod ') + + if classname: + signode += addnodes.desc_addname(classname, classname) + # exceptions are a special case, since they are documented in the + # 'exceptions' module. + elif add_module and self.env.config.add_module_names: + modname = self.options.get('module', self.env.currmodule) + if modname and modname != 'exceptions': + nodetext = modname + '.' + signode += addnodes.desc_addname(nodetext, nodetext) + signode += addnodes.desc_name(name, name) - # clean up parentheses from canonical name - m = c_funcptr_name_re.match(name) - if m: - name = m.group(1) - if not arglist: - if desctype == 'cfunction': - # for functions, add an empty parameter list - signode += addnodes.desc_parameterlist() - return name + if not arglist: + # XXX! + if self.desctype in ('function', 'method', + 'staticmethod', 'classmethod'): + # for callables, add an empty parameter list + signode += addnodes.desc_parameterlist() + if retann: + signode += addnodes.desc_returns(retann, retann) + return fullname, classname + signode += addnodes.desc_parameterlist() + + stack = [signode[-1]] + for token in py_paramlist_re.split(arglist): + if token == '[': + opt = addnodes.desc_optional() + stack[-1] += opt + stack.append(opt) + elif token == ']': + try: + stack.pop() + except IndexError: + raise ValueError + elif not token or token == ',' or token.isspace(): + pass + else: + token = token.strip() + stack[-1] += addnodes.desc_parameter(token, token) + if len(stack) != 1: + raise ValueError + if retann: + signode += addnodes.desc_returns(retann, retann) + return fullname, classname - paramlist = addnodes.desc_parameterlist() - arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup - # this messes up function pointer types, but not too badly ;) - args = arglist.split(',') - for arg in args: - arg = arg.strip() - param = addnodes.desc_parameter('', '', noemph=True) - try: - ctype, argname = arg.rsplit(' ', 1) - except ValueError: - # no argument name given, only the type - parse_c_type(param, arg) + def get_index_text(self, modname, name): + raise NotImplementedError('must be implemented in subclasses') + + def add_target_and_index(self, name_cls, sig, signode): + modname = self.options.get('module', self.env.currmodule) + fullname = (modname and modname + '.' or '') + name_cls[0] + # note target + if fullname not in self.state.document.ids: + signode['names'].append(fullname) + signode['ids'].append(fullname) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + self.env.note_descref(fullname, self.desctype, self.lineno) + + indextext = self.get_index_text(modname, name_cls) + if indextext: + self.indexnode['entries'].append(('single', indextext, + fullname, fullname)) + + def before_content(self): + # needed for automatic qualification of members (reset in subclasses) + self.clsname_set = False + + def after_content(self): + if self.clsname_set: + self.env.currclass = None + + +class ModulelevelDesc(PythonDesc): + def get_index_text(self, modname, name_cls): + if self.desctype == 'function': + if not modname: + return _('%s() (built-in function)') % name_cls[0] + return _('%s() (in module %s)') % (name_cls[0], modname) + elif self.desctype == 'data': + if not modname: + return _('%s (built-in variable)') % name_cls[0] + return _('%s (in module %s)') % (name_cls[0], modname) else: - parse_c_type(param, ctype) - param += nodes.emphasis(' '+argname, ' '+argname) - paramlist += param - signode += paramlist - if const: - signode += addnodes.desc_addname(const, const) - return name + return '' -option_desc_re = re.compile( - r'((?:/|-|--)[-_a-zA-Z0-9]+)(\s*.*?)(?=,\s+(?:/|-|--)|$)') - -def parse_option_desc(signode, sig): - """Transform an option description into RST nodes.""" - count = 0 - firstname = '' - for m in option_desc_re.finditer(sig): - optname, args = m.groups() - if count: - signode += addnodes.desc_addname(', ', ', ') - signode += addnodes.desc_name(optname, optname) - signode += addnodes.desc_addname(args, args) - if not count: - firstname = optname - count += 1 - if not firstname: - raise ValueError - return firstname +class ClasslikeDesc(PythonDesc): + def get_index_text(self, modname, name_cls): + if self.desctype == 'class': + if not modname: + return _('%s (built-in class)') % name_cls[0] + return _('%s (class in %s)') % (name_cls[0], modname) + elif self.desctype == 'exception': + return name_cls[0] + else: + return '' + def before_content(self): + PythonDesc.before_content(self) + if self.names: + self.env.currclass = self.names[0][0] + self.clsname_set = True -strip_backslash_re = re.compile(r'\\(?=[^\\])') -def desc_directive(desctype, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - inode = addnodes.index(entries=[]) - node = addnodes.desc() - node.document = state.document - node['desctype'] = desctype - - noindex = ('noindex' in options) - node['noindex'] = noindex - # remove backslashes to support (dummy) escapes; helps Vim's highlighting - signatures = map(lambda s: strip_backslash_re.sub('', s.strip()), - arguments[0].split('\n')) - names = [] - clsname = None - module = options.get('module', env.currmodule) - for i, sig in enumerate(signatures): - # add a signature node for each signature in the current unit - # and add a reference target for it - sig = sig.strip() - signode = addnodes.desc_signature(sig, '') - signode['first'] = False - node.append(signode) - try: - if desctype in ('function', 'data', 'class', 'exception', - 'method', 'staticmethod', 'classmethod', - 'attribute'): - name, clsname = parse_py_signature(signode, sig, - desctype, module, env) - elif desctype in ('cfunction', 'cmember', 'cmacro', - 'ctype', 'cvar'): - name = parse_c_signature(signode, sig, desctype) - elif desctype == 'cmdoption': - optname = parse_option_desc(signode, sig) - if not noindex: - targetname = optname.replace('/', '-') - if env.currprogram: - targetname = '-' + env.currprogram + targetname - targetname = 'cmdoption' + targetname - signode['ids'].append(targetname) - state.document.note_explicit_target(signode) - inode['entries'].append( - ('pair', _('%scommand line option; %s') % - ((env.currprogram and env.currprogram + ' ' or ''), - sig), - targetname, targetname)) - env.note_progoption(optname, targetname) - continue - elif desctype == 'describe': - signode.clear() - signode += addnodes.desc_name(sig, sig) - continue +class ClassmemberDesc(PythonDesc): + def get_index_text(self, modname, name_cls): + name, cls = name_cls + add_modules = self.env.config.add_module_names + if self.desctype == 'method': + try: + clsname, methname = name.rsplit('.', 1) + except ValueError: + if modname: + return _('%s() (in module %s)') % (name, modname) + else: + return '%s()' % name + if modname and add_modules: + return _('%s() (%s.%s method)') % (methname, modname, clsname) else: - # another registered generic x-ref directive - rolename, indextemplate, parse_node = \ - additional_xref_types[desctype] - if parse_node: - fullname = parse_node(env, sig, signode) + return _('%s() (%s method)') % (methname, clsname) + elif self.desctype == 'staticmethod': + try: + clsname, methname = name.rsplit('.', 1) + except ValueError: + if modname: + return _('%s() (in module %s)') % (name, modname) else: - signode.clear() - signode += addnodes.desc_name(sig, sig) - # normalize whitespace like xfileref_role does - fullname = ws_re.sub('', sig) - if not noindex: - targetname = '%s-%s' % (rolename, fullname) - signode['ids'].append(targetname) - state.document.note_explicit_target(signode) - if indextemplate: - indexentry = _(indextemplate) % (fullname,) - indextype = 'single' - colon = indexentry.find(':') - if colon != -1: - indextype = indexentry[:colon].strip() - indexentry = indexentry[colon+1:].strip() - inode['entries'].append((indextype, indexentry, - targetname, targetname)) - env.note_reftarget(rolename, fullname, targetname) - # don't use object indexing below - continue - except ValueError, err: - # signature parsing failed + return '%s()' % name + if modname and add_modules: + return _('%s() (%s.%s static method)') % (methname, modname, + clsname) + else: + return _('%s() (%s static method)') % (methname, clsname) + elif self.desctype == 'classmethod': + try: + clsname, methname = name.rsplit('.', 1) + except ValueError: + if modname: + return '%s() (in module %s)' % (name, modname) + else: + return '%s()' % name + if modname: + return '%s() (%s.%s class method)' % (methname, modname, + clsname) + else: + return '%s() (%s class method)' % (methname, clsname) + elif self.desctype == 'attribute': + try: + clsname, attrname = name.rsplit('.', 1) + except ValueError: + if modname: + return _('%s (in module %s)') % (name, modname) + else: + return name + if modname and add_modules: + return _('%s (%s.%s attribute)') % (attrname, modname, clsname) + else: + return _('%s (%s attribute)') % (attrname, clsname) + else: + return '' + + def before_content(self): + PythonDesc.before_content(self) + if self.names and self.names[-1][1] and not self.env.currclass: + self.env.currclass = self.names[-1][1].strip('.') + self.clsname_set = True + + +class CDesc(DescDirective): + + # These C types aren't described anywhere, so don't try to create + # a cross-reference to them + stopwords = set(('const', 'void', 'char', 'int', 'long', 'FILE', 'struct')) + + def _parse_type(self, node, ctype): + # add cross-ref nodes for all words + for part in filter(None, wsplit_re.split(ctype)): + tnode = nodes.Text(part, part) + if part[0] in string.ascii_letters+'_' and \ + part not in self.stopwords: + pnode = addnodes.pending_xref( + '', reftype='ctype', reftarget=part, + modname=None, classname=None) + pnode += tnode + node += pnode + else: + node += tnode + + def parse_signature(self, sig, signode): + """Transform a C (or C++) signature into RST nodes.""" + # first try the function pointer signature regex, it's more specific + m = c_funcptr_sig_re.match(sig) + if m is None: + m = c_sig_re.match(sig) + if m is None: + raise ValueError('no match') + rettype, name, arglist, const = m.groups() + + signode += addnodes.desc_type('', '') + self._parse_type(signode[-1], rettype) + try: + classname, funcname = name.split('::', 1) + classname += '::' + signode += addnodes.desc_addname(classname, classname) + signode += addnodes.desc_name(funcname, funcname) + # name (the full name) is still both parts + except ValueError: + signode += addnodes.desc_name(name, name) + # clean up parentheses from canonical name + m = c_funcptr_name_re.match(name) + if m: + name = m.group(1) + if not arglist: + if self.desctype == 'cfunction': + # for functions, add an empty parameter list + signode += addnodes.desc_parameterlist() + return name + + paramlist = addnodes.desc_parameterlist() + arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup + # this messes up function pointer types, but not too badly ;) + args = arglist.split(',') + for arg in args: + arg = arg.strip() + param = addnodes.desc_parameter('', '', noemph=True) + try: + ctype, argname = arg.rsplit(' ', 1) + except ValueError: + # no argument name given, only the type + self._parse_type(param, arg) + else: + self._parse_type(param, ctype) + param += nodes.emphasis(' '+argname, ' '+argname) + paramlist += param + signode += paramlist + if const: + signode += addnodes.desc_addname(const, const) + return name + + def get_index_text(self, modname, name): + if self.desctype == 'cfunction': + return _('%s (C function)') % name + elif self.desctype == 'cmember': + return _('%s (C member)') % name + elif self.desctype == 'cmacro': + return _('%s (C macro)') % name + elif self.desctype == 'ctype': + return _('%s (C type)') % name + elif self.desctype == 'cvar': + return _('%s (C variable)') % name + else: + return '' + + # just copy that one + add_target_and_index = PythonDesc.__dict__['add_target_and_index'] + + +class CmdoptionDesc(DescDirective): + """ + A command-line option (.. cmdoption). + """ + + def parse_signature(self, sig, signode): + """Transform an option description into RST nodes.""" + count = 0 + firstname = '' + for m in option_desc_re.finditer(sig): + optname, args = m.groups() + if count: + signode += addnodes.desc_addname(', ', ', ') + signode += addnodes.desc_name(optname, optname) + signode += addnodes.desc_addname(args, args) + if not count: + firstname = optname + count += 1 + if not firstname: + raise ValueError + return firstname + + def add_target_and_index(self, name, sig, signode): + targetname = name.replace('/', '-') + if self.env.currprogram: + targetname = '-' + self.env.currprogram + targetname + targetname = 'cmdoption' + targetname + signode['ids'].append(targetname) + self.state.document.note_explicit_target(signode) + self.indexnode['entries'].append( + ('pair', _('%scommand line option; %s') % + ((self.env.currprogram and + self.env.currprogram + ' ' or ''), sig), + targetname, targetname)) + self.env.note_progoption(name, targetname) + + +class GenericDesc(DescDirective): + """ + A generic x-ref directive registered with Sphinx.add_description_unit(). + """ + + def parse_signature(self, sig, signode): + parse_node = additional_xref_types[self.desctype][2] + if parse_node: + name = parse_node(self.env, sig, signode) + else: signode.clear() signode += addnodes.desc_name(sig, sig) - continue # we don't want an index entry here - # only add target and index entry if this is the first description - # of the function name in this desc block - if not noindex and name not in names: - fullname = (module and module + '.' or '') + name - # note target - if fullname not in state.document.ids: - signode['names'].append(fullname) - signode['ids'].append(fullname) - signode['first'] = (not names) - state.document.note_explicit_target(signode) - env.note_descref(fullname, desctype, lineno) - names.append(name) - - indextext = desc_index_text(desctype, module, name, - env.config.add_module_names) - inode['entries'].append(('single', indextext, fullname, fullname)) - - subnode = addnodes.desc_content() - node.append(subnode) - # needed for automatic qualification of members - clsname_set = False - if desctype in ('class', 'exception') and names: - env.currclass = names[0] - clsname_set = True - elif desctype in ('method', 'staticmethod', 'classmethod', - 'attribute') and clsname and not env.currclass: - env.currclass = clsname.strip('.') - clsname_set = True - # needed for association of version{added,changed} directives - if names: - env.currdesc = names[0] - state.nested_parse(content, content_offset, subnode) - handle_doc_fields(subnode, env) - if clsname_set: - env.currclass = None - env.currdesc = None - return [inode, node] - -desc_directive.content = 1 -desc_directive.arguments = (1, 0, 1) -desc_directive.options = {'noindex': directives.flag, - 'module': directives.unchanged} - -desctypes = [ - # the Python ones - 'function', - 'data', - 'class', - 'method', - 'classmethod', - 'staticmethod', - 'attribute', - 'exception', - # the C ones - 'cfunction', - 'cmember', - 'cmacro', - 'ctype', - 'cvar', - # for command line options - 'cmdoption', - # the generic one - 'describe', - 'envvar', -] - -for _name in desctypes: - directives.register_directive(_name, desc_directive) + # normalize whitespace like xfileref_role does + name = ws_re.sub('', sig) + return name + + def add_target_and_index(self, name, sig, signode): + rolename, indextemplate, _ = additional_xref_types[self.desctype] + targetname = '%s-%s' % (rolename, name) + signode['ids'].append(targetname) + self.state.document.note_explicit_target(signode) + if indextemplate: + indexentry = _(indextemplate) % (name,) + indextype = 'single' + colon = indexentry.find(':') + if colon != -1: + indextype = indexentry[:colon].strip() + indexentry = indexentry[colon+1:].strip() + self.indexnode['entries'].append((indextype, indexentry, + targetname, targetname)) + self.env.note_reftarget(rolename, name, targetname) + + +class Target(Directive): + """ + Generic target for user-defined cross-reference types. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + env = self.state.document.settings.env + rolename, indextemplate, foo = additional_xref_types[self.name] + # normalize whitespace in fullname like xfileref_role does + fullname = ws_re.sub('', self.arguments[0].strip()) + targetname = '%s-%s' % (rolename, fullname) + node = nodes.target('', '', ids=[targetname]) + self.state.document.note_explicit_target(node) + ret = [node] + if indextemplate: + indexentry = indextemplate % (fullname,) + indextype = 'single' + colon = indexentry.find(':') + if colon != -1: + indextype = indexentry[:colon].strip() + indexentry = indexentry[colon+1:].strip() + inode = addnodes.index(entries=[(indextype, indexentry, + targetname, targetname)]) + ret.insert(0, inode) + env.note_reftarget(rolename, fullname, targetname) + return ret + +# Note: the target directive is not registered here, it is used by the +# application when registering additional xref types. _ = lambda x: x # Generic cross-reference types; they can be registered in the application; -# the directives are either desc_directive or target_directive +# the directives are either desc_directive or target_directive. additional_xref_types = { # directive name: (role name, index text, function to parse the desc node) 'envvar': ('envvar', _('environment variable; %s'), None), @@ -589,34 +667,22 @@ additional_xref_types = { del _ -# ------ target ---------------------------------------------------------------- - -def target_directive(targettype, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Generic target for user-defined cross-reference types.""" - env = state.document.settings.env - rolename, indextemplate, foo = additional_xref_types[targettype] - # normalize whitespace in fullname like xfileref_role does - fullname = ws_re.sub('', arguments[0].strip()) - targetname = '%s-%s' % (rolename, fullname) - node = nodes.target('', '', ids=[targetname]) - state.document.note_explicit_target(node) - ret = [node] - if indextemplate: - indexentry = indextemplate % (fullname,) - indextype = 'single' - colon = indexentry.find(':') - if colon != -1: - indextype = indexentry[:colon].strip() - indexentry = indexentry[colon+1:].strip() - inode = addnodes.index(entries=[(indextype, indexentry, - targetname, targetname)]) - ret.insert(0, inode) - env.note_reftarget(rolename, fullname, targetname) - return ret - -target_directive.content = 0 -target_directive.arguments = (1, 0, 1) - -# note, the target directive is not registered here, it is used by the -# application when registering additional xref types +directives.register_directive('describe', DescDirective) + +directives.register_directive('function', ModulelevelDesc) +directives.register_directive('data', ModulelevelDesc) +directives.register_directive('class', ClasslikeDesc) +directives.register_directive('exception', ClasslikeDesc) +directives.register_directive('method', ClassmemberDesc) +directives.register_directive('classmethod', ClassmemberDesc) +directives.register_directive('staticmethod', ClassmemberDesc) +directives.register_directive('attribute', ClassmemberDesc) + +directives.register_directive('cfunction', CDesc) +directives.register_directive('cmember', CDesc) +directives.register_directive('cmacro', CDesc) +directives.register_directive('ctype', CDesc) +directives.register_directive('cvar', CDesc) + +directives.register_directive('cmdoption', CmdoptionDesc) +directives.register_directive('envvar', GenericDesc) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 3d060b02..7601be1f 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -15,266 +15,313 @@ from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.locale import pairindextypes from sphinx.util import patfilter, ws_re, caption_ref_re, url_re, docname_join -from sphinx.util.compat import make_admonition - - -# ------ the TOC tree ---------------------------------------------------------- - -def toctree_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - suffix = env.config.source_suffix - glob = 'glob' in options - - ret = [] - # (title, ref) pairs, where ref may be a document, or an external link, - # and title may be None if the document's title is to be used - entries = [] - includefiles = [] - includetitles = {} - all_docnames = env.found_docs.copy() - # don't add the currently visited file in catch-all patterns - all_docnames.remove(env.docname) - for entry in content: - if not entry: - continue - if not glob: - # look for explicit titles and documents ("Some Title "). - m = caption_ref_re.match(entry) - if m: - ref = m.group(2) - title = m.group(1) - docname = ref - else: - ref = docname = entry - title = None - # remove suffixes (backwards compatibility) - if docname.endswith(suffix): - docname = docname[:-len(suffix)] - # absolutize filenames - docname = docname_join(env.docname, docname) - if url_re.match(ref) or ref == 'self': - entries.append((title, ref)) - elif docname not in env.found_docs: - ret.append(state.document.reporter.warning( - 'toctree references unknown document %r' % docname, - line=lineno)) +from sphinx.util.compat import Directive, make_admonition + + +class TocTree(Directive): + """ + Directive to notify Sphinx about the hierarchical structure of the docs, + and to include a table-of-contents like tree in the current document. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'maxdepth': int, + 'glob': directives.flag, + 'hidden': directives.flag, + } + + def run(self): + env = self.state.document.settings.env + suffix = env.config.source_suffix + glob = 'glob' in self.options + + ret = [] + # (title, ref) pairs, where ref may be a document, or an external link, + # and title may be None if the document's title is to be used + entries = [] + includefiles = [] + includetitles = {} + all_docnames = env.found_docs.copy() + # don't add the currently visited file in catch-all patterns + all_docnames.remove(env.docname) + for entry in self.content: + if not entry: + continue + if not glob: + # look for explicit titles ("Some Title ") + m = caption_ref_re.match(entry) + if m: + ref = m.group(2) + title = m.group(1) + docname = ref + else: + ref = docname = entry + title = None + # remove suffixes (backwards compatibility) + if docname.endswith(suffix): + docname = docname[:-len(suffix)] + # absolutize filenames + docname = docname_join(env.docname, docname) + if url_re.match(ref) or ref == 'self': + entries.append((title, ref)) + elif docname not in env.found_docs: + ret.append(self.state.document.reporter.warning( + 'toctree references unknown document %r' % docname, + line=self.lineno)) + else: + entries.append((title, docname)) + includefiles.append(docname) else: - entries.append((title, docname)) - includefiles.append(docname) - else: - patname = docname_join(env.docname, entry) - docnames = sorted(patfilter(all_docnames, patname)) - for docname in docnames: - all_docnames.remove(docname) # don't include it again - entries.append((None, docname)) - includefiles.append(docname) - if not docnames: - ret.append(state.document.reporter.warning( - 'toctree glob pattern %r didn\'t match any documents' - % entry, line=lineno)) - subnode = addnodes.toctree() - subnode['parent'] = env.docname - subnode['entries'] = entries - subnode['includefiles'] = includefiles - subnode['maxdepth'] = options.get('maxdepth', -1) - subnode['glob'] = glob - subnode['hidden'] = 'hidden' in options - ret.append(subnode) - return ret - -toctree_directive.content = 1 -toctree_directive.options = {'maxdepth': int, 'glob': directives.flag, - 'hidden': directives.flag} -directives.register_directive('toctree', toctree_directive) - - -# ------ section metadata ------------------------------------------------------ - -def module_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - modname = arguments[0].strip() - noindex = 'noindex' in options - env.currmodule = modname - env.note_module(modname, options.get('synopsis', ''), - options.get('platform', ''), - 'deprecated' in options) - modulenode = addnodes.module() - modulenode['modname'] = modname - modulenode['synopsis'] = options.get('synopsis', '') - targetnode = nodes.target('', '', ids=['module-' + modname]) - state.document.note_explicit_target(targetnode) - ret = [modulenode, targetnode] - if 'platform' in options: - modulenode['platform'] = options['platform'] - node = nodes.paragraph() - node += nodes.emphasis('', _('Platforms: ')) - node += nodes.Text(options['platform'], options['platform']) - ret.append(node) - # the synopsis isn't printed; in fact, it is only used in the - # modindex currently - if not noindex: - indextext = _('%s (module)') % modname - inode = addnodes.index(entries=[('single', indextext, - 'module-' + modname, modname)]) - ret.insert(0, inode) - return ret - -module_directive.arguments = (1, 0, 0) -module_directive.options = {'platform': lambda x: x, - 'synopsis': lambda x: x, - 'noindex': directives.flag, - 'deprecated': directives.flag} -directives.register_directive('module', module_directive) - - -def currentmodule_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # This directive is just to tell people that we're documenting - # stuff in module foo, but links to module foo won't lead here. - env = state.document.settings.env - modname = arguments[0].strip() - if modname == 'None': - env.currmodule = None - else: + patname = docname_join(env.docname, entry) + docnames = sorted(patfilter(all_docnames, patname)) + for docname in docnames: + all_docnames.remove(docname) # don't include it again + entries.append((None, docname)) + includefiles.append(docname) + if not docnames: + ret.append(self.state.document.reporter.warning( + 'toctree glob pattern %r didn\'t match any documents' + % entry, line=self.lineno)) + subnode = addnodes.toctree() + subnode['parent'] = env.docname + subnode['entries'] = entries + subnode['includefiles'] = includefiles + subnode['maxdepth'] = self.options.get('maxdepth', -1) + subnode['glob'] = glob + subnode['hidden'] = 'hidden' in self.options + ret.append(subnode) + return ret + + +class Module(Directive): + """ + Directive to mark description of a new module. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'platform': lambda x: x, + 'synopsis': lambda x: x, + 'noindex': directives.flag, + 'deprecated': directives.flag, + } + + def run(self): + env = self.state.document.settings.env + modname = self.arguments[0].strip() + noindex = 'noindex' in self.options env.currmodule = modname - return [] + env.note_module(modname, self.options.get('synopsis', ''), + self.options.get('platform', ''), + 'deprecated' in self.options) + modulenode = addnodes.module() + modulenode['modname'] = modname + modulenode['synopsis'] = self.options.get('synopsis', '') + targetnode = nodes.target('', '', ids=['module-' + modname]) + self.state.document.note_explicit_target(targetnode) + ret = [modulenode, targetnode] + if 'platform' in self.options: + platform = self.options['platform'] + modulenode['platform'] = platform + node = nodes.paragraph() + node += nodes.emphasis('', _('Platforms: ')) + node += nodes.Text(platform, platform) + ret.append(node) + # the synopsis isn't printed; in fact, it is only used in the + # modindex currently + if not noindex: + indextext = _('%s (module)') % modname + inode = addnodes.index(entries=[('single', indextext, + 'module-' + modname, modname)]) + ret.insert(0, inode) + return ret + + +class CurrentModule(Directive): + """ + This directive is just to tell Sphinx that we're documenting + stuff in module foo, but links to module foo won't lead here. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + env = self.state.document.settings.env + modname = self.arguments[0].strip() + if modname == 'None': + env.currmodule = None + else: + env.currmodule = modname + return [] -currentmodule_directive.arguments = (1, 0, 0) -directives.register_directive('currentmodule', currentmodule_directive) +class Author(Directive): + """ + Directive to give the name of the author of the current document + or section. Shown in the output only if the show_authors option is on. + """ -def author_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # Show authors only if the show_authors option is on - env = state.document.settings.env - if not env.config.show_authors: - return [] - para = nodes.paragraph() - emph = nodes.emphasis() - para += emph - if name == 'sectionauthor': - text = _('Section author: ') - elif name == 'moduleauthor': - text = _('Module author: ') - else: - text = _('Author: ') - emph += nodes.Text(text, text) - inodes, messages = state.inline_text(arguments[0], lineno) - emph.extend(inodes) - return [para] + messages - -author_directive.arguments = (1, 0, 1) -directives.register_directive('sectionauthor', author_directive) -directives.register_directive('moduleauthor', author_directive) - - -def program_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - program = ws_re.sub('-', arguments[0].strip()) - if program == 'None': - env.currprogram = None - else: - env.currprogram = program - return [] - -program_directive.arguments = (1, 0, 1) -directives.register_directive('program', program_directive) - - -# ------ index markup ---------------------------------------------------------- - -indextypes = [ - 'single', 'pair', 'triple', -] - -def index_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - arguments = arguments[0].split('\n') - env = state.document.settings.env - targetid = 'index-%s' % env.index_num - env.index_num += 1 - targetnode = nodes.target('', '', ids=[targetid]) - state.document.note_explicit_target(targetnode) - indexnode = addnodes.index() - indexnode['entries'] = ne = [] - for entry in arguments: - entry = entry.strip() - for type in pairindextypes: - if entry.startswith(type+':'): - value = entry[len(type)+1:].strip() - value = pairindextypes[type] + '; ' + value - ne.append(('pair', value, targetid, value)) - break + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + env = self.state.document.settings.env + if not env.config.show_authors: + return [] + para = nodes.paragraph() + emph = nodes.emphasis() + para += emph + if self.name == 'sectionauthor': + text = _('Section author: ') + elif self.name == 'moduleauthor': + text = _('Module author: ') + else: + text = _('Author: ') + emph += nodes.Text(text, text) + inodes, messages = self.state.inline_text(self.arguments[0], + self.lineno) + emph.extend(inodes) + return [para] + messages + + +class Program(Directive): + """ + Directive to name the program for which options are documented. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + env = self.state.document.settings.env + program = ws_re.sub('-', self.arguments[0].strip()) + if program == 'None': + env.currprogram = None else: - for type in indextypes: + env.currprogram = program + return [] + + +class Index(Directive): + """ + Directive to add entries to the index. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + indextypes = [ + 'single', 'pair', 'triple', + ] + + def run(self): + arguments = self.arguments[0].split('\n') + env = self.state.document.settings.env + targetid = 'index-%s' % env.index_num + env.index_num += 1 + targetnode = nodes.target('', '', ids=[targetid]) + self.state.document.note_explicit_target(targetnode) + indexnode = addnodes.index() + indexnode['entries'] = ne = [] + for entry in arguments: + entry = entry.strip() + for type in pairindextypes: if entry.startswith(type+':'): value = entry[len(type)+1:].strip() - ne.append((type, value, targetid, value)) + value = pairindextypes[type] + '; ' + value + ne.append(('pair', value, targetid, value)) break - # shorthand notation for single entries else: - for value in entry.split(','): - value = value.strip() - if not value: - continue - ne.append(('single', value, targetid, value)) - return [indexnode, targetnode] - -index_directive.arguments = (1, 0, 1) -directives.register_directive('index', index_directive) - -# ------ versionadded/versionchanged ------------------------------------------- - -def version_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - node = addnodes.versionmodified() - node.document = state.document - node['type'] = name - node['version'] = arguments[0] - if len(arguments) == 2: - inodes, messages = state.inline_text(arguments[1], lineno+1) - node.extend(inodes) - if content: - state.nested_parse(content, content_offset, node) - ret = [node] + messages - else: - ret = [node] - env = state.document.settings.env - env.note_versionchange(node['type'], node['version'], node, lineno) - return ret - -version_directive.arguments = (1, 1, 1) -version_directive.content = 1 - -directives.register_directive('deprecated', version_directive) -directives.register_directive('versionadded', version_directive) -directives.register_directive('versionchanged', version_directive) - - -# ------ see also -------------------------------------------------------------- - -def seealso_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - ret = make_admonition( - addnodes.seealso, name, [_('See also')], options, content, - lineno, content_offset, block_text, state, state_machine) - if arguments: - argnodes, msgs = state.inline_text(arguments[0], lineno) - para = nodes.paragraph() - para += argnodes - para += msgs - ret[0].insert(1, para) - return ret - -seealso_directive.content = 1 -seealso_directive.arguments = (0, 1, 1) -directives.register_directive('seealso', seealso_directive) - + for type in self.indextypes: + if entry.startswith(type+':'): + value = entry[len(type)+1:].strip() + ne.append((type, value, targetid, value)) + break + # shorthand notation for single entries + else: + for value in entry.split(','): + value = value.strip() + if not value: + continue + ne.append(('single', value, targetid, value)) + return [indexnode, targetnode] + + +class VersionChange(Directive): + """ + Directive to describe a change/addition/deprecation in a specific version. + """ + + has_content = True + required_arguments = 1 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = {} + + def run(self): + node = addnodes.versionmodified() + node.document = self.state.document + node['type'] = self.name + node['version'] = self.arguments[0] + if len(self.arguments) == 2: + inodes, messages = self.state.inline_text(self.arguments[1], + self.lineno+1) + node.extend(inodes) + if self.content: + self.state.nested_parse(self.content, self.content_offset, node) + ret = [node] + messages + else: + ret = [node] + env = self.state.document.settings.env + env.note_versionchange(node['type'], node['version'], node, self.lineno) + return ret + + +class SeeAlso(Directive): + """ + An admonition mentioning things to look at as reference. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = {} + + def run(self): + ret = make_admonition( + addnodes.seealso, self.name, [_('See also')], self.options, + self.content, self.lineno, self.content_offset, self.block_text, + self.state, self.state_machine) + if self.arguments: + argnodes, msgs = self.state.inline_text(self.arguments[0], + self.lineno) + para = nodes.paragraph() + para += argnodes + para += msgs + ret[0].insert(1, para) + return ret -# ------ production list (for the reference) ----------------------------------- token_re = re.compile('`([a-z_]+)`') @@ -297,149 +344,202 @@ def token_xrefs(text, env): retnodes.append(nodes.Text(text[pos:], text[pos:])) return retnodes -def productionlist_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env - node = addnodes.productionlist() - messages = [] - i = 0 - - for rule in arguments[0].split('\n'): - if i == 0 and ':' not in rule: - # production group - continue - i += 1 - try: - name, tokens = rule.split(':', 1) - except ValueError: - break - subnode = addnodes.production() - subnode['tokenname'] = name.strip() - if subnode['tokenname']: - idname = 'grammar-token-%s' % subnode['tokenname'] - if idname not in state.document.ids: - subnode['ids'].append(idname) - state.document.note_implicit_target(subnode, subnode) - env.note_reftarget('token', subnode['tokenname'], idname) - subnode.extend(token_xrefs(tokens, env)) - node.append(subnode) - return [node] + messages - -productionlist_directive.content = 0 -productionlist_directive.arguments = (1, 0, 1) -directives.register_directive('productionlist', productionlist_directive) - - -# ------ glossary directive ---------------------------------------------------- - -def glossary_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - """Glossary with cross-reference targets for :term: roles.""" - env = state.document.settings.env - node = addnodes.glossary() - node.document = state.document - state.nested_parse(content, content_offset, node) - - # the content should be definition lists - dls = [child for child in node if isinstance(child, nodes.definition_list)] - # now, extract definition terms to enable cross-reference creation - for dl in dls: - dl['classes'].append('glossary') - for li in dl.children: - if not li.children or not isinstance(li[0], nodes.term): +class ProductionList(Directive): + """ + Directive to list grammar productions. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + env = self.state.document.settings.env + node = addnodes.productionlist() + messages = [] + i = 0 + + for rule in self.arguments[0].split('\n'): + if i == 0 and ':' not in rule: + # production group continue - termtext = li.children[0].astext() - new_id = 'term-' + nodes.make_id(termtext) - if new_id in env.gloss_entries: - new_id = 'term-' + str(len(env.gloss_entries)) - env.gloss_entries.add(new_id) - li[0]['names'].append(new_id) - li[0]['ids'].append(new_id) - state.document.settings.env.note_reftarget('term', termtext.lower(), - new_id) - # add an index entry too - indexnode = addnodes.index() - indexnode['entries'] = [('single', termtext, new_id, termtext)] - li.insert(0, indexnode) - return [node] - -glossary_directive.content = 1 -glossary_directive.arguments = (0, 0, 0) -directives.register_directive('glossary', glossary_directive) - - -# ------ miscellaneous markup -------------------------------------------------- - -def centered_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - if not arguments: - return [] - subnode = addnodes.centered() - inodes, messages = state.inline_text(arguments[0], lineno) - subnode.extend(inodes) - return [subnode] + messages - -centered_directive.arguments = (1, 0, 1) -directives.register_directive('centered', centered_directive) - - -def acks_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - node = addnodes.acks() - node.document = state.document - state.nested_parse(content, content_offset, node) - if len(node.children) != 1 or not isinstance(node.children[0], - nodes.bullet_list): - return [state.document.reporter.warning('.. acks content is not a list', - line=lineno)] - return [node] - -acks_directive.content = 1 -acks_directive.arguments = (0, 0, 0) -directives.register_directive('acks', acks_directive) - - -def hlist_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - ncolumns = options.get('columns', 2) - node = nodes.paragraph() - node.document = state.document - state.nested_parse(content, content_offset, node) - if len(node.children) != 1 or not isinstance(node.children[0], - nodes.bullet_list): - return [state.document.reporter.warning( - '.. hlist content is not a list', line=lineno)] - fulllist = node.children[0] - # create a hlist node where the items are distributed - npercol, nmore = divmod(len(fulllist), ncolumns) - index = 0 - newnode = addnodes.hlist() - for column in range(ncolumns): - endindex = index + (column < nmore and (npercol+1) or npercol) - col = addnodes.hlistcol() - col += nodes.bullet_list() - col[0] += fulllist.children[index:endindex] - index = endindex - newnode += col - return [newnode] - -hlist_directive.content = 1 -hlist_directive.arguments = (0, 0, 0) -hlist_directive.options = {'columns': int} -directives.register_directive('hlist', hlist_directive) - - -def tabularcolumns_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # support giving explicit tabulary column definition to latex - node = addnodes.tabular_col_spec() - node['spec'] = arguments[0] - return [node] - -tabularcolumns_directive.content = 0 -tabularcolumns_directive.arguments = (1, 0, 1) -directives.register_directive('tabularcolumns', tabularcolumns_directive) - + i += 1 + try: + name, tokens = rule.split(':', 1) + except ValueError: + break + subnode = addnodes.production() + subnode['tokenname'] = name.strip() + if subnode['tokenname']: + idname = 'grammar-token-%s' % subnode['tokenname'] + if idname not in self.state.document.ids: + subnode['ids'].append(idname) + self.state.document.note_implicit_target(subnode, subnode) + env.note_reftarget('token', subnode['tokenname'], idname) + subnode.extend(token_xrefs(tokens, env)) + node.append(subnode) + return [node] + messages + + +class Glossary(Directive): + """ + Directive to create a glossary with cross-reference targets + for :term: roles. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + env = self.state.document.settings.env + node = addnodes.glossary() + node.document = self.state.document + self.state.nested_parse(self.content, self.content_offset, node) + + # the content should be definition lists + dls = [child for child in node + if isinstance(child, nodes.definition_list)] + # now, extract definition terms to enable cross-reference creation + for dl in dls: + dl['classes'].append('glossary') + for li in dl.children: + if not li.children or not isinstance(li[0], nodes.term): + continue + termtext = li.children[0].astext() + new_id = 'term-' + nodes.make_id(termtext) + if new_id in env.gloss_entries: + new_id = 'term-' + str(len(env.gloss_entries)) + env.gloss_entries.add(new_id) + li[0]['names'].append(new_id) + li[0]['ids'].append(new_id) + env.note_reftarget('term', termtext.lower(), new_id) + # add an index entry too + indexnode = addnodes.index() + indexnode['entries'] = [('single', termtext, new_id, termtext)] + li.insert(0, indexnode) + return [node] + + +class Centered(Directive): + """ + Directive to create a centered line of bold text. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + if not self.arguments: + return [] + subnode = addnodes.centered() + inodes, messages = self.state.inline_text(self.arguments[0], + self.lineno) + subnode.extend(inodes) + return [subnode] + messages + + + +class Acks(Directive): + """ + Directive for a list of names. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} + + def run(self): + node = addnodes.acks() + node.document = self.state.document + self.state.nested_parse(self.content, self.content_offset, node) + if len(node.children) != 1 or not isinstance(node.children[0], + nodes.bullet_list): + return [self.state.document.reporter.warning( + '.. acks content is not a list', line=self.lineno)] + return [node] + + +class HList(Directive): + """ + Directive for a list that gets compacted horizontally. + """ + + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = { + 'columns': int, + } + + def run(self): + ncolumns = self.options.get('columns', 2) + node = nodes.paragraph() + node.document = self.state.document + self.state.nested_parse(self.content, self.content_offset, node) + if len(node.children) != 1 or not isinstance(node.children[0], + nodes.bullet_list): + return [self.state.document.reporter.warning( + '.. hlist content is not a list', line=self.lineno)] + fulllist = node.children[0] + # create a hlist node where the items are distributed + npercol, nmore = divmod(len(fulllist), ncolumns) + index = 0 + newnode = addnodes.hlist() + for column in range(ncolumns): + endindex = index + (column < nmore and (npercol+1) or npercol) + col = addnodes.hlistcol() + col += nodes.bullet_list() + col[0] += fulllist.children[index:endindex] + index = endindex + newnode += col + return [newnode] + + +class TabularColumns(Directive): + """ + Directive to give an explicit tabulary column definition to LaTeX. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + node = addnodes.tabular_col_spec() + node['spec'] = self.arguments[0] + return [node] + + +directives.register_directive('toctree', TocTree) +directives.register_directive('module', Module) +directives.register_directive('currentmodule', CurrentModule) +directives.register_directive('sectionauthor', Author) +directives.register_directive('moduleauthor', Author) +directives.register_directive('program', Program) +directives.register_directive('index', Index) +directives.register_directive('deprecated', VersionChange) +directives.register_directive('versionadded', VersionChange) +directives.register_directive('versionchanged', VersionChange) +directives.register_directive('seealso', SeeAlso) +directives.register_directive('productionlist', ProductionList) +directives.register_directive('glossary', Glossary) +directives.register_directive('centered', Centered) +directives.register_directive('acks', Acks) +directives.register_directive('hlist', HList) +directives.register_directive('tabularcolumns', TabularColumns) # register the standard rst class directive under a different name -- cgit v1.2.1 From a071068e62710a36d0e2938aff5ecc21c6a763a1 Mon Sep 17 00:00:00 2001 From: mitsuhiko Date: Wed, 18 Feb 2009 21:05:35 +0100 Subject: Fixed a bug in autodoc that caused a type error if automodule was used without members. --- sphinx/ext/autodoc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 82e16e04..192c37e3 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -614,7 +614,7 @@ class ModuleDocumenter(Documenter): else: memberlist = self.options.members ret = [] - for mname in memberlist: + for mname in memberlist or (): try: ret.append((mname, getattr(self.object, mname))) except AttributeError: -- cgit v1.2.1 From d44f67e3afd6f788fc84a770970c6f1eb13be580 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 18 Feb 2009 21:14:14 +0100 Subject: Add more stuff to the autodoc test document, and fix two bugs. --- sphinx/ext/autodoc.py | 7 ++++--- tests/root/autodoc.txt | 21 +++++++++++++++++++++ 2 files changed, 25 insertions(+), 3 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 192c37e3..e0d27458 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -612,9 +612,9 @@ class ModuleDocumenter(Documenter): else: memberlist = self.object.__all__ else: - memberlist = self.options.members + memberlist = self.options.members or [] ret = [] - for mname in memberlist or (): + for mname in memberlist: try: ret.append((mname, getattr(self.object, mname))) except AttributeError: @@ -716,7 +716,8 @@ class ClassDocumenter(ModuleLevelDocumenter): ret = ModuleLevelDocumenter.import_object(self) # if the class is documented under another name, document it # as data/attribute - self.doc_as_attr = (self.objpath[-1] != self.object.__name__) + if ret: + self.doc_as_attr = (self.objpath[-1] != self.object.__name__) return ret def format_args(self): diff --git a/tests/root/autodoc.txt b/tests/root/autodoc.txt index 2b57e0e9..c718feb4 100644 --- a/tests/root/autodoc.txt +++ b/tests/root/autodoc.txt @@ -1,7 +1,28 @@ Autodoc tests ============= +Just testing a few autodoc possibilities... + +.. automodule:: util + .. automodule:: test_autodoc :members: .. autofunction:: function + +.. autoclass:: Class + :inherited-members: + + Additional content. + +.. autoclass:: Outer + :members: Inner + +.. autoattribute:: Class.docattr + +.. autoexception:: CustomEx + :members: f + +.. autoclass:: CustomDict + :show-inheritance: + :members: -- cgit v1.2.1 From 3c566ba9734c38825a4cfc2bcbfee106248efd25 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 18 Feb 2009 21:48:00 +0100 Subject: Convert directives in builtin extensions to class API. --- sphinx/ext/doctest.py | 130 +++++++++++++++++++++++++++---------------------- sphinx/ext/ifconfig.py | 26 +++++++--- sphinx/ext/mathbase.py | 48 +++++++++++------- sphinx/ext/todo.py | 75 ++++++++++++++++++---------- 4 files changed, 167 insertions(+), 112 deletions(-) diff --git a/sphinx/ext/doctest.py b/sphinx/ext/doctest.py index d2aacaa4..51463661 100644 --- a/sphinx/ext/doctest.py +++ b/sphinx/ext/doctest.py @@ -23,6 +23,7 @@ from docutils import nodes from docutils.parsers.rst import directives from sphinx.builders import Builder +from sphinx.util.compat import Directive from sphinx.util.console import bold blankline_re = re.compile(r'^\s*', re.MULTILINE) @@ -30,63 +31,77 @@ doctestopt_re = re.compile(r'#\s*doctest:.+$', re.MULTILINE) # set up the necessary directives -def test_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # use ordinary docutils nodes for test code: they get special attributes - # so that our builder recognizes them, and the other builders are happy. - code = '\n'.join(content) - test = None - if name == 'doctest': - if '' in code: - # convert s to ordinary blank lines for presentation - test = code - code = blankline_re.sub('', code) - if doctestopt_re.search(code): - if not test: - test = code - code = doctestopt_re.sub('', code) - nodetype = nodes.literal_block - if name == 'testsetup' or 'hide' in options: - nodetype = nodes.comment - if arguments: - groups = [x.strip() for x in arguments[0].split(',')] - else: - groups = ['default'] - node = nodetype(code, code, testnodetype=name, groups=groups) - node.line = lineno - if test is not None: - # only save if it differs from code - node['test'] = test - if name == 'testoutput': - # don't try to highlight output - node['language'] = 'none' - node['options'] = {} - if name in ('doctest', 'testoutput') and 'options' in options: - # parse doctest-like output comparison flags - option_strings = options['options'].replace(',', ' ').split() - for option in option_strings: - if (option[0] not in '+-' or option[1:] not in - doctest.OPTIONFLAGS_BY_NAME): - # XXX warn? - continue - flag = doctest.OPTIONFLAGS_BY_NAME[option[1:]] - node['options'][flag] = (option[0] == '+') - return [node] +class TestDirective(Directive): + """ + Base class for doctest-related directives. + """ -# need to have individual functions for each directive due to different -# options they accept + has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + + def run(self): + # use ordinary docutils nodes for test code: they get special attributes + # so that our builder recognizes them, and the other builders are happy. + code = '\n'.join(self.content) + test = None + if self.name == 'doctest': + if '' in code: + # convert s to ordinary blank lines for presentation + test = code + code = blankline_re.sub('', code) + if doctestopt_re.search(code): + if not test: + test = code + code = doctestopt_re.sub('', code) + nodetype = nodes.literal_block + if self.name == 'testsetup' or 'hide' in self.options: + nodetype = nodes.comment + if self.arguments: + groups = [x.strip() for x in self.arguments[0].split(',')] + else: + groups = ['default'] + node = nodetype(code, code, testnodetype=self.name, groups=groups) + node.line = self.lineno + if test is not None: + # only save if it differs from code + node['test'] = test + if self.name == 'testoutput': + # don't try to highlight output + node['language'] = 'none' + node['options'] = {} + if self.name in ('doctest', 'testoutput') and 'options' in self.options: + # parse doctest-like output comparison flags + option_strings = self.options['options'].replace(',', ' ').split() + for option in option_strings: + if (option[0] not in '+-' or option[1:] not in + doctest.OPTIONFLAGS_BY_NAME): + # XXX warn? + continue + flag = doctest.OPTIONFLAGS_BY_NAME[option[1:]] + node['options'][flag] = (option[0] == '+') + return [node] -def testsetup_directive(*args): - return test_directive(*args) +class TestsetupDirective(TestDirective): + option_spec = {} -def doctest_directive(*args): - return test_directive(*args) +class DoctestDirective(TestDirective): + option_spec = { + 'hide': directives.flag, + 'options': directives.unchanged, + } -def testcode_directive(*args): - return test_directive(*args) +class TestcodeDirective(TestDirective): + option_spec = { + 'hide': directives.flag, + } -def testoutput_directive(*args): - return test_directive(*args) +class TestoutputDirective(TestDirective): + option_spec = { + 'hide': directives.flag, + 'options': directives.unchanged, + } parser = doctest.DocTestParser() @@ -334,13 +349,10 @@ Doctest summary def setup(app): - app.add_directive('testsetup', testsetup_directive, 1, (0, 1, 1)) - app.add_directive('doctest', doctest_directive, 1, (0, 1, 1), - hide=directives.flag, options=directives.unchanged) - app.add_directive('testcode', testcode_directive, 1, (0, 1, 1), - hide=directives.flag) - app.add_directive('testoutput', testoutput_directive, 1, (0, 1, 1), - hide=directives.flag, options=directives.unchanged) + app.add_directive('testsetup', TestsetupDirective) + app.add_directive('doctest', DoctestDirective) + app.add_directive('testcode', TestcodeDirective) + app.add_directive('testoutput', TestoutputDirective) app.add_builder(DocTestBuilder) # this config value adds to sys.path app.add_config_value('doctest_path', [], False) diff --git a/sphinx/ext/ifconfig.py b/sphinx/ext/ifconfig.py index af3975b8..90cd2b2c 100644 --- a/sphinx/ext/ifconfig.py +++ b/sphinx/ext/ifconfig.py @@ -22,17 +22,27 @@ from docutils import nodes +from sphinx.util.compat import Directive + class ifconfig(nodes.Element): pass -def ifconfig_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - node = ifconfig() - node.line = lineno - node['expr'] = arguments[0] - state.nested_parse(content, content_offset, node) - return [node] +class IfConfig(Directive): + + has_content = True + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + node = ifconfig() + node.document = self.state.document + node.line = self.lineno + node['expr'] = self.arguments[0] + self.state.nested_parse(self.content, self.content_offset, node) + return [node] def process_ifconfig_nodes(app, doctree, docname): @@ -58,5 +68,5 @@ def process_ifconfig_nodes(app, doctree, docname): def setup(app): app.add_node(ifconfig) - app.add_directive('ifconfig', ifconfig_directive, 1, (1, 0, 1)) + app.add_directive('ifconfig', IfConfig) app.connect('doctree-resolved', process_ifconfig_nodes) diff --git a/sphinx/ext/mathbase.py b/sphinx/ext/mathbase.py index 12af089d..fea786e3 100644 --- a/sphinx/ext/mathbase.py +++ b/sphinx/ext/mathbase.py @@ -12,6 +12,8 @@ from docutils import nodes, utils from docutils.parsers.rst import directives +from sphinx.util.compat import Directive + class math(nodes.Inline, nodes.TextElement): pass @@ -45,22 +47,33 @@ def eq_role(role, rawtext, text, lineno, inliner, options={}, content=[]): node['docname'] = inliner.document.settings.env.docname return [node], [] -def math_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - latex = '\n'.join(content) - if arguments and arguments[0]: - latex = arguments[0] + '\n\n' + latex - node = displaymath() - node['latex'] = latex - node['label'] = options.get('label', None) - node['nowrap'] = 'nowrap' in options - node['docname'] = state.document.settings.env.docname - ret = [node] - if node['label']: - tnode = nodes.target('', '', ids=['equation-' + node['label']]) - state.document.note_explicit_target(tnode) - ret.insert(0, tnode) - return ret + +class MathDirective(Directive): + + has_content = True + required_arguments = 0 + optional_arguments = 1 + final_argument_whitespace = True + option_spec = { + 'label': directives.unchanged, + 'nowrap': directives.flag, + } + + def run(self): + latex = '\n'.join(self.content) + if self.arguments and self.arguments[0]: + latex = self.arguments[0] + '\n\n' + latex + node = displaymath() + node['latex'] = latex + node['label'] = self.options.get('label', None) + node['nowrap'] = 'nowrap' in self.options + node['docname'] = self.state.document.settings.env.docname + ret = [node] + if node['label']: + tnode = nodes.target('', '', ids=['equation-' + node['label']]) + self.state.document.note_explicit_target(tnode) + ret.insert(0, tnode) + return ret def latex_visit_math(self, node): @@ -134,6 +147,5 @@ def setup(app, htmlinlinevisitors, htmldisplayvisitors): html=(html_visit_eqref, html_depart_eqref)) app.add_role('math', math_role) app.add_role('eq', eq_role) - app.add_directive('math', math_directive, 1, (0, 1, 1), - label=directives.unchanged, nowrap=directives.flag) + app.add_directive('math', MathDirective) app.connect('doctree-resolved', number_equations) diff --git a/sphinx/ext/todo.py b/sphinx/ext/todo.py index 7294e4f9..61dd4d67 100644 --- a/sphinx/ext/todo.py +++ b/sphinx/ext/todo.py @@ -14,42 +14,63 @@ from docutils import nodes -from sphinx.util.compat import make_admonition +from sphinx.util.compat import Directive, make_admonition class todo_node(nodes.Admonition, nodes.Element): pass class todolist(nodes.General, nodes.Element): pass -def todo_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env +class Todo(Directive): + """ + A todo entry, displayed (if configured) in the form of an admonition. + """ - targetid = "todo-%s" % env.index_num - env.index_num += 1 - targetnode = nodes.target('', '', ids=[targetid]) + has_content = True + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} - ad = make_admonition(todo_node, name, [_('Todo')], options, content, lineno, - content_offset, block_text, state, state_machine) + def run(self): + env = self.state.document.settings.env + + targetid = "todo-%s" % env.index_num + env.index_num += 1 + targetnode = nodes.target('', '', ids=[targetid]) + + ad = make_admonition(todo_node, self.name, [_('Todo')], self.options, + self.content, self.lineno, self.content_offset, + self.block_text, self.state, self.state_machine) + + # Attach a list of all todos to the environment, + # the todolist works with the collected todo nodes + if not hasattr(env, 'todo_all_todos'): + env.todo_all_todos = [] + env.todo_all_todos.append({ + 'docname': env.docname, + 'lineno': self.lineno, + 'todo': ad[0].deepcopy(), + 'target': targetnode, + }) + + return [targetnode] + ad - # Attach a list of all todos to the environment, - # the todolist works with the collected todo nodes - if not hasattr(env, 'todo_all_todos'): - env.todo_all_todos = [] - env.todo_all_todos.append({ - 'docname': env.docname, - 'lineno': lineno, - 'todo': ad[0].deepcopy(), - 'target': targetnode, - }) - return [targetnode] + ad +class TodoList(Directive): + """ + A list of all todo entries. + """ + has_content = False + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + option_spec = {} -def todolist_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - # Simply insert an empty todolist node which will be replaced later - # when process_todo_nodes is called - return [todolist('')] + def run(self): + # Simply insert an empty todolist node which will be replaced later + # when process_todo_nodes is called + return [todolist('')] def process_todo_nodes(app, doctree, fromdocname): @@ -119,8 +140,8 @@ def setup(app): latex=(visit_todo_node, depart_todo_node), text=(visit_todo_node, depart_todo_node)) - app.add_directive('todo', todo_directive, 1, (0, 0, 1)) - app.add_directive('todolist', todolist_directive, 0, (0, 0, 0)) + app.add_directive('todo', Todo) + app.add_directive('todolist', TodoList) app.connect('doctree-resolved', process_todo_nodes) app.connect('env-purge-doc', purge_todos) -- cgit v1.2.1 From 99cd1e2e0b67d41ed8319591d255df626193cf2b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 18 Feb 2009 21:49:37 +0100 Subject: Fix #105: one shouldn't use the i18n function as a placeholder... --- sphinx/directives/desc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index e45042b9..c7c05959 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -603,7 +603,7 @@ class GenericDesc(DescDirective): return name def add_target_and_index(self, name, sig, signode): - rolename, indextemplate, _ = additional_xref_types[self.desctype] + rolename, indextemplate = additional_xref_types[self.desctype][:2] targetname = '%s-%s' % (rolename, name) signode['ids'].append(targetname) self.state.document.note_explicit_target(signode) -- cgit v1.2.1 From 5ce51fe2e2bc0e525a79f1bda7eba2f25825adb7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 18 Feb 2009 22:12:03 +0100 Subject: Test add_description_unit in test suite. --- tests/root/conf.py | 11 +++++++++++ tests/root/desc.txt | 11 +++++++++++ tests/test_build.py | 8 +++++--- 3 files changed, 27 insertions(+), 3 deletions(-) diff --git a/tests/root/conf.py b/tests/root/conf.py index ace6ac6c..9ccbbb87 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -48,5 +48,16 @@ coverage_c_path = ['special/*.h'] coverage_c_regexes = {'cfunction': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'} +from sphinx import addnodes + +def userdesc_parse(env, sig, signode): + x, y = sig.split(':') + signode += addnodes.desc_name(x, x) + signode += addnodes.desc_parameterlist() + signode[-1] += addnodes.desc_parameter(y, y) + return x + def setup(app): app.add_config_value('value_from_conf_py', 42, False) + app.add_description_unit('userdesc', 'userdescrole', '%s (userdesc)', + userdesc_parse) diff --git a/tests/root/desc.txt b/tests/root/desc.txt index beb470b6..d6915dc2 100644 --- a/tests/root/desc.txt +++ b/tests/root/desc.txt @@ -58,3 +58,14 @@ Testing references ================== Referencing :class:`mod.Cls` or :Class:`mod.Cls` should be the same. + + +User markup +=========== + +.. userdesc:: myobj:parameter + + Description of userdesc. + + +Referencing :userdescrole:`myobj`. diff --git a/tests/test_build.py b/tests/test_build.py index 326a4bd6..5b84a9da 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -88,6 +88,9 @@ HTML_XPATH = { ".//dt[@id='mod.Cls.meth1']": '', ".//dt[@id='errmod.Error']": '', ".//a[@href='#mod.Cls']": '', + ".//dl[@class='userdesc']": '', + ".//dt[@id='userdescrole-myobj']": '', + ".//a[@href='#userdescrole-myobj']": '', }, 'contents.html': { ".//meta[@name='hc'][@content='hcval']": '', @@ -147,9 +150,8 @@ def test_html(app): etree = ET.parse(os.path.join(app.outdir, fname), parser) for path, check in paths.iteritems(): nodes = list(etree.findall(path)) - if not nodes: - import pdb; pdb.set_trace() - assert nodes != [] + assert nodes != [], ('did not find any node matching xpath ' + '%r in file %s' % (path, fname)) if hasattr(check, '__call__'): check(nodes) elif not check: -- cgit v1.2.1 From b8d44e256e70bfdc77aaac0c0c80380a0e22baae Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 18 Feb 2009 23:49:51 +0100 Subject: Add docstrings to autodoc. --- sphinx/ext/autodoc.py | 145 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 133 insertions(+), 12 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index e0d27458..eafe167d 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -34,6 +34,7 @@ except NameError: base_exception = Exception +#: extended signature RE: with explicit module name separated by :: py_ext_sig_re = re.compile( r'''^ ([\w.]+::)? # explicit module name ([\w.]+\.)? # module and/or class name(s) @@ -45,6 +46,7 @@ py_ext_sig_re = re.compile( class DefDict(dict): + """A dict that returns a default on nonexisting keys.""" def __init__(self, default): dict.__init__(self) self.default = default @@ -61,21 +63,25 @@ identity = lambda x: x class Options(dict): + """A dict/attribute hybrid that returns None on nonexisting keys.""" def __getattr__(self, name): try: return self[name.replace('_', '-')] except KeyError: - return False + return None ALL = object() def members_option(arg): + """Used to convert the :members: option to auto directives.""" if arg is None: return ALL return [x.strip() for x in arg.split(',')] def bool_option(arg): + """Used to convert flag options to auto directives. (Instead of + directives.flag(), which returns None.)""" return True @@ -191,12 +197,30 @@ def isdescriptor(x): class Documenter(object): - # name by which the directive is called (auto...) and the default - # generated directive name + """ + A Documenter knows how to autodocument a single object type. When + registered with the AutoDirective, it will be used to document objects + of that type when needed by autodoc. + + Its *objtype* attribute selects what auto directive it is assigned to + (the directive name is 'auto' + objtype), and what directive it generates + by default, though that can be overridden by an attribute called + *directivetype*. + + A Documenter has an *option_spec* that works like a docutils directive's; + in fact, it will be used to parse an auto directive's options that matches + the documenter. + + The *special_attrgetters* attribute is used to customize ``getattr()`` + calls that the Documenter makes; its entries are of the form + ``type: getattr_function``. + """ + #: name by which the directive is called (auto...) and the default + #: generated directive name objtype = 'object' - # indentation by which to indent the directive content + #: indentation by which to indent the directive content content_indent = u' ' - # priority if multiple documenters return True from can_document_member + #: priority if multiple documenters return True from can_document_member priority = 0 option_spec = {'noindex': bool_option} @@ -238,16 +262,26 @@ class Documenter(object): self.analyzer = None def add_line(self, line, source, *lineno): + """Append one line of generated reST to the output.""" self.directive.result.append(self.indent + line, source, *lineno) def resolve_name(self, modname, parents, path, base): + """ + Resolve the module and name of the object to document given by the + arguments and the current module/class. + + Must return a pair of the module name and a chain of attributes; for + example, it would return ``('zipfile', ['ZipFile', 'open'])`` for the + ``zipfile.ZipFile.open`` method. + """ raise NotImplementedError('must be implemented in subclasses') def parse_name(self): """ Determine what module to import and what attribute to document. - Returns True if parsing and resolving was successful. + Returns True and sets *self.modname*, *self.objpath*, *self.fullname*, + *self.args* and *self.retann* if parsing and resolving was successful. """ # first, parse the definition -- auto directives for classes and # functions can contain a signature which is then used instead of @@ -276,11 +310,17 @@ class Documenter(object): self.args = args self.retann = retann - self.fullname = (self.modname or '') + (self.objpath and - '.' + '.'.join(self.objpath) or '') + self.fullname = (self.modname or '') + \ + (self.objpath and '.' + '.'.join(self.objpath) or '') return True def import_object(self): + """ + Import the object given by *self.modname* and *self.objpath* and sets + it as *self.object*. + + Returns True if successful, False if an error occurred. + """ try: __import__(self.modname) obj = self.module = sys.modules[self.modname] @@ -296,18 +336,34 @@ class Documenter(object): return False def get_real_modname(self): + """ + Get the real module name of an object to document. (It can differ + from the name of the module through which the object was imported.) + """ return self.get_attr(self.object, '__module__', None) or self.modname def check_module(self): + """ + Check if *self.object* is really defined in the module given by + *self.modname*. + """ modname = self.get_attr(self.object, '__module__', None) if modname and modname != self.modname: return False return True def format_args(self): + """ + Format the argument signature of *self.object*. Should return None if + the object does not have a signature. + """ return None def format_signature(self): + """ + Format the signature (arguments and return annotation) of the object. + Let the user process it via the ``autodoc-process-signature`` event. + """ if self.args is not None: # signature given explicitly args = "(%s)" % self.args @@ -330,6 +386,7 @@ class Documenter(object): return '' def add_directive_header(self, sig): + """Add the directive header and options to the generated content.""" directive = getattr(self, 'directivetype', self.objtype) # the name to put into the generated directive -- doesn't contain # the module (except for module directive of course) @@ -353,7 +410,7 @@ class Documenter(object): return [] def process_doc(self, docstrings): - """Let the user process the docstrings.""" + """Let the user process the docstrings before adding them.""" for docstringlines in docstrings: if self.env.app: # let extensions preprocess docstrings @@ -364,6 +421,7 @@ class Documenter(object): yield line def add_content(self, more_content, no_docstring=False): + """Add content from docstrings, attribute documentation and user.""" # set sourcename and add content from attribute documentation if self.analyzer: # prevent encoding errors when the file name is non-ASCII @@ -395,6 +453,12 @@ class Documenter(object): self.add_line(line, src[0], src[1]) def get_object_members(self, want_all): + """ + Return (membername, member) pairs of the members of *self.object*. + + If *want_all* is True, return all members. Else, only return those + members given by *self.options.members* (which may also be none). + """ if not want_all: if not self.options.members: return False, [] @@ -419,6 +483,15 @@ class Documenter(object): for mname in self.object.__dict__]) def filter_members(self, members, want_all): + """ + Filter the given member list: members are skipped if + + - they are private (except if given explicitly) + - they are undocumented (except if undoc-members is given) + + The user can override the skipping decision by connecting to the + ``autodoc-skip-member`` event. + """ ret = [] # search for members in source code too @@ -464,6 +537,10 @@ class Documenter(object): return ret def document_members(self, all_members=False): + """ + Generate reST for member documentation. If *all_members* is True, + do all members, else those given by *self.options.members*. + """ # set current namespace for finding members self.env.autodoc_current_module = self.modname if self.objpath: @@ -499,6 +576,14 @@ class Documenter(object): def generate(self, more_content=None, real_modname=None, check_module=False, all_members=False): + """ + Generate reST for the object given by *self.name*, and possibly members. + + If *more_content* is given, include that content. If *real_modname* is + given, use that module name to find attribute docs. If *check_module* is + True, only generate if the object is defined in the module name it is + imported from. If *all_members* is True, document all members. + """ if not self.parse_name(): # need a module to import self.directive.warn( @@ -563,6 +648,9 @@ class Documenter(object): class ModuleDocumenter(Documenter): + """ + Specialized Documenter subclass for modules. + """ objtype = 'module' content_indent = u'' @@ -625,6 +713,10 @@ class ModuleDocumenter(Documenter): class ModuleLevelDocumenter(Documenter): + """ + Specialized Documenter subclass for objects on module level (functions, + classes, data/constants). + """ def resolve_name(self, modname, parents, path, base): if modname is None: if path: @@ -642,6 +734,10 @@ class ModuleLevelDocumenter(Documenter): class ClassLevelDocumenter(Documenter): + """ + Specialized Documenter subclass for objects on class level (methods, + attributes). + """ def resolve_name(self, modname, parents, path, base): if modname is None: if path: @@ -671,6 +767,9 @@ class ClassLevelDocumenter(Documenter): class FunctionDocumenter(ModuleLevelDocumenter): + """ + Specialized Documenter subclass for functions. + """ objtype = 'function' @classmethod @@ -701,6 +800,9 @@ class FunctionDocumenter(ModuleLevelDocumenter): class ClassDocumenter(ModuleLevelDocumenter): + """ + Specialized Documenter subclass for classes. + """ objtype = 'class' option_spec = { 'members': members_option, 'undoc-members': bool_option, @@ -795,6 +897,9 @@ class ClassDocumenter(ModuleLevelDocumenter): class ExceptionDocumenter(ClassDocumenter): + """ + Specialized ClassDocumenter subclass for exceptions. + """ objtype = 'exception' # needs a higher priority than ClassDocumenter @@ -807,6 +912,9 @@ class ExceptionDocumenter(ClassDocumenter): class DataDocumenter(ModuleLevelDocumenter): + """ + Specialized Documenter subclass for data items. + """ objtype = 'data' @classmethod @@ -818,6 +926,9 @@ class DataDocumenter(ModuleLevelDocumenter): class MethodDocumenter(ClassLevelDocumenter): + """ + Specialized Documenter subclass for methods (normal, static and class). + """ objtype = 'method' @classmethod @@ -855,6 +966,9 @@ class MethodDocumenter(ClassLevelDocumenter): class AttributeDocumenter(ClassLevelDocumenter): + """ + Specialized Documenter subclass for attributes. + """ objtype = 'attribute' @classmethod @@ -867,6 +981,11 @@ class AttributeDocumenter(ClassLevelDocumenter): class AutoDirective(Directive): + """ + The AutoDirective class is used for all autodoc directives. It dispatches + most of the work to one of the Documenters, which it selects through its + *_registry* dictionary. + """ # a registry of objtype -> documenter class _registry = {} @@ -920,12 +1039,14 @@ class AutoDirective(Directive): def add_documenter(cls): + """Register a new Documenter.""" if not issubclass(cls, Documenter): raise ExtensionError('autodoc documenter %r must be a subclass ' 'of Documenter' % cls) - if cls.objtype in AutoDirective._registry: - raise ExtensionError('autodoc documenter for %r is already ' - 'registered' % cls.objtype) + # actually, it should be possible to override Documenters + #if cls.objtype in AutoDirective._registry: + # raise ExtensionError('autodoc documenter for %r is already ' + # 'registered' % cls.objtype) AutoDirective._registry[cls.objtype] = cls -- cgit v1.2.1 From 2997b9f44893f6e39ad953e64f077783d1c49b39 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 00:07:47 +0100 Subject: Add DirectoryHTMLBuilder (contributed as PrettyHTMLBuilder by Will Maier). --- AUTHORS | 1 + CHANGES | 7 ++++++- doc/Makefile | 9 ++++++++- doc/builders.rst | 13 +++++++++++++ sphinx/builders/__init__.py | 1 + sphinx/builders/html.py | 34 +++++++++++++++++++++++++++++++--- sphinx/quickstart.py | 17 ++++++++++++++++- 7 files changed, 76 insertions(+), 6 deletions(-) diff --git a/AUTHORS b/AUTHORS index c13d267e..0d8afda5 100644 --- a/AUTHORS +++ b/AUTHORS @@ -11,6 +11,7 @@ Other contributors, listed alphabetically, are: * Martin Hans -- autodoc improvements * Dave Kuhlman -- original LaTeX writer * Thomas Lamb -- linkcheck builder +* Will Maier -- directory HTML builder * Benjamin Peterson -- unittests * Stefan Seefeld -- toctree improvements * Antonio Valentino -- qthelp builder diff --git a/CHANGES b/CHANGES index 510738b4..8170cb94 100644 --- a/CHANGES +++ b/CHANGES @@ -25,7 +25,7 @@ New features added if name.startswith('_'): return True -* Theming support. +* Theming support, see the new section in the documentation. * Markup: @@ -98,6 +98,11 @@ New features added - New builder for Qt help collections, by Antonio Valentino. + - The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates + a separate directory for every page, and places the page there + in a file called ``index.html``. Therefore, page URLs and links + don't need to contain ``.html``. + - The new ``html_link_suffix`` config value can be used to select the suffix of generated links between HTML files. diff --git a/doc/Makefile b/doc/Makefile index 6da1654b..07cee744 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -11,11 +11,12 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d _build/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) . -.PHONY: help clean html pickle htmlhelp qthelp latex changes linkcheck doctest +.PHONY: help clean html dirhtml pickle htmlhelp qthelp latex changes linkcheck doctest help: @echo "Please use \`make ' where is one of" @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files called index.html in directories" @echo " pickle to make pickle files" @echo " htmlhelp to make HTML files and a HTML help project" @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" @@ -31,6 +32,12 @@ html: @echo @echo "Build finished. The HTML pages are in _build/html." +dirhtml: + mkdir -p _build/dirhtml _build/doctrees + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) _build/dirhtml + @echo + @echo "Build finished. The HTML pages are in _build/dirhtml." + text: mkdir -p _build/text _build/doctrees $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) _build/text diff --git a/doc/builders.rst b/doc/builders.rst index 0055a28b..bee0094c 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -23,6 +23,19 @@ The builder's "name" must be given to the **-b** command-line option of Its name is ``html``. +.. class:: DirectoryHTMLBuilder + + This is a subclass of the standard HTML builder. Its output is a directory + with HTML files, where each file is called ``index.html`` and placed in a + subdirectory named like its page name. For example, the document + ``markup/rest.rst`` will not result in an output file ``markup/rest.html``, + but ``markup/rest/index.html``. When generating links between pages, the + ``index.html`` is omitted, so that the URL would look like ``markup/rest/``. + + Its name is ``dirhtml``. + + .. versionadded:: 0.6 + .. class:: HTMLHelpBuilder This builder produces the same output as the standalone HTML builder, but diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 46054460..19699033 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -352,6 +352,7 @@ class Builder(object): BUILTIN_BUILDERS = { 'html': ('html', 'StandaloneHTMLBuilder'), + 'dirhtml': ('html', 'DirectoryHTMLBuilder'), 'pickle': ('html', 'PickleHTMLBuilder'), 'json': ('html', 'JSONHTMLBuilder'), 'web': ('html', 'PickleHTMLBuilder'), diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 61c0c0b1..93f5181c 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -560,6 +560,9 @@ class StandaloneHTMLBuilder(Builder): return self.render_partial(self.env.get_toctree_for( docname, self, collapse))['fragment'] + def get_outfilename(self, pagename): + return path.join(self.outdir, os_path(pagename) + self.out_suffix) + # --------- these are overwritten by the serialization builder def get_target_uri(self, docname, typ=None): @@ -587,8 +590,7 @@ class StandaloneHTMLBuilder(Builder): output = self.templates.render(templatename, ctx) if not outfilename: - outfilename = path.join(self.outdir, - os_path(pagename) + self.out_suffix) + outfilename = self.get_outfilename(pagename) # outfilename's path is in general different from self.outdir ensuredir(path.dirname(outfilename)) try: @@ -636,9 +638,35 @@ class StandaloneHTMLBuilder(Builder): self.info('done') +class DirectoryHTMLBuilder(StandaloneHTMLBuilder): + """ + A StandaloneHTMLBuilder that creates all HTML pages as "index.html" in + a directory given by their pagename, so that generated URLs don't have + ``.html`` in them. + """ + name = 'dirhtml' + + def get_target_uri(self, docname, typ=None): + if docname == 'index': + return '' + if docname.endswith(SEP + 'index'): + return docname[:-5] # up to sep + return docname + SEP + + def get_outfilename(self, pagename): + if pagename == 'index' or pagename.endswith(SEP + 'index'): + outfilename = path.join(self.outdir, os_path(pagename) + + self.out_suffix) + else: + outfilename = path.join(self.outdir, os_path(pagename), + 'index' + self.out_suffix) + + return outfilename + + class SerializingHTMLBuilder(StandaloneHTMLBuilder): """ - An abstract builder that serializes the HTML generated. + An abstract builder that serializes the generated HTML. """ #: the serializing implementation to use. Set this to a module that #: implements a `dump`, `load`, `dumps` and `loads` functions diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index d2a1c62d..d3cf18c5 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -263,11 +263,13 @@ PAPEROPT_letter = -D latex_paper_size=letter ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) \ $(SPHINXOPTS) %(rsrcdir)s -.PHONY: help clean html pickle json htmlhelp qthelp latex changes linkcheck doctest +.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes \ +linkcheck doctest help: \t@echo "Please use \\`make ' where is one of" \t@echo " html to make standalone HTML files" +\t@echo " dirhtml to make HTML files named index.html in directories" \t@echo " pickle to make pickle files" \t@echo " json to make JSON files" \t@echo " htmlhelp to make HTML files and a HTML help project" @@ -285,6 +287,11 @@ html: \t@echo \t@echo "Build finished. The HTML pages are in %(rbuilddir)s/html." +dirhtml: +\t$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) %(rbuilddir)s/dirhtml +\t@echo +\t@echo "Build finished. The HTML pages are in %(rbuilddir)s/dirhtml." + pickle: \t$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) %(rbuilddir)s/pickle \t@echo @@ -351,6 +358,7 @@ if "%%1" == "help" ( \t:help \techo.Please use `make ^` where ^ is one of \techo. html to make standalone HTML files +\techo. dirhtml to make HTML files named index.html in directories \techo. pickle to make pickle files \techo. json to make JSON files \techo. htmlhelp to make HTML files and a HTML help project @@ -375,6 +383,13 @@ if "%%1" == "html" ( \tgoto end ) +if "%%1" == "dirhtml" ( +\t%%SPHINXBUILD%% -b dirhtml %%ALLSPHINXOPTS%% %(rbuilddir)s/dirhtml +\techo. +\techo.Build finished. The HTML pages are in %(rbuilddir)s/dirhtml. +\tgoto end +) + if "%%1" == "pickle" ( \t%%SPHINXBUILD%% -b pickle %%ALLSPHINXOPTS%% %(rbuilddir)s/pickle \techo. -- cgit v1.2.1 From aab4b1967041f5687b718f458baaf2f80710bdc5 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 16:15:36 +0100 Subject: The HTML builder now stores a small file named ``.buildinfo`` in its output directory. It stores a hash of config values that can be used to determine if a full rebuild needs to be done (e.g. after changing ``html_theme``). --- CHANGES | 5 ++ doc/conf.py | 2 +- doc/ext/appapi.rst | 17 +++++-- sphinx/application.py | 6 ++- sphinx/builders/html.py | 93 +++++++++++++++++++++++++--------- sphinx/config.py | 132 ++++++++++++++++++++++++------------------------ sphinx/environment.py | 4 +- 7 files changed, 160 insertions(+), 99 deletions(-) diff --git a/CHANGES b/CHANGES index 8170cb94..8085b39f 100644 --- a/CHANGES +++ b/CHANGES @@ -96,6 +96,11 @@ New features added * Builders: + - The HTML builder now stores a small file named ``.buildinfo`` in + its output directory. It stores a hash of config values that + can be used to determine if a full rebuild needs to be done (e.g. + after changing ``html_theme``). + - New builder for Qt help collections, by Antonio Valentino. - The new ``DirectoryHTMLBuilder`` (short name ``dirhtml``) creates diff --git a/doc/conf.py b/doc/conf.py index e1a48aa2..a86f8648 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -31,7 +31,7 @@ release = version show_authors = True # The HTML template theme. -html_theme = 'sphinxdoc' +html_theme = 'default' # A list of ignored prefixes names for module index sorting. modindex_common_prefix = ['sphinx.'] diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index aad41e35..b23b6774 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -15,20 +15,29 @@ the following public API: Register a new builder. *builder* must be a class that inherits from :class:`~sphinx.builders.Builder`. -.. method:: Sphinx.add_config_value(name, default, rebuild_env) +.. method:: Sphinx.add_config_value(name, default, rebuild) Register a configuration value. This is necessary for Sphinx to recognize new values and set default values accordingly. The *name* should be prefixed with the extension name, to avoid clashes. The *default* value can be any - Python object. The boolean value *rebuild_env* must be ``True`` if a change - in the setting only takes effect when a document is parsed -- this means that - the whole environment must be rebuilt. + Python object. The string value *rebuild* must be one of those values: + + * ``'env'`` if a change in the setting only takes effect when a document is + parsed -- this means that the whole environment must be rebuilt. + * ``'html'`` if a change in the setting needs a full rebuild of HTML + documents. + * ``''`` if a change in the setting will not need any special rebuild. .. versionchanged:: 0.4 If the *default* value is a callable, it will be called with the config object as its argument in order to get the default value. This can be used to implement config values whose default depends on other values. + .. versionchanged:: 0.6 + Changed *rebuild* from a simple boolean (equivalent to ``''`` or + ``'env'``) to a string. However, booleans are still accepted and + converted internally. + .. method:: Sphinx.add_event(name) Register an event called *name*. diff --git a/sphinx/application.py b/sphinx/application.py index f221e1c7..45c340d2 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -260,10 +260,12 @@ class Sphinx(object): builder.name, self.builderclasses[builder.name].__module__)) self.builderclasses[builder.name] = builder - def add_config_value(self, name, default, rebuild_env): + def add_config_value(self, name, default, rebuild): if name in self.config.values: raise ExtensionError('Config value %r already present' % name) - self.config.values[name] = (default, rebuild_env) + if rebuild in (False, True): + rebuild = rebuild and 'env' or '' + self.config.values[name] = (default, rebuild) def add_event(self, name): if name in self._events: diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 93f5181c..234c1fb9 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -15,6 +15,13 @@ import shutil import posixpath import cPickle as pickle from os import path +try: + import hashlib + md5 = hashlib.md5 +except ImportError: + # 2.4 compatibility + import md5 + md5 = md5.new from docutils import nodes from docutils.io import DocTreeInput, StringOutput @@ -67,6 +74,8 @@ class StandaloneHTMLBuilder(Builder): script_files = ['_static/jquery.js', '_static/doctools.js'] def init(self): + # a hash of all config values that, if changed, cause a full rebuild + self.config_hash = '' self.init_templates() self.init_highlighter() self.init_translator_class() @@ -102,6 +111,55 @@ class StandaloneHTMLBuilder(Builder): else: self.translator_class = HTMLTranslator + def get_outdated_docs(self): + cfgdict = dict((name, self.config[name]) + for (name, desc) in self.config.values.iteritems() + if desc[1] == 'html') + self.config_hash = md5(str(cfgdict)).hexdigest() + try: + fp = open(path.join(self.outdir, '.buildinfo')) + version = fp.readline() + if version.rstrip() != '# Sphinx build info version 1': + raise ValueError + fp.readline() # skip commentary + cfg, old_hash = fp.readline().strip().split(': ') + if cfg != 'config': + raise ValueError + fp.close() + except ValueError: + self.warn('unsupported build info format in %r, building all' % + path.join(self.outdir, '.buildinfo')) + old_hash = '' + except Exception: + old_hash = '' + if old_hash != self.config_hash: + for docname in self.env.found_docs: + yield docname + return + + if self.templates: + template_mtime = self.templates.newest_template_mtime() + else: + template_mtime = 0 + for docname in self.env.found_docs: + if docname not in self.env.all_docs: + yield docname + continue + targetname = self.env.doc2path(docname, self.outdir, + self.out_suffix) + try: + targetmtime = path.getmtime(targetname) + except Exception: + targetmtime = 0 + try: + srcmtime = max(path.getmtime(self.env.doc2path(docname)), + template_mtime) + if srcmtime > targetmtime: + yield docname + except EnvironmentError: + # source doesn't exist anymore + pass + def render_partial(self, node): """Utility: Render a lone doctree node.""" doc = new_document('') @@ -479,6 +537,17 @@ class StandaloneHTMLBuilder(Builder): logobase = path.basename(self.config.html_logo) shutil.copyfile(path.join(self.confdir, self.config.html_logo), path.join(self.outdir, '_static', logobase)) + + # write build info file + fp = open(path.join(self.outdir, '.buildinfo'), 'w') + try: + fp.write('# Sphinx build info version 1\n' + '# This file hashes the configuration used when building' + ' these files. When it is not found, a full rebuild will' + ' be done.\nconfig: %s\n' % self.config_hash) + finally: + fp.close() + self.info('done') # dump the search index @@ -511,30 +580,6 @@ class StandaloneHTMLBuilder(Builder): node.replace_self(reference) reference.append(node) - def get_outdated_docs(self): - if self.templates: - template_mtime = self.templates.newest_template_mtime() - else: - template_mtime = 0 - for docname in self.env.found_docs: - if docname not in self.env.all_docs: - yield docname - continue - targetname = self.env.doc2path(docname, self.outdir, - self.out_suffix) - try: - targetmtime = path.getmtime(targetname) - except Exception: - targetmtime = 0 - try: - srcmtime = max(path.getmtime(self.env.doc2path(docname)), - template_mtime) - if srcmtime > targetmtime: - yield docname - except EnvironmentError: - # source doesn't exist anymore - pass - def load_indexer(self, docnames): keep = set(self.env.all_docs) - set(docnames) try: diff --git a/sphinx/config.py b/sphinx/config.py index d5bb6471..d4604b53 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -18,92 +18,92 @@ from sphinx.util import make_filename class Config(object): """Configuration file abstraction.""" - # the values are: (default, needs fresh doctrees if changed) + # the values are: (default, what needs to be rebuilt if changed) # If you add a value here, don't forget to include it in the # quickstart.py file template as well as in the docs! config_values = dict( # general options - project = ('Python', True), - copyright = ('', False), - version = ('', True), - release = ('', True), - today = ('', True), - today_fmt = (None, True), # the real default is locale-dependent - - language = (None, True), - locale_dirs = ([], True), - - master_doc = ('contents', True), - source_suffix = ('.rst', True), - source_encoding = ('utf-8', True), - unused_docs = ([], True), - exclude_dirs = ([], True), - exclude_trees = ([], True), - exclude_dirnames = ([], True), - default_role = (None, True), - add_function_parentheses = (True, True), - add_module_names = (True, True), - trim_footnote_reference_space = (False, True), - show_authors = (False, True), - pygments_style = (None, False), - highlight_language = ('python', False), - templates_path = ([], False), - template_bridge = (None, False), - keep_warnings = (False, True), - modindex_common_prefix = ([], False), - rst_epilog = (None, True), + project = ('Python', 'env'), + copyright = ('', 'html'), + version = ('', 'env'), + release = ('', 'env'), + today = ('', 'env'), + today_fmt = (None, 'env'), # the real default is locale-dependent + + language = (None, 'env'), + locale_dirs = ([], 'env'), + + master_doc = ('contents', 'env'), + source_suffix = ('.rst', 'env'), + source_encoding = ('utf-8', 'env'), + unused_docs = ([], 'env'), + exclude_dirs = ([], 'env'), + exclude_trees = ([], 'env'), + exclude_dirnames = ([], 'env'), + default_role = (None, 'env'), + add_function_parentheses = (True, 'env'), + add_module_names = (True, 'env'), + trim_footnote_reference_space = (False, 'env'), + show_authors = (False, 'env'), + pygments_style = (None, 'html'), + highlight_language = ('python', 'env'), + templates_path = ([], 'html'), + template_bridge = (None, 'html'), + keep_warnings = (False, 'env'), + modindex_common_prefix = ([], 'html'), + rst_epilog = (None, 'env'), # HTML options - html_theme = ('default', False), - html_theme_path = ([], False), - html_theme_options = ({}, False), + html_theme = ('default', 'html'), + html_theme_path = ([], 'html'), + html_theme_options = ({}, 'html'), html_title = (lambda self: '%s v%s documentation' % (self.project, self.release), - False), - html_short_title = (lambda self: self.html_title, False), - html_style = (None, False), - html_logo = (None, False), - html_favicon = (None, False), - html_static_path = ([], False), + 'html'), + html_short_title = (lambda self: self.html_title, 'html'), + html_style = (None, 'html'), + html_logo = (None, 'html'), + html_favicon = (None, 'html'), + html_static_path = ([], 'html'), # the real default is locale-dependent - html_last_updated_fmt = (None, False), - html_use_smartypants = (True, False), - html_translator_class = (None, False), - html_sidebars = ({}, False), - html_additional_pages = ({}, False), - html_use_modindex = (True, False), - html_add_permalinks = (True, False), - html_use_index = (True, False), - html_split_index = (False, False), - html_copy_source = (True, False), - html_show_sourcelink = (True, False), - html_use_opensearch = ('', False), - html_file_suffix = (None, False), - html_link_suffix = (None, False), - html_show_sphinx = (True, False), - html_context = ({}, False), + html_last_updated_fmt = (None, 'html'), + html_use_smartypants = (True, 'html'), + html_translator_class = (None, 'html'), + html_sidebars = ({}, 'html'), + html_additional_pages = ({}, 'html'), + html_use_modindex = (True, 'html'), + html_add_permalinks = (True, 'html'), + html_use_index = (True, 'html'), + html_split_index = (False, 'html'), + html_copy_source = (True, 'html'), + html_show_sourcelink = (True, 'html'), + html_use_opensearch = ('', 'html'), + html_file_suffix = (None, 'html'), + html_link_suffix = (None, 'html'), + html_show_sphinx = (True, 'html'), + html_context = ({}, 'html'), # HTML help only options - htmlhelp_basename = (lambda self: make_filename(self.project), False), + htmlhelp_basename = (lambda self: make_filename(self.project), None), # Qt help only options - qthelp_basename = (lambda self: make_filename(self.project), False), + qthelp_basename = (lambda self: make_filename(self.project), None), # LaTeX options - latex_documents = ([], False), - latex_logo = (None, False), - latex_appendices = ([], False), - latex_use_parts = (False, False), - latex_use_modindex = (True, False), + latex_documents = ([], None), + latex_logo = (None, None), + latex_appendices = ([], None), + latex_use_parts = (False, None), + latex_use_modindex = (True, None), # paper_size and font_size are still separate values # so that you can give them easily on the command line - latex_paper_size = ('letter', False), - latex_font_size = ('10pt', False), - latex_elements = ({}, False), + latex_paper_size = ('letter', None), + latex_font_size = ('10pt', None), + latex_elements = ({}, None), # now deprecated - use latex_elements - latex_preamble = ('', False), + latex_preamble = ('', None), ) def __init__(self, dirname, filename, overrides): diff --git a/sphinx/environment.py b/sphinx/environment.py index 4b6e199f..805d579d 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -460,8 +460,8 @@ class BuildEnvironment: else: # check if a config value was changed that affects how # doctrees are read - for key, descr in config.config_values.iteritems(): - if not descr[1]: + for key, descr in config.values.iteritems(): + if descr[1] != 'env': continue if self.config[key] != config[key]: msg = '[config changed] ' -- cgit v1.2.1 From 3a5205c97ab82ac00704127b5eb2437c9354c5f0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 21:56:34 +0100 Subject: Added an ``only`` directive that can selectively include text based on enabled "tags". Tags can be given on the command line. Also, the current builder output format (e.g. "html" or "latex") is always a defined tag. --- CHANGES | 5 +++ doc/config.rst | 5 +++ doc/intro.rst | 6 +++ doc/markup/misc.rst | 22 +++++++++++ setup.py | 2 +- sphinx/addnodes.py | 3 ++ sphinx/application.py | 8 +++- sphinx/builders/__init__.py | 2 + sphinx/builders/html.py | 26 ++++++++----- sphinx/builders/latex.py | 5 ++- sphinx/builders/text.py | 1 + sphinx/cmdline.py | 9 ++++- sphinx/config.py | 3 +- sphinx/directives/other.py | 33 ++++++++++++++--- sphinx/environment.py | 13 +++++++ sphinx/util/tags.py | 90 +++++++++++++++++++++++++++++++++++++++++++++ tests/root/conf.py | 2 + tests/root/markup.txt | 20 ++++++++++ tests/test_build.py | 5 ++- tests/util.py | 9 +++-- 20 files changed, 242 insertions(+), 27 deletions(-) create mode 100644 sphinx/util/tags.py diff --git a/CHANGES b/CHANGES index 8085b39f..13d835d2 100644 --- a/CHANGES +++ b/CHANGES @@ -36,6 +36,11 @@ New features added - #4: Added a ``:download:`` role that marks a non-document file for inclusion into the HTML output and links to it. + - Added an ``only`` directive that can selectively include text + based on enabled "tags". Tags can be given on the command + line. Also, the current builder output format (e.g. "html" or + "latex") is always a defined tag. + - The ``literalinclude`` directive now supports several more options, to include only parts of a file. diff --git a/doc/config.rst b/doc/config.rst index 2c9e09d0..cc313d75 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -38,6 +38,11 @@ Important points to note: delete them from the namespace with ``del`` if appropriate. Modules are removed automatically, so you don't need to ``del`` your imports after use. +* There is a special object named ``tags`` available in the config file. + It can be used to query and change the tags (see :ref:`tags`). Use + ``tags.has('tag')`` to query, ``tags.add('tag')`` and ``tags.remove('tag')`` + to change. + General configuration --------------------- diff --git a/doc/intro.rst b/doc/intro.rst index 782328be..4306a44f 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -89,6 +89,12 @@ The :program:`sphinx-build` script has several more options: cross-references), but rebuild it completely. The default is to only read and parse source files that are new or have changed since the last run. +**-t** *tag* + Define the tag *tag*. This is relevant for :dir:`only` directives that only + include their content if this tag is set. + + .. versionadded:: 0.6 + **-d** *path* Since Sphinx has to read and parse all source files before it can write an output file, the parsed source files are cached as "doctree pickles". diff --git a/doc/markup/misc.rst b/doc/markup/misc.rst index 5bff00dc..01e5a3f1 100644 --- a/doc/markup/misc.rst +++ b/doc/markup/misc.rst @@ -48,6 +48,28 @@ Meta-information markup output. +.. _tags: + +Including content based on tags +------------------------------- + +.. directive:: .. only:: + + Include the content of the directive only if the *expression* is true. The + expression should consist of tags, like this:: + + .. only:: html and draft + + Undefined tags are false, defined tags (via the ``-t`` command-line option or + within :file:`conf.py`) are true. Boolean expressions, also using + parentheses (like ``html and (latex or draft)`` are supported. + + The format of the current builder (``html``, ``latex`` or ``text``) is always + set as a tag. + + .. versionadded:: 0.6 + + Tables ------ diff --git a/setup.py b/setup.py index 095ef114..bdfbd3f7 100644 --- a/setup.py +++ b/setup.py @@ -36,7 +36,7 @@ are already present, work fine and can be seen "in action" in the Python docs: and inclusion of appropriately formatted docstrings. ''' -requires = ['Pygments>=0.8', 'Jinja2>=2.0', 'docutils>=0.4'] +requires = ['Pygments>=0.8', 'Jinja2>=2.1', 'docutils>=0.4'] if sys.version_info < (2, 4): print 'ERROR: Sphinx requires at least Python 2.4 to run.' diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index a4af584c..f0b0b063 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -96,6 +96,9 @@ class start_of_file(nodes.Element): pass # tabular column specification, used for the LaTeX writer class tabular_col_spec(nodes.Element): pass +# only (in/exclusion based on tags) +class only(nodes.Element): pass + # meta directive -- same as docutils' standard meta node, but pickleable class meta(nodes.Special, nodes.PreBibliographic, nodes.Element): pass diff --git a/sphinx/application.py b/sphinx/application.py index 45c340d2..6c01ab11 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -59,6 +59,7 @@ from sphinx.config import Config from sphinx.builders import BUILTIN_BUILDERS from sphinx.directives import GenericDesc, Target, additional_xref_types from sphinx.environment import SphinxStandaloneReader +from sphinx.util.tags import Tags from sphinx.util.compat import Directive, directive_dwim from sphinx.util.console import bold @@ -82,7 +83,7 @@ class Sphinx(object): def __init__(self, srcdir, confdir, outdir, doctreedir, buildername, confoverrides, status, warning=sys.stderr, freshenv=False, - warningiserror=False): + warningiserror=False, tags=None): self.next_listener_id = 0 self._listeners = {} self.builderclasses = BUILTIN_BUILDERS.copy() @@ -113,7 +114,8 @@ class Sphinx(object): self.statuscode = 0 # read config - self.config = Config(confdir, CONFIG_FILENAME, confoverrides) + self.tags = Tags(tags) + self.config = Config(confdir, CONFIG_FILENAME, confoverrides, self.tags) # load all extension modules for extension in self.config.extensions: @@ -141,6 +143,8 @@ class Sphinx(object): builderclass = getattr( __import__('sphinx.builders.' + mod, None, None, [cls]), cls) self.builder = builderclass(self, freshenv=freshenv) + self.builder.tags = self.tags + self.builder.tags.add(self.builder.format) self.emit('builder-inited') def build(self, all_files, filenames): diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 19699033..6529dd80 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -35,6 +35,8 @@ class Builder(object): # builder's name, for the -b command line options name = '' + # builder's output format, or '' if no document output is produced + format = '' def __init__(self, app, env=None, freshenv=False): self.srcdir = app.srcdir diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 234c1fb9..6c6ea77e 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -60,12 +60,13 @@ class StandaloneHTMLBuilder(Builder): Builds standalone HTML docs. """ name = 'html' + format = 'html' copysource = True out_suffix = '.html' link_suffix = '.html' # defaults to matching out_suffix indexer_format = js_index - supported_image_types = ['image/svg+xml', - 'image/png', 'image/gif', 'image/jpeg'] + supported_image_types = ['image/svg+xml', 'image/png', + 'image/gif', 'image/jpeg'] searchindex_filename = 'searchindex.js' add_permalinks = True embedded = False # for things like HTML help or Qt help: suppresses sidebar @@ -76,6 +77,7 @@ class StandaloneHTMLBuilder(Builder): def init(self): # a hash of all config values that, if changed, cause a full rebuild self.config_hash = '' + self.tags_hash = '' self.init_templates() self.init_highlighter() self.init_translator_class() @@ -116,23 +118,28 @@ class StandaloneHTMLBuilder(Builder): for (name, desc) in self.config.values.iteritems() if desc[1] == 'html') self.config_hash = md5(str(cfgdict)).hexdigest() + self.tags_hash = md5(str(sorted(self.tags))).hexdigest() + old_config_hash = old_tags_hash = '' try: fp = open(path.join(self.outdir, '.buildinfo')) version = fp.readline() if version.rstrip() != '# Sphinx build info version 1': raise ValueError fp.readline() # skip commentary - cfg, old_hash = fp.readline().strip().split(': ') + cfg, old_config_hash = fp.readline().strip().split(': ') if cfg != 'config': raise ValueError + tag, old_tags_hash = fp.readline().strip().split(': ') + if tag != 'tags': + raise ValueError fp.close() except ValueError: self.warn('unsupported build info format in %r, building all' % path.join(self.outdir, '.buildinfo')) - old_hash = '' except Exception: - old_hash = '' - if old_hash != self.config_hash: + pass + if old_config_hash != self.config_hash or \ + old_tags_hash != self.tags_hash: for docname in self.env.found_docs: yield docname return @@ -544,7 +551,8 @@ class StandaloneHTMLBuilder(Builder): fp.write('# Sphinx build info version 1\n' '# This file hashes the configuration used when building' ' these files. When it is not found, a full rebuild will' - ' be done.\nconfig: %s\n' % self.config_hash) + ' be done.\nconfig: %s\ntags: %s\n' % + (self.config_hash, self.tags_hash)) finally: fp.close() @@ -721,8 +729,8 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): #: the filename for the global context file globalcontext_filename = None - supported_image_types = ('image/svg+xml', 'image/png', 'image/gif', - 'image/jpeg') + supported_image_types = ['image/svg+xml', 'image/png', + 'image/gif', 'image/jpeg'] def init(self): self.init_translator_class() diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index fd612d9f..7041fe04 100644 --- a/sphinx/builders/latex.py +++ b/sphinx/builders/latex.py @@ -31,8 +31,9 @@ class LaTeXBuilder(Builder): Builds LaTeX output to create PDF. """ name = 'latex' - supported_image_types = ['application/pdf', 'image/png', 'image/gif', - 'image/jpeg'] + format = 'latex' + supported_image_types = ['application/pdf', 'image/png', + 'image/gif', 'image/jpeg'] def init(self): self.docnames = [] diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py index d243e5c7..93737285 100644 --- a/sphinx/builders/text.py +++ b/sphinx/builders/text.py @@ -21,6 +21,7 @@ from sphinx.writers.text import TextWriter class TextBuilder(Builder): name = 'text' + format = 'text' out_suffix = '.txt' def init(self): diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index b4c3cc7b..cdceac6e 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -34,6 +34,7 @@ Options: -b -- builder to use; default is html -a -- write all files; default is to only write \ new and changed files -E -- don't use a saved environment, always read all files + -t -- include "only" blocks with -d -- path for the cached environment and doctree files (default: outdir/.doctrees) -c -- path where configuration file (conf.py) is located @@ -58,7 +59,7 @@ def main(argv): nocolor() try: - opts, args = getopt.getopt(argv[1:], 'ab:d:c:CD:A:NEqQWP') + opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:NEqQWP') allopts = set(opt[0] for opt in opts) srcdir = confdir = path.abspath(args[0]) if not path.isdir(srcdir): @@ -92,6 +93,7 @@ def main(argv): warning = sys.stderr confoverrides = {} htmlcontext = {} + tags = [] doctreedir = path.join(outdir, '.doctrees') for opt, val in opts: if opt == '-b': @@ -101,6 +103,8 @@ def main(argv): usage(argv, 'Cannot combine -a option and filenames.') return 1 all_files = True + elif opt == '-t': + tags.append(val) elif opt == '-d': doctreedir = path.abspath(val) elif opt == '-c': @@ -152,7 +156,8 @@ def main(argv): try: app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername, - confoverrides, status, warning, freshenv, warningiserror) + confoverrides, status, warning, freshenv, + warningiserror, tags) app.build(all_files, filenames) return app.statuscode except KeyboardInterrupt: diff --git a/sphinx/config.py b/sphinx/config.py index d4604b53..7af6e3c0 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -106,12 +106,13 @@ class Config(object): latex_preamble = ('', None), ) - def __init__(self, dirname, filename, overrides): + def __init__(self, dirname, filename, overrides, tags): self.overrides = overrides self.values = Config.config_values.copy() config = {} if dirname is not None: config['__file__'] = path.join(dirname, filename) + config['tags'] = tags olddir = os.getcwd() try: os.chdir(dirname) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 7601be1f..6376d912 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -383,6 +383,23 @@ class ProductionList(Directive): return [node] + messages +class TabularColumns(Directive): + """ + Directive to give an explicit tabulary column definition to LaTeX. + """ + + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = {} + + def run(self): + node = addnodes.tabular_col_spec() + node['spec'] = self.arguments[0] + return [node] + + class Glossary(Directive): """ Directive to create a glossary with cross-reference targets @@ -506,20 +523,23 @@ class HList(Directive): return [newnode] -class TabularColumns(Directive): +class Only(Directive): """ - Directive to give an explicit tabulary column definition to LaTeX. + Directive to only include text if the given tag(s) are enabled. """ - has_content = False + has_content = True required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True option_spec = {} def run(self): - node = addnodes.tabular_col_spec() - node['spec'] = self.arguments[0] + node = addnodes.only() + node.document = self.state.document + node.line = self.lineno + node['expr'] = self.arguments[0] + self.state.nested_parse(self.content, self.content_offset, node) return [node] @@ -535,11 +555,12 @@ directives.register_directive('versionadded', VersionChange) directives.register_directive('versionchanged', VersionChange) directives.register_directive('seealso', SeeAlso) directives.register_directive('productionlist', ProductionList) +directives.register_directive('tabularcolumns', TabularColumns) directives.register_directive('glossary', Glossary) directives.register_directive('centered', Centered) directives.register_directive('acks', Acks) directives.register_directive('hlist', HList) -directives.register_directive('tabularcolumns', TabularColumns) +directives.register_directive('only', Only) # register the standard rst class directive under a different name diff --git a/sphinx/environment.py b/sphinx/environment.py index 805d579d..c8e7cd28 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -1270,6 +1270,19 @@ class BuildEnvironment: if newnode: node.replace_self(newnode) + for node in doctree.traverse(addnodes.only): + try: + ret = builder.tags.eval_condition(node['expr']) + except Exception, err: + self.warn(fromdocname, 'exception while evaluating only ' + 'directive expression: %s' % err, node.line) + node.replace_self(node.children) + else: + if ret: + node.replace_self(node.children) + else: + node.replace_self([]) + # allow custom references to be resolved builder.app.emit('doctree-resolved', doctree, fromdocname) diff --git a/sphinx/util/tags.py b/sphinx/util/tags.py new file mode 100644 index 00000000..c08e5e5a --- /dev/null +++ b/sphinx/util/tags.py @@ -0,0 +1,90 @@ +# -*- coding: utf-8 -*- +""" + sphinx.util.tags + ~~~~~~~~~~~~~~~~ + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import warnings +# jinja2.sandbox imports the sets module on purpose +warnings.filterwarnings('ignore', 'the sets module', DeprecationWarning, + module='jinja2.sandbox') + +# (ab)use the Jinja parser for parsing our boolean expressions +from jinja2 import nodes +from jinja2.parser import Parser +from jinja2.environment import Environment + +env = Environment() + + +class BooleanParser(Parser): + """ + Only allow condition exprs and/or/not operations. + """ + + def parse_compare(self): + token = self.stream.current + if token.type == 'name': + if token.value in ('true', 'false', 'True', 'False'): + node = nodes.Const(token.value in ('true', 'True'), + lineno=token.lineno) + elif token.value in ('none', 'None'): + node = nodes.Const(None, lineno=token.lineno) + else: + node = nodes.Name(token.value, 'load', lineno=token.lineno) + self.stream.next() + elif token.type == 'lparen': + self.stream.next() + node = self.parse_expression() + self.stream.expect('rparen') + else: + self.fail("unexpected token '%s'" % (token,), token.lineno) + return node + + +class Tags(object): + def __init__(self, tags=None): + self.tags = dict.fromkeys(tags or [], True) + + def has(self, tag): + return tag in self.tags + + __contains__ = has + + def __iter__(self): + return iter(self.tags) + + def add(self, tag): + self.tags[tag] = True + + def remove(self, tag): + self.tags.pop(tag, None) + + def eval_condition(self, condition): + # exceptions are handled by the caller + parser = BooleanParser(env, condition, state='variable') + expr = parser.parse_expression() + if not parser.stream.eos: + raise ValueError('chunk after expression') + + def eval_node(node): + if isinstance(node, nodes.CondExpr): + if eval_node(node.test): + return eval_node(node.expr1) + else: + return eval_node(node.expr2) + elif isinstance(node, nodes.And): + return eval_node(node.left) and eval_node(node.right) + elif isinstance(node, nodes.Or): + return eval_node(node.left) or eval_node(node.right) + elif isinstance(node, nodes.Not): + return not eval_node(node.node) + elif isinstance(node, nodes.Name): + return self.tags.get(node.name, False) + else: + raise ValueError('invalid node, check parsing') + + return eval_node(expr) diff --git a/tests/root/conf.py b/tests/root/conf.py index 9ccbbb87..9901e008 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -47,6 +47,8 @@ value_from_conf_py = 84 coverage_c_path = ['special/*.h'] coverage_c_regexes = {'cfunction': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'} +# modify tags from conf.py +tags.add('confpytag') from sphinx import addnodes diff --git a/tests/root/markup.txt b/tests/root/markup.txt index e01d2152..532ecbac 100644 --- a/tests/root/markup.txt +++ b/tests/root/markup.txt @@ -176,6 +176,26 @@ Invalid index markup... Testing öäü... +Only directive +-------------- + +.. only:: html + + In HTML. + +.. only:: latex + + In LaTeX. + +.. only:: html or latex + + In both. + +.. only:: confpytag and (testtag or nonexisting_tag) + + Always present, because set through conf.py/command line. + + .. rubric:: Footnotes .. [#] Like footnotes. diff --git a/tests/test_build.py b/tests/test_build.py index 5b84a9da..3a61a352 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -83,6 +83,9 @@ HTML_XPATH = { ".//div[@id='label']": '', ".//span[@class='option']": '--help', ".//p": 'A global substitution.', + ".//p": 'In HTML.', + ".//p": 'In both.', + ".//p": 'Always present', }, 'desc.html': { ".//dt[@id='mod.Cls.meth1']": '', @@ -135,7 +138,7 @@ class NslessParser(ET.XMLParser): return name -@with_app(buildername='html', warning=html_warnfile) +@with_app(buildername='html', warning=html_warnfile, tags=['testtag']) def test_html(app): app.builder.build_all() html_warnings = html_warnfile.getvalue().replace(os.sep, '/') diff --git a/tests/util.py b/tests/util.py index 5d0b4a98..eeb2720f 100644 --- a/tests/util.py +++ b/tests/util.py @@ -99,8 +99,9 @@ class TestApp(application.Sphinx): def __init__(self, srcdir=None, confdir=None, outdir=None, doctreedir=None, buildername='html', confoverrides=None, - status=None, warning=None, - freshenv=None, confname='conf.py', cleanenv=False): + status=None, warning=None, freshenv=None, + warningiserror=None, tags=None, + confname='conf.py', cleanenv=False): application.CONFIG_FILENAME = confname @@ -136,10 +137,12 @@ class TestApp(application.Sphinx): warning = ListOutput('stderr') if freshenv is None: freshenv = False + if warningiserror is None: + warningiserror = False application.Sphinx.__init__(self, srcdir, confdir, outdir, doctreedir, buildername, confoverrides, status, warning, - freshenv) + freshenv, warningiserror, tags) def cleanup(self, doctrees=False): AutoDirective._registry.clear() -- cgit v1.2.1 From 135516c4a32858b97f95844b0cdb56be66420547 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 22:12:47 +0100 Subject: Make the HTML xpath tests generator tests. --- tests/test_build.py | 39 +++++++++++++++++++++------------------ tests/util.py | 22 ++++++++++++++++++++-- 2 files changed, 41 insertions(+), 20 deletions(-) diff --git a/tests/test_build.py b/tests/test_build.py index 3a61a352..25d9a5cc 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -138,7 +138,26 @@ class NslessParser(ET.XMLParser): return name -@with_app(buildername='html', warning=html_warnfile, tags=['testtag']) +def check_xpath(etree, fname, path, check): + nodes = list(etree.findall(path)) + assert nodes != [], ('did not find any node matching xpath ' + '%r in file %s' % (path, fname)) + if hasattr(check, '__call__'): + check(nodes) + elif not check: + # only check for node presence + pass + else: + rex = re.compile(check) + for node in nodes: + if node.text and rex.search(node.text): + break + else: + assert False, ('%r not found in any node matching ' + 'path %s in %s: %r' % (check, path, fname, + [node.text for node in nodes])) + +@gen_with_app(buildername='html', warning=html_warnfile, tags=['testtag']) def test_html(app): app.builder.build_all() html_warnings = html_warnfile.getvalue().replace(os.sep, '/') @@ -152,23 +171,7 @@ def test_html(app): parser.entity.update(htmlentitydefs.entitydefs) etree = ET.parse(os.path.join(app.outdir, fname), parser) for path, check in paths.iteritems(): - nodes = list(etree.findall(path)) - assert nodes != [], ('did not find any node matching xpath ' - '%r in file %s' % (path, fname)) - if hasattr(check, '__call__'): - check(nodes) - elif not check: - # only check for node presence - continue - else: - rex = re.compile(check) - for node in nodes: - if node.text and rex.search(node.text): - break - else: - assert False, ('%r not found in any node matching ' - 'path %s in %s: %r' % (check, path, fname, - [node.text for node in nodes])) + yield check_xpath, etree, fname, path, check @with_app(buildername='latex', warning=latex_warnfile) diff --git a/tests/util.py b/tests/util.py index eeb2720f..2130e20a 100644 --- a/tests/util.py +++ b/tests/util.py @@ -30,7 +30,7 @@ from nose import tools __all__ = [ 'test_root', 'raises', 'raises_msg', 'Struct', - 'ListOutput', 'TestApp', 'with_app', + 'ListOutput', 'TestApp', 'with_app', 'gen_with_app', 'path', 'with_tempdir', 'write_file', 'sprint', ] @@ -160,7 +160,25 @@ def with_app(*args, **kwargs): def deco(*args2, **kwargs2): app = TestApp(*args, **kwargs) try: - func(app, *args2, **kwargs2) + return func(app, *args2, **kwargs2) + finally: + app.cleanup() + return deco + return generator + + +def gen_with_app(*args, **kwargs): + """ + Make a TestApp with args and kwargs, pass it to the test and clean up + properly. + """ + def generator(func): + @wraps(func) + def deco(*args2, **kwargs2): + app = TestApp(*args, **kwargs) + try: + for item in func(app, *args2, **kwargs2): + yield item finally: app.cleanup() return deco -- cgit v1.2.1 From 73f9dceafce399bed2e52bfd9edada72c51ccc54 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 22:36:00 +0100 Subject: Fix a bug in FilenameUniqDict that led to test failures. --- sphinx/util/__init__.py | 7 ++++--- tests/test_build.py | 4 ++++ tests/util.py | 16 +++++++--------- 3 files changed, 15 insertions(+), 12 deletions(-) diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 8449aff2..5f9462be 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -307,7 +307,7 @@ class FilenameUniqDict(dict): def add_file(self, docname, newfile): if newfile in self: self[newfile][0].add(docname) - return + return self[newfile][1] uniquename = path.basename(newfile) base, ext = path.splitext(uniquename) i = 0 @@ -321,8 +321,9 @@ class FilenameUniqDict(dict): def purge_doc(self, docname): for filename, (docs, _) in self.items(): docs.discard(docname) - if not docs: - del self[filename] + #if not docs: + # del self[filename] + # self._existing.discard(filename) def __getstate__(self): return self._existing diff --git a/tests/test_build.py b/tests/test_build.py index 25d9a5cc..c3286bfa 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -30,6 +30,10 @@ from sphinx.builders.latex import LaTeXBuilder from sphinx.writers.latex import LaTeXTranslator +def teardown_module(): + (test_root / '_build').rmtree() + + html_warnfile = StringIO() latex_warnfile = StringIO() diff --git a/tests/util.py b/tests/util.py index 2130e20a..2c9d3176 100644 --- a/tests/util.py +++ b/tests/util.py @@ -159,10 +159,9 @@ def with_app(*args, **kwargs): @wraps(func) def deco(*args2, **kwargs2): app = TestApp(*args, **kwargs) - try: - return func(app, *args2, **kwargs2) - finally: - app.cleanup() + func(app, *args2, **kwargs2) + # don't execute cleanup if test failed + app.cleanup() return deco return generator @@ -176,11 +175,10 @@ def gen_with_app(*args, **kwargs): @wraps(func) def deco(*args2, **kwargs2): app = TestApp(*args, **kwargs) - try: - for item in func(app, *args2, **kwargs2): - yield item - finally: - app.cleanup() + for item in func(app, *args2, **kwargs2): + yield item + # don't execute cleanup if test failed + app.cleanup() return deco return generator -- cgit v1.2.1 From f590e164fbbe68d9531d43bf61057cddeca766b4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 22:54:34 +0100 Subject: Fix #106, fix #107: make _special_attrgetters an attribute of AutoDirective, to avoid confusion how it should be overridden in subclasses. --- doc/ext/appapi.rst | 9 +++++++++ sphinx/application.py | 4 ++++ sphinx/ext/autodoc.py | 32 ++++++++++++++++++++------------ 3 files changed, 33 insertions(+), 12 deletions(-) diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index b23b6774..fba1d945 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -216,6 +216,15 @@ the following public API: .. versionadded:: 0.6 +.. method:: Sphinx.add_autodoc_attrgetter(type, getter) + + Add *getter*, which must be a function with an interface compatible to the + :func:`getattr` builtin, as the autodoc attribute getter for objects that are + instances of *type*. All cases where autodoc needs to get an attribute of a + type are then handled by this function instead of :func:`getattr`. + + .. versionadded:: 0.6 + .. method:: Sphinx.connect(event, callback) Register *callback* to be called when *event* is emitted. For details on diff --git a/sphinx/application.py b/sphinx/application.py index 6c01ab11..5ab16c3e 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -351,6 +351,10 @@ class Sphinx(object): autodoc.add_documenter(cls) self.add_directive('auto' + cls.objtype, autodoc.AutoDirective) + def add_autodoc_attrgetter(self, type, getter): + from sphinx.ext import autodoc + autodoc.AutoDirective._special_attrgetters[type] = getter + class TemplateBridge(object): """ diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index eafe167d..a9efb0f1 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -210,10 +210,6 @@ class Documenter(object): A Documenter has an *option_spec* that works like a docutils directive's; in fact, it will be used to parse an auto directive's options that matches the documenter. - - The *special_attrgetters* attribute is used to customize ``getattr()`` - calls that the Documenter makes; its entries are of the form - ``type: getattr_function``. """ #: name by which the directive is called (auto...) and the default #: generated directive name @@ -225,12 +221,10 @@ class Documenter(object): option_spec = {'noindex': bool_option} - special_attrgetters = {} - - @classmethod - def get_attr(cls, obj, name, *defargs): + @staticmethod + def get_attr(obj, name, *defargs): """getattr() override for types such as Zope interfaces.""" - for typ, func in cls.special_attrgetters.iteritems(): + for typ, func in AutoDirective._special_attrgetters.iteritems(): if isinstance(obj, typ): return func(obj, name, *defargs) return getattr(obj, name, *defargs) @@ -454,7 +448,8 @@ class Documenter(object): def get_object_members(self, want_all): """ - Return (membername, member) pairs of the members of *self.object*. + Return `(members_check_module, members)` where `members` is a + list of `(membername, member)` pairs of the members of *self.object*. If *want_all* is True, return all members. Else, only return those members given by *self.options.members* (which may also be none). @@ -479,8 +474,9 @@ class Documenter(object): # __dict__ contains only the members directly defined in # the class (but get them via getattr anyway, to e.g. get # unbound method objects instead of function objects) - return False, sorted([(mname, self.get_attr(self.object, mname)) - for mname in self.object.__dict__]) + return False, sorted([ + (mname, self.get_attr(self.object, mname)) + for mname in self.get_attr(self.object, '__dict__')]) def filter_members(self, members, want_all): """ @@ -985,10 +981,22 @@ class AutoDirective(Directive): The AutoDirective class is used for all autodoc directives. It dispatches most of the work to one of the Documenters, which it selects through its *_registry* dictionary. + + The *_special_attrgetters* attribute is used to customize ``getattr()`` calls + that the Documenters make; its entries are of the form ``type: + getattr_function``. + + Note: When importing an object, all items along the import chain are + accessed using the descendant's *_special_attrgetters*, thus this + dictionary should include all necessary functions for accessing + attributes of the parents. """ # a registry of objtype -> documenter class _registry = {} + # a registry of type -> getattr function + _special_attrgetters = {} + # standard docutils directive settings has_content = True required_arguments = 1 -- cgit v1.2.1 From a2d37c81a221f89043ed24a5d03566ca8bbbbc06 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 23:02:54 +0100 Subject: Add MyHDL. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 0562a7f2..a6535498 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -28,6 +28,7 @@ included, please mail to `the Google group * MeshPy: http://documen.tician.de/meshpy/ * Mixin.com: http://dev.mixin.com/ * mpmath: http://mpmath.googlecode.com/svn/trunk/doc/build/index.html +* MyHDL: http://www.myhdl.org/doc/0.6/ * NetworkX: http://networkx.lanl.gov/ * NumPy: http://docs.scipy.org/doc/numpy/reference/ * ObjectListView: http://objectlistview.sourceforge.net/python -- cgit v1.2.1 From b52bba8eb28b963197b77158aa11fee14e5ae447 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 23:09:20 +0100 Subject: Restore docutils 0.4 compatibility. --- sphinx/application.py | 5 +++-- sphinx/directives/code.py | 12 ++++++------ sphinx/directives/desc.py | 34 +++++++++++++++++----------------- sphinx/directives/other.py | 40 ++++++++++++++++++++-------------------- 4 files changed, 46 insertions(+), 45 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 5ab16c3e..d5f4a1ba 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -319,7 +319,8 @@ class Sphinx(object): parse_node=None, ref_nodeclass=None): additional_xref_types[directivename] = (rolename, indextemplate, parse_node) - directives.register_directive(directivename, GenericDesc) + directives.register_directive(directivename, + directive_dwim(GenericDesc)) roles.register_canonical_role(rolename, xfileref_role) if ref_nodeclass is not None: innernodetypes[rolename] = ref_nodeclass @@ -327,7 +328,7 @@ class Sphinx(object): def add_crossref_type(self, directivename, rolename, indextemplate='', ref_nodeclass=None): additional_xref_types[directivename] = (rolename, indextemplate, None) - directives.register_directive(directivename, Target) + directives.register_directive(directivename, directive_dwim(Target)) roles.register_canonical_role(rolename, xfileref_role) if ref_nodeclass is not None: innernodetypes[rolename] = ref_nodeclass diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index a6694085..70aecd83 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -16,7 +16,7 @@ from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.util import parselinenos -from sphinx.util.compat import Directive +from sphinx.util.compat import Directive, directive_dwim class Highlight(Directive): @@ -167,8 +167,8 @@ class LiteralInclude(Directive): return [retnode] -directives.register_directive('highlight', Highlight) -directives.register_directive('highlightlang', Highlight) # old name -directives.register_directive('code-block', CodeBlock) -directives.register_directive('sourcecode', CodeBlock) -directives.register_directive('literalinclude', LiteralInclude) +directives.register_directive('highlight', directive_dwim(Highlight)) +directives.register_directive('highlightlang', directive_dwim(Highlight)) # old +directives.register_directive('code-block', directive_dwim(CodeBlock)) +directives.register_directive('sourcecode', directive_dwim(CodeBlock)) +directives.register_directive('literalinclude', directive_dwim(LiteralInclude)) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index c7c05959..56a829c8 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -15,7 +15,7 @@ from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.util import ws_re -from sphinx.util.compat import Directive +from sphinx.util.compat import Directive, directive_dwim def _is_only_paragraph(node): @@ -667,22 +667,22 @@ additional_xref_types = { del _ -directives.register_directive('describe', DescDirective) +directives.register_directive('describe', directive_dwim(DescDirective)) -directives.register_directive('function', ModulelevelDesc) -directives.register_directive('data', ModulelevelDesc) -directives.register_directive('class', ClasslikeDesc) -directives.register_directive('exception', ClasslikeDesc) -directives.register_directive('method', ClassmemberDesc) -directives.register_directive('classmethod', ClassmemberDesc) -directives.register_directive('staticmethod', ClassmemberDesc) -directives.register_directive('attribute', ClassmemberDesc) +directives.register_directive('function', directive_dwim(ModulelevelDesc)) +directives.register_directive('data', directive_dwim(ModulelevelDesc)) +directives.register_directive('class', directive_dwim(ClasslikeDesc)) +directives.register_directive('exception', directive_dwim(ClasslikeDesc)) +directives.register_directive('method', directive_dwim(ClassmemberDesc)) +directives.register_directive('classmethod', directive_dwim(ClassmemberDesc)) +directives.register_directive('staticmethod', directive_dwim(ClassmemberDesc)) +directives.register_directive('attribute', directive_dwim(ClassmemberDesc)) -directives.register_directive('cfunction', CDesc) -directives.register_directive('cmember', CDesc) -directives.register_directive('cmacro', CDesc) -directives.register_directive('ctype', CDesc) -directives.register_directive('cvar', CDesc) +directives.register_directive('cfunction', directive_dwim(CDesc)) +directives.register_directive('cmember', directive_dwim(CDesc)) +directives.register_directive('cmacro', directive_dwim(CDesc)) +directives.register_directive('ctype', directive_dwim(CDesc)) +directives.register_directive('cvar', directive_dwim(CDesc)) -directives.register_directive('cmdoption', CmdoptionDesc) -directives.register_directive('envvar', GenericDesc) +directives.register_directive('cmdoption', directive_dwim(CmdoptionDesc)) +directives.register_directive('envvar', directive_dwim(GenericDesc)) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index 6376d912..f66a6092 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -15,7 +15,7 @@ from docutils.parsers.rst import directives from sphinx import addnodes from sphinx.locale import pairindextypes from sphinx.util import patfilter, ws_re, caption_ref_re, url_re, docname_join -from sphinx.util.compat import Directive, make_admonition +from sphinx.util.compat import Directive, directive_dwim, make_admonition class TocTree(Directive): @@ -543,31 +543,31 @@ class Only(Directive): return [node] -directives.register_directive('toctree', TocTree) -directives.register_directive('module', Module) -directives.register_directive('currentmodule', CurrentModule) -directives.register_directive('sectionauthor', Author) -directives.register_directive('moduleauthor', Author) -directives.register_directive('program', Program) -directives.register_directive('index', Index) -directives.register_directive('deprecated', VersionChange) -directives.register_directive('versionadded', VersionChange) -directives.register_directive('versionchanged', VersionChange) -directives.register_directive('seealso', SeeAlso) -directives.register_directive('productionlist', ProductionList) -directives.register_directive('tabularcolumns', TabularColumns) -directives.register_directive('glossary', Glossary) -directives.register_directive('centered', Centered) -directives.register_directive('acks', Acks) -directives.register_directive('hlist', HList) -directives.register_directive('only', Only) +directives.register_directive('toctree', directive_dwim(TocTree)) +directives.register_directive('module', directive_dwim(Module)) +directives.register_directive('currentmodule', directive_dwim(CurrentModule)) +directives.register_directive('sectionauthor', directive_dwim(Author)) +directives.register_directive('moduleauthor', directive_dwim(Author)) +directives.register_directive('program', directive_dwim(Program)) +directives.register_directive('index', directive_dwim(Index)) +directives.register_directive('deprecated', directive_dwim(VersionChange)) +directives.register_directive('versionadded', directive_dwim(VersionChange)) +directives.register_directive('versionchanged', directive_dwim(VersionChange)) +directives.register_directive('seealso', directive_dwim(SeeAlso)) +directives.register_directive('productionlist', directive_dwim(ProductionList)) +directives.register_directive('tabularcolumns', directive_dwim(TabularColumns)) +directives.register_directive('glossary', directive_dwim(Glossary)) +directives.register_directive('centered', directive_dwim(Centered)) +directives.register_directive('acks', directive_dwim(Acks)) +directives.register_directive('hlist', directive_dwim(HList)) +directives.register_directive('only', directive_dwim(Only)) # register the standard rst class directive under a different name try: # docutils 0.4 from docutils.parsers.rst.directives.misc import class_directive - directives.register_directive('cssclass', class_directive) + directives.register_directive('cssclass' class_directive) except ImportError: try: # docutils 0.5 -- cgit v1.2.1 From 4e857f47280395864fcaca9e721430553ab0c13c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 23:10:48 +0100 Subject: Fix. --- sphinx/directives/other.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index f66a6092..fd9c869d 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -567,7 +567,7 @@ directives.register_directive('only', directive_dwim(Only)) try: # docutils 0.4 from docutils.parsers.rst.directives.misc import class_directive - directives.register_directive('cssclass' class_directive) + directives.register_directive('cssclass', class_directive) except ImportError: try: # docutils 0.5 -- cgit v1.2.1 From 5fd17a73ad41269c51b2c7667246af6bf9de10f9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 23:17:34 +0100 Subject: But maybe this time it works! --- sphinx/util/compat.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/util/compat.py b/sphinx/util/compat.py index 3ef3debd..c00f9d4e 100644 --- a/sphinx/util/compat.py +++ b/sphinx/util/compat.py @@ -73,7 +73,7 @@ except ImportError: class or function. For that, we need to convert classes to a function for docutils 0.4. """ - if isinstance(obj, Directive): + if isinstance(obj, type) and issubclass(obj, Directive): def _class_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): -- cgit v1.2.1 From 14eb32b0835072a188966ba3db63d9f2bdc728cd Mon Sep 17 00:00:00 2001 From: mitsuhiko Date: Thu, 19 Feb 2009 23:20:29 +0100 Subject: Enabled default jinja sandbox in sphinx. Makes it safer to share themes. --- sphinx/jinja2glue.py | 17 ++++++++++------- 1 file changed, 10 insertions(+), 7 deletions(-) diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index d7ad328d..d835391e 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -11,8 +11,10 @@ import codecs from os import path +from pprint import pformat -import jinja2 +from jinja2 import FileSystemLoader, BaseLoader, TemplateNotFound, contextfunction +from jinja2.sandbox import SandboxedEnvironment from sphinx.util import mtimes_of_files from sphinx.application import TemplateBridge @@ -24,7 +26,7 @@ def _tobool(val): return bool(val) -class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): +class BuiltinTemplateLoader(TemplateBridge, BaseLoader): """ Interfaces the rendering environment of jinja2 for use in Sphinx. """ @@ -49,13 +51,14 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): self.pathchain = chain # make the paths into loaders - self.loaders = map(jinja2.FileSystemLoader, chain) + self.loaders = map(FileSystemLoader, chain) use_i18n = builder.translator is not None extensions = use_i18n and ['jinja2.ext.i18n'] or [] - self.environment = jinja2.Environment(loader=self, - extensions=extensions) + self.environment = SandboxedEnvironment(loader=self, + extensions=extensions) self.environment.filters['tobool'] = _tobool + self.environment.globals['debug'] = contextfunction(pformat) if use_i18n: self.environment.install_gettext_translations(builder.translator) @@ -79,6 +82,6 @@ class BuiltinTemplateLoader(TemplateBridge, jinja2.BaseLoader): for loader in loaders: try: return loader.get_source(environment, template) - except jinja2.TemplateNotFound: + except TemplateNotFound: pass - raise jinja2.TemplateNotFound(template) + raise TemplateNotFound(template) -- cgit v1.2.1 From 32755834c34b03e35b900b091822012b62ebfbf6 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 23:22:36 +0100 Subject: Fixed another of the isinstance tests that should have been issubclass. This doesn't make me look good... --- sphinx/application.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sphinx/application.py b/sphinx/application.py index d5f4a1ba..f75d746d 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -12,12 +12,16 @@ """ import sys +import types import posixpath from cStringIO import StringIO from docutils import nodes from docutils.parsers.rst import directives, roles +# Directive is either new-style or old-style +clstypes = (type, types.ClassType) + # create the error classes before importing the rest of Sphinx, so that # they can be imported in a circular fashion @@ -298,7 +302,7 @@ class Sphinx(object): setattr(translator, 'depart_'+node.__name__, depart) def add_directive(self, name, obj, content=None, arguments=None, **options): - if isinstance(obj, Directive): + if isinstance(obj, clstypes) and issubclass(obj, Directive): if content or arguments or options: raise ExtensionError('when adding directive classes, no ' 'additional arguments may be given') -- cgit v1.2.1 From 9e16a98b5b8542935b312b1732a416a214de2ece Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 19 Feb 2009 23:31:34 +0100 Subject: Make "make check" happy. --- doc/config.rst | 4 ++-- doc/faq.rst | 2 +- doc/templating.rst | 2 +- doc/theming.rst | 2 +- sphinx/environment.py | 38 +++++++++++++++++++++----------------- sphinx/ext/autodoc.py | 4 ++-- sphinx/jinja2glue.py | 3 ++- sphinx/quickstart.py | 5 +++-- sphinx/util/__init__.py | 3 ++- sphinx/writers/latex.py | 5 +++-- tests/test_autodoc.py | 3 ++- utils/check_sources.py | 6 +++--- 12 files changed, 43 insertions(+), 34 deletions(-) diff --git a/doc/config.rst b/doc/config.rst index cc313d75..8bb2db6c 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -160,7 +160,7 @@ General configuration """ .. versionadded:: 0.6 - + .. confval:: default_role .. index:: default; role @@ -302,7 +302,7 @@ Project information .. versionadded:: 0.6 - + .. _html-options: Options for HTML output diff --git a/doc/faq.rst b/doc/faq.rst index 7e5cffd5..a43e9c72 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -17,7 +17,7 @@ How do I... ... write my own extension? See the :ref:`extension tutorial `. - + ... use Sphinx with Epydoc? There's a third-party extension providing an `api role`_ which refers to Epydoc's API docs for a given identifier. diff --git a/doc/templating.rst b/doc/templating.rst index bccdd689..61657547 100644 --- a/doc/templating.rst +++ b/doc/templating.rst @@ -342,7 +342,7 @@ in the future. In addition to these values, there are also all **theme options** available (prefixed by ``theme_``), as well as the values given by the user in :confval:`html_context`. - + In documents that are created from source files (as opposed to automatically-generated files like the module index, or documents that already are in HTML form), these variables are also available: diff --git a/doc/theming.rst b/doc/theming.rst index 7c3ae709..4696df5a 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -178,7 +178,7 @@ templating to put the color options into the stylesheet. When a documentation is built with the default theme, the output directory will contain a ``_static/default.css`` file where all template tags have been processed. - + .. [1] It is not an executable Python file, as opposed to :file:`conf.py`, because that would pose an unnecessary security risk if themes are shared. diff --git a/sphinx/environment.py b/sphinx/environment.py index c8e7cd28..eb591242 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -995,11 +995,10 @@ class BuildEnvironment: subnode.parent.remove(subnode) elif isinstance(subnode, nodes.reference): - # Identify the toc entry pointing to the current document. - if subnode['refuri'] == docname and not subnode['anchorname']: + # identify the toc entry pointing to the current document + if subnode['refuri'] == docname and \ + not subnode['anchorname']: # tag the whole branch as 'current' - # (We can't use traverse here as 'ascend' un-intuitively - # implies 'siblings'.) p = subnode while p: p['classes'].append('current') @@ -1012,13 +1011,15 @@ class BuildEnvironment: for (title, ref) in refs: try: if url_re.match(ref): - reference = nodes.reference('', '', refuri=ref, anchorname='', + reference = nodes.reference('', '', + refuri=ref, anchorname='', *[nodes.Text(title)]) para = addnodes.compact_paragraph('', '', reference) item = nodes.list_item('', para) toc = nodes.bullet_list('', item) elif ref == 'self': - # 'self' refers to the document from which this toctree originates. + # 'self' refers to the document from which this + # toctree originates ref = toctreenode['parent'] if not title: title = self.titles[ref].astext() @@ -1028,13 +1029,15 @@ class BuildEnvironment: *[nodes.Text(title)]) para = addnodes.compact_paragraph('', '', reference) item = nodes.list_item('', para) - # Don't show subitems. + # don't show subitems toc = nodes.bullet_list('', item) else: toc = self.tocs[ref].deepcopy() if title and toc.children and len(toc.children) == 1: - for refnode in toc.children[0].traverse(nodes.reference): - if refnode['refuri'] == ref and not refnode['anchorname']: + child = toc.children[0] + for refnode in child.traverse(nodes.reference): + if refnode['refuri'] == ref and \ + not refnode['anchorname']: refnode.children = [nodes.Text(title)] if not toc.children: # empty toc means: no titles will show up in the toctree @@ -1090,7 +1093,8 @@ class BuildEnvironment: # prune the tree to maxdepth and replace titles, also set level classes _walk_depth(newnode, 1, prune and maxdepth or 0) - # set the target paths in the toctrees (they are not known at TOC generation time) + # set the target paths in the toctrees (they are not known at TOC + # generation time) for refnode in newnode.traverse(nodes.reference): if not url_re.match(refnode['refuri']): refnode['refuri'] = builder.get_relative_uri( @@ -1121,19 +1125,19 @@ class BuildEnvironment: docname, labelid = self.anonlabels.get(target, ('','')) sectname = node.astext() if not docname: - self.warn(fromdocname, 'undefined label: %s' % target, - node.line) + self.warn(fromdocname, 'undefined label: %s' % + target, node.line) else: # reference to the named label; the final node will # contain the section name after the label docname, labelid, sectname = self.labels.get(target, ('','','')) if not docname: - self.warn(fromdocname, - 'undefined label: %s' % target + - ' -- if you don\'t give a link caption ' - 'the label must precede a section header.', - node.line) + self.warn( + fromdocname, + 'undefined label: %s' % target + ' -- if you ' + 'don\'t give a link caption the label must ' + 'precede a section header.', node.line) if docname: newnode = nodes.reference('', '') innernode = nodes.emphasis(sectname, sectname) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index a9efb0f1..d07ab465 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -982,8 +982,8 @@ class AutoDirective(Directive): most of the work to one of the Documenters, which it selects through its *_registry* dictionary. - The *_special_attrgetters* attribute is used to customize ``getattr()`` calls - that the Documenters make; its entries are of the form ``type: + The *_special_attrgetters* attribute is used to customize ``getattr()`` + calls that the Documenters make; its entries are of the form ``type: getattr_function``. Note: When importing an object, all items along the import chain are diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index d835391e..8424d12c 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -13,7 +13,8 @@ import codecs from os import path from pprint import pformat -from jinja2 import FileSystemLoader, BaseLoader, TemplateNotFound, contextfunction +from jinja2 import FileSystemLoader, BaseLoader, TemplateNotFound, \ + contextfunction from jinja2.sandbox import SandboxedEnvironment from sphinx.util import mtimes_of_files diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index d3cf18c5..a25c0466 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -38,7 +38,7 @@ QUICKSTART_CONF = '''\ import sys, os -# If your extensions (or modules documented by autodoc) are in another directory, +# If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. #sys.path.append(os.path.abspath('.')) @@ -277,7 +277,8 @@ help: \t@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" \t@echo " changes to make an overview of all changed/added/deprecated items" \t@echo " linkcheck to check all external links for integrity" -\t@echo " doctest to run all doctests embedded in the documentation (if enabled)" +\t@echo " doctest to run all doctests embedded in the documentation \ +(if enabled)" clean: \t-rm -rf %(rbuilddir)s/* diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 5f9462be..20854af3 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -407,7 +407,8 @@ def _new_traverse(self, condition=None, return self._all_traverse() elif isinstance(condition, (types.ClassType, type)): return self._fast_traverse(condition) - return self._old_traverse(condition, include_self, descend, siblings, ascend) + return self._old_traverse(condition, include_self, + descend, siblings, ascend) import docutils.nodes docutils.nodes.Node._old_traverse = docutils.nodes.Node.traverse diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 9deb184b..841a5ba1 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -584,8 +584,9 @@ class LaTeXTranslator(nodes.NodeVisitor): def visit_table(self, node): if self.table: - raise UnsupportedError('%s:%s: nested tables are not yet implemented.' % - (self.curfilestack[-1], node.line or '')) + raise UnsupportedError( + '%s:%s: nested tables are not yet implemented.' % + (self.curfilestack[-1], node.line or '')) self.table = Table() self.tablebody = [] # Redirect body output until table is finished. diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index d1da4439..25d833a2 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -401,7 +401,8 @@ def test_generate(): options.members = ALL assert_result_contains('.. class:: Class', 'module', 'test_autodoc') try: - assert_result_contains('.. exception:: CustomEx', 'module', 'test_autodoc') + assert_result_contains('.. exception:: CustomEx', + 'module', 'test_autodoc') except AssertionError: pass else: diff --git a/utils/check_sources.py b/utils/check_sources.py index 8a115c71..361fcfc1 100755 --- a/utils/check_sources.py +++ b/utils/check_sources.py @@ -64,9 +64,9 @@ def check_style_and_encoding(fn, lines): encoding = co.group(1) if line.strip().startswith('#'): continue - m = not_ix_re.search(line) - if m: - yield lno+1, '"' + m.group() + '"' + #m = not_ix_re.search(line) + #if m: + # yield lno+1, '"' + m.group() + '"' if is_const_re.search(line): yield lno+1, 'using == None/True/False' try: -- cgit v1.2.1 From eba16783ee8814e40abe861350064f86fb26f9cf Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 20 Feb 2009 09:35:14 +0100 Subject: Fix a reuse problem with CDesc signatures. --- sphinx/directives/desc.py | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index 56a829c8..a59b29d8 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -531,7 +531,7 @@ class CDesc(DescDirective): signode += addnodes.desc_addname(const, const) return name - def get_index_text(self, modname, name): + def get_index_text(self, name): if self.desctype == 'cfunction': return _('%s (C function)') % name elif self.desctype == 'cmember': @@ -545,8 +545,18 @@ class CDesc(DescDirective): else: return '' - # just copy that one - add_target_and_index = PythonDesc.__dict__['add_target_and_index'] + def add_target_and_index(self, name, sig, signode): + # note target + if name not in self.state.document.ids: + signode['names'].append(name) + signode['ids'].append(name) + signode['first'] = (not self.names) + self.state.document.note_explicit_target(signode) + self.env.note_descref(name, self.desctype, self.lineno) + + indextext = self.get_index_text(name) + if indextext: + self.indexnode['entries'].append(('single', indextext, name, name)) class CmdoptionDesc(DescDirective): -- cgit v1.2.1 From 9d670f7788b61e0e8ec154a9d34e6a71c03cd6fa Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 20 Feb 2009 09:43:00 +0100 Subject: Only move module targets that really come from module directives. --- sphinx/directives/other.py | 2 +- sphinx/environment.py | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index fd9c869d..b1270b01 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -124,7 +124,7 @@ class Module(Directive): modulenode = addnodes.module() modulenode['modname'] = modname modulenode['synopsis'] = self.options.get('synopsis', '') - targetnode = nodes.target('', '', ids=['module-' + modname]) + targetnode = nodes.target('', '', ids=['module-' + modname], ismod=True) self.state.document.note_explicit_target(targetnode) ret = [modulenode, targetnode] if 'platform' in self.options: diff --git a/sphinx/environment.py b/sphinx/environment.py index eb591242..cccd0192 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -117,7 +117,8 @@ class MoveModuleTargets(Transform): if not node['ids']: continue if node['ids'][0].startswith('module-') and \ - node.parent.__class__ is nodes.section: + node.parent.__class__ is nodes.section and \ + node.has_key('ismod'): node.parent['ids'] = node['ids'] node.parent.remove(node) -- cgit v1.2.1 From 3cccc65890a68f1c9d69993ccb4cb8094e14784b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 20 Feb 2009 10:22:56 +0100 Subject: Add a few more docstrings, and remove the last XXX comments in the desc directives. --- sphinx/directives/desc.py | 97 ++++++++++++++++++++++++++++++++++++++++------- sphinx/writers/html.py | 2 - 2 files changed, 84 insertions(+), 15 deletions(-) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index a59b29d8..1ea973a3 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -70,7 +70,8 @@ strip_backslash_re = re.compile(r'\\(?=[^\\])') class DescDirective(Directive): """ - Directive to describe a class, function or similar object. + Directive to describe a class, function or similar object. Not used + directly, but subclassed to add custom behavior. """ has_content = True @@ -113,6 +114,10 @@ class DescDirective(Directive): } def handle_doc_fields(self, node): + """ + Convert field lists with known keys inside the description content into + better-looking equivalents. + """ # don't traverse, only handle field lists that are immediate children for child in node.children: if not isinstance(child, nodes.field_list): @@ -193,20 +198,39 @@ class DescDirective(Directive): child.replace_self(new_list) def get_signatures(self): + """ + Retrieve the signatures to document from the directive arguments. + """ # remove backslashes to support (dummy) escapes; helps Vim highlighting return [strip_backslash_re.sub('', sig.strip()) for sig in self.arguments[0].split('\n')] def parse_signature(self, sig, signode): - raise ValueError # must be implemented in subclasses + """ + Parse the signature *sig* into individual nodes and append them to + *signode*. If ValueError is raised, parsing is aborted and the whole + *sig* is put into a single desc_name node. + """ + raise ValueError def add_target_and_index(self, name, sig, signode): + """ + Add cross-reference IDs and entries to self.indexnode, if applicable. + """ return # do nothing by default def before_content(self): + """ + Called before parsing content. Used to set information about the current + directive context on the build environment. + """ pass def after_content(self): + """ + Called after parsing content. Used to reset information about the + current directive context on the build environment. + """ pass def run(self): @@ -255,10 +279,27 @@ class DescDirective(Directive): class PythonDesc(DescDirective): + """ + Description of a general Python object. + """ + + def get_signature_prefix(self, sig): + """ + May return a prefix to put before the object name in the signature. + """ + return '' + + def needs_arglist(self): + """ + May return true if an empty argument list is to be generated even if + the document contains none. + """ + return False + def parse_signature(self, sig, signode): """ - Transform a python signature into RST nodes. - Return (fully qualified name of the thing, classname if any). + Transform a Python signature into RST nodes. + Returns (fully qualified name of the thing, classname if any). If inside a class, the current class name is handled intelligently: * it is stripped from the displayed name if present @@ -286,11 +327,9 @@ class PythonDesc(DescDirective): add_module = True fullname = classname and classname + name or name - # XXX! - if self.desctype == 'staticmethod': - signode += addnodes.desc_annotation('static ', 'static ') - elif self.desctype == 'classmethod': - signode += addnodes.desc_annotation('classmethod ', 'classmethod ') + prefix = self.get_signature_prefix(sig) + if prefix: + signode += addnodes.desc_annotation(prefix, prefix) if classname: signode += addnodes.desc_addname(classname, classname) @@ -304,9 +343,7 @@ class PythonDesc(DescDirective): signode += addnodes.desc_name(name, name) if not arglist: - # XXX! - if self.desctype in ('function', 'method', - 'staticmethod', 'classmethod'): + if self.needs_arglist(): # for callables, add an empty parameter list signode += addnodes.desc_parameterlist() if retann: @@ -337,6 +374,9 @@ class PythonDesc(DescDirective): return fullname, classname def get_index_text(self, modname, name): + """ + Return the text for the index entry of the object. + """ raise NotImplementedError('must be implemented in subclasses') def add_target_and_index(self, name_cls, sig, signode): @@ -365,6 +405,13 @@ class PythonDesc(DescDirective): class ModulelevelDesc(PythonDesc): + """ + Description of an object on module level (functions, data). + """ + + def needs_arglist(self): + return self.desctype == 'function' + def get_index_text(self, modname, name_cls): if self.desctype == 'function': if not modname: @@ -379,6 +426,13 @@ class ModulelevelDesc(PythonDesc): class ClasslikeDesc(PythonDesc): + """ + Description of a class-like object (classes, interfaces, exceptions). + """ + + def get_signature_prefix(self, sig): + return self.desctype + ' ' + def get_index_text(self, modname, name_cls): if self.desctype == 'class': if not modname: @@ -397,6 +451,20 @@ class ClasslikeDesc(PythonDesc): class ClassmemberDesc(PythonDesc): + """ + Description of a class member (methods, attributes). + """ + + def needs_arglist(self): + return self.argtype.endswith('method') + + def get_signature_prefix(self, sig): + if self.desctype == 'staticmethod': + return 'static ' + elif self.desctype == 'classmethod': + return 'classmethod ' + return '' + def get_index_text(self, modname, name_cls): name, cls = name_cls add_modules = self.env.config.add_module_names @@ -461,6 +529,9 @@ class ClassmemberDesc(PythonDesc): class CDesc(DescDirective): + """ + Description of a C language object. + """ # These C types aren't described anywhere, so don't try to create # a cross-reference to them @@ -561,7 +632,7 @@ class CDesc(DescDirective): class CmdoptionDesc(DescDirective): """ - A command-line option (.. cmdoption). + Description of a command-line option (.. cmdoption). """ def parse_signature(self, sig, signode): diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 0859bae6..95b7f8b8 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -71,8 +71,6 @@ class HTMLTranslator(BaseTranslator): if node.parent['desctype'] != 'describe' \ and node['ids'] and node['first']: self.body.append('' % node['ids'][0]) - if node.parent['desctype'] in ('class', 'exception'): - self.body.append('%s ' % node.parent['desctype']) def depart_desc_signature(self, node): if node['ids'] and self.add_permalinks and self.builder.add_permalinks: self.body.append(u' Date: Fri, 20 Feb 2009 10:42:50 +0100 Subject: Fix wrong attribute name. --- sphinx/directives/desc.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/directives/desc.py b/sphinx/directives/desc.py index 1ea973a3..60b43a5d 100644 --- a/sphinx/directives/desc.py +++ b/sphinx/directives/desc.py @@ -456,7 +456,7 @@ class ClassmemberDesc(PythonDesc): """ def needs_arglist(self): - return self.argtype.endswith('method') + return self.desctype.endswith('method') def get_signature_prefix(self, sig): if self.desctype == 'staticmethod': -- cgit v1.2.1 From 18d13aa2d8ab92d4ab741976169725e122e7e829 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 20 Feb 2009 10:43:56 +0100 Subject: Fix #103: add all (usable) builtin extensions to quickstart. --- sphinx/quickstart.py | 16 ++++++++++++++-- tests/test_quickstart.py | 4 ++++ 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index a25c0466..165d20ec 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -589,6 +589,17 @@ Please indicate if you want to use one of the following Sphinx extensions:''' 'in doctest blocks (y/N)', 'n', boolean) do_prompt(d, 'ext_intersphinx', 'intersphinx: link between Sphinx ' 'documentation of different projects (y/N)', 'n', boolean) + do_prompt(d, 'ext_todo', 'todo: write "todo" entries ' + 'that can be shown or hidden on build (y/N)', 'n', boolean) + do_prompt(d, 'ext_coverage', 'coverage: checks for documentation ' + 'coverage (y/N)', 'n', boolean) + do_prompt(d, 'ext_pngmath', 'pngmath: include math, rendered ' + 'as PNG images (y/N)', 'n', boolean) + do_prompt(d, 'ext_jsmath', 'jsmath: include math, rendered in the ' + 'browser by JSMath (y/N)', 'n', boolean) + if d['ext_pngmath'] and d['ext_jsmath']: + print '''Note: pngmath and jsmath cannot be enabled at the same time. +pngmath has been deselected.''' print ''' A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build @@ -601,8 +612,9 @@ directly.''' d['now'] = time.asctime() d['underline'] = len(d['project']) * '=' d['extensions'] = ', '.join( - repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', - 'intersphinx') + repr('sphinx.ext.' + name) + for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage', + 'pngmath', 'jsmath') if d['ext_' + name].upper() in ('Y', 'YES')) d['copyright'] = time.strftime('%Y') + ', ' + d['author'] d['author_texescaped'] = unicode(d['author']).\ diff --git a/tests/test_quickstart.py b/tests/test_quickstart.py index 976e2bee..fd48b3de 100644 --- a/tests/test_quickstart.py +++ b/tests/test_quickstart.py @@ -121,6 +121,10 @@ def test_quickstart_all_answers(tempdir): 'autodoc': 'y', 'doctest': 'yes', 'intersphinx': 'no', + 'todo': 'n', + 'coverage': 'no', + 'pngmath': 'N', + 'jsmath': 'no', 'Create Makefile': 'no', 'Create Windows command file': 'no', } -- cgit v1.2.1 From 36f57bd479e19d1aa411a5aae7dcc5827f10c950 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 20 Feb 2009 10:45:24 +0100 Subject: Forgot ifconfig. --- sphinx/quickstart.py | 4 +++- tests/test_quickstart.py | 1 + 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/sphinx/quickstart.py b/sphinx/quickstart.py index 165d20ec..cfdb97e7 100644 --- a/sphinx/quickstart.py +++ b/sphinx/quickstart.py @@ -600,6 +600,8 @@ Please indicate if you want to use one of the following Sphinx extensions:''' if d['ext_pngmath'] and d['ext_jsmath']: print '''Note: pngmath and jsmath cannot be enabled at the same time. pngmath has been deselected.''' + do_prompt(d, 'ext_ifconfig', 'ifconfig: conditional inclusion of ' + 'content based on config values (y/N)', 'n', boolean) print ''' A Makefile and a Windows command file can be generated for you so that you only have to run e.g. `make html' instead of invoking sphinx-build @@ -614,7 +616,7 @@ directly.''' d['extensions'] = ', '.join( repr('sphinx.ext.' + name) for name in ('autodoc', 'doctest', 'intersphinx', 'todo', 'coverage', - 'pngmath', 'jsmath') + 'pngmath', 'jsmath', 'ifconfig') if d['ext_' + name].upper() in ('Y', 'YES')) d['copyright'] = time.strftime('%Y') + ', ' + d['author'] d['author_texescaped'] = unicode(d['author']).\ diff --git a/tests/test_quickstart.py b/tests/test_quickstart.py index fd48b3de..ae001eb6 100644 --- a/tests/test_quickstart.py +++ b/tests/test_quickstart.py @@ -125,6 +125,7 @@ def test_quickstart_all_answers(tempdir): 'coverage': 'no', 'pngmath': 'N', 'jsmath': 'no', + 'ifconfig': 'no', 'Create Makefile': 'no', 'Create Windows command file': 'no', } -- cgit v1.2.1 From 18228ff545e65b664e970a1ee7084f1214b576f1 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 20 Feb 2009 11:01:46 +0100 Subject: #62: There is now a ``-w`` option for sphinx-build that writes warnings to a file, in addition to stderr. --- CHANGES | 3 +++ doc/intro.rst | 3 +++ doc/sphinx-build.1 | 6 ++++++ sphinx/cmdline.py | 51 +++++++++++++++++++++++++++++-------------------- sphinx/util/__init__.py | 13 +++++++++++++ 5 files changed, 55 insertions(+), 21 deletions(-) diff --git a/CHANGES b/CHANGES index 13d835d2..7b54115b 100644 --- a/CHANGES +++ b/CHANGES @@ -160,6 +160,9 @@ New features added - Quickstart can now generate a Windows ``make.bat`` file. + - #62: There is now a ``-w`` option for sphinx-build that writes + warnings to a file, in addition to stderr. + - There is now a ``-W`` option for sphinx-build that turns warnings into errors. diff --git a/doc/intro.rst b/doc/intro.rst index 4306a44f..7b8f8651 100644 --- a/doc/intro.rst +++ b/doc/intro.rst @@ -139,6 +139,9 @@ The :program:`sphinx-build` script has several more options: Do not output anything on standard output, also suppress warnings. Only errors are written to standard error. +**-w** *file* + Write warnings (and errors) to the given file, in addition to standard error. + **-W** Turn warnings into errors. This means that the build stops at the first warning and ``sphinx-build`` exits with exit status 1. diff --git a/doc/sphinx-build.1 b/doc/sphinx-build.1 index 16f8bd34..498771c9 100644 --- a/doc/sphinx-build.1 +++ b/doc/sphinx-build.1 @@ -84,6 +84,12 @@ Quiet operation, just prints warnings and errors on stderr. \fB-Q\fR Very quiet operation, doesn't print anything except for errors. .TP +\fB-w\fR +Write warnings and errors into the given file, in addition to stderr. +.TP +\fB-W\fR +Turn warnings into errors. +.TP \fB-P\fR Runs Pdb on exception. .SH "SEE ALSO" diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index cdceac6e..cd2c4008 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -19,7 +19,7 @@ from docutils.utils import SystemMessage from sphinx import __version__ from sphinx.application import Sphinx, SphinxError -from sphinx.util import format_exception_cut_frames, save_traceback +from sphinx.util import Tee, format_exception_cut_frames, save_traceback from sphinx.util.console import darkred, nocolor, color_terminal @@ -45,6 +45,7 @@ new and changed files -N -- do not do colored output -q -- no output on stdout, just warnings on stderr -Q -- no output at all, not even warnings + -w -- write warnings (and errors) to given file -W -- turn warnings into errors -P -- run Pdb on exception Modi: @@ -59,7 +60,7 @@ def main(argv): nocolor() try: - opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:NEqQWP') + opts, args = getopt.getopt(argv[1:], 'ab:t:d:c:CD:A:NEqQWw:P') allopts = set(opt[0] for opt in opts) srcdir = confdir = path.abspath(args[0]) if not path.isdir(srcdir): @@ -91,6 +92,8 @@ def main(argv): freshenv = warningiserror = use_pdb = False status = sys.stdout warning = sys.stderr + error = sys.stderr + warnfile = None confoverrides = {} htmlcontext = {} tags = [] @@ -150,10 +153,17 @@ def main(argv): warning = None elif opt == '-W': warningiserror = True + elif opt == '-w': + warnfile = val elif opt == '-P': use_pdb = True confoverrides['html_context'] = htmlcontext + if warning and warnfile: + warnfp = open(warnfile, 'w') + warning = Tee(warning, warnfp) + error = warning + try: app = Sphinx(srcdir, confdir, outdir, doctreedir, buildername, confoverrides, status, warning, freshenv, @@ -163,36 +173,35 @@ def main(argv): except KeyboardInterrupt: if use_pdb: import pdb - print >>sys.stderr, darkred('Interrupted while building, ' - 'starting debugger:') + print >>error, darkred('Interrupted while building, ' + 'starting debugger:') traceback.print_exc() pdb.post_mortem(sys.exc_info()[2]) return 1 except Exception, err: if use_pdb: import pdb - print >>sys.stderr, darkred('Exception occurred while building, ' - 'starting debugger:') + print >>error, darkred('Exception occurred while building, ' + 'starting debugger:') traceback.print_exc() pdb.post_mortem(sys.exc_info()[2]) else: if isinstance(err, SystemMessage): - print >>sys.stderr, darkred('reST markup error:') - print >>sys.stderr, err.args[0].encode('ascii', - 'backslashreplace') + print >>error, darkred('reST markup error:') + print >>error, err.args[0].encode('ascii', 'backslashreplace') elif isinstance(err, SphinxError): - print >>sys.stderr, darkred('%s:' % err.category) - print >>sys.stderr, err + print >>error, darkred('%s:' % err.category) + print >>error, err else: - print >>sys.stderr, darkred('Exception occurred:') - print >>sys.stderr, format_exception_cut_frames().rstrip() + print >>error, darkred('Exception occurred:') + print >>error, format_exception_cut_frames().rstrip() tbpath = save_traceback() - print >>sys.stderr, darkred('The full traceback has been saved ' - 'in %s, if you want to report the ' - 'issue to the author.' % tbpath) - print >>sys.stderr, ('Please also report this if it was a user ' - 'error, so that a better error message ' - 'can be provided next time.') - print >>sys.stderr, ('Send reports to ' - 'sphinx-dev@googlegroups.com. Thanks!') + print >>error, darkred('The full traceback has been saved ' + 'in %s, if you want to report the ' + 'issue to the author.' % tbpath) + print >>error, ('Please also report this if it was a user ' + 'error, so that a better error message ' + 'can be provided next time.') + print >>error, ('Send reports to sphinx-dev@googlegroups.com. ' + 'Thanks!') return 1 diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index 20854af3..e02fd1b7 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -295,6 +295,19 @@ def ustrftime(format, *args): return time.strftime(unicode(format).encode('utf-8'), *args).decode('utf-8') +class Tee(object): + """ + File-like object writing to two streams. + """ + def __init__(self, stream1, stream2): + self.stream1 = stream1 + self.stream2 = stream2 + + def write(self, text): + self.stream1.write(text) + self.stream2.write(text) + + class FilenameUniqDict(dict): """ A dictionary that automatically generates unique names for its keys, -- cgit v1.2.1 From 18c93131a49268ebe9cacc9369c51901f6dba981 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 20 Feb 2009 11:09:54 +0100 Subject: Oops. --- doc/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index a86f8648..e1a48aa2 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -31,7 +31,7 @@ release = version show_authors = True # The HTML template theme. -html_theme = 'default' +html_theme = 'sphinxdoc' # A list of ignored prefixes names for module index sorting. modindex_common_prefix = ['sphinx.'] -- cgit v1.2.1 From 81b94fa925f50a610e96c1bf19da115336ab5abc Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 20 Feb 2009 11:20:15 +0100 Subject: The new ``latex_additional_files`` config value can be used to copy files (that Sphinx doesn't copy automatically, e.g. if they are referenced in custom LaTeX added in ``latex_elements``) to the build directory. --- CHANGES | 6 +++++- doc/config.rst | 13 +++++++++++++ sphinx/builders/latex.py | 9 +++++++++ sphinx/config.py | 1 + tests/root/conf.py | 2 ++ tests/test_build.py | 2 ++ 6 files changed, 32 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 7b54115b..fa25a8f5 100644 --- a/CHANGES +++ b/CHANGES @@ -90,7 +90,6 @@ New features added - The default value for ``htmlhelp_basename`` is now the project title, cleaned up as a filename. - - The new ``modindex_common_prefix`` config value can be used to ignore certain package names for module index sorting. @@ -99,6 +98,11 @@ New features added space before a footnote reference that is necessary for reST to recognize the reference. + - The new ``latex_additional_files`` config value can be used to + copy files (that Sphinx doesn't copy automatically, e.g. if they + are referenced in custom LaTeX added in ``latex_elements``) to + the build directory. + * Builders: - The HTML builder now stores a small file named ``.buildinfo`` in diff --git a/doc/config.rst b/doc/config.rst index 8bb2db6c..54303bbb 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -652,6 +652,19 @@ These options influence LaTeX output. ``'shorthandoff'`` ``'printmodindex'`` +.. confval:: latex_additional_files + + A list of file names, relative to the configuration directory, to copy to the + build directory when building LaTeX output. This is useful to copy files + that Sphinx doesn't copy automatically, e.g. if they are referenced in custom + LaTeX added in ``latex_elements``. Image files that are referenced in source + files (e.g. via ``.. image::``) are copied automatically. + + You have to make sure yourself that the filenames don't collide with those of + any automatically copied files. + + .. versionadded:: 0.6 + .. confval:: latex_preamble Additional LaTeX markup for the preamble. diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index 7041fe04..9fe7b8a5 100644 --- a/sphinx/builders/latex.py +++ b/sphinx/builders/latex.py @@ -178,6 +178,15 @@ class LaTeXBuilder(Builder): path.join(self.outdir, dest)) self.info() + # copy additional files + if self.config.latex_additional_files: + self.info(bold('copying additional files...'), nonl=1) + for filename in self.config.latex_additional_files: + self.info(' '+filename, nonl=1) + shutil.copyfile(path.join(self.confdir, filename), + path.join(self.outdir, path.basename(filename))) + self.info() + # the logo is handled differently if self.config.latex_logo: logobase = path.basename(self.config.latex_logo) diff --git a/sphinx/config.py b/sphinx/config.py index 7af6e3c0..3e3abb0d 100644 --- a/sphinx/config.py +++ b/sphinx/config.py @@ -102,6 +102,7 @@ class Config(object): latex_paper_size = ('letter', None), latex_font_size = ('10pt', None), latex_elements = ({}, None), + latex_additional_files = ([], None), # now deprecated - use latex_elements latex_preamble = ('', None), ) diff --git a/tests/root/conf.py b/tests/root/conf.py index 9901e008..7b67d03e 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -42,6 +42,8 @@ latex_documents = [ 'Georg Brandl', 'manual'), ] +latex_additional_files = ['svgimg.svg'] + value_from_conf_py = 84 coverage_c_path = ['special/*.h'] diff --git a/tests/test_build.py b/tests/test_build.py index c3286bfa..f85e61ca 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -187,6 +187,8 @@ def test_latex(app): assert latex_warnings == latex_warnings_exp, 'Warnings don\'t match:\n' + \ '\n'.join(difflib.ndiff(latex_warnings_exp.splitlines(), latex_warnings.splitlines())) + # file from latex_additional_files + assert (app.outdir / 'svgimg.svg').isfile() # only run latex if all needed packages are there def kpsetest(filename): -- cgit v1.2.1 From 01bf7e7470533b166349ac98b6941ee899153609 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 21 Feb 2009 17:16:56 +0100 Subject: More generator tests. --- tests/test_markup.py | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/tests/test_markup.py b/tests/test_markup.py index cd6de561..f0fbcf9e 100644 --- a/tests/test_markup.py +++ b/tests/test_markup.py @@ -80,39 +80,39 @@ def test_inline(): # correct interpretation of code with whitespace _html = ('

      ' 'code   sample

      ') - verify('``code sample``', _html, '\\code{code sample}') - verify(':samp:`code sample`', _html, '\\samp{code sample}') + yield verify, '``code sample``', _html, '\\code{code sample}' + yield verify, ':samp:`code sample`', _html, '\\samp{code sample}' # interpolation of braces in samp and file roles (HTML only) - verify(':samp:`a{b}c`', + yield (verify, ':samp:`a{b}c`', '

      a' 'b' 'c

      ', '\\samp{abc}') # interpolation of arrows in menuselection - verify(':menuselection:`a --> b`', + yield (verify, ':menuselection:`a --> b`', u'

      a \N{TRIANGULAR BULLET} b

      ', '\\emph{a \\(\\rightarrow\\) b}') # non-interpolation of dashes in option role - verify_re(':option:`--with-option`', - '

      --with-option

      $', - r'\\emph{\\texttt{-{-}with-option}}$') + yield (verify_re, ':option:`--with-option`', + '

      --with-option

      $', + r'\\emph{\\texttt{-{-}with-option}}$') # verify smarty-pants quotes - verify('"John"', '

      “John”

      ', "``John''") + yield verify, '"John"', '

      “John”

      ', "``John''" # ... but not in literal text - verify('``"John"``', + yield (verify, '``"John"``', '

      ' '"John"

      ', '\\code{"John"}') def test_latex_escaping(): # correct escaping in normal mode - verify(u'Γ\\\\∞$', None, ur'\(\Gamma\)\textbackslash{}\(\infty\)\$') + yield verify, u'Γ\\\\∞$', None, ur'\(\Gamma\)\textbackslash{}\(\infty\)\$' # in verbatim code fragments - verify(u'::\n\n @Γ\\∞$[]', None, + yield (verify, u'::\n\n @Γ\\∞$[]', None, u'\\begin{Verbatim}[commandchars=@\\[\\]]\n' u'@PYGZat[]@(@Gamma@)\\@(@infty@)@$@PYGZlb[]@PYGZrb[]\n' u'\\end{Verbatim}') -- cgit v1.2.1 From 0cbd0ddc0d9e094e3f15956ed6f9e1841d1381ad Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 21 Feb 2009 17:17:21 +0100 Subject: Fix the serializing and changes builders, and really test them. --- sphinx/application.py | 12 ++++++--- sphinx/builders/__init__.py | 11 ++------ sphinx/builders/changes.py | 27 ++++++++++++------- sphinx/builders/html.py | 63 ++++++++++++++++++++++++--------------------- sphinx/jinja2glue.py | 18 ++++++++----- sphinx/theming.py | 4 +-- sphinx/util/__init__.py | 20 ++++++++++++++ tests/root/conf.py | 1 + tests/root/markup.txt | 6 ++--- tests/test_build.py | 14 +++++++++- 10 files changed, 112 insertions(+), 64 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index f75d746d..b2cdca99 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -367,11 +367,15 @@ class TemplateBridge(object): that renders templates given a template name and a context. """ - def init(self, builder): + def init(self, builder, theme=None, dirs=None): """ - Called by the builder to initialize the template system. *builder* - is the builder object; you'll probably want to look at the value of - ``builder.config.templates_path``. + Called by the builder to initialize the template system. + + *builder* is the builder object; you'll probably want to look at the + value of ``builder.config.templates_path``. + + *theme* is a :class:`sphinx.theming.Theme` object or None; in the latter + case, *dirs* can be list of fixed directories to look for templates. """ raise NotImplementedError('must be implemented in subclasses') diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 6529dd80..25008388 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -72,23 +72,16 @@ class Builder(object): """ pass - def init_templates(self): + def create_template_bridge(self): """ - Initialize the theme and template system. - - Call this method from init() if you need templates in your builder. + Return the template bridge configured. """ - from sphinx.theming import Theme - Theme.init_themes(self) - self.theme = Theme(self.config.html_theme) - if self.config.template_bridge: self.templates = self.app.import_object( self.config.template_bridge, 'template_bridge setting')() else: from sphinx.jinja2glue import BuiltinTemplateLoader self.templates = BuiltinTemplateLoader() - self.templates.init(self) def get_target_uri(self, docname, typ=None): """ diff --git a/sphinx/builders/changes.py b/sphinx/builders/changes.py index d4520fa5..e07b06d8 100644 --- a/sphinx/builders/changes.py +++ b/sphinx/builders/changes.py @@ -15,7 +15,8 @@ from os import path from cgi import escape from sphinx import package_dir -from sphinx.util import ensuredir, os_path +from sphinx.util import ensuredir, os_path, copy_static_entry +from sphinx.theming import Theme from sphinx.builders import Builder from sphinx.util.console import bold @@ -27,7 +28,10 @@ class ChangesBuilder(Builder): name = 'changes' def init(self): - self.init_templates() + self.create_template_bridge() + Theme.init_themes(self) + self.theme = Theme('default') + self.templates.init(self, self.theme) def get_outdated_docs(self): return self.outdir @@ -44,11 +48,13 @@ class ChangesBuilder(Builder): apichanges = [] otherchanges = {} if version not in self.env.versionchanges: - self.info(bold('no changes in this version.')) + self.info(bold('no changes in version %s.' % version)) return self.info(bold('writing summary file...')) for type, docname, lineno, module, descname, content in \ self.env.versionchanges[version]: + if isinstance(descname, tuple): + descname = descname[0] ttext = self.typemap[type] context = content.replace('\n', ' ') if descname and docname.startswith('c-api'): @@ -129,12 +135,15 @@ class ChangesBuilder(Builder): f.write(self.templates.render('changes/rstsource.html', ctx)) finally: f.close() - shutil.copyfile(path.join(package_dir, 'themes', 'default', - 'static', 'default.css'), - path.join(self.outdir, 'default.css')) - shutil.copyfile(path.join(package_dir, 'themes', 'basic', - 'static', 'basic.css'), - path.join(self.outdir, 'basic.css')) + themectx = dict(('theme_' + key, val) for (key, val) in + self.theme.get_options({}).iteritems()) + copy_static_entry(path.join(package_dir, 'themes', 'default', + 'static', 'default.css_t'), + path.join(self.outdir, 'default.css_t'), + self, themectx) + copy_static_entry(path.join(package_dir, 'themes', 'basic', + 'static', 'basic.css'), + path.join(self.outdir, 'basic.css'), self) def hl(self, text, version): text = escape(text) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 6c6ea77e..2c4569df 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -32,8 +32,9 @@ from docutils.readers.doctree import Reader as DoctreeReader from sphinx import package_dir, __version__ from sphinx.util import SEP, os_path, relative_uri, ensuredir, \ - movefile, ustrftime + movefile, ustrftime, copy_static_entry from sphinx.search import js_index +from sphinx.theming import Theme from sphinx.builders import Builder, ENV_PICKLE_FILENAME from sphinx.application import SphinxError from sphinx.highlighting import PygmentsBridge @@ -95,12 +96,20 @@ class StandaloneHTMLBuilder(Builder): if path.isfile(jsfile): self.script_files.append('_static/translations.js') + def init_templates(self): + Theme.init_themes(self) + self.theme = Theme(self.config.html_theme) + self.create_template_bridge() + self.templates.init(self, self.theme) + def init_highlighter(self): # determine Pygments style and create the highlighter if self.config.pygments_style is not None: style = self.config.pygments_style - else: + elif self.theme: style = self.theme.get_confstr('theme', 'pygments_style', 'none') + else: + style = 'sphinx' self.highlighter = PygmentsBridge('html', style) def init_translator_class(self): @@ -219,8 +228,10 @@ class StandaloneHTMLBuilder(Builder): if self.config.html_style is not None: stylename = self.config.html_style - else: + elif self.theme: stylename = self.theme.get_confstr('theme', 'stylesheet') + else: + stylename = 'default.css' self.globalcontext = dict( embedded = self.embedded, @@ -246,9 +257,11 @@ class StandaloneHTMLBuilder(Builder): logo = logo, favicon = favicon, ) - self.globalcontext.update( - ('theme_' + key, val) for (key, val) in - self.theme.get_options(self.config.html_theme_options).iteritems()) + if self.theme: + self.globalcontext.update( + ('theme_' + key, val) for (key, val) in + self.theme.get_options( + self.config.html_theme_options).iteritems()) self.globalcontext.update(self.config.html_context) def get_doc_context(self, docname, body, metatags): @@ -509,10 +522,13 @@ class StandaloneHTMLBuilder(Builder): shutil.copyfile(jsfile, path.join(self.outdir, '_static', 'translations.js')) # then, copy over all user-supplied static files - staticdirnames = [path.join(themepath, 'static') - for themepath in self.theme.get_dirchain()[::-1]] + \ - [path.join(self.confdir, spath) - for spath in self.config.html_static_path] + if self.theme: + staticdirnames = [path.join(themepath, 'static') + for themepath in self.theme.get_dirchain()[::-1]] + else: + staticdirnames = [] + staticdirnames += [path.join(self.confdir, spath) + for spath in self.config.html_static_path] for staticdirname in staticdirnames: if not path.isdir(staticdirname): self.warn('static directory %r does not exist' % staticdirname) @@ -522,23 +538,8 @@ class StandaloneHTMLBuilder(Builder): continue fullname = path.join(staticdirname, filename) targetname = path.join(self.outdir, '_static', filename) - if path.isfile(fullname): - if fullname.lower().endswith('_t'): - # templated! - fsrc = open(fullname, 'rb') - fdst = open(targetname[:-2], 'wb') - fdst.write(self.templates.render_string( - fsrc.read(), self.globalcontext)) - fsrc.close() - fdst.close() - else: - shutil.copyfile(fullname, targetname) - elif path.isdir(fullname): - if filename in self.config.exclude_dirnames: - continue - if path.exists(targetname): - shutil.rmtree(targetname) - shutil.copytree(fullname, targetname) + copy_static_entry(fullname, targetname, self, + self.globalcontext) # last, copy logo file (handled differently) if self.config.html_logo: logobase = path.basename(self.config.html_logo) @@ -563,7 +564,8 @@ class StandaloneHTMLBuilder(Builder): def cleanup(self): # clean up theme stuff - self.theme.cleanup() + if self.theme: + self.theme.cleanup() def post_process_images(self, doctree): """ @@ -733,9 +735,12 @@ class SerializingHTMLBuilder(StandaloneHTMLBuilder): 'image/gif', 'image/jpeg'] def init(self): + self.config_hash = '' + self.tags_hash = '' + self.theme = None # no theme necessary + self.templates = None # no template bridge necessary self.init_translator_class() self.init_highlighter() - self.templates = None # no template bridge necessary def get_target_uri(self, docname, typ=None): if docname == 'index': diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index 8424d12c..a7acf33a 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -34,13 +34,17 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader): # TemplateBridge interface - def init(self, builder): - self.theme = builder.theme - # create a chain of paths to search: - # the theme's own dir and its bases' dirs - chain = self.theme.get_dirchain() - # then the theme parent paths (XXX doc) - chain.extend(self.theme.themepath) + def init(self, builder, theme=None, dirs=None): + # create a chain of paths to search + if theme: + # the theme's own dir and its bases' dirs + chain = theme.get_dirchain() + # then the theme parent paths + chain.extend(theme.themepath) + elif dirs: + chain = list(dirs) + else: + chain = [] # prepend explicit template paths self.templatepathlen = len(builder.config.templates_path) diff --git a/sphinx/theming.py b/sphinx/theming.py index d9fde636..e25498e1 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -30,11 +30,11 @@ class Theme(object): """ Represents the theme chosen in the configuration. """ + themes = {} + @classmethod def init_themes(cls, builder): """Search all theme paths for available themes.""" - cls.themes = {} - cls.themepath = list(builder.config.html_theme_path) cls.themepath.append( path.join(path.abspath(path.dirname(__file__)), 'themes')) diff --git a/sphinx/util/__init__.py b/sphinx/util/__init__.py index e02fd1b7..c03016a4 100644 --- a/sphinx/util/__init__.py +++ b/sphinx/util/__init__.py @@ -14,6 +14,7 @@ import re import sys import time import types +import shutil import fnmatch import tempfile import posixpath @@ -392,6 +393,25 @@ def movefile(source, dest): os.rename(source, dest) +def copy_static_entry(source, target, builder, context={}): + if path.isfile(source): + if source.lower().endswith('_t'): + # templated! + fsrc = open(source, 'rb') + fdst = open(target[:-2], 'wb') + fdst.write(builder.templates.render_string(fsrc.read(), context)) + fsrc.close() + fdst.close() + else: + shutil.copyfile(source, target) + elif path.isdir(source): + if filename in builder.config.exclude_dirnames: + return + if path.exists(target): + shutil.rmtree(target) + shutil.copytree(source, target) + + # monkey-patch Node.traverse to get more speed # traverse() is called so many times during a build that it saves # on average 20-25% overall build time! diff --git a/tests/root/conf.py b/tests/root/conf.py index 7b67d03e..85e9f468 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -16,6 +16,7 @@ source_suffix = '.txt' project = 'Sphinx ' copyright = '2008, Georg Brandl & Team' +# If this is changed, remember to update the versionchanges! version = '0.6' release = '0.6alpha1' today_fmt = '%B %d, %Y' diff --git a/tests/root/markup.txt b/tests/root/markup.txt index 532ecbac..d799c80d 100644 --- a/tests/root/markup.txt +++ b/tests/root/markup.txt @@ -84,13 +84,13 @@ Tables Version markup -------------- -.. versionadded:: 0.5 +.. versionadded:: 0.6 Some funny **stuff**. -.. versionchanged:: 0.5 +.. versionchanged:: 0.6 Even more funny stuff. -.. deprecated:: 0.4 +.. deprecated:: 0.6 Boring stuff. diff --git a/tests/test_build.py b/tests/test_build.py index f85e61ca..b9d2c779 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -239,6 +239,10 @@ def test_latex(app): # just let the remaining ones run for now +@with_app(buildername='pickle') +def test_pickle(app): + app.builder.build_all() + @with_app(buildername='linkcheck') def test_linkcheck(app): app.builder.build_all() @@ -247,6 +251,14 @@ def test_linkcheck(app): def test_text(app): app.builder.build_all() -@with_app(buildername='changes', cleanenv=True) +@with_app(buildername='htmlhelp') +def test_htmlhelp(app): + app.builder.build_all() + +@with_app(buildername='qthelp') +def test_qthelp(app): + app.builder.build_all() + +@with_app(buildername='changes') def test_changes(app): app.builder.build_all() -- cgit v1.2.1 From dacd37bf7d256ed6c631e6c6d83edda94c5b4cfd Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 21 Feb 2009 20:28:20 +0100 Subject: #96: The LaTeX builder now supports figures wrapped by text, when using the ``figwidth`` option and right/left alignment. --- CHANGES | 3 +++ sphinx/directives/__init__.py | 13 +++++++++++++ sphinx/texinputs/sphinx.sty | 4 ++++ sphinx/writers/latex.py | 26 ++++++++++++++++---------- 4 files changed, 36 insertions(+), 10 deletions(-) diff --git a/CHANGES b/CHANGES index b9874590..5f526270 100644 --- a/CHANGES +++ b/CHANGES @@ -120,6 +120,9 @@ New features added - The new ``html_link_suffix`` config value can be used to select the suffix of generated links between HTML files. + - #96: The LaTeX builder now supports figures wrapped by text, when + using the ``figwidth`` option and right/left alignment. + * New translations: - Italian by Sandro Dentella. diff --git a/sphinx/directives/__init__.py b/sphinx/directives/__init__.py index df86f997..2de29010 100644 --- a/sphinx/directives/__init__.py +++ b/sphinx/directives/__init__.py @@ -9,6 +9,19 @@ :license: BSD, see LICENSE for details. """ +from docutils.parsers.rst import directives +from docutils.parsers.rst.directives import images + +# import and register directives from sphinx.directives.desc import * from sphinx.directives.code import * from sphinx.directives.other import * + + +# allow units for the figure's "figwidth" +try: + images.Figure.option_spec['figwidth'] = \ + directives.length_or_percentage_or_unitless +except AttributeError: + images.figure.options['figwidth'] = \ + directives.length_or_percentage_or_unitless diff --git a/sphinx/texinputs/sphinx.sty b/sphinx/texinputs/sphinx.sty index 36768308..0ce6b863 100644 --- a/sphinx/texinputs/sphinx.sty +++ b/sphinx/texinputs/sphinx.sty @@ -17,11 +17,15 @@ \RequirePackage{makeidx} \RequirePackage{framed} \RequirePackage{color} +% For highlighted code. \RequirePackage{fancyvrb} +% For table captions. \RequirePackage{threeparttable} % Handle footnotes in tables. \RequirePackage{footnote} \makesavenoteenv{tabulary} +% For floating figures in the text. +\RequirePackage{wrapfig} % Redefine these colors to your liking in the preamble. \definecolor{TitleColor}{rgb}{0.126,0.263,0.361} diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 841a5ba1..2ff24203 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -850,17 +850,23 @@ class LaTeXTranslator(nodes.NodeVisitor): pass def visit_figure(self, node): - if (not node.attributes.has_key('align') or - node.attributes['align'] == 'center'): - # centering does not add vertical space like center. - align = '\n\\centering' - align_end = '' + if node.has_key('width') and node.get('align', '') in ('left', 'right'): + self.body.append('\\begin{wrapfigure}{%s}{%s}\n\\centering' % + (node['align'] == 'right' and 'r' or 'l', + node['width'])) + self.context.append('\\end{wrapfigure}\n') else: - # TODO non vertical space for other alignments. - align = '\\begin{flush%s}' % node.attributes['align'] - align_end = '\\end{flush%s}' % node.attributes['align'] - self.body.append('\\begin{figure}[htbp]%s\n' % align) - self.context.append('%s\\end{figure}\n' % align_end) + if (not node.attributes.has_key('align') or + node.attributes['align'] == 'center'): + # centering does not add vertical space like center. + align = '\n\\centering' + align_end = '' + else: + # TODO non vertical space for other alignments. + align = '\\begin{flush%s}' % node.attributes['align'] + align_end = '\\end{flush%s}' % node.attributes['align'] + self.body.append('\\begin{figure}[htbp]%s\n' % align) + self.context.append('%s\\end{figure}\n' % align_end) def depart_figure(self, node): self.body.append(self.context.pop()) -- cgit v1.2.1 From de5b27114e06ad034ec9a377ffd6414868e03f18 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 21 Feb 2009 22:01:27 +0100 Subject: Remove removed method. --- doc/ext/builderapi.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/doc/ext/builderapi.rst b/doc/ext/builderapi.rst index 5c671f2d..bb11bfe2 100644 --- a/doc/ext/builderapi.rst +++ b/doc/ext/builderapi.rst @@ -29,6 +29,3 @@ Writing new builders .. automethod:: write_doc .. automethod:: finish - Useful helpers: - - .. automethod:: init_templates -- cgit v1.2.1 From c85d410a0c77a640139aa02ba237e967f54706b1 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 21 Feb 2009 23:05:07 +0100 Subject: Style nits. --- sphinx/writers/html.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index 95b7f8b8..e40e8023 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -24,6 +24,7 @@ try: except ImportError: Image = None + class HTMLWriter(Writer): def __init__(self, builder): Writer.__init__(self) @@ -305,8 +306,7 @@ class HTMLTranslator(BaseTranslator): if Image and not (node.has_key('width') and node.has_key('height')): try: - im = Image.open(os.path.join(self.builder.srcdir, - olduri)) + im = Image.open(os.path.join(self.builder.srcdir, olduri)) except (IOError, # Source image can't be found or opened UnicodeError): # PIL doesn't like Unicode paths. pass -- cgit v1.2.1 From f2a538513d5b0b378c59d4a2b46a75d9f5c0ba1b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 22 Feb 2009 14:46:47 +0100 Subject: Small cosmetic fix. --- doc/_templates/layout.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/_templates/layout.html b/doc/_templates/layout.html index 2c370dbd..080c0935 100644 --- a/doc/_templates/layout.html +++ b/doc/_templates/layout.html @@ -1,8 +1,8 @@ {% extends "!layout.html" %} {% block rootrellink %} -
    • Sphinx home  | 
      • -
    • Documentation »
      • +
    • Sphinx home | 
      • +
    • Documentation»
      • {% endblock %} {% block header %} -- cgit v1.2.1 From 25931e26e4ee037472c256fb4cba4c6fbc17b78a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 22 Feb 2009 15:22:23 +0100 Subject: #10: implement HTML section numbering. --- CHANGES | 3 +++ doc/concepts.rst | 15 ++++++++++- doc/faq.rst | 6 ++++- sphinx/builders/__init__.py | 16 ++++++++--- sphinx/builders/html.py | 4 +++ sphinx/directives/other.py | 2 ++ sphinx/environment.py | 65 ++++++++++++++++++++++++++++++++++++++++++++- sphinx/writers/html.py | 18 +++++++++++++ tests/root/contents.txt | 1 + tests/test_env.py | 17 +++++++----- 10 files changed, 134 insertions(+), 13 deletions(-) diff --git a/CHANGES b/CHANGES index 5f526270..794af9b3 100644 --- a/CHANGES +++ b/CHANGES @@ -41,6 +41,9 @@ New features added line. Also, the current builder output format (e.g. "html" or "latex") is always a defined tag. + - #10: Added HTML section numbers, enabled by giving a + ``:numbered:`` flag to the ``toctree`` directive. + - The ``literalinclude`` directive now supports several more options, to include only parts of a file. diff --git a/doc/concepts.rst b/doc/concepts.rst index 3212256d..e6d5fa02 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -77,6 +77,18 @@ tables of contents. The ``toctree`` directive is the central element. You can also add external links, by giving an HTTP URL instead of a document name. + If you want to have section numbers even in HTML output, give the toctree a + ``numbered`` flag option. For example:: + + .. toctree:: + :numbered: + + foo + bar + + Numbering then starts at the heading of ``foo``. Sub-toctrees are + automatically numbered (don't give the ``numbered`` flag to those). + You can use "globbing" in toctree directives, by giving the ``glob`` flag option. All entries are then matched against the list of available documents, and matches are inserted into the list alphabetically. Example:: @@ -124,7 +136,8 @@ tables of contents. The ``toctree`` directive is the central element. Added "globbing" option. .. versionchanged:: 0.6 - Added "hidden" option and external links, as well as support for "self". + Added "numbered" and "hidden" options as well as external links and + support for "self" references. Special names diff --git a/doc/faq.rst b/doc/faq.rst index a43e9c72..ae12cdad 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -9,10 +9,14 @@ suggest new entries! How do I... ----------- +... get section numbers? + They are automatic in LaTeX output; for HTML, give a ``:numbered:`` option to + the :dir:`toctree` directive where you want to start numbering. + ... customize the look of the built HTML files? Use themes, see :doc:`theming`. -... add global substitutions? +... add global substitutions or includes? Add them in the :confval:`rst_epilog` config value. ... write my own extension? diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 25008388..097be078 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -246,7 +246,7 @@ class Builder(object): self.info(bold('building [%s]: ' % self.name), nonl=1) self.info(summary) - updated_docnames = [] + updated_docnames = set() # while reading, collect all warnings from docutils warnings = [] self.env.set_warnfunc(warnings.append) @@ -257,7 +257,7 @@ class Builder(object): self.info(iterator.next()) for docname in self.status_iterator(iterator, 'reading sources... ', purple): - updated_docnames.append(docname) + updated_docnames.add(docname) # nothing further to do, the environment has already # done the reading for warning in warnings: @@ -265,6 +265,16 @@ class Builder(object): self.warn(warning) self.env.set_warnfunc(self.warn) + doccount = len(updated_docnames) + self.info(bold('looking for now-outdated files... '), nonl=1) + for docname in self.env.check_dependents(updated_docnames): + updated_docnames.add(docname) + outdated = len(updated_docnames) - doccount + if outdated: + self.info('%d found' % outdated) + else: + self.info('none found') + if updated_docnames: # save the environment self.info(bold('pickling environment... '), nonl=True) @@ -282,7 +292,7 @@ class Builder(object): # another indirection to support builders that don't build # files individually - self.write(docnames, updated_docnames, method) + self.write(docnames, list(updated_docnames), method) # finish (write static files etc.) self.finish() diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 2c4569df..2b92c2cb 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -79,6 +79,9 @@ class StandaloneHTMLBuilder(Builder): # a hash of all config values that, if changed, cause a full rebuild self.config_hash = '' self.tags_hash = '' + # section numbers for headings in the currently visited document + self.secnumbers = {} + self.init_templates() self.init_highlighter() self.init_translator_class() @@ -336,6 +339,7 @@ class StandaloneHTMLBuilder(Builder): destination = StringOutput(encoding='utf-8') doctree.settings = self.docsettings + self.secnumbers = self.env.toc_secnumbers.get(docname, {}) self.imgpath = relative_uri(self.get_target_uri(docname), '_images') self.post_process_images(doctree) self.dlpath = relative_uri(self.get_target_uri(docname), '_downloads') diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index b1270b01..f1d67a3c 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -32,6 +32,7 @@ class TocTree(Directive): 'maxdepth': int, 'glob': directives.flag, 'hidden': directives.flag, + 'numbered': directives.flag, } def run(self): @@ -93,6 +94,7 @@ class TocTree(Directive): subnode['maxdepth'] = self.options.get('maxdepth', -1) subnode['glob'] = glob subnode['hidden'] = 'hidden' in self.options + subnode['numbered'] = 'numbered' in self.options ret.append(subnode) return ret diff --git a/sphinx/environment.py b/sphinx/environment.py index 3d93b63c..1f7d0f2f 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -277,11 +277,13 @@ class BuildEnvironment: self.toc_num_entries = {} # docname -> number of real entries # used to determine when to show the TOC # in a sidebar (don't show if it's only one item) + self.toc_secnumbers = {} # docname -> dict of sectionid -> number self.toctree_includes = {} # docname -> list of toctree includefiles self.files_to_rebuild = {} # docname -> set of files # (containing its TOCs) to rebuild too self.glob_toctrees = set() # docnames that have :glob: toctrees + self.numbered_toctrees = set() # docnames that have :numbered: toctrees # X-ref target inventory self.descrefs = {} # fullname -> docname, desctype @@ -341,11 +343,13 @@ class BuildEnvironment: self.dependencies.pop(docname, None) self.titles.pop(docname, None) self.tocs.pop(docname, None) + self.toc_secnumbers.pop(docname, None) self.toc_num_entries.pop(docname, None) self.toctree_includes.pop(docname, None) self.filemodules.pop(docname, None) self.indexentries.pop(docname, None) self.glob_toctrees.discard(docname) + self.numbered_toctrees.discard(docname) self.images.purge_doc(docname) self.dlfiles.purge_doc(docname) @@ -502,7 +506,8 @@ class BuildEnvironment: self.clear_doc(docname) # read all new and changed files - for docname in sorted(added | changed): + to_read = added | changed + for docname in sorted(to_read): yield docname self.read_doc(docname, app=app) @@ -514,6 +519,11 @@ class BuildEnvironment: if app: app.emit('env-updated', self) + def check_dependents(self, already): + to_rewrite = self.assign_section_numbers() + for docname in to_rewrite: + if docname not in already: + yield docname # --------- SINGLE FILE READING -------------------------------------------- @@ -824,6 +834,8 @@ class BuildEnvironment: file relations from it.""" if toctreenode['glob']: self.glob_toctrees.add(docname) + if toctreenode['numbered']: + self.numbered_toctrees.add(docname) includefiles = toctreenode['includefiles'] for includefile in includefiles: # note that if the included file is rebuilt, this one must be @@ -1315,6 +1327,57 @@ class BuildEnvironment: # allow custom references to be resolved builder.app.emit('doctree-resolved', doctree, fromdocname) + def assign_section_numbers(self): + """Assign a section number to each heading under a numbered toctree.""" + # a list of all docnames whose section numbers changed + rewrite_needed = [] + + old_secnumbers = self.toc_secnumbers + self.toc_secnumbers = {} + + def _walk_toc(node, secnums, titlenode=None): + # titlenode is the title of the document, it will get assigned a + # secnumber too, so that it shows up in next/prev/parent rellinks + for subnode in node.children: + if isinstance(subnode, nodes.bullet_list): + numstack.append(0) + _walk_toc(subnode, secnums, titlenode) + numstack.pop() + titlenode = None + elif isinstance(subnode, nodes.list_item): + _walk_toc(subnode, secnums, titlenode) + titlenode = None + elif isinstance(subnode, addnodes.compact_paragraph): + numstack[-1] += 1 + secnums[subnode[0]['anchorname']] = \ + subnode[0]['secnumber'] = tuple(numstack) + if titlenode: + titlenode['secnumber'] = tuple(numstack) + titlenode = None + elif isinstance(subnode, addnodes.toctree): + _walk_toctree(subnode) + + def _walk_toctree(toctreenode): + for (title, ref) in toctreenode['entries']: + if url_re.match(ref) or ref == 'self': + # don't mess with those + continue + if ref in self.tocs: + secnums = self.toc_secnumbers[ref] = {} + _walk_toc(self.tocs[ref], secnums, self.titles.get(ref)) + if secnums != old_secnumbers.get(ref): + rewrite_needed.append(ref) + + for docname in self.numbered_toctrees: + doctree = self.get_doctree(docname) + for toctreenode in doctree.traverse(addnodes.toctree): + if toctreenode.get('numbered'): + # every numbered toctree gets new numbering + numstack = [0] + _walk_toctree(toctreenode) + + return rewrite_needed + def create_index(self, builder, _fixre=re.compile(r'(.*) ([(][^()]*[)])')): """Create the real index from the collected index entries.""" new = {} diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index e40e8023..e2f754a8 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -158,6 +158,8 @@ class HTMLTranslator(BaseTranslator): return self.body[-1] = ' tag BaseTranslator.visit_title(self, node, move_ids=0) + self.add_secnumber(node) + else: + def visit_title(self, node): + BaseTranslator.visit_title(self, node) + self.add_secnumber(node) # overwritten def visit_literal_block(self, node): diff --git a/tests/root/contents.txt b/tests/root/contents.txt index c87a2d8e..719034ce 100644 --- a/tests/root/contents.txt +++ b/tests/root/contents.txt @@ -9,6 +9,7 @@ Contents: .. toctree:: :maxdepth: 2 + :numbered: images subdir/images diff --git a/tests/test_env.py b/tests/test_env.py index 5d27bcfd..07e2cbe4 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -76,19 +76,22 @@ def test_second_update(): # delete, add and "edit" (change saved mtime) some files and update again env.all_docs['contents'] = 0 root = path(app.srcdir) - (root / 'images.txt').unlink() + # important: using "autodoc" because it is the last one to be included in + # the contents.txt toctree; otherwise section numbers would shift + (root / 'autodoc.txt').unlink() (root / 'new.txt').write_text('New file\n========\n') it = env.update(app.config, app.srcdir, app.doctreedir, app) msg = it.next() - assert '1 added, 2 changed, 1 removed' in msg + assert '1 added, 3 changed, 1 removed' in msg docnames = set() for docname in it: docnames.add(docname) - # "includes" is in there because it contains a reference to a nonexisting - # downloadable file, which is given another chance to exist - assert docnames == set(['contents', 'new', 'includes']) - assert 'images' not in env.all_docs - assert 'images' not in env.found_docs + # "includes" and "images" are in there because they contain references + # to nonexisting downloadable or image files, which are given another + # chance to exist + assert docnames == set(['contents', 'new', 'includes', 'images']) + assert 'autodoc' not in env.all_docs + assert 'autodoc' not in env.found_docs def test_object_inventory(): refs = env.descrefs -- cgit v1.2.1 From 8c06d1be5c28a7fc1d2511d4601430ef15ef0cd1 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 22 Feb 2009 16:30:40 +0100 Subject: Bump ENV_VERSION after section numbering change. --- sphinx/environment.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/environment.py b/sphinx/environment.py index 1f7d0f2f..6d34eb61 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -61,7 +61,7 @@ default_settings = { # This is increased every time an environment attribute is added # or changed to properly invalidate pickle files. -ENV_VERSION = 28 +ENV_VERSION = 29 default_substitutions = set([ -- cgit v1.2.1 From 8041e28a58f85edac09ce74722a656f09de95a78 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 22 Feb 2009 19:00:36 +0100 Subject: Add makefile target for easy test coverage checking. --- Makefile | 3 + tests/coverage.py | 1163 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1166 insertions(+) create mode 100755 tests/coverage.py diff --git a/Makefile b/Makefile index 4d5048d1..108ed96d 100644 --- a/Makefile +++ b/Makefile @@ -30,3 +30,6 @@ reindent: test: @cd tests; $(PYTHON) run.py -d -m '^[tT]est' $(TEST) + +covertest: + @cd tests; $(PYTHON) run.py -d -m '^[tT]est' --with-coverage --cover-package=sphinx $(TEST) diff --git a/tests/coverage.py b/tests/coverage.py new file mode 100755 index 00000000..148e573c --- /dev/null +++ b/tests/coverage.py @@ -0,0 +1,1163 @@ +#!/usr/bin/python +# +# Perforce Defect Tracking Integration Project +# +# +# COVERAGE.PY -- COVERAGE TESTING +# +# Gareth Rees, Ravenbrook Limited, 2001-12-04 +# Ned Batchelder, 2004-12-12 +# http://nedbatchelder.com/code/modules/coverage.html +# +# +# 1. INTRODUCTION +# +# This module provides coverage testing for Python code. +# +# The intended readership is all Python developers. +# +# This document is not confidential. +# +# See [GDR 2001-12-04a] for the command-line interface, programmatic +# interface and limitations. See [GDR 2001-12-04b] for requirements and +# design. + +r"""Usage: + +coverage.py -x [-p] MODULE.py [ARG1 ARG2 ...] + Execute module, passing the given command-line arguments, collecting + coverage data. With the -p option, write to a temporary file containing + the machine name and process ID. + +coverage.py -e + Erase collected coverage data. + +coverage.py -c + Collect data from multiple coverage files (as created by -p option above) + and store it into a single file representing the union of the coverage. + +coverage.py -r [-m] [-o dir1,dir2,...] FILE1 FILE2 ... + Report on the statement coverage for the given files. With the -m + option, show line numbers of the statements that weren't executed. + +coverage.py -a [-d dir] [-o dir1,dir2,...] FILE1 FILE2 ... + Make annotated copies of the given files, marking statements that + are executed with > and statements that are missed with !. With + the -d option, make the copies in that directory. Without the -d + option, make each copy in the same directory as the original. + +-o dir,dir2,... + Omit reporting or annotating files when their filename path starts with + a directory listed in the omit list. + e.g. python coverage.py -i -r -o c:\python23,lib\enthought\traits + +Coverage data is saved in the file .coverage by default. Set the +COVERAGE_FILE environment variable to save it somewhere else.""" + +__version__ = "2.85.20080914" # see detailed history at the end of this file. + +import compiler +import compiler.visitor +import glob +import os +import re +import string +import symbol +import sys +import threading +import token +import types +import zipimport +from socket import gethostname + +# Python version compatibility +try: + strclass = basestring # new to 2.3 +except: + strclass = str + +# 2. IMPLEMENTATION +# +# This uses the "singleton" pattern. +# +# The word "morf" means a module object (from which the source file can +# be deduced by suitable manipulation of the __file__ attribute) or a +# filename. +# +# When we generate a coverage report we have to canonicalize every +# filename in the coverage dictionary just in case it refers to the +# module we are reporting on. It seems a shame to throw away this +# information so the data in the coverage dictionary is transferred to +# the 'cexecuted' dictionary under the canonical filenames. +# +# The coverage dictionary is called "c" and the trace function "t". The +# reason for these short names is that Python looks up variables by name +# at runtime and so execution time depends on the length of variables! +# In the bottleneck of this application it's appropriate to abbreviate +# names to increase speed. + +class StatementFindingAstVisitor(compiler.visitor.ASTVisitor): + """ A visitor for a parsed Abstract Syntax Tree which finds executable + statements. + """ + def __init__(self, statements, excluded, suite_spots): + compiler.visitor.ASTVisitor.__init__(self) + self.statements = statements + self.excluded = excluded + self.suite_spots = suite_spots + self.excluding_suite = 0 + + def doRecursive(self, node): + for n in node.getChildNodes(): + self.dispatch(n) + + visitStmt = visitModule = doRecursive + + def doCode(self, node): + if hasattr(node, 'decorators') and node.decorators: + self.dispatch(node.decorators) + self.recordAndDispatch(node.code) + else: + self.doSuite(node, node.code) + + visitFunction = visitClass = doCode + + def getFirstLine(self, node): + # Find the first line in the tree node. + lineno = node.lineno + for n in node.getChildNodes(): + f = self.getFirstLine(n) + if lineno and f: + lineno = min(lineno, f) + else: + lineno = lineno or f + return lineno + + def getLastLine(self, node): + # Find the first line in the tree node. + lineno = node.lineno + for n in node.getChildNodes(): + lineno = max(lineno, self.getLastLine(n)) + return lineno + + def doStatement(self, node): + self.recordLine(self.getFirstLine(node)) + + visitAssert = visitAssign = visitAssTuple = visitPrint = \ + visitPrintnl = visitRaise = visitSubscript = visitDecorators = \ + doStatement + + def visitPass(self, node): + # Pass statements have weird interactions with docstrings. If this + # pass statement is part of one of those pairs, claim that the statement + # is on the later of the two lines. + l = node.lineno + if l: + lines = self.suite_spots.get(l, [l,l]) + self.statements[lines[1]] = 1 + + def visitDiscard(self, node): + # Discard nodes are statements that execute an expression, but then + # discard the results. This includes function calls, so we can't + # ignore them all. But if the expression is a constant, the statement + # won't be "executed", so don't count it now. + if node.expr.__class__.__name__ != 'Const': + self.doStatement(node) + + def recordNodeLine(self, node): + # Stmt nodes often have None, but shouldn't claim the first line of + # their children (because the first child might be an ignorable line + # like "global a"). + if node.__class__.__name__ != 'Stmt': + return self.recordLine(self.getFirstLine(node)) + else: + return 0 + + def recordLine(self, lineno): + # Returns a bool, whether the line is included or excluded. + if lineno: + # Multi-line tests introducing suites have to get charged to their + # keyword. + if lineno in self.suite_spots: + lineno = self.suite_spots[lineno][0] + # If we're inside an excluded suite, record that this line was + # excluded. + if self.excluding_suite: + self.excluded[lineno] = 1 + return 0 + # If this line is excluded, or suite_spots maps this line to + # another line that is exlcuded, then we're excluded. + elif self.excluded.has_key(lineno) or \ + self.suite_spots.has_key(lineno) and \ + self.excluded.has_key(self.suite_spots[lineno][1]): + return 0 + # Otherwise, this is an executable line. + else: + self.statements[lineno] = 1 + return 1 + return 0 + + default = recordNodeLine + + def recordAndDispatch(self, node): + self.recordNodeLine(node) + self.dispatch(node) + + def doSuite(self, intro, body, exclude=0): + exsuite = self.excluding_suite + if exclude or (intro and not self.recordNodeLine(intro)): + self.excluding_suite = 1 + self.recordAndDispatch(body) + self.excluding_suite = exsuite + + def doPlainWordSuite(self, prevsuite, suite): + # Finding the exclude lines for else's is tricky, because they aren't + # present in the compiler parse tree. Look at the previous suite, + # and find its last line. If any line between there and the else's + # first line are excluded, then we exclude the else. + lastprev = self.getLastLine(prevsuite) + firstelse = self.getFirstLine(suite) + for l in range(lastprev+1, firstelse): + if self.suite_spots.has_key(l): + self.doSuite(None, suite, exclude=self.excluded.has_key(l)) + break + else: + self.doSuite(None, suite) + + def doElse(self, prevsuite, node): + if node.else_: + self.doPlainWordSuite(prevsuite, node.else_) + + def visitFor(self, node): + self.doSuite(node, node.body) + self.doElse(node.body, node) + + visitWhile = visitFor + + def visitIf(self, node): + # The first test has to be handled separately from the rest. + # The first test is credited to the line with the "if", but the others + # are credited to the line with the test for the elif. + self.doSuite(node, node.tests[0][1]) + for t, n in node.tests[1:]: + self.doSuite(t, n) + self.doElse(node.tests[-1][1], node) + + def visitTryExcept(self, node): + self.doSuite(node, node.body) + for i in range(len(node.handlers)): + a, b, h = node.handlers[i] + if not a: + # It's a plain "except:". Find the previous suite. + if i > 0: + prev = node.handlers[i-1][2] + else: + prev = node.body + self.doPlainWordSuite(prev, h) + else: + self.doSuite(a, h) + self.doElse(node.handlers[-1][2], node) + + def visitTryFinally(self, node): + self.doSuite(node, node.body) + self.doPlainWordSuite(node.body, node.final) + + def visitWith(self, node): + self.doSuite(node, node.body) + + def visitGlobal(self, node): + # "global" statements don't execute like others (they don't call the + # trace function), so don't record their line numbers. + pass + +the_coverage = None + +class CoverageException(Exception): + pass + +class coverage: + # Name of the cache file (unless environment variable is set). + cache_default = ".coverage" + + # Environment variable naming the cache file. + cache_env = "COVERAGE_FILE" + + # A dictionary with an entry for (Python source file name, line number + # in that file) if that line has been executed. + c = {} + + # A map from canonical Python source file name to a dictionary in + # which there's an entry for each line number that has been + # executed. + cexecuted = {} + + # Cache of results of calling the analysis2() method, so that you can + # specify both -r and -a without doing double work. + analysis_cache = {} + + # Cache of results of calling the canonical_filename() method, to + # avoid duplicating work. + canonical_filename_cache = {} + + def __init__(self): + global the_coverage + if the_coverage: + raise CoverageException("Only one coverage object allowed.") + self.usecache = 1 + self.cache = None + self.parallel_mode = False + self.exclude_re = '' + self.nesting = 0 + self.cstack = [] + self.xstack = [] + self.relative_dir = self.abs_file(os.curdir)+os.sep + self.exclude('# *pragma[: ]*[nN][oO] *[cC][oO][vV][eE][rR]') + + # t(f, x, y). This method is passed to sys.settrace as a trace function. + # See [van Rossum 2001-07-20b, 9.2] for an explanation of sys.settrace and + # the arguments and return value of the trace function. + # See [van Rossum 2001-07-20a, 3.2] for a description of frame and code + # objects. + + def t(self, f, w, unused): #pragma: no cover + if w == 'line': + self.c[(f.f_code.co_filename, f.f_lineno)] = 1 + #-for c in self.cstack: + #- c[(f.f_code.co_filename, f.f_lineno)] = 1 + return self.t + + def help(self, error=None): #pragma: no cover + if error: + print error + print + print __doc__ + sys.exit(1) + + def command_line(self, argv, help_fn=None): + import getopt + help_fn = help_fn or self.help + settings = {} + optmap = { + '-a': 'annotate', + '-c': 'collect', + '-d:': 'directory=', + '-e': 'erase', + '-h': 'help', + '-i': 'ignore-errors', + '-m': 'show-missing', + '-p': 'parallel-mode', + '-r': 'report', + '-x': 'execute', + '-o:': 'omit=', + } + short_opts = string.join(map(lambda o: o[1:], optmap.keys()), '') + long_opts = optmap.values() + options, args = getopt.getopt(argv, short_opts, long_opts) + for o, a in options: + if optmap.has_key(o): + settings[optmap[o]] = 1 + elif optmap.has_key(o + ':'): + settings[optmap[o + ':']] = a + elif o[2:] in long_opts: + settings[o[2:]] = 1 + elif o[2:] + '=' in long_opts: + settings[o[2:]+'='] = a + else: #pragma: no cover + pass # Can't get here, because getopt won't return anything unknown. + + if settings.get('help'): + help_fn() + + for i in ['erase', 'execute']: + for j in ['annotate', 'report', 'collect']: + if settings.get(i) and settings.get(j): + help_fn("You can't specify the '%s' and '%s' " + "options at the same time." % (i, j)) + + args_needed = (settings.get('execute') + or settings.get('annotate') + or settings.get('report')) + action = (settings.get('erase') + or settings.get('collect') + or args_needed) + if not action: + help_fn("You must specify at least one of -e, -x, -c, -r, or -a.") + if not args_needed and args: + help_fn("Unexpected arguments: %s" % " ".join(args)) + + self.parallel_mode = settings.get('parallel-mode') + self.get_ready() + + if settings.get('erase'): + self.erase() + if settings.get('execute'): + if not args: + help_fn("Nothing to do.") + sys.argv = args + self.start() + import __main__ + sys.path[0] = os.path.dirname(sys.argv[0]) + execfile(sys.argv[0], __main__.__dict__) + if settings.get('collect'): + self.collect() + if not args: + args = self.cexecuted.keys() + + ignore_errors = settings.get('ignore-errors') + show_missing = settings.get('show-missing') + directory = settings.get('directory=') + + omit = settings.get('omit=') + if omit is not None: + omit = [self.abs_file(p) for p in omit.split(',')] + else: + omit = [] + + if settings.get('report'): + self.report(args, show_missing, ignore_errors, omit_prefixes=omit) + if settings.get('annotate'): + self.annotate(args, directory, ignore_errors, omit_prefixes=omit) + + def use_cache(self, usecache, cache_file=None): + self.usecache = usecache + if cache_file and not self.cache: + self.cache_default = cache_file + + def get_ready(self, parallel_mode=False): + if self.usecache and not self.cache: + self.cache = os.environ.get(self.cache_env, self.cache_default) + if self.parallel_mode: + self.cache += "." + gethostname() + "." + str(os.getpid()) + self.restore() + self.analysis_cache = {} + + def start(self, parallel_mode=False): + self.get_ready() + if self.nesting == 0: #pragma: no cover + sys.settrace(self.t) + if hasattr(threading, 'settrace'): + threading.settrace(self.t) + self.nesting += 1 + + def stop(self): + self.nesting -= 1 + if self.nesting == 0: #pragma: no cover + sys.settrace(None) + if hasattr(threading, 'settrace'): + threading.settrace(None) + + def erase(self): + self.get_ready() + self.c = {} + self.analysis_cache = {} + self.cexecuted = {} + if self.cache and os.path.exists(self.cache): + os.remove(self.cache) + + def exclude(self, re): + if self.exclude_re: + self.exclude_re += "|" + self.exclude_re += "(" + re + ")" + + def begin_recursive(self): + self.cstack.append(self.c) + self.xstack.append(self.exclude_re) + + def end_recursive(self): + self.c = self.cstack.pop() + self.exclude_re = self.xstack.pop() + + # save(). Save coverage data to the coverage cache. + + def save(self): + if self.usecache and self.cache: + self.canonicalize_filenames() + cache = open(self.cache, 'wb') + import marshal + marshal.dump(self.cexecuted, cache) + cache.close() + + # restore(). Restore coverage data from the coverage cache (if it exists). + + def restore(self): + self.c = {} + self.cexecuted = {} + assert self.usecache + if os.path.exists(self.cache): + self.cexecuted = self.restore_file(self.cache) + + def restore_file(self, file_name): + try: + cache = open(file_name, 'rb') + import marshal + cexecuted = marshal.load(cache) + cache.close() + if isinstance(cexecuted, types.DictType): + return cexecuted + else: + return {} + except: + return {} + + # collect(). Collect data in multiple files produced by parallel mode + + def collect(self): + cache_dir, local = os.path.split(self.cache) + for f in os.listdir(cache_dir or '.'): + if not f.startswith(local): + continue + + full_path = os.path.join(cache_dir, f) + cexecuted = self.restore_file(full_path) + self.merge_data(cexecuted) + + def merge_data(self, new_data): + for file_name, file_data in new_data.items(): + if self.cexecuted.has_key(file_name): + self.merge_file_data(self.cexecuted[file_name], file_data) + else: + self.cexecuted[file_name] = file_data + + def merge_file_data(self, cache_data, new_data): + for line_number in new_data.keys(): + if not cache_data.has_key(line_number): + cache_data[line_number] = new_data[line_number] + + def abs_file(self, filename): + """ Helper function to turn a filename into an absolute normalized + filename. + """ + return os.path.normcase(os.path.abspath(os.path.realpath(filename))) + + def get_zip_data(self, filename): + """ Get data from `filename` if it is a zip file path, or return None + if it is not. + """ + markers = ['.zip'+os.sep, '.egg'+os.sep] + for marker in markers: + if marker in filename: + parts = filename.split(marker) + try: + zi = zipimport.zipimporter(parts[0]+marker[:-1]) + except zipimport.ZipImportError: + continue + try: + data = zi.get_data(parts[1]) + except IOError: + continue + return data + return None + + # canonical_filename(filename). Return a canonical filename for the + # file (that is, an absolute path with no redundant components and + # normalized case). See [GDR 2001-12-04b, 3.3]. + + def canonical_filename(self, filename): + if not self.canonical_filename_cache.has_key(filename): + f = filename + if os.path.isabs(f) and not os.path.exists(f): + if not self.get_zip_data(f): + f = os.path.basename(f) + if not os.path.isabs(f): + for path in [os.curdir] + sys.path: + g = os.path.join(path, f) + if os.path.exists(g): + f = g + break + cf = self.abs_file(f) + self.canonical_filename_cache[filename] = cf + return self.canonical_filename_cache[filename] + + # canonicalize_filenames(). Copy results from "c" to "cexecuted", + # canonicalizing filenames on the way. Clear the "c" map. + + def canonicalize_filenames(self): + for filename, lineno in self.c.keys(): + if filename == '': + # Can't do anything useful with exec'd strings, so skip them. + continue + f = self.canonical_filename(filename) + if not self.cexecuted.has_key(f): + self.cexecuted[f] = {} + self.cexecuted[f][lineno] = 1 + self.c = {} + + # morf_filename(morf). Return the filename for a module or file. + + def morf_filename(self, morf): + if hasattr(morf, '__file__'): + f = morf.__file__ + else: + f = morf + return self.canonical_filename(f) + + # analyze_morf(morf). Analyze the module or filename passed as + # the argument. If the source code can't be found, raise an error. + # Otherwise, return a tuple of (1) the canonical filename of the + # source code for the module, (2) a list of lines of statements + # in the source code, (3) a list of lines of excluded statements, + # and (4), a map of line numbers to multi-line line number ranges, for + # statements that cross lines. + + def analyze_morf(self, morf): + if self.analysis_cache.has_key(morf): + return self.analysis_cache[morf] + filename = self.morf_filename(morf) + ext = os.path.splitext(filename)[1] + source, sourcef = None, None + if ext == '.pyc': + if not os.path.exists(filename[:-1]): + source = self.get_zip_data(filename[:-1]) + if not source: + raise CoverageException( + "No source for compiled code '%s'." % filename + ) + filename = filename[:-1] + if not source: + sourcef = open(filename, 'rU') + source = sourcef.read() + try: + lines, excluded_lines, line_map = self.find_executable_statements( + source, exclude=self.exclude_re + ) + except SyntaxError, synerr: + raise CoverageException( + "Couldn't parse '%s' as Python source: '%s' at line %d" % + (filename, synerr.msg, synerr.lineno) + ) + if sourcef: + sourcef.close() + result = filename, lines, excluded_lines, line_map + self.analysis_cache[morf] = result + return result + + def first_line_of_tree(self, tree): + while True: + if len(tree) == 3 and type(tree[2]) == type(1): + return tree[2] + tree = tree[1] + + def last_line_of_tree(self, tree): + while True: + if len(tree) == 3 and type(tree[2]) == type(1): + return tree[2] + tree = tree[-1] + + def find_docstring_pass_pair(self, tree, spots): + for i in range(1, len(tree)): + if self.is_string_constant(tree[i]) and self.is_pass_stmt(tree[i+1]): + first_line = self.first_line_of_tree(tree[i]) + last_line = self.last_line_of_tree(tree[i+1]) + self.record_multiline(spots, first_line, last_line) + + def is_string_constant(self, tree): + try: + return tree[0] == symbol.stmt and tree[1][1][1][0] == symbol.expr_stmt + except: + return False + + def is_pass_stmt(self, tree): + try: + return tree[0] == symbol.stmt and tree[1][1][1][0] == symbol.pass_stmt + except: + return False + + def record_multiline(self, spots, i, j): + for l in range(i, j+1): + spots[l] = (i, j) + + def get_suite_spots(self, tree, spots): + """ Analyze a parse tree to find suite introducers which span a number + of lines. + """ + for i in range(1, len(tree)): + if type(tree[i]) == type(()): + if tree[i][0] == symbol.suite: + # Found a suite, look back for the colon and keyword. + lineno_colon = lineno_word = None + for j in range(i-1, 0, -1): + if tree[j][0] == token.COLON: + # Colons are never executed themselves: we want the + # line number of the last token before the colon. + lineno_colon = self.last_line_of_tree(tree[j-1]) + elif tree[j][0] == token.NAME: + if tree[j][1] == 'elif': + # Find the line number of the first non-terminal + # after the keyword. + t = tree[j+1] + while t and token.ISNONTERMINAL(t[0]): + t = t[1] + if t: + lineno_word = t[2] + else: + lineno_word = tree[j][2] + break + elif tree[j][0] == symbol.except_clause: + # "except" clauses look like: + # ('except_clause', ('NAME', 'except', lineno), ...) + if tree[j][1][0] == token.NAME: + lineno_word = tree[j][1][2] + break + if lineno_colon and lineno_word: + # Found colon and keyword, mark all the lines + # between the two with the two line numbers. + self.record_multiline(spots, lineno_word, lineno_colon) + + # "pass" statements are tricky: different versions of Python + # treat them differently, especially in the common case of a + # function with a doc string and a single pass statement. + self.find_docstring_pass_pair(tree[i], spots) + + elif tree[i][0] == symbol.simple_stmt: + first_line = self.first_line_of_tree(tree[i]) + last_line = self.last_line_of_tree(tree[i]) + if first_line != last_line: + self.record_multiline(spots, first_line, last_line) + self.get_suite_spots(tree[i], spots) + + def find_executable_statements(self, text, exclude=None): + # Find lines which match an exclusion pattern. + excluded = {} + suite_spots = {} + if exclude: + reExclude = re.compile(exclude) + lines = text.split('\n') + for i in range(len(lines)): + if reExclude.search(lines[i]): + excluded[i+1] = 1 + + # Parse the code and analyze the parse tree to find out which statements + # are multiline, and where suites begin and end. + import parser + tree = parser.suite(text+'\n\n').totuple(1) + self.get_suite_spots(tree, suite_spots) + #print "Suite spots:", suite_spots + + # Use the compiler module to parse the text and find the executable + # statements. We add newlines to be impervious to final partial lines. + statements = {} + ast = compiler.parse(text+'\n\n') + visitor = StatementFindingAstVisitor(statements, excluded, suite_spots) + compiler.walk(ast, visitor, walker=visitor) + + lines = statements.keys() + lines.sort() + excluded_lines = excluded.keys() + excluded_lines.sort() + return lines, excluded_lines, suite_spots + + # format_lines(statements, lines). Format a list of line numbers + # for printing by coalescing groups of lines as long as the lines + # represent consecutive statements. This will coalesce even if + # there are gaps between statements, so if statements = + # [1,2,3,4,5,10,11,12,13,14] and lines = [1,2,5,10,11,13,14] then + # format_lines will return "1-2, 5-11, 13-14". + + def format_lines(self, statements, lines): + pairs = [] + i = 0 + j = 0 + start = None + pairs = [] + while i < len(statements) and j < len(lines): + if statements[i] == lines[j]: + if start == None: + start = lines[j] + end = lines[j] + j = j + 1 + elif start: + pairs.append((start, end)) + start = None + i = i + 1 + if start: + pairs.append((start, end)) + def stringify(pair): + start, end = pair + if start == end: + return "%d" % start + else: + return "%d-%d" % (start, end) + ret = string.join(map(stringify, pairs), ", ") + return ret + + # Backward compatibility with version 1. + def analysis(self, morf): + f, s, _, m, mf = self.analysis2(morf) + return f, s, m, mf + + def analysis2(self, morf): + filename, statements, excluded, line_map = self.analyze_morf(morf) + self.canonicalize_filenames() + if not self.cexecuted.has_key(filename): + self.cexecuted[filename] = {} + missing = [] + for line in statements: + lines = line_map.get(line, [line, line]) + for l in range(lines[0], lines[1]+1): + if self.cexecuted[filename].has_key(l): + break + else: + missing.append(line) + return (filename, statements, excluded, missing, + self.format_lines(statements, missing)) + + def relative_filename(self, filename): + """ Convert filename to relative filename from self.relative_dir. + """ + return filename.replace(self.relative_dir, "") + + def morf_name(self, morf): + """ Return the name of morf as used in report. + """ + if hasattr(morf, '__name__'): + return morf.__name__ + else: + return self.relative_filename(os.path.splitext(morf)[0]) + + def filter_by_prefix(self, morfs, omit_prefixes): + """ Return list of morfs where the morf name does not begin + with any one of the omit_prefixes. + """ + filtered_morfs = [] + for morf in morfs: + for prefix in omit_prefixes: + if self.morf_name(morf).startswith(prefix): + break + else: + filtered_morfs.append(morf) + + return filtered_morfs + + def morf_name_compare(self, x, y): + return cmp(self.morf_name(x), self.morf_name(y)) + + def report(self, morfs, show_missing=1, ignore_errors=0, file=None, omit_prefixes=[]): + if not isinstance(morfs, types.ListType): + morfs = [morfs] + # On windows, the shell doesn't expand wildcards. Do it here. + globbed = [] + for morf in morfs: + if isinstance(morf, strclass): + globbed.extend(glob.glob(morf)) + else: + globbed.append(morf) + morfs = globbed + + morfs = self.filter_by_prefix(morfs, omit_prefixes) + morfs.sort(self.morf_name_compare) + + max_name = max([5,] + map(len, map(self.morf_name, morfs))) + fmt_name = "%%- %ds " % max_name + fmt_err = fmt_name + "%s: %s" + header = fmt_name % "Name" + " Stmts Exec Cover" + fmt_coverage = fmt_name + "% 6d % 6d % 5d%%" + if show_missing: + header = header + " Missing" + fmt_coverage = fmt_coverage + " %s" + if not file: + file = sys.stdout + print >>file, header + print >>file, "-" * len(header) + total_statements = 0 + total_executed = 0 + for morf in morfs: + name = self.morf_name(morf) + try: + _, statements, _, missing, readable = self.analysis2(morf) + n = len(statements) + m = n - len(missing) + if n > 0: + pc = 100.0 * m / n + else: + pc = 100.0 + args = (name, n, m, pc) + if show_missing: + args = args + (readable,) + print >>file, fmt_coverage % args + total_statements = total_statements + n + total_executed = total_executed + m + except KeyboardInterrupt: #pragma: no cover + raise + except: + if not ignore_errors: + typ, msg = sys.exc_info()[:2] + print >>file, fmt_err % (name, typ, msg) + if len(morfs) > 1: + print >>file, "-" * len(header) + if total_statements > 0: + pc = 100.0 * total_executed / total_statements + else: + pc = 100.0 + args = ("TOTAL", total_statements, total_executed, pc) + if show_missing: + args = args + ("",) + print >>file, fmt_coverage % args + + # annotate(morfs, ignore_errors). + + blank_re = re.compile(r"\s*(#|$)") + else_re = re.compile(r"\s*else\s*:\s*(#|$)") + + def annotate(self, morfs, directory=None, ignore_errors=0, omit_prefixes=[]): + morfs = self.filter_by_prefix(morfs, omit_prefixes) + for morf in morfs: + try: + filename, statements, excluded, missing, _ = self.analysis2(morf) + self.annotate_file(filename, statements, excluded, missing, directory) + except KeyboardInterrupt: + raise + except: + if not ignore_errors: + raise + + def annotate_file(self, filename, statements, excluded, missing, directory=None): + source = open(filename, 'r') + if directory: + dest_file = os.path.join(directory, + os.path.basename(filename) + + ',cover') + else: + dest_file = filename + ',cover' + dest = open(dest_file, 'w') + lineno = 0 + i = 0 + j = 0 + covered = 1 + while 1: + line = source.readline() + if line == '': + break + lineno = lineno + 1 + while i < len(statements) and statements[i] < lineno: + i = i + 1 + while j < len(missing) and missing[j] < lineno: + j = j + 1 + if i < len(statements) and statements[i] == lineno: + covered = j >= len(missing) or missing[j] > lineno + if self.blank_re.match(line): + dest.write(' ') + elif self.else_re.match(line): + # Special logic for lines containing only 'else:'. + # See [GDR 2001-12-04b, 3.2]. + if i >= len(statements) and j >= len(missing): + dest.write('! ') + elif i >= len(statements) or j >= len(missing): + dest.write('> ') + elif statements[i] == missing[j]: + dest.write('! ') + else: + dest.write('> ') + elif lineno in excluded: + dest.write('- ') + elif covered: + dest.write('> ') + else: + dest.write('! ') + dest.write(line) + source.close() + dest.close() + +# Singleton object. +the_coverage = coverage() + +# Module functions call methods in the singleton object. +def use_cache(*args, **kw): + return the_coverage.use_cache(*args, **kw) + +def start(*args, **kw): + return the_coverage.start(*args, **kw) + +def stop(*args, **kw): + return the_coverage.stop(*args, **kw) + +def erase(*args, **kw): + return the_coverage.erase(*args, **kw) + +def begin_recursive(*args, **kw): + return the_coverage.begin_recursive(*args, **kw) + +def end_recursive(*args, **kw): + return the_coverage.end_recursive(*args, **kw) + +def exclude(*args, **kw): + return the_coverage.exclude(*args, **kw) + +def analysis(*args, **kw): + return the_coverage.analysis(*args, **kw) + +def analysis2(*args, **kw): + return the_coverage.analysis2(*args, **kw) + +def report(*args, **kw): + return the_coverage.report(*args, **kw) + +def annotate(*args, **kw): + return the_coverage.annotate(*args, **kw) + +def annotate_file(*args, **kw): + return the_coverage.annotate_file(*args, **kw) + +# Save coverage data when Python exits. (The atexit module wasn't +# introduced until Python 2.0, so use sys.exitfunc when it's not +# available.) +try: + import atexit + atexit.register(the_coverage.save) +except ImportError: + sys.exitfunc = the_coverage.save + +def main(): + the_coverage.command_line(sys.argv[1:]) + +# Command-line interface. +if __name__ == '__main__': + main() + + +# A. REFERENCES +# +# [GDR 2001-12-04a] "Statement coverage for Python"; Gareth Rees; +# Ravenbrook Limited; 2001-12-04; +# . +# +# [GDR 2001-12-04b] "Statement coverage for Python: design and +# analysis"; Gareth Rees; Ravenbrook Limited; 2001-12-04; +# . +# +# [van Rossum 2001-07-20a] "Python Reference Manual (releae 2.1.1)"; +# Guide van Rossum; 2001-07-20; +# . +# +# [van Rossum 2001-07-20b] "Python Library Reference"; Guido van Rossum; +# 2001-07-20; . +# +# +# B. DOCUMENT HISTORY +# +# 2001-12-04 GDR Created. +# +# 2001-12-06 GDR Added command-line interface and source code +# annotation. +# +# 2001-12-09 GDR Moved design and interface to separate documents. +# +# 2001-12-10 GDR Open cache file as binary on Windows. Allow +# simultaneous -e and -x, or -a and -r. +# +# 2001-12-12 GDR Added command-line help. Cache analysis so that it +# only needs to be done once when you specify -a and -r. +# +# 2001-12-13 GDR Improved speed while recording. Portable between +# Python 1.5.2 and 2.1.1. +# +# 2002-01-03 GDR Module-level functions work correctly. +# +# 2002-01-07 GDR Update sys.path when running a file with the -x option, +# so that it matches the value the program would get if it were run on +# its own. +# +# 2004-12-12 NMB Significant code changes. +# - Finding executable statements has been rewritten so that docstrings and +# other quirks of Python execution aren't mistakenly identified as missing +# lines. +# - Lines can be excluded from consideration, even entire suites of lines. +# - The filesystem cache of covered lines can be disabled programmatically. +# - Modernized the code. +# +# 2004-12-14 NMB Minor tweaks. Return 'analysis' to its original behavior +# and add 'analysis2'. Add a global for 'annotate', and factor it, adding +# 'annotate_file'. +# +# 2004-12-31 NMB Allow for keyword arguments in the module global functions. +# Thanks, Allen. +# +# 2005-12-02 NMB Call threading.settrace so that all threads are measured. +# Thanks Martin Fuzzey. Add a file argument to report so that reports can be +# captured to a different destination. +# +# 2005-12-03 NMB coverage.py can now measure itself. +# +# 2005-12-04 NMB Adapted Greg Rogers' patch for using relative filenames, +# and sorting and omitting files to report on. +# +# 2006-07-23 NMB Applied Joseph Tate's patch for function decorators. +# +# 2006-08-21 NMB Applied Sigve Tjora and Mark van der Wal's fixes for argument +# handling. +# +# 2006-08-22 NMB Applied Geoff Bache's parallel mode patch. +# +# 2006-08-23 NMB Refactorings to improve testability. Fixes to command-line +# logic for parallel mode and collect. +# +# 2006-08-25 NMB "#pragma: nocover" is excluded by default. +# +# 2006-09-10 NMB Properly ignore docstrings and other constant expressions that +# appear in the middle of a function, a problem reported by Tim Leslie. +# Minor changes to avoid lint warnings. +# +# 2006-09-17 NMB coverage.erase() shouldn't clobber the exclude regex. +# Change how parallel mode is invoked, and fix erase() so that it erases the +# cache when called programmatically. +# +# 2007-07-21 NMB In reports, ignore code executed from strings, since we can't +# do anything useful with it anyway. +# Better file handling on Linux, thanks Guillaume Chazarain. +# Better shell support on Windows, thanks Noel O'Boyle. +# Python 2.2 support maintained, thanks Catherine Proulx. +# +# 2007-07-22 NMB Python 2.5 now fully supported. The method of dealing with +# multi-line statements is now less sensitive to the exact line that Python +# reports during execution. Pass statements are handled specially so that their +# disappearance during execution won't throw off the measurement. +# +# 2007-07-23 NMB Now Python 2.5 is *really* fully supported: the body of the +# new with statement is counted as executable. +# +# 2007-07-29 NMB Better packaging. +# +# 2007-09-30 NMB Don't try to predict whether a file is Python source based on +# the extension. Extensionless files are often Pythons scripts. Instead, simply +# parse the file and catch the syntax errors. Hat tip to Ben Finney. +# +# 2008-05-25 NMB Open files in rU mode to avoid line ending craziness. +# Thanks, Edward Loper. +# +# 2008-09-14 NMB Add support for finding source files in eggs. +# Don't check for morf's being instances of ModuleType, instead use duck typing +# so that pseudo-modules can participate. Thanks, Imri Goldberg. +# Use os.realpath as part of the fixing of filenames so that symlinks won't +# confuse things. Thanks, Patrick Mezard. +# +# +# C. COPYRIGHT AND LICENCE +# +# Copyright 2001 Gareth Rees. All rights reserved. +# Copyright 2004-2008 Ned Batchelder. All rights reserved. +# +# Redistribution and use in source and binary forms, with or without +# modification, are permitted provided that the following conditions are +# met: +# +# 1. Redistributions of source code must retain the above copyright +# notice, this list of conditions and the following disclaimer. +# +# 2. Redistributions in binary form must reproduce the above copyright +# notice, this list of conditions and the following disclaimer in the +# documentation and/or other materials provided with the +# distribution. +# +# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +# HOLDERS AND CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, +# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, +# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS +# OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND +# ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR +# TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE +# USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH +# DAMAGE. +# +# $Id: coverage.py 100 2008-10-12 12:08:22Z nedbat $ -- cgit v1.2.1 From c619ba5c48b6a2014ac19a85d051f63566d6d0a8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 23 Feb 2009 19:24:22 +0100 Subject: Add coverage output file. --- .hgignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.hgignore b/.hgignore index 99fc8d87..b3df24f4 100644 --- a/.hgignore +++ b/.hgignore @@ -3,6 +3,7 @@ .*\.so build/ dist/ +tests/.coverage sphinx/pycode/Grammar.*pickle Sphinx.egg-info/ doc/_build/ -- cgit v1.2.1 From cc48768155fe243d3d09f1084eb0f3e54b64b99c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 24 Feb 2009 13:34:21 +0100 Subject: Allow multiple calls to setup_extension(). --- sphinx/application.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/sphinx/application.py b/sphinx/application.py index 659a9846..e8218225 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -89,6 +89,7 @@ class Sphinx(object): confoverrides, status, warning=sys.stderr, freshenv=False, warningiserror=False, tags=None): self.next_listener_id = 0 + self._extensions = {} self._listeners = {} self.builderclasses = BUILTIN_BUILDERS.copy() self.builder = None @@ -190,7 +191,9 @@ class Sphinx(object): # general extensibility interface def setup_extension(self, extension): - """Import and setup a Sphinx extension module.""" + """Import and setup a Sphinx extension module. No-op if called twice.""" + if extension in self._extensions: + return try: mod = __import__(extension, None, None, ['setup']) except ImportError, err: @@ -198,6 +201,7 @@ class Sphinx(object): err) if hasattr(mod, 'setup'): mod.setup(self) + self._extensions[extension] = mod def import_object(self, objname, source=None): """Import an object from a 'module.name' string.""" -- cgit v1.2.1 From 830aa8ebd393e719c65aa2ef08c14da8e46f44e0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 24 Feb 2009 13:34:39 +0100 Subject: Import style nit. --- sphinx/builders/html.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 2b92c2cb..4a26eed8 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -16,12 +16,10 @@ import posixpath import cPickle as pickle from os import path try: - import hashlib - md5 = hashlib.md5 + from hashlib import md5 except ImportError: # 2.4 compatibility - import md5 - md5 = md5.new + from md5 import md5 from docutils import nodes from docutils.io import DocTreeInput, StringOutput -- cgit v1.2.1 From f8465010e73c3a2add6d9c7a668f0e24eea9cc8d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 24 Feb 2009 13:38:15 +0100 Subject: Paths to literal include files and download files can now be absolute too. --- CHANGES | 5 +++-- doc/markup/code.rst | 7 +++++-- doc/markup/inline.rst | 9 ++++++--- sphinx/directives/code.py | 12 +++++++----- sphinx/environment.py | 16 ++++++++-------- tests/root/contents.txt | 1 + tests/root/special/code.py | 2 ++ tests/root/subdir/includes.txt | 12 ++++++++++++ tests/test_build.py | 5 +++++ 9 files changed, 49 insertions(+), 20 deletions(-) create mode 100644 tests/root/special/code.py create mode 100644 tests/root/subdir/includes.txt diff --git a/CHANGES b/CHANGES index 794af9b3..3f71d1ae 100644 --- a/CHANGES +++ b/CHANGES @@ -52,8 +52,9 @@ New features added the directive -- this allows you to define your document structure, but place the links yourself. - - Image paths can now be absolute (like ``/images/foo.png``). - They are treated as relative to the top source directory. + - Paths to images, literal include files and download files + can now be absolute (like ``/images/foo.png``). They are + treated as relative to the top source directory. - #52: There is now a ``hlist`` directive, creating a compact list by placing distributing items into multiple columns. diff --git a/doc/markup/code.rst b/doc/markup/code.rst index 28f75236..93cd127b 100644 --- a/doc/markup/code.rst +++ b/doc/markup/code.rst @@ -99,7 +99,9 @@ Includes .. literalinclude:: example.py - The file name is relative to the current file's path. + The file name is usually relative to the current file's path. However, if it + is absolute (starting with ``/``), it is relative to the top source + directory. The directive also supports the ``linenos`` flag option to switch on line numbers, and a ``language`` option to select a language different from the @@ -144,7 +146,8 @@ Includes .. versionadded:: 0.4.3 The ``encoding`` option. .. versionadded:: 0.6 - The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options. + The ``pyobject``, ``lines``, ``start-after`` and ``end-before`` options, + as well as support for absolute filenames. .. rubric:: Footnotes diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 9f8a01a5..97b20da7 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -264,9 +264,12 @@ Referencing downloadable files See :download:`this example script <../example.py>`. - The given filename is relative to the directory the current source file is - contained in. The ``../example.py`` file will be copied to the output - directory, and a suitable link generated to it. + The given filename is usually relative to the directory the current source + file is contained in, but if it absolute (starting with ``/``), it is taken + as relative to the top source directory. + + The ``example.py`` file will be copied to the output directory, and a + suitable link generated to it. Other semantic markup diff --git a/sphinx/directives/code.py b/sphinx/directives/code.py index 70aecd83..645bc784 100644 --- a/sphinx/directives/code.py +++ b/sphinx/directives/code.py @@ -7,6 +7,7 @@ :license: BSD, see LICENSE for details. """ +import os import sys import codecs from os import path @@ -95,11 +96,12 @@ class LiteralInclude(Directive): return [document.reporter.warning('File insertion disabled', line=self.lineno)] env = document.settings.env - rel_fn = filename - sourcename = self.state_machine.input_lines.source( - self.lineno - self.state_machine.input_offset - 1) - source_dir = path.dirname(path.abspath(sourcename)) - fn = path.normpath(path.join(source_dir, rel_fn)) + if filename.startswith('/') or filename.startswith(os.sep): + rel_fn = filename[1:] + else: + docdir = path.dirname(env.doc2path(env.docname, base=None)) + rel_fn = path.normpath(path.join(docdir, filename)) + fn = path.join(env.srcdir, rel_fn) if 'pyobject' in self.options and 'lines' in self.options: return [document.reporter.warning( diff --git a/sphinx/environment.py b/sphinx/environment.py index 6d34eb61..6deea1d5 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -24,12 +24,10 @@ from glob import glob from string import ascii_uppercase as uppercase from itertools import izip, groupby try: - import hashlib - md5 = hashlib.md5 + from hashlib import md5 except ImportError: # 2.4 compatibility - import md5 - md5 = md5.new + from md5 import md5 from docutils import nodes from docutils.io import FileInput, NullOutput @@ -682,7 +680,12 @@ class BuildEnvironment: """ docdir = path.dirname(self.doc2path(docname, base=None)) for node in doctree.traverse(addnodes.download_reference): - filepath = path.normpath(path.join(docdir, node['reftarget'])) + targetname = node['reftarget'] + if targetname.startswith('/') or targetname.startswith(os.sep): + # absolute + filepath = targetname[1:] + else: + filepath = path.normpath(path.join(docdir, node['reftarget'])) self.dependencies.setdefault(docname, set()).add(filepath) if not os.access(path.join(self.srcdir, filepath), os.R_OK): self.warn(docname, 'Download file not readable: %s' % filepath, @@ -952,9 +955,6 @@ class BuildEnvironment: node.astext())) def note_dependency(self, filename): - basename = path.dirname(self.doc2path(self.docname, base=None)) - # this will do the right thing when filename is absolute too - filename = path.join(basename, filename) self.dependencies.setdefault(self.docname, set()).add(filename) # ------- diff --git a/tests/root/contents.txt b/tests/root/contents.txt index 719034ce..0e52593e 100644 --- a/tests/root/contents.txt +++ b/tests/root/contents.txt @@ -13,6 +13,7 @@ Contents: images subdir/images + subdir/includes includes markup desc diff --git a/tests/root/special/code.py b/tests/root/special/code.py new file mode 100644 index 00000000..70c48d2e --- /dev/null +++ b/tests/root/special/code.py @@ -0,0 +1,2 @@ +print "line 1" +print "line 2" diff --git a/tests/root/subdir/includes.txt b/tests/root/subdir/includes.txt new file mode 100644 index 00000000..3e1ae0d1 --- /dev/null +++ b/tests/root/subdir/includes.txt @@ -0,0 +1,12 @@ +Including in subdir +=================== + +.. absolute filename +.. literalinclude:: /special/code.py + :lines: 1 + +.. relative filename +.. literalinclude:: ../special/code.py + :lines: 2 + +Absolute :download:`/img.png` download. diff --git a/tests/test_build.py b/tests/test_build.py index b9d2c779..f451b305 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -70,6 +70,11 @@ HTML_XPATH = { ".//img[@src='../_images/img1.png']": '', ".//img[@src='../_images/rimg.png']": '', }, + 'subdir/includes.html': { + ".//pre/span": 'line 1', + ".//pre/span": 'line 2', + ".//a[@href='../_downloads/img.png']": '', + }, 'includes.html': { ".//pre": u'Max Strauß', ".//a[@href='_downloads/img.png']": '', -- cgit v1.2.1 From 5b065da469d64ad262cf388660953d8689f34609 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 24 Feb 2009 19:15:39 +0100 Subject: #109: fix circular import problems by moving exceptions into their own module. --- sphinx/application.py | 43 +++++-------------------------------------- sphinx/builders/html.py | 2 +- sphinx/cmdline.py | 3 ++- sphinx/environment.py | 2 +- sphinx/errors.py | 48 ++++++++++++++++++++++++++++++++++++++++++++++++ sphinx/ext/pngmath.py | 2 +- sphinx/theming.py | 6 +----- sphinx/writers/latex.py | 2 +- 8 files changed, 60 insertions(+), 48 deletions(-) create mode 100644 sphinx/errors.py diff --git a/sphinx/application.py b/sphinx/application.py index e8218225..76c8f3c9 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -19,47 +19,10 @@ from cStringIO import StringIO from docutils import nodes from docutils.parsers.rst import directives, roles -# Directive is either new-style or old-style -clstypes = (type, types.ClassType) - -# create the error classes before importing the rest of Sphinx, so that -# they can be imported in a circular fashion - -class SphinxError(Exception): - """ - Base class for Sphinx errors that are shown to the user in a nicer - way than normal exceptions. - """ - category = 'Sphinx error' - -class SphinxWarning(SphinxError): - """Raised for warnings if warnings are treated as errors.""" - category = 'Warning, treated as error' - -class ExtensionError(SphinxError): - """Raised if something's wrong with the configuration.""" - category = 'Extension error' - - def __init__(self, message, orig_exc=None): - super(ExtensionError, self).__init__(message) - self.orig_exc = orig_exc - - def __repr__(self): - if self.orig_exc: - return '%s(%r, %r)' % (self.__class__.__name__, - self.message, self.orig_exc) - return '%s(%r)' % (self.__class__.__name__, self.message) - - def __str__(self): - parent_str = super(ExtensionError, self).__str__() - if self.orig_exc: - return '%s (exception: %s)' % (parent_str, self.orig_exc) - return parent_str - - import sphinx from sphinx.roles import xfileref_role, innernodetypes from sphinx.config import Config +from sphinx.errors import SphinxError, SphinxWarning, ExtensionError from sphinx.builders import BUILTIN_BUILDERS from sphinx.directives import GenericDesc, Target, additional_xref_types from sphinx.environment import SphinxStandaloneReader @@ -68,6 +31,9 @@ from sphinx.util.compat import Directive, directive_dwim from sphinx.util.console import bold +# Directive is either new-style or old-style +clstypes = (type, types.ClassType) + # List of all known core events. Maps name to arguments description. events = { 'builder-inited': '', @@ -83,6 +49,7 @@ events = { CONFIG_FILENAME = 'conf.py' + class Sphinx(object): def __init__(self, srcdir, confdir, outdir, doctreedir, buildername, diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 4a26eed8..6c2593ba 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -31,10 +31,10 @@ from docutils.readers.doctree import Reader as DoctreeReader from sphinx import package_dir, __version__ from sphinx.util import SEP, os_path, relative_uri, ensuredir, \ movefile, ustrftime, copy_static_entry +from sphinx.errors import SphinxError from sphinx.search import js_index from sphinx.theming import Theme from sphinx.builders import Builder, ENV_PICKLE_FILENAME -from sphinx.application import SphinxError from sphinx.highlighting import PygmentsBridge from sphinx.util.console import bold from sphinx.writers.html import HTMLWriter, HTMLTranslator, \ diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index cd2c4008..497c118e 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -18,7 +18,8 @@ from os import path from docutils.utils import SystemMessage from sphinx import __version__ -from sphinx.application import Sphinx, SphinxError +from sphinx.errors import SphinxError +from sphinx.application import Sphinx from sphinx.util import Tee, format_exception_cut_frames, save_traceback from sphinx.util.console import darkred, nocolor, color_terminal diff --git a/sphinx/environment.py b/sphinx/environment.py index 6deea1d5..de2b2430 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -44,8 +44,8 @@ from docutils.transforms.parts import ContentsFilter from sphinx import addnodes from sphinx.util import movefile, get_matching_docs, SEP, ustrftime, \ docname_join, FilenameUniqDict, url_re +from sphinx.errors import SphinxError from sphinx.directives import additional_xref_types -from sphinx.application import SphinxError default_settings = { 'embed_stylesheet': False, diff --git a/sphinx/errors.py b/sphinx/errors.py new file mode 100644 index 00000000..d9b8b6b8 --- /dev/null +++ b/sphinx/errors.py @@ -0,0 +1,48 @@ +# -*- coding: utf-8 -*- +""" + sphinx.errors + ~~~~~~~~~~~~~ + + Contains SphinxError and a few subclasses (in an extra module to avoid + circular import problems). + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +class SphinxError(Exception): + """ + Base class for Sphinx errors that are shown to the user in a nicer + way than normal exceptions. + """ + category = 'Sphinx error' + + +class SphinxWarning(SphinxError): + """Raised for warnings if warnings are treated as errors.""" + category = 'Warning, treated as error' + + +class ExtensionError(SphinxError): + """Raised if something's wrong with the configuration.""" + category = 'Extension error' + + def __init__(self, message, orig_exc=None): + super(ExtensionError, self).__init__(message) + self.orig_exc = orig_exc + + def __repr__(self): + if self.orig_exc: + return '%s(%r, %r)' % (self.__class__.__name__, + self.message, self.orig_exc) + return '%s(%r)' % (self.__class__.__name__, self.message) + + def __str__(self): + parent_str = super(ExtensionError, self).__str__() + if self.orig_exc: + return '%s (exception: %s)' % (parent_str, self.orig_exc) + return parent_str + + +class ThemeError(SphinxError): + category = 'Theme error' diff --git a/sphinx/ext/pngmath.py b/sphinx/ext/pngmath.py index 1ec64639..f779a64f 100644 --- a/sphinx/ext/pngmath.py +++ b/sphinx/ext/pngmath.py @@ -22,9 +22,9 @@ except ImportError: from docutils import nodes +from sphinx.errors import SphinxError from sphinx.util import ensuredir from sphinx.util.png import read_png_depth, write_png_depth -from sphinx.application import SphinxError from sphinx.ext.mathbase import setup as mathbase_setup, wrap_displaymath class MathExtError(SphinxError): diff --git a/sphinx/theming.py b/sphinx/theming.py index e25498e1..97b05233 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -16,16 +16,12 @@ import tempfile import ConfigParser from os import path -from sphinx.application import SphinxError +from sphinx.errors import ThemeError NODEFAULT = object() THEMECONF = 'theme.conf' -class ThemeError(SphinxError): - category = 'Theme error' - - class Theme(object): """ Represents the theme chosen in the configuration. diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 2ff24203..9954350f 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -21,8 +21,8 @@ from docutils.writers.latex2e import Babel from sphinx import addnodes from sphinx import highlighting +from sphinx.errors import SphinxError from sphinx.locale import admonitionlabels, versionlabels -from sphinx.application import SphinxError from sphinx.util import ustrftime from sphinx.util.texescape import tex_escape_map from sphinx.util.smartypants import educateQuotesLatex -- cgit v1.2.1 From 28bee672f05128f07cd0f7600d3b6b09dfae1003 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 24 Feb 2009 21:05:50 +0100 Subject: Make "numbered" toctree attribute optional. --- sphinx/environment.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/environment.py b/sphinx/environment.py index de2b2430..c210c395 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -837,7 +837,7 @@ class BuildEnvironment: file relations from it.""" if toctreenode['glob']: self.glob_toctrees.add(docname) - if toctreenode['numbered']: + if toctreenode.get('numbered'): self.numbered_toctrees.add(docname) includefiles = toctreenode['includefiles'] for includefile in includefiles: -- cgit v1.2.1 From 1aab81e9f3f134885b049fdb9ba4a77f31c6252e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 24 Feb 2009 23:38:12 +0100 Subject: Output each accesskey only once, regardless of the number of relbars. --- sphinx/jinja2glue.py | 10 ++++++++++ sphinx/themes/basic/layout.html | 4 ++-- 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index a7acf33a..679447a8 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -26,6 +26,15 @@ def _tobool(val): return val.lower() in ('true', '1', 'yes', 'on') return bool(val) +def accesskey(context, key): + """Helper to output each access key only once.""" + if '_accesskeys' not in context: + context.vars['_accesskeys'] = {} + if key not in context.vars['_accesskeys']: + context.vars['_accesskeys'][key] = 1 + return 'accesskey="%s"' % key + return '' + class BuiltinTemplateLoader(TemplateBridge, BaseLoader): """ @@ -64,6 +73,7 @@ class BuiltinTemplateLoader(TemplateBridge, BaseLoader): extensions=extensions) self.environment.filters['tobool'] = _tobool self.environment.globals['debug'] = contextfunction(pformat) + self.environment.globals['accesskey'] = contextfunction(accesskey) if use_i18n: self.environment.install_gettext_translations(builder.translator) diff --git a/sphinx/themes/basic/layout.html b/sphinx/themes/basic/layout.html index 7a2d5859..15cb42c9 100644 --- a/sphinx/themes/basic/layout.html +++ b/sphinx/themes/basic/layout.html @@ -12,14 +12,14 @@ {%- for rellink in rellinks %}
    • {{ rellink[3] }} + {{ accesskey(rellink[2]) }}>{{ rellink[3] }} {%- if not loop.first %}{{ reldelim2 }}{% endif %}
      • {%- endfor %} {%- block rootrellink %}
    • {{ shorttitle|e }}{{ reldelim1 }}
      • {%- endblock %} {%- for parent in parents %} -
    • {{ parent.title }}{{ reldelim1 }}
      • +
    • {{ parent.title }}{{ reldelim1 }}
      • {%- endfor %} {%- block relbaritems %} {% endblock %}
    -- cgit v1.2.1 From 5e096f48b5ea718f36546176d36fa8497b8393ad Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 27 Feb 2009 12:11:35 +0100 Subject: Add headlink/headbgcolors. --- doc/theming.rst | 4 +++- sphinx/themes/default/static/default.css_t | 8 ++++---- sphinx/themes/default/theme.conf | 4 +++- 3 files changed, 10 insertions(+), 6 deletions(-) diff --git a/doc/theming.rst b/doc/theming.rst index 4696df5a..3e3a33c8 100644 --- a/doc/theming.rst +++ b/doc/theming.rst @@ -86,7 +86,9 @@ Sphinx comes with a selection of themes to choose from: - **bgcolor** (CSS color): Body background color. - **textcolor** (CSS color): Body text color. - **linkcolor** (CSS color): Body link color. - - **headcolor** (CSS color): Text color for headings. + - **headbgcolor** (CSS color): Background color for headings. + - **headtextcolor** (CSS color): Text color for headings. + - **headlinkcolor** (CSS color): Link color for headings. - **codebgcolor** (CSS color): Background color for code blocks. - **codetextcolor** (CSS color): Default text color for code blocks, if not set differently by the highlighting style. diff --git a/sphinx/themes/default/static/default.css_t b/sphinx/themes/default/static/default.css_t index 77307084..ab2aeb0c 100644 --- a/sphinx/themes/default/static/default.css_t +++ b/sphinx/themes/default/static/default.css_t @@ -154,9 +154,9 @@ div.body h4, div.body h5, div.body h6 { font-family: {{ theme_headfont }}; - background-color: #f2f2f2; + background-color: {{ theme_headbgcolor }}; font-weight: normal; - color: {{ theme_headcolor }}; + color: {{ theme_headtextcolor }}; border-bottom: 1px solid #ccc; margin: 20px -20px 10px -20px; padding: 3px 0 3px 10px; @@ -170,14 +170,14 @@ div.body h5 { font-size: 110%; } div.body h6 { font-size: 100%; } a.headerlink { - color: #c60f0f; + color: {{ theme_headlinkcolor }}; font-size: 0.8em; padding: 0 4px 0 4px; text-decoration: none; } a.headerlink:hover { - background-color: #c60f0f; + background-color: {{ theme_headlinkcolor }}; color: white; } diff --git a/sphinx/themes/default/theme.conf b/sphinx/themes/default/theme.conf index 9a24b978..812330f8 100644 --- a/sphinx/themes/default/theme.conf +++ b/sphinx/themes/default/theme.conf @@ -17,7 +17,9 @@ relbartextcolor = #ffffff relbarlinkcolor = #ffffff bgcolor = #ffffff textcolor = #000000 -headcolor = #20435c +headbgcolor = #f2f2f2 +headtextcolor = #20435c +headlinkcolor = #c60f0f linkcolor = #355f7c codebgcolor = #eeffcc codetextcolor = #333333 -- cgit v1.2.1 From 16ba2e5411025d8d8f8e29a1502f8620238965c3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 27 Feb 2009 15:09:54 +0100 Subject: Add Quex. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index a6535498..3ccb2936 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -48,6 +48,7 @@ included, please mail to `the Google group * Python: http://docs.python.org/ * python-apt: http://people.debian.org/~jak/python-apt-doc/ * PyUblas: http://documen.tician.de/pyublas/ +* Quex: http://quex.sourceforge.net/ * Reteisi: http://docs.argolinux.org/reteisi/ * Roundup: http://www.roundup-tracker.org/ * Satchmo: http://www.satchmoproject.com/docs/svn/ -- cgit v1.2.1 From 50efec8efc3674961909dafce3303e5a00828433 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 27 Feb 2009 15:22:45 +0100 Subject: Remove docs for removed automodule_skip_lines setting. --- doc/ext/autodoc.rst | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 00fafdb7..c54125de 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -182,19 +182,6 @@ directive. There are also new config values that you can set: -.. confval:: automodule_skip_lines - - This value (whose default is ``0``) can be used to skip an amount of lines in - every module docstring that is processed by an :dir:`automodule` directive. - This is provided because some projects like to put headings in the module - docstring, which would then interfere with your sectioning, or automatic - fields with version control tags, that you don't want to put in the generated - documentation. - - .. deprecated:: 0.4 - Use the more versatile docstring processing provided by - :event:`autodoc-process-docstring`. - .. confval:: autoclass_content This value selects what content will be inserted into the main body of an -- cgit v1.2.1 From 0aa7aea4a50c51062325bec02896006369435d8a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 27 Feb 2009 15:48:41 +0100 Subject: Autodoc can now order members either alphabetically (like previously) or by member type; configurable either with the config value ``autodoc_member_order`` or a ``member-order`` option per directive. Also fix a bug that documented module-level functions as attributes. --- CHANGES | 5 +++++ doc/ext/autodoc.rst | 14 ++++++++++++++ sphinx/ext/autodoc.py | 41 +++++++++++++++++++++++++++++++++-------- 3 files changed, 52 insertions(+), 8 deletions(-) diff --git a/CHANGES b/CHANGES index 3f71d1ae..4ca63c28 100644 --- a/CHANGES +++ b/CHANGES @@ -148,6 +148,11 @@ New features added - Autodoc can document classes as functions now if explicitly marked with `autofunction`. + - Autodoc can now order members either alphabetically (like + previously) or by member type; configurable either with the + config value ``autodoc_member_order`` or a ``member-order`` + option per directive. + - The function ``Sphinx.add_directive()`` now also supports docutils 0.5-style directive classes. If they inherit from ``sphinx.util.compat.Directive``, they also work with diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index c54125de..17a2766b 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -135,6 +135,12 @@ directive. .. versionadded:: 0.5 + * :dir:`automodule` and :dir:`autoclass` also has an ``member-order`` option + that can be used to override the global value of + :confval:`autodoc_member_order` for one directive. + + .. versionadded:: 0.6 + .. note:: In an :dir:`automodule` directive with the ``members`` option set, only @@ -199,6 +205,14 @@ There are also new config values that you can set: .. versionadded:: 0.3 +.. confval:: autodoc_member_order + + This value selects if automatically documented members are sorted + alphabetical (value ``'alphabetical'``) or by member type (value + ``'groupwise'``). The default is alphabetical. + + .. versionadded:: 0.6 + Docstring preprocessing ----------------------- diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index d07ab465..10f2bb32 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -218,6 +218,8 @@ class Documenter(object): content_indent = u' ' #: priority if multiple documenters return True from can_document_member priority = 0 + #: order if autodoc_member_order is set to 'groupwise' + member_order = 0 option_spec = {'noindex': bool_option} @@ -548,6 +550,7 @@ class Documenter(object): members_check_module, members = self.get_object_members(want_all) # document non-skipped members + memberdocumenters = [] for (mname, member, isattr) in self.filter_members(members, want_all): classes = [cls for cls in AutoDirective._registry.itervalues() if cls.can_document_member(member, mname, isattr, self)] @@ -560,11 +563,19 @@ class Documenter(object): # of inner classes can be documented full_mname = self.modname + '::' + \ '.'.join(self.objpath + [mname]) - memberdocmtr = classes[-1](self.directive, full_mname, - self.indent) - memberdocmtr.generate(all_members=True, - real_modname=self.real_modname, - check_module=members_check_module) + memberdocumenters.append( + classes[-1](self.directive, full_mname, self.indent)) + + if (self.options.member_order or self.env.config.autodoc_member_order) \ + == 'groupwise': + # sort by group; relies on stable sort to keep items in the + # same group sorted alphabetically + memberdocumenters.sort(key=lambda d: d.member_order) + + for documenter in memberdocumenters: + documenter.generate(all_members=True, + real_modname=self.real_modname, + check_module=members_check_module) # reset current objects self.env.autodoc_current_module = None @@ -655,6 +666,7 @@ class ModuleDocumenter(Documenter): 'noindex': bool_option, 'inherited-members': bool_option, 'show-inheritance': bool_option, 'synopsis': identity, 'platform': identity, 'deprecated': bool_option, + 'member-order': identity, } @classmethod @@ -767,6 +779,7 @@ class FunctionDocumenter(ModuleLevelDocumenter): Specialized Documenter subclass for functions. """ objtype = 'function' + member_order = 30 @classmethod def can_document_member(cls, member, membername, isattr, parent): @@ -800,10 +813,11 @@ class ClassDocumenter(ModuleLevelDocumenter): Specialized Documenter subclass for classes. """ objtype = 'class' + member_order = 20 option_spec = { 'members': members_option, 'undoc-members': bool_option, 'noindex': bool_option, 'inherited-members': bool_option, - 'show-inheritance': bool_option, + 'show-inheritance': bool_option, 'member-order': identity, } @classmethod @@ -897,6 +911,7 @@ class ExceptionDocumenter(ClassDocumenter): Specialized ClassDocumenter subclass for exceptions. """ objtype = 'exception' + member_order = 10 # needs a higher priority than ClassDocumenter priority = 10 @@ -912,6 +927,7 @@ class DataDocumenter(ModuleLevelDocumenter): Specialized Documenter subclass for data items. """ objtype = 'data' + member_order = 40 @classmethod def can_document_member(cls, member, membername, isattr, parent): @@ -926,6 +942,7 @@ class MethodDocumenter(ClassLevelDocumenter): Specialized Documenter subclass for methods (normal, static and class). """ objtype = 'method' + member_order = 50 @classmethod def can_document_member(cls, member, membername, isattr, parent): @@ -939,10 +956,14 @@ class MethodDocumenter(ClassLevelDocumenter): (isinstance(self.object, MethodType) and self.object.im_self is not None): self.directivetype = 'classmethod' + # document class and static members before ordinary ones + self.member_order = self.member_order - 1 elif isinstance(self.object, FunctionType) or \ (isinstance(self.object, BuiltinFunctionType) and self.object.__self__ is not None): self.directivetype = 'staticmethod' + # document class and static members before ordinary ones + self.member_order = self.member_order - 1 else: self.directivetype = 'method' return ret @@ -966,11 +987,13 @@ class AttributeDocumenter(ClassLevelDocumenter): Specialized Documenter subclass for attributes. """ objtype = 'attribute' + member_order = 60 @classmethod def can_document_member(cls, member, membername, isattr, parent): - return isdescriptor(member) or \ - (not isinstance(parent, ModuleDocumenter) and isattr) + return (isdescriptor(member) and not + isinstance(member, (FunctionType, BuiltinFunctionType))) \ + or (not isinstance(parent, ModuleDocumenter) and isattr) def document_members(self, all_members=False): pass @@ -1033,6 +1056,7 @@ class AutoDirective(Directive): old_reporter = self.state.memo.reporter self.state.memo.reporter = AutodocReporter(self.result, self.state.memo.reporter) + if self.name == 'automodule': node = nodes.section() # necessary so that the child nodes get the right source/line set @@ -1068,6 +1092,7 @@ def setup(app): app.add_autodocumenter(AttributeDocumenter) app.add_config_value('autoclass_content', 'class', True) + app.add_config_value('autodoc_member_order', 'alphabetic', True) app.add_event('autodoc-process-docstring') app.add_event('autodoc-process-signature') app.add_event('autodoc-skip-member') -- cgit v1.2.1 From 59f7fac652529a2b66d1ff2e863a6556213849aa Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 27 Feb 2009 17:13:34 +0100 Subject: Add PyMOTW. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 3ccb2936..2a5dc6f3 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -42,6 +42,7 @@ included, please mail to `the Google group * Pyevolve: http://pyevolve.sourceforge.net/ * Pylo: http://documen.tician.de/pylo/ * Pylons: http://docs.pylonshq.com/ +* PyMOTW: http://www.doughellmann.com/PyMOTW/ * PyPubSub: http://pubsub.sourceforge.net/ * pyrticle: http://documen.tician.de/pyrticle/ * Pysparse: http://pysparse.sourceforge.net/ -- cgit v1.2.1 From 2ce68ce1e23ab18069d99b3b774c99d4a780af72 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 1 Mar 2009 16:40:01 +0100 Subject: Re-add dependency recording in autodoc which was lost during the refactoring. --- sphinx/ext/autodoc.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 10f2bb32..43c4b26a 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -1051,6 +1051,11 @@ class AutoDirective(Directive): if not self.result: return self.warnings + # record all filenames as dependencies -- this will at least + # partially make automatic invalidation possible + for fn in self.filename_set: + self.env.note_dependency(fn) + # use a custom reporter that correctly assigns lines to source # filename/description and lineno old_reporter = self.state.memo.reporter -- cgit v1.2.1 From 4fdcb75be0417e2c9085a69454ff02af0784114e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 3 Mar 2009 08:55:34 +0100 Subject: Add default parent attribute to Node classes. --- sphinx/pycode/nodes.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx/pycode/nodes.py b/sphinx/pycode/nodes.py index efdf8f06..f8f57740 100644 --- a/sphinx/pycode/nodes.py +++ b/sphinx/pycode/nodes.py @@ -14,6 +14,7 @@ class BaseNode(object): """ Node superclass for both terminal and nonterminal nodes. """ + parent = None def _eq(self, other): raise NotImplementedError -- cgit v1.2.1 From 5736b6d92a75237b4aad021157dab6c125718aa6 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 4 Mar 2009 23:49:32 +0100 Subject: Fix grammar. --- doc/ext/math.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/ext/math.rst b/doc/ext/math.rst index e538edcd..a214b41e 100644 --- a/doc/ext/math.rst +++ b/doc/ext/math.rst @@ -108,8 +108,8 @@ There are various config values you can set to influence how the images are buil .. confval:: pngmath_latex The command name with which to invoke LaTeX. The default is ``'latex'``; you - may need to set this to a full path if ``latex`` not in the executable search - path. + may need to set this to a full path if ``latex`` is not in the executable + search path. Since this setting is not portable from system to system, it is normally not useful to set it in ``conf.py``; rather, giving it on the -- cgit v1.2.1 From e444166923eb4e5cc16d15f5ccfe84adf9d01ba4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 4 Mar 2009 23:51:36 +0100 Subject: Add two comments. --- sphinx/directives/other.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index f1d67a3c..bc9a54df 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -89,7 +89,9 @@ class TocTree(Directive): % entry, line=self.lineno)) subnode = addnodes.toctree() subnode['parent'] = env.docname + # entries contains all entries (self references, external links etc.) subnode['entries'] = entries + # includefiles only entries that are documents subnode['includefiles'] = includefiles subnode['maxdepth'] = self.options.get('maxdepth', -1) subnode['glob'] = glob -- cgit v1.2.1 From 2c004ae5097979e06029a7ce0df6fad6301c3874 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 4 Mar 2009 23:52:56 +0100 Subject: New ``graphviz`` extension to embed graphviz graphs. --- AUTHORS | 1 + CHANGES | 2 + doc/ext/graphviz.rst | 77 +++++++++++++++++++++ doc/extensions.rst | 2 + sphinx/ext/graphviz.py | 182 +++++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 264 insertions(+) create mode 100644 doc/ext/graphviz.rst create mode 100644 sphinx/ext/graphviz.py diff --git a/AUTHORS b/AUTHORS index 0d8afda5..d4bc729f 100644 --- a/AUTHORS +++ b/AUTHORS @@ -6,6 +6,7 @@ Substantial parts of the templates were written by Armin Ronacher Other contributors, listed alphabetically, are: * Daniel Bültmann -- todo extension +* Charles Duffy -- original graphviz extension * Josip Dzolonga -- coverage builder * Horst Gutmann -- internationalization support * Martin Hans -- autodoc improvements diff --git a/CHANGES b/CHANGES index 4ca63c28..44152b1d 100644 --- a/CHANGES +++ b/CHANGES @@ -137,6 +137,8 @@ New features added * Extensions and API: + - New ``graphviz`` extension to embed graphviz graphs. + - Autodoc now has a reusable Python API, which can be used to create custom types of objects to auto-document (e.g. Zope interfaces). See also ``Sphinx.add_autodocumenter()``. diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst new file mode 100644 index 00000000..1d4ed807 --- /dev/null +++ b/doc/ext/graphviz.rst @@ -0,0 +1,77 @@ +.. highlight:: rest + +The Graphviz extension +====================== + +.. module:: sphinx.ext.graphviz + :synopsis: Support for Graphviz graphs. + +.. versionadded:: 0.6 + +This extension allows you to embed `Graphviz `_ graphs in +your documents. + +It adds these directives: + + +.. directive:: graphviz + + Directive to embed graphviz code. The input code for ``dot`` is given as the + content. For example:: + + .. graphviz:: + + digraph foo { + "bar" -> "baz"; + } + + In HTML output, the code will be rendered to a PNG image. In LaTeX output, + the code will be rendered to an embeddable PDF file. + + +.. directive:: graph + + Directive for embedding a single undirected graph. The name is given as a + directive argument, the contents of the graph are the directive content. + This is a convenience directive to generate ``graph { }``. + + For example:: + + .. graph:: foo + + "bar" -- "baz"; + + +.. directive:: digraph + + Directive for embedding a single directed graph. The name is given as a + directive argument, the contents of the graph are the directive content. + This is a convenience directive to generate ``digraph { }``. + + For example:: + + .. digraph:: foo + + "bar" -> "baz" -> "quux"; + + +There are also these new config values: + +.. confval:: graphviz_dot + + The command name with which to invoke ``dot``. The default is ``'dot'``; you + may need to set this to a full path if ``dot`` is not in the executable + search path. + + Since this setting is not portable from system to system, it is normally not + useful to set it in ``conf.py``; rather, giving it on the + :program:`sphinx-build` command line via the :option:`-D` option should be + preferable, like this:: + + sphinx-build -b html -D graphviz_dot=C:\graphviz\bin\dot.exe . _build/html + +.. confval:: graphviz_dot_args + + Additional command-line arguments to give to dot, as a list. The default is + an empty list. This is the right place to set global graph, node or edge + attributes via dot's ``-G``, ``-N`` and ``-E`` options. diff --git a/doc/extensions.rst b/doc/extensions.rst index 12c82da5..21ba0fd8 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -44,6 +44,8 @@ These extensions are built in and can be activated by respective entries in the ext/doctest ext/intersphinx ext/math + ext/graphviz + ext/inheritance ext/refcounting ext/ifconfig ext/coverage diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py new file mode 100644 index 00000000..084797b7 --- /dev/null +++ b/sphinx/ext/graphviz.py @@ -0,0 +1,182 @@ +# -*- coding: utf-8 -*- +""" + sphinx.ext.graphviz + ~~~~~~~~~~~~~~~~~~~ + + Allow graphviz-formatted graphs to be included in Sphinx-generated + documents inline. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import re +import sys +import posixpath +from os import path +from subprocess import Popen, PIPE +try: + from hashlib import sha1 as sha +except ImportError: + from sha import sha + +from docutils import nodes + +from sphinx.errors import SphinxError +from sphinx.util import ensuredir +from sphinx.util.compat import Directive + + +mapname_re = re.compile(r' and ) + self.body.append('%s\n' % + (fname, self.encode(code).strip(), imgcss)) + else: + # has a map: get the name of the map and connect the parts + mapname = mapname_re.match(imgmap[0]).group(1) + self.body.append('%s\n' % + (fname, self.encode(code).strip(), + mapname, imgcss)) + self.body.extend(imgmap) + self.body.append('

    \n') + raise nodes.SkipNode + + +def html_visit_graphviz(self, node): + render_dot_html(self, node, node['code'], node['options']) + + +def render_dot_latex(self, node, code, options, prefix='graphviz'): + try: + fname = render_dot(self, code, options, 'pdf', prefix) + except GraphvizError, exc: + self.builder.warn('dot code %r: ' % code + str(exc)) + raise nodes.SkipNode + + if fname is not None: + self.body.append('\\includegraphics{%s}' % fname) + raise nodes.SkipNode + + +def latex_visit_graphviz(self, node): + render_dot_latex(self, node, node['code'], node['options']) + +def setup(app): + app.add_node(graphviz, + html=(html_visit_graphviz, None), + latex=(latex_visit_graphviz, None)) + app.add_directive('graphviz', Graphviz) + app.add_directive('graph', GraphvizSimple) + app.add_directive('digraph', GraphvizSimple) + app.add_config_value('graphviz_dot', 'dot', 'html') + app.add_config_value('graphviz_dot_args', [], 'html') -- cgit v1.2.1 From 1f1c6f7d9ea151d07610b7cb9a8bd958c7bf7740 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Mar 2009 00:14:29 +0100 Subject: New ``inheritance_diagram`` extension to embed... inheritance diagrams! --- AUTHORS | 1 + CHANGES | 3 + doc/ext/inheritance.rst | 46 +++++ sphinx/ext/inheritance_diagram.py | 367 ++++++++++++++++++++++++++++++++++++++ 4 files changed, 417 insertions(+) create mode 100644 doc/ext/inheritance.rst create mode 100644 sphinx/ext/inheritance_diagram.py diff --git a/AUTHORS b/AUTHORS index d4bc729f..73ec5ed2 100644 --- a/AUTHORS +++ b/AUTHORS @@ -6,6 +6,7 @@ Substantial parts of the templates were written by Armin Ronacher Other contributors, listed alphabetically, are: * Daniel Bültmann -- todo extension +* Michael Droettboom -- inheritance_diagram extension * Charles Duffy -- original graphviz extension * Josip Dzolonga -- coverage builder * Horst Gutmann -- internationalization support diff --git a/CHANGES b/CHANGES index 44152b1d..3518cb03 100644 --- a/CHANGES +++ b/CHANGES @@ -139,6 +139,9 @@ New features added - New ``graphviz`` extension to embed graphviz graphs. + - New ``inheritance_diagram`` extension to embed... inheritance + diagrams! + - Autodoc now has a reusable Python API, which can be used to create custom types of objects to auto-document (e.g. Zope interfaces). See also ``Sphinx.add_autodocumenter()``. diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst new file mode 100644 index 00000000..edec6c8e --- /dev/null +++ b/doc/ext/inheritance.rst @@ -0,0 +1,46 @@ +.. highlight:: rest + +The inheritance diagram extension +================================= + +.. module:: sphinx.ext.inheritance_diagram + :synopsis: Support for displaying inheritance diagrams via graphviz. + +.. versionadded:: 0.6 + +This extension allows you to include inheritance diagrams, rendered via the +:mod:`Graphviz extension `. + +It adds this directive: + +.. directive:: inheritance-diagram + + This directive has one or more arguments, each giving a module or class + name. Class names can be unqualified; in that case they are taken to exist + in the currently described module (see :dir:`module`). + + For each given class, and each class in each given module, the base classes + are determined. Then, from all classes and their base classes, a graph is + generated which is then rendered via the graphviz extension to a directed + graph. + + This directive supports an option called ``parts`` that, if given, must be an + integer, advising the directive to remove that many parts of module names + from the displayed names. (For example, if all your class names start with + ``lib.``, you can give ``:parts: 1`` to remove that prefix from the displayed + node names.) + + +New config values are: + +.. confval:: inheritance_graph_attrs + + A dictionary of graphviz graph attributes for inheritance diagrams. + +.. confval:: inheritance_node_attrs + + A dictionary of graphviz node attributes for inheritance diagrams. + +.. confval:: inheritance_edge_attrs + + A dictionary of graphviz edge attributes for inheritance diagrams. diff --git a/sphinx/ext/inheritance_diagram.py b/sphinx/ext/inheritance_diagram.py new file mode 100644 index 00000000..8183359d --- /dev/null +++ b/sphinx/ext/inheritance_diagram.py @@ -0,0 +1,367 @@ +""" + sphinx.ext.inheritance_diagram + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + Defines a docutils directive for inserting inheritance diagrams. + + Provide the directive with one or more classes or modules (separated + by whitespace). For modules, all of the classes in that module will + be used. + + Example:: + + Given the following classes: + + class A: pass + class B(A): pass + class C(A): pass + class D(B, C): pass + class E(B): pass + + .. inheritance-diagram: D E + + Produces a graph like the following: + + A + / \ + B C + / \ / + E D + + The graph is inserted as a PNG+image map into HTML and a PDF in + LaTeX. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. +""" + +import os +import re +import sys +import inspect +import subprocess +try: + from hashlib import md5 +except ImportError: + from md5 import md5 + +from docutils import nodes +from docutils.parsers.rst import directives + +from sphinx.roles import xfileref_role +from sphinx.ext.graphviz import render_dot_html, render_dot_latex +from sphinx.util.compat import Directive + + +class_sig_re = re.compile(r'''^([\w.]*\.)? # module names + (\w+) \s* $ # class/final module name + ''', re.VERBOSE) + + +class InheritanceException(Exception): + pass + + +class InheritanceGraph(object): + """ + Given a list of classes, determines the set of classes that they inherit + from all the way to the root "object", and then is able to generate a + graphviz dot graph from them. + """ + def __init__(self, class_names, currmodule, show_builtins=False): + """ + *class_names* is a list of child classes to show bases from. + + If *show_builtins* is True, then Python builtins will be shown + in the graph. + """ + self.class_names = class_names + self.classes = self._import_classes(class_names, currmodule) + self.all_classes = self._all_classes(self.classes) + if len(self.all_classes) == 0: + raise InheritanceException('No classes found for ' + 'inheritance diagram') + self.show_builtins = show_builtins + + def _import_class_or_module(self, name, currmodule): + """ + Import a class using its fully-qualified *name*. + """ + try: + path, base = class_sig_re.match(name).groups() + except ValueError: + raise InheritanceException('Invalid class or module %r specified ' + 'for inheritance diagram' % name) + + fullname = (path or '') + base + path = (path and path.rstrip('.') or '') + + # two possibilities: either it is a module, then import it + try: + module = __import__(fullname) + todoc = sys.modules[fullname] + except ImportError: + # else it is a class, then import the module + if not path: + if currmodule: + # try the current module + path = currmodule + else: + raise InheritanceException( + 'Could not import class %r specified for ' + 'inheritance diagram' % base) + try: + module = __import__(path) + todoc = getattr(sys.modules[path], base) + except (ImportError, AttributeError): + raise InheritanceException( + 'Could not import class or module %r specified for ' + 'inheritance diagram' % (path + '.' + base)) + + # If a class, just return it + if inspect.isclass(todoc): + return [todoc] + elif inspect.ismodule(todoc): + classes = [] + for cls in todoc.__dict__.values(): + if inspect.isclass(cls) and cls.__module__ == todoc.__name__: + classes.append(cls) + return classes + raise InheritanceException('%r specified for inheritance diagram is ' + 'not a class or module' % name) + + def _import_classes(self, class_names, currmodule): + """ + Import a list of classes. + """ + classes = [] + for name in class_names: + classes.extend(self._import_class_or_module(name, currmodule)) + return classes + + def _all_classes(self, classes): + """ + Return a list of all classes that are ancestors of *classes*. + """ + all_classes = {} + + def recurse(cls): + all_classes[cls] = None + for c in cls.__bases__: + if c not in all_classes: + recurse(c) + + for cls in classes: + recurse(cls) + + return all_classes.keys() + + def class_name(self, cls, parts=0): + """ + Given a class object, return a fully-qualified name. This + works for things I've tested in matplotlib so far, but may not + be completely general. + """ + module = cls.__module__ + if module == '__builtin__': + fullname = cls.__name__ + else: + fullname = '%s.%s' % (module, cls.__name__) + if parts == 0: + return fullname + name_parts = fullname.split('.') + return '.'.join(name_parts[-parts:]) + + def get_all_class_names(self): + """ + Get all of the class names involved in the graph. + """ + return [self.class_name(x) for x in self.all_classes] + + # These are the default attrs for graphviz + default_graph_attrs = { + 'rankdir': 'LR', + 'size': '"8.0, 12.0"', + } + default_node_attrs = { + 'shape': 'box', + 'fontsize': 10, + 'height': 0.25, + 'fontname': 'Vera Sans, DejaVu Sans, Liberation Sans, ' + 'Arial, Helvetica, sans', + 'style': '"setlinewidth(0.5)"', + } + default_edge_attrs = { + 'arrowsize': 0.5, + 'style': '"setlinewidth(0.5)"', + } + + def _format_node_attrs(self, attrs): + return ','.join(['%s=%s' % x for x in attrs.items()]) + + def _format_graph_attrs(self, attrs): + return ''.join(['%s=%s;\n' % x for x in attrs.items()]) + + def generate_dot(self, name, parts=0, urls={}, env=None, + graph_attrs={}, node_attrs={}, edge_attrs={}): + """ + Generate a graphviz dot graph from the classes that + were passed in to __init__. + + *name* is the name of the graph. + + *urls* is a dictionary mapping class names to HTTP URLs. + + *graph_attrs*, *node_attrs*, *edge_attrs* are dictionaries containing + key/value pairs to pass on as graphviz properties. + """ + g_attrs = self.default_graph_attrs.copy() + n_attrs = self.default_node_attrs.copy() + e_attrs = self.default_edge_attrs.copy() + g_attrs.update(graph_attrs) + n_attrs.update(node_attrs) + e_attrs.update(edge_attrs) + if env: + g_attrs.update(env.config.inheritance_graph_attrs) + n_attrs.update(env.config.inheritance_node_attrs) + e_attrs.update(env.config.inheritance_edge_attrs) + + res = [] + res.append('digraph %s {\n' % name) + res.append(self._format_graph_attrs(g_attrs)) + + for cls in self.all_classes: + if not self.show_builtins and cls in __builtins__.values(): + continue + + name = self.class_name(cls, parts) + + # Write the node + this_node_attrs = n_attrs.copy() + url = urls.get(self.class_name(cls)) + if url is not None: + this_node_attrs['URL'] = '"%s"' % url + res.append(' "%s" [%s];\n' % + (name, self._format_node_attrs(this_node_attrs))) + + # Write the edges + for base in cls.__bases__: + if not self.show_builtins and base in __builtins__.values(): + continue + + base_name = self.class_name(base, parts) + res.append(' "%s" -> "%s" [%s];\n' % + (base_name, name, + self._format_node_attrs(e_attrs))) + res.append('}\n') + return ''.join(res) + + +class inheritance_diagram(nodes.General, nodes.Element): + """ + A docutils node to use as a placeholder for the inheritance diagram. + """ + pass + + +class InheritanceDiagram(Directive): + """ + Run when the inheritance_diagram directive is first encountered. + """ + has_content = False + required_arguments = 1 + optional_arguments = 0 + final_argument_whitespace = True + option_spec = { + 'parts': directives.nonnegative_int, + } + + def run(self): + node = inheritance_diagram() + node.document = self.state.document + env = self.state.document.settings.env + class_names = self.arguments[0].split() + + # Create a graph starting with the list of classes + try: + graph = InheritanceGraph(class_names, env.currmodule) + except InheritanceException, err: + return [node.document.reporter.warning(err.args[0], + line=self.lineno)] + + # Create xref nodes for each target of the graph's image map and + # add them to the doc tree so that Sphinx can resolve the + # references to real URLs later. These nodes will eventually be + # removed from the doctree after we're done with them. + for name in graph.get_all_class_names(): + refnodes, x = xfileref_role( + 'class', ':class:`%s`' % name, name, 0, self.state) + node.extend(refnodes) + # Store the graph object so we can use it to generate the + # dot file later + node['graph'] = graph + # Store the original content for use as a hash + node['parts'] = self.options.get('parts', 0) + node['content'] = ' '.join(class_names) + return [node] + + +def get_graph_hash(node): + return md5(node['content'] + str(node['parts'])).hexdigest()[-10:] + + +def html_visit_inheritance_diagram(self, node): + """ + Output the graph for HTML. This will insert a PNG with clickable + image map. + """ + graph = node['graph'] + parts = node['parts'] + + graph_hash = get_graph_hash(node) + name = 'inheritance%s' % graph_hash + + # Create a mapping from fully-qualified class names to URLs. + urls = {} + for child in node: + if child.get('refuri') is not None: + urls[child['reftitle']] = child.get('refuri') + elif child.get('refid') is not None: + urls[child['reftitle']] = '#' + child.get('refid') + + dotcode = graph.generate_dot(name, parts, urls, env=self.builder.env) + render_dot_html(self, node, dotcode, [], 'inheritance', 'inheritance') + raise nodes.SkipNode + + +def latex_visit_inheritance_diagram(self, node): + """ + Output the graph for LaTeX. This will insert a PDF. + """ + graph = node['graph'] + parts = node['parts'] + + graph_hash = get_graph_hash(node) + name = 'inheritance%s' % graph_hash + + dotcode = graph.generate_dot(name, parts, urls, env=self.builder.env, + graph_attrs={'size': '"6.0,6.0"'}) + render_dot_latex(self, node, dotcode, [], 'inheritance') + raise nodes.SkipNode + + +def skip(self, node): + raise nodes.SkipNode + + +def setup(app): + app.setup_extension('sphinx.ext.graphviz') + app.add_node( + inheritance_diagram, + latex=(latex_visit_inheritance_diagram, None), + html=(html_visit_inheritance_diagram, None), + text=(skip, None)) + app.add_directive('inheritance-diagram', InheritanceDiagram) + app.add_config_value('inheritance_graph_attrs', {}, False), + app.add_config_value('inheritance_node_attrs', {}, False), + app.add_config_value('inheritance_edge_attrs', {}, False), -- cgit v1.2.1 From 15daf416c4df699a8e414777fea346d9215afd8d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Mar 2009 00:15:15 +0100 Subject: Add Scapy. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 2a5dc6f3..2f7365d2 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -53,6 +53,7 @@ included, please mail to `the Google group * Reteisi: http://docs.argolinux.org/reteisi/ * Roundup: http://www.roundup-tracker.org/ * Satchmo: http://www.satchmoproject.com/docs/svn/ +* Scapy: http://www.secdev.org/projects/scapy/doc/ * Self: http://selflanguage.org/ * SimPy: http://simpy.sourceforge.net/ * Sphinx: http://sphinx.pocoo.org/ -- cgit v1.2.1 From aaf084a590dd2abcb6486a4a703e799011d09f08 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Mar 2009 00:17:14 +0100 Subject: Make titles consistent. --- doc/ext/graphviz.rst | 4 ++-- doc/ext/inheritance.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/ext/graphviz.rst b/doc/ext/graphviz.rst index 1d4ed807..d007bf25 100644 --- a/doc/ext/graphviz.rst +++ b/doc/ext/graphviz.rst @@ -1,7 +1,7 @@ .. highlight:: rest -The Graphviz extension -====================== +:mod:`sphinx.ext.graphviz` -- Add Graphviz graphs +================================================= .. module:: sphinx.ext.graphviz :synopsis: Support for Graphviz graphs. diff --git a/doc/ext/inheritance.rst b/doc/ext/inheritance.rst index edec6c8e..fe6d636d 100644 --- a/doc/ext/inheritance.rst +++ b/doc/ext/inheritance.rst @@ -1,7 +1,7 @@ .. highlight:: rest -The inheritance diagram extension -================================= +:mod:`sphinx.ext.inheritance_diagram` -- Include inheritance diagrams +===================================================================== .. module:: sphinx.ext.inheritance_diagram :synopsis: Support for displaying inheritance diagrams via graphviz. -- cgit v1.2.1 From 1ea50bf165f0456df9d2181c366aecca73e96118 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Mar 2009 09:21:35 +0100 Subject: Use standard ``file:line: warning: message`` format for warning messages. --- sphinx/application.py | 11 ++++++----- sphinx/builders/__init__.py | 16 +++++++--------- sphinx/builders/html.py | 2 +- sphinx/builders/latex.py | 9 +++++---- sphinx/builders/linkcheck.py | 6 ++++-- sphinx/builders/text.py | 2 +- sphinx/environment.py | 24 ++++++++++++------------ sphinx/theming.py | 2 +- sphinx/writers/latex.py | 17 +++++++++++++---- tests/test_application.py | 2 +- tests/test_autodoc.py | 1 + tests/test_build.py | 20 ++++++++++---------- tests/test_env.py | 8 ++++---- 13 files changed, 66 insertions(+), 54 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 76c8f3c9..9e450240 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -134,16 +134,17 @@ class Sphinx(object): self.emit('build-finished', None) self.builder.cleanup() - def warn(self, message): + def warn(self, message, location=None, prefix='warning: '): + warntext = location and '%s: %s%s\n' % (location, prefix, message) or \ + '%s%s\n' % (prefix, message) if self.warningiserror: - raise SphinxWarning('WARNING: %s\n' % message) + raise SphinxWarning(warntext) self._warncount += 1 try: - self._warning.write('WARNING: %s\n' % message) + self._warning.write(warntext) except UnicodeEncodeError: encoding = getattr(self._warning, 'encoding', 'ascii') - self._warning.write(('WARNING: %s\n' % message).encode(encoding, - 'replace')) + self._warning.write(warntext.encode(encoding, 'replace')) def info(self, message='', nonl=False): try: diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 097be078..7b8a7095 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -136,9 +136,9 @@ class Builder(object): if candidate: break else: - self.warn('%s:%s: no matching candidate for image URI %r' % - (node.source, getattr(node, 'lineno', ''), - node['uri'])) + self.warn( + 'no matching candidate for image URI %r' % node['uri'], + '%s:%s' % (node.source, getattr(node, 'line', ''))) continue node['uri'] = candidate else: @@ -249,7 +249,7 @@ class Builder(object): updated_docnames = set() # while reading, collect all warnings from docutils warnings = [] - self.env.set_warnfunc(warnings.append) + self.env.set_warnfunc(lambda *args: warnings.append(args)) self.info(bold('updating environment: '), nonl=1) iterator = self.env.update(self.config, self.srcdir, self.doctreedir, self.app) @@ -261,8 +261,7 @@ class Builder(object): # nothing further to do, the environment has already # done the reading for warning in warnings: - if warning.strip(): - self.warn(warning) + self.warn(*warning) self.env.set_warnfunc(self.warn) doccount = len(updated_docnames) @@ -327,14 +326,13 @@ class Builder(object): # write target files warnings = [] - self.env.set_warnfunc(warnings.append) + self.env.set_warnfunc(lambda *args: warnings.append(args)) for docname in self.status_iterator(sorted(docnames), 'writing output... ', darkgreen): doctree = self.env.get_and_resolve_doctree(docname, self) self.write_doc(docname, doctree) for warning in warnings: - if warning.strip(): - self.warn(warning) + self.warn(*warning) self.env.set_warnfunc(self.warn) def prepare_writing(self, docnames): diff --git a/sphinx/builders/html.py b/sphinx/builders/html.py index 6c2593ba..365cf5f9 100644 --- a/sphinx/builders/html.py +++ b/sphinx/builders/html.py @@ -657,7 +657,7 @@ class StandaloneHTMLBuilder(Builder): finally: f.close() except (IOError, OSError), err: - self.warn("Error writing file %s: %s" % (outfilename, err)) + self.warn("error writing file %s: %s" % (outfilename, err)) if self.copysource and ctx.get('sourcename'): # copy the source file for the "show source" link source_name = path.join(self.outdir, '_sources', diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index 9fe7b8a5..96d70e3e 100644 --- a/sphinx/builders/latex.py +++ b/sphinx/builders/latex.py @@ -60,8 +60,8 @@ class LaTeXBuilder(Builder): def init_document_data(self): preliminary_document_data = map(list, self.config.latex_documents) if not preliminary_document_data: - self.warn('No "latex_documents" config value found; no documents ' - 'will be written.') + self.warn('no "latex_documents" config value found; no documents ' + 'will be written') return # assign subdirs to titles self.titles = [] @@ -121,8 +121,9 @@ class LaTeXBuilder(Builder): includefile, self.env.get_doctree(includefile)) self.docnames.add(includefile) except Exception: - self.warn('%s: toctree contains ref to nonexisting ' - 'file %r' % (docname, includefile)) + self.warn('toctree contains ref to nonexisting ' + 'file %r' % includefile, + self.builder.env.doc2path(docname)) else: sof = addnodes.start_of_file(docname=includefile) sof.children = subtree.children diff --git a/sphinx/builders/linkcheck.py b/sphinx/builders/linkcheck.py index b0fa9ba6..f3962965 100644 --- a/sphinx/builders/linkcheck.py +++ b/sphinx/builders/linkcheck.py @@ -87,7 +87,8 @@ class CheckExternalLinksBuilder(Builder): self.write_entry('broken', docname, lineno, uri + ': ' + s) self.broken[uri] = (r, s) if self.app.quiet: - self.warn('%s:%s: broken link: %s' % (docname, lineno, uri)) + self.warn('broken link: %s' % uri, + '%s:%s' % (self.env.doc2path(docname), lineno)) else: self.info(' - ' + purple('redirected') + ' to ' + s) self.write_entry('redirected', docname, @@ -99,7 +100,8 @@ class CheckExternalLinksBuilder(Builder): self.warn(uri + ' - ' + red('malformed!')) self.write_entry('malformed', docname, lineno, uri) if self.app.quiet: - self.warn('%s:%s: malformed link: %s' % (docname, lineno, uri)) + self.warn('malformed link: %s' % uri, + '%s:%s' % (self.env.doc2path(docname), lineno)) self.app.statuscode = 1 if self.broken: diff --git a/sphinx/builders/text.py b/sphinx/builders/text.py index 93737285..8651778c 100644 --- a/sphinx/builders/text.py +++ b/sphinx/builders/text.py @@ -64,7 +64,7 @@ class TextBuilder(Builder): finally: f.close() except (IOError, OSError), err: - self.warn("Error writing file %s: %s" % (outfilename, err)) + self.warn("error writing file %s: %s" % (outfilename, err)) def finish(self): pass diff --git a/sphinx/environment.py b/sphinx/environment.py index c210c395..5840d2e2 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -71,12 +71,12 @@ default_substitutions = set([ dummy_reporter = Reporter('', 4, 4) -class RedirStream(object): - def __init__(self, writefunc): - self.writefunc = writefunc +class WarningStream(object): + def __init__(self, warnfunc): + self.warnfunc = warnfunc def write(self, text): if text.strip(): - self.writefunc(text) + self.warnfunc(text, None, '') class NoUri(Exception): @@ -323,15 +323,15 @@ class BuildEnvironment: def set_warnfunc(self, func): self._warnfunc = func - self.settings['warning_stream'] = RedirStream(func) + self.settings['warning_stream'] = WarningStream(func) def warn(self, docname, msg, lineno=None): if docname: if lineno is None: lineno = '' - self._warnfunc('%s:%s: %s' % (self.doc2path(docname), lineno, msg)) + self._warnfunc(msg, '%s:%s' % (self.doc2path(docname), lineno)) else: - self._warnfunc('GLOBAL:: ' + msg) + self._warnfunc(msg) def clear_doc(self, docname): """Remove all traces of a source file in the inventory.""" @@ -688,7 +688,7 @@ class BuildEnvironment: filepath = path.normpath(path.join(docdir, node['reftarget'])) self.dependencies.setdefault(docname, set()).add(filepath) if not os.access(path.join(self.srcdir, filepath), os.R_OK): - self.warn(docname, 'Download file not readable: %s' % filepath, + self.warn(docname, 'download file not readable: %s' % filepath, getattr(node, 'line', None)) continue uniquename = self.dlfiles.add_file(docname, filepath) @@ -707,7 +707,7 @@ class BuildEnvironment: node['candidates'] = candidates = {} imguri = node['uri'] if imguri.find('://') != -1: - self.warn(docname, 'Nonlocal image URI found: %s' % imguri, + self.warn(docname, 'nonlocal image URI found: %s' % imguri, node.line) candidates['?'] = imguri continue @@ -735,7 +735,7 @@ class BuildEnvironment: f.close() except (OSError, IOError): self.warn(docname, - 'Image file %s not readable' % filename) + 'image file %s not readable' % filename) if imgtype: candidates['image/' + imgtype] = new_imgpath else: @@ -745,7 +745,7 @@ class BuildEnvironment: for imgpath in candidates.itervalues(): self.dependencies.setdefault(docname, set()).add(imgpath) if not os.access(path.join(self.srcdir, imgpath), os.R_OK): - self.warn(docname, 'Image file not readable: %s' % imgpath, + self.warn(docname, 'image file not readable: %s' % imgpath, node.line) continue self.images.add_file(docname, imgpath) @@ -970,7 +970,7 @@ class BuildEnvironment: f.close() doctree.settings.env = self doctree.reporter = Reporter(self.doc2path(docname), 2, 4, - stream=RedirStream(self._warnfunc)) + stream=WarningStream(self._warnfunc)) return doctree diff --git a/sphinx/theming.py b/sphinx/theming.py index 97b05233..77c3137c 100644 --- a/sphinx/theming.py +++ b/sphinx/theming.py @@ -48,7 +48,7 @@ class Theme(object): tname = theme[:-4] tinfo = zfile except Exception: - builder.warn('File %r on theme path is not a valid ' + builder.warn('file %r on theme path is not a valid ' 'zipfile or contains no theme' % theme) continue else: diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 9954350f..9ec3b00d 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -368,7 +368,10 @@ class LaTeXTranslator(nodes.NodeVisitor): elif self.this_is_the_title: if len(node.children) != 1 and not isinstance(node.children[0], nodes.Text): - self.builder.warn('document title is not a single Text node') + self.builder.warn( + 'document title is not a single Text node', + '%s:%s' % (self.builder.env.doc2path(self.curfilestack[-1]), + node.line or '')) if not self.elements['title']: # text needs to be escaped since it is inserted into # the output literally @@ -394,8 +397,11 @@ class LaTeXTranslator(nodes.NodeVisitor): self.table.caption = self.encode(node.astext()) raise nodes.SkipNode else: - self.builder.warn('encountered title node not in section, topic, ' - 'table, admonition or sidebar') + self.builder.warn( + 'encountered title node not in section, topic, table, ' + 'admonition or sidebar', + '%s:%s' % (self.builder.env.doc2path(self.curfilestack[-1]), + node.line or '')) self.body.append('\\textbf{') self.context.append('}\n') self.in_title = 1 @@ -1002,7 +1008,10 @@ class LaTeXTranslator(nodes.NodeVisitor): self.body.append('\\grammartoken{') self.context.append('}') else: - self.builder.warn('unusable reference target found: %s' % uri) + self.builder.warn( + 'unusable reference target found: %s' % uri, + '%s:%s' % (self.builder.env.doc2path(self.curfilestack[-1]), + node.line or '')) self.context.append('') def depart_reference(self, node): self.body.append(self.context.pop()) diff --git a/tests/test_application.py b/tests/test_application.py index 6425e275..4fda0edb 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -53,7 +53,7 @@ def test_output(): old_count = app._warncount app.warn("Bad news!") - assert warnings.getvalue() == "WARNING: Bad news!\n" + assert warnings.getvalue() == "warning: Bad news!\n" assert app._warncount == old_count + 1 finally: app.cleanup() diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index 25d833a2..a9e030fe 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -36,6 +36,7 @@ def setup_module(): platform = '', deprecated = False, members = [], + member_order = 'alphabetic', ) directive = Struct( diff --git a/tests/test_build.py b/tests/test_build.py index f451b305..00a82b4d 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -38,24 +38,24 @@ html_warnfile = StringIO() latex_warnfile = StringIO() ENV_WARNINGS = """\ -WARNING: %(root)s/images.txt:9: Image file not readable: foo.png -WARNING: %(root)s/images.txt:23: Nonlocal image URI found: \ +%(root)s/images.txt:9: warning: image file not readable: foo.png +%(root)s/images.txt:23: warning: nonlocal image URI found: \ http://www.python.org/logo.png -WARNING: %(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading \ +%(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading \ included file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option -WARNING: %(root)s/includes.txt:56: Download file not readable: nonexisting.png +%(root)s/includes.txt:56: warning: download file not readable: nonexisting.png """ HTML_WARNINGS = ENV_WARNINGS + """\ -WARNING: %(root)s/images.txt:: no matching candidate for image URI u'foo.*' -WARNING: %(root)s/markup.txt:: invalid index entry u'' -WARNING: %(root)s/markup.txt:: invalid pair index entry u'' -WARNING: %(root)s/markup.txt:: invalid pair index entry u'keyword; ' +%(root)s/images.txt:20: warning: no matching candidate for image URI u'foo.*' +%(root)s/markup.txt:: warning: invalid index entry u'' +%(root)s/markup.txt:: warning: invalid pair index entry u'' +%(root)s/markup.txt:: warning: invalid pair index entry u'keyword; ' """ LATEX_WARNINGS = ENV_WARNINGS + """\ -WARNING: None:: no matching candidate for image URI u'foo.*' -WARNING: invalid pair index entry u'' +None:None: warning: no matching candidate for image URI u'foo.*' +warning: invalid pair index entry u'' """ HTML_XPATH = { diff --git a/tests/test_env.py b/tests/test_env.py index 07e2cbe4..0b944c50 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -22,14 +22,14 @@ def setup_module(): global app, env app = TestApp(srcdir='(temp)') env = BuildEnvironment(app.srcdir, app.doctreedir, app.config) - env.set_warnfunc(warnings.append) + env.set_warnfunc(lambda *args: warnings.append(args)) def teardown_module(): app.cleanup() def warning_emitted(file, text): for warning in warnings: - if file+':' in warning and text in warning: + if len(warning) == 2 and file+':' in warning[1] and text in warning[0]: return True return False @@ -46,8 +46,8 @@ def test_first_update(): assert docnames == env.found_docs == set(env.all_docs) def test_images(): - assert warning_emitted('images.txt', 'Image file not readable: foo.png') - assert warning_emitted('images.txt', 'Nonlocal image URI found: ' + assert warning_emitted('images.txt', 'image file not readable: foo.png') + assert warning_emitted('images.txt', 'nonlocal image URI found: ' 'http://www.python.org/logo.png') tree = env.get_doctree('images') -- cgit v1.2.1 From 9051b533459712afdd770992bc6935d09c7c0a6d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Mar 2009 09:48:55 +0100 Subject: #114: Added an ``abbr`` role to markup abbreviations and acronyms. --- CHANGES | 3 +++ doc/concepts.rst | 2 ++ doc/markup/inline.rst | 10 ++++++++++ sphinx/addnodes.py | 6 +++++- sphinx/roles.py | 13 +++++++++++++ sphinx/writers/html.py | 8 ++++++++ sphinx/writers/latex.py | 13 +++++++++++++ sphinx/writers/text.py | 6 ++++++ tests/root/markup.txt | 1 + 9 files changed, 61 insertions(+), 1 deletion(-) diff --git a/CHANGES b/CHANGES index 3518cb03..9823bb98 100644 --- a/CHANGES +++ b/CHANGES @@ -44,6 +44,9 @@ New features added - #10: Added HTML section numbers, enabled by giving a ``:numbered:`` flag to the ``toctree`` directive. + - #114: Added an ``abbr`` role to markup abbreviations and + acronyms. + - The ``literalinclude`` directive now supports several more options, to include only parts of a file. diff --git a/doc/concepts.rst b/doc/concepts.rst index e6d5fa02..d3c8cf7c 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -19,6 +19,8 @@ such a document name. Examples for document names are ``index``, ``library/zipfile``, or ``reference/datamodel/types``. Note that there is no leading slash. +This is a :abbr:`LIFO (last-in, first-out)` and a :abbr:`LIFO (last-in, first-out)`. + The TOC tree ------------ diff --git a/doc/markup/inline.rst b/doc/markup/inline.rst index 97b20da7..69721b32 100644 --- a/doc/markup/inline.rst +++ b/doc/markup/inline.rst @@ -278,6 +278,16 @@ Other semantic markup The following roles don't do anything special except formatting the text in a different style: +.. role:: abbr + + An abbreviation. If the role content contains a parenthesized explanation, + it will be treated specially: it will be shown in a tool-tip in HTML, and + output only once in LaTeX. + + Example: ``:abbr:`LIFO (last-in, first-out)```. + + .. versionadded:: 0.6 + .. role:: command The name of an OS-level command, such as ``rm``. diff --git a/sphinx/addnodes.py b/sphinx/addnodes.py index f0b0b063..63907a0e 100644 --- a/sphinx/addnodes.py +++ b/sphinx/addnodes.py @@ -84,6 +84,9 @@ class highlightlang(nodes.Element): pass # like emphasis, but doesn't apply further text processors, e.g. smartypants class literal_emphasis(nodes.emphasis): pass +# for abbreviations (with explanations) +class abbreviation(nodes.Inline, nodes.TextElement): pass + # glossary class glossary(nodes.Element): pass @@ -109,4 +112,5 @@ nodes._add_node_class_names("""index desc desc_content desc_signature desc_parameter desc_optional download_reference hlist hlistcol centered versionmodified seealso productionlist production toctree pending_xref compact_paragraph highlightlang literal_emphasis - glossary acks module start_of_file tabular_col_spec meta""".split()) + abbreviation glossary acks module start_of_file tabular_col_spec + meta""".split()) diff --git a/sphinx/roles.py b/sphinx/roles.py index 9cc7fcd2..550deb3e 100644 --- a/sphinx/roles.py +++ b/sphinx/roles.py @@ -226,6 +226,18 @@ def emph_literal_role(typ, rawtext, text, lineno, inliner, return [retnode], [] +_abbr_re = re.compile('\((.*)\)$') + +def abbr_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): + text = utils.unescape(text) + m = _abbr_re.search(text) + if m is None: + return [addnodes.abbreviation(text, text)], [] + abbr = text[:m.start()].strip() + expl = m.group(1) + return [addnodes.abbreviation(abbr, abbr, explanation=expl)], [] + + specific_docroles = { 'data': xfileref_role, 'exc': xfileref_role, @@ -254,6 +266,7 @@ specific_docroles = { 'menuselection': menusel_role, 'file': emph_literal_role, 'samp': emph_literal_role, + 'abbr': abbr_role, } for rolename, func in specific_docroles.iteritems(): diff --git a/sphinx/writers/html.py b/sphinx/writers/html.py index e2f754a8..f600e8bd 100644 --- a/sphinx/writers/html.py +++ b/sphinx/writers/html.py @@ -453,6 +453,14 @@ class HTMLTranslator(BaseTranslator): def depart_literal_emphasis(self, node): return self.depart_emphasis(node) + def visit_abbreviation(self, node): + attrs = {} + if node.hasattr('explanation'): + attrs['title'] = node['explanation'] + self.body.append(self.starttag(node, 'abbr', **attrs)) + def depart_abbreviation(self, node): + self.body.append('') + def depart_title(self, node): close_tag = self.context[-1] if self.add_permalinks and self.builder.add_permalinks and \ diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 9ec3b00d..fddc0a79 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -216,6 +216,7 @@ class LaTeXTranslator(nodes.NodeVisitor): self.written_ids = set() self.footnotestack = [] self.curfilestack = [] + self.handled_abbrs = set() if self.elements['docclass'] == 'manual': if builder.config.latex_use_parts: self.top_sectionlevel = 0 @@ -1043,6 +1044,18 @@ class LaTeXTranslator(nodes.NodeVisitor): def depart_strong(self, node): self.body.append('}') + def visit_abbreviation(self, node): + abbr = node.astext() + self.body.append(r'\textsc{') + # spell out the explanation once + if node.hasattr('explanation') and abbr not in self.handled_abbrs: + self.context.append('} (%s)' % self.encode(node['explanation'])) + self.handled_abbrs.add(abbr) + else: + self.context.append('}') + def depart_abbreviation(self, node): + self.body.append(self.context.pop()) + def visit_title_reference(self, node): self.body.append(r'\emph{') def depart_title_reference(self, node): diff --git a/sphinx/writers/text.py b/sphinx/writers/text.py index 787e7020..b3b565c5 100644 --- a/sphinx/writers/text.py +++ b/sphinx/writers/text.py @@ -645,6 +645,12 @@ class TextTranslator(nodes.NodeVisitor): def depart_strong(self, node): self.add_text('**') + def visit_abbreviation(self, node): + self.add_text('') + def depart_abbreviation(self, node): + if node.hasattr('explanation'): + self.add_text(' (%s)' % node['explanation']) + def visit_title_reference(self, node): self.add_text('*') def depart_title_reference(self, node): diff --git a/tests/root/markup.txt b/tests/root/markup.txt index d799c80d..52d407e2 100644 --- a/tests/root/markup.txt +++ b/tests/root/markup.txt @@ -152,6 +152,7 @@ Option list: try2_stmt: "try" ":" `suite` : "finally" ":" `suite` +Test :abbr:`abbr (abbreviation)` and another :abbr:`abbr (abbreviation)`. Index markup ------------ -- cgit v1.2.1 From 87b02776e25b4baaf28d3dda502b63ab3f1b9902 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Mar 2009 10:05:27 +0100 Subject: Remove testing text. --- doc/concepts.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/concepts.rst b/doc/concepts.rst index d3c8cf7c..e6d5fa02 100644 --- a/doc/concepts.rst +++ b/doc/concepts.rst @@ -19,8 +19,6 @@ such a document name. Examples for document names are ``index``, ``library/zipfile``, or ``reference/datamodel/types``. Note that there is no leading slash. -This is a :abbr:`LIFO (last-in, first-out)` and a :abbr:`LIFO (last-in, first-out)`. - The TOC tree ------------ -- cgit v1.2.1 From 00351527a48409b70e1f80250151569a91f772b6 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Mar 2009 10:06:18 +0100 Subject: Make WARNING the default warning prefix. --- sphinx/application.py | 2 +- tests/test_application.py | 2 +- tests/test_build.py | 18 +++++++++--------- 3 files changed, 11 insertions(+), 11 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 9e450240..9c467066 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -134,7 +134,7 @@ class Sphinx(object): self.emit('build-finished', None) self.builder.cleanup() - def warn(self, message, location=None, prefix='warning: '): + def warn(self, message, location=None, prefix='WARNING: '): warntext = location and '%s: %s%s\n' % (location, prefix, message) or \ '%s%s\n' % (prefix, message) if self.warningiserror: diff --git a/tests/test_application.py b/tests/test_application.py index 4fda0edb..6425e275 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -53,7 +53,7 @@ def test_output(): old_count = app._warncount app.warn("Bad news!") - assert warnings.getvalue() == "warning: Bad news!\n" + assert warnings.getvalue() == "WARNING: Bad news!\n" assert app._warncount == old_count + 1 finally: app.cleanup() diff --git a/tests/test_build.py b/tests/test_build.py index 00a82b4d..f509a9f4 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -38,24 +38,24 @@ html_warnfile = StringIO() latex_warnfile = StringIO() ENV_WARNINGS = """\ -%(root)s/images.txt:9: warning: image file not readable: foo.png -%(root)s/images.txt:23: warning: nonlocal image URI found: \ +%(root)s/images.txt:9: WARNING: image file not readable: foo.png +%(root)s/images.txt:23: WARNING: nonlocal image URI found: \ http://www.python.org/logo.png %(root)s/includes.txt:: (WARNING/2) Encoding 'utf-8' used for reading \ included file u'wrongenc.inc' seems to be wrong, try giving an :encoding: option -%(root)s/includes.txt:56: warning: download file not readable: nonexisting.png +%(root)s/includes.txt:56: WARNING: download file not readable: nonexisting.png """ HTML_WARNINGS = ENV_WARNINGS + """\ -%(root)s/images.txt:20: warning: no matching candidate for image URI u'foo.*' -%(root)s/markup.txt:: warning: invalid index entry u'' -%(root)s/markup.txt:: warning: invalid pair index entry u'' -%(root)s/markup.txt:: warning: invalid pair index entry u'keyword; ' +%(root)s/images.txt:20: WARNING: no matching candidate for image URI u'foo.*' +%(root)s/markup.txt:: WARNING: invalid index entry u'' +%(root)s/markup.txt:: WARNING: invalid pair index entry u'' +%(root)s/markup.txt:: WARNING: invalid pair index entry u'keyword; ' """ LATEX_WARNINGS = ENV_WARNINGS + """\ -None:None: warning: no matching candidate for image URI u'foo.*' -warning: invalid pair index entry u'' +None:None: WARNING: no matching candidate for image URI u'foo.*' +WARNING: invalid pair index entry u'' """ HTML_XPATH = { -- cgit v1.2.1 From 1089e377ecc146b346d86564d9ca34d138dc846b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 5 Mar 2009 20:25:39 +0100 Subject: Sanitize the Environment.update() method API. --- sphinx/builders/__init__.py | 26 ++++++++++++++++------- sphinx/environment.py | 51 +++++++++++++++++++++++++-------------------- 2 files changed, 46 insertions(+), 31 deletions(-) diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 7b8a7095..4fafa87d 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -109,7 +109,7 @@ class Builder(object): """ raise NotImplementedError - def status_iterator(self, iterable, summary, colorfunc=darkgreen): + def status_iterator(self, iterable, length, summary, colorfunc=darkgreen): l = -1 for item in iterable: if l == -1: @@ -120,6 +120,17 @@ class Builder(object): if l == 0: self.info() + ## new version with progress info + #def status_iterator(self, iterable, length, summary, colorfunc=darkgreen): + # l = 0 + # for item in iterable: + # if l == 0: + # self.info(bold(summary)) + # l += 1 + # self.info(' [%3d%%] %s\n' % (100*l/length, colorfunc(item)), + # nonl=1) + # yield item + supported_image_types = [] def post_process_images(self, doctree): @@ -251,12 +262,11 @@ class Builder(object): warnings = [] self.env.set_warnfunc(lambda *args: warnings.append(args)) self.info(bold('updating environment: '), nonl=1) - iterator = self.env.update(self.config, self.srcdir, - self.doctreedir, self.app) - # the first item in the iterator is a summary message - self.info(iterator.next()) - for docname in self.status_iterator(iterator, 'reading sources... ', - purple): + msg, length, iterator = self.env.update(self.config, self.srcdir, + self.doctreedir, self.app) + self.info(msg) + for docname in self.status_iterator(iterator, length, + 'reading sources... ', purple): updated_docnames.add(docname) # nothing further to do, the environment has already # done the reading @@ -327,7 +337,7 @@ class Builder(object): # write target files warnings = [] self.env.set_warnfunc(lambda *args: warnings.append(args)) - for docname in self.status_iterator(sorted(docnames), + for docname in self.status_iterator(sorted(docnames), len(docnames), 'writing output... ', darkgreen): doctree = self.env.get_and_resolve_doctree(docname, self) self.write_doc(docname, doctree) diff --git a/sphinx/environment.py b/sphinx/environment.py index 5840d2e2..0884ecca 100644 --- a/sphinx/environment.py +++ b/sphinx/environment.py @@ -453,10 +453,13 @@ class BuildEnvironment: return added, changed, removed def update(self, config, srcdir, doctreedir, app=None): - """(Re-)read all files new or changed since last update. - Yields a summary and then docnames as it processes them. - Store all environment docnames in the canonical format - (ie using SEP as a separator in place of os.path.sep).""" + """ + (Re-)read all files new or changed since last update. Returns a + summary, the total count of documents to reread and an iterator that + yields docnames as it processes them. Store all environment docnames in + the canonical format (ie using SEP as a separator in place of + os.path.sep). + """ config_changed = False if self.config is None: msg = '[new config] ' @@ -482,6 +485,7 @@ class BuildEnvironment: self.srcdir = srcdir self.doctreedir = doctreedir self.find_files(config) + self.config = config added, changed, removed = self.get_outdated_files(config_changed) @@ -492,30 +496,31 @@ class BuildEnvironment: msg += '%s added, %s changed, %s removed' % (len(added), len(changed), len(removed)) - yield msg - self.config = config - self.app = app + def update_generator(): + self.app = app - # clear all files no longer present - for docname in removed: - if app: - app.emit('env-purge-doc', self, docname) - self.clear_doc(docname) + # clear all files no longer present + for docname in removed: + if app: + app.emit('env-purge-doc', self, docname) + self.clear_doc(docname) - # read all new and changed files - to_read = added | changed - for docname in sorted(to_read): - yield docname - self.read_doc(docname, app=app) + # read all new and changed files + to_read = added | changed + for docname in sorted(to_read): + yield docname + self.read_doc(docname, app=app) - if config.master_doc not in self.all_docs: - self.warn(None, 'master file %s not found' % - self.doc2path(config.master_doc)) + if config.master_doc not in self.all_docs: + self.warn(None, 'master file %s not found' % + self.doc2path(config.master_doc)) - self.app = None - if app: - app.emit('env-updated', self) + self.app = None + if app: + app.emit('env-updated', self) + + return msg, len(added | changed), update_generator() def check_dependents(self, already): to_rewrite = self.assign_section_numbers() -- cgit v1.2.1 From 8dd54a55c9a1f1cb1cdde5d0b0ab8e1787c7c087 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 7 Mar 2009 22:54:36 +0100 Subject: Update tutorial for directive classes. --- doc/ext/tutorial.rst | 71 ++++++++++++++++++++++++++++++---------------------- 1 file changed, 41 insertions(+), 30 deletions(-) diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst index 7d93817c..5f24c0fc 100644 --- a/doc/ext/tutorial.rst +++ b/doc/ext/tutorial.rst @@ -109,8 +109,8 @@ new Python module called :file:`todo.py` and add the setup function:: latex=(visit_todo_node, depart_todo_node), text=(visit_todo_node, depart_todo_node)) - app.add_directive('todo', todo_directive, 1, (0, 0, 1)) - app.add_directive('todolist', todolist_directive, 0, (0, 0, 0)) + app.add_directive('todo', TodoDirective) + app.add_directive('todolist', TodolistDirective) app.connect('doctree-resolved', process_todo_nodes) app.connect('env-purge-doc', purge_todos) @@ -132,9 +132,7 @@ the individual calls do is the following: We need to create the two node classes ``todo`` and ``todolist`` later. -* :meth:`~Sphinx.add_directive` adds a new *directive*, given by name, handler - function and two arguments that specify if the directive has content and how - many arguments it accepts. +* :meth:`~Sphinx.add_directive` adds a new *directive*, given by name and class. The handler functions are created later. @@ -168,17 +166,25 @@ docutils classes defined in :mod:`docutils.nodes`. ``todo`` inherits from is just a "general" node. -The Directive Handlers ----------------------- +The Directive Classes +--------------------- -A directive handler is a function with a host of arguments, covered in detail in -the docutils documentation. It must return a list of nodes. +A directive class is a class deriving usually from +``docutils.parsers.rst.Directive``. Since the class-based directive interface +doesn't exist yet in Docutils 0.4, Sphinx has another base class called +``sphinx.util.compat.Directive`` that you can derive your directive from, and it +will work with both Docutils 0.4 and 0.5 upwards. The directive interface is +covered in detail in the docutils documentation; the important thing is that the +class has a method ``run`` that returns a list of nodes. The ``todolist`` directive is quite simple:: - def todolist_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - return [todolist('')] + from sphinx.util.compat import Directive + + class TodolistDirective(Directive): + + def run(self): + return [todolist('')] An instance of our ``todolist`` node class is created and returned. The todolist directive has neither content nor arguments that need to be handled. @@ -187,30 +193,35 @@ The ``todo`` directive function looks like this:: from sphinx.util.compat import make_admonition - def todo_directive(name, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): - env = state.document.settings.env + class TodoDirective(Directive): - targetid = "todo-%s" % env.index_num - env.index_num += 1 - targetnode = nodes.target('', '', ids=[targetid]) + # this enables content in the directive + has_content = True - ad = make_admonition(todo, name, [_('Todo')], options, content, lineno, - content_offset, block_text, state, state_machine) + def run(self): + env = self.state.document.settings.env - if not hasattr(env, 'todo_all_todos'): - env.todo_all_todos = [] - env.todo_all_todos.append({ - 'docname': env.docname, - 'lineno': lineno, - 'todo': ad[0].deepcopy(), - 'target': targetnode, - }) + targetid = "todo-%s" % env.index_num + env.index_num += 1 + targetnode = nodes.target('', '', ids=[targetid]) + + ad = make_admonition(todo, self.name, [_('Todo')], self.options, + self.content, self.lineno, self.content_offset, + self.block_text, self.state, self.state_machine) + + if not hasattr(env, 'todo_all_todos'): + env.todo_all_todos = [] + env.todo_all_todos.append({ + 'docname': env.docname, + 'lineno': self.lineno, + 'todo': ad[0].deepcopy(), + 'target': targetnode, + }) - return [targetnode] + ad + return [targetnode] + ad Several important things are covered here. First, as you can see, you can refer -to the build environment instance using ``state.document.settings.env``. +to the build environment instance using ``self.state.document.settings.env``. Then, to act as a link target (from the todolist), the todo directive needs to return a target node in addition to the todo node. The target ID (in HTML, this -- cgit v1.2.1 From b03fa8ea963a9b538c1abbde01414964bb2cdbcc Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 8 Mar 2009 10:21:07 +0100 Subject: Use a new progress indicator with percents. --- sphinx/builders/__init__.py | 46 +++++++++++++++++++++++++-------------------- sphinx/util/console.py | 15 ++++++++------- 2 files changed, 34 insertions(+), 27 deletions(-) diff --git a/sphinx/builders/__init__.py b/sphinx/builders/__init__.py index 4fafa87d..41f63de4 100644 --- a/sphinx/builders/__init__.py +++ b/sphinx/builders/__init__.py @@ -18,7 +18,7 @@ from docutils import nodes from sphinx import package_dir, locale from sphinx.util import SEP, relative_uri from sphinx.environment import BuildEnvironment -from sphinx.util.console import bold, purple, darkgreen +from sphinx.util.console import bold, purple, darkgreen, term_width_line # side effect: registers roles and directives from sphinx import roles @@ -109,27 +109,33 @@ class Builder(object): """ raise NotImplementedError - def status_iterator(self, iterable, length, summary, colorfunc=darkgreen): - l = -1 + def old_status_iterator(self, iterable, summary, colorfunc=darkgreen): + l = 0 for item in iterable: - if l == -1: + if l == 0: self.info(bold(summary), nonl=1) - l = 0 + l = 1 self.info(colorfunc(item) + ' ', nonl=1) yield item - if l == 0: + if l == 1: self.info() - ## new version with progress info - #def status_iterator(self, iterable, length, summary, colorfunc=darkgreen): - # l = 0 - # for item in iterable: - # if l == 0: - # self.info(bold(summary)) - # l += 1 - # self.info(' [%3d%%] %s\n' % (100*l/length, colorfunc(item)), - # nonl=1) - # yield item + # new version with progress info + def status_iterator(self, iterable, summary, colorfunc=darkgreen, length=0): + if length == 0: + for item in self.old_status_iterator(iterable, summary, colorfunc): + yield item + return + l = 0 + summary = bold(summary) + for item in iterable: + l += 1 + self.info(term_width_line('%s[%3d%%] %s' % + (summary, 100*l/length, + colorfunc(item))), nonl=1) + yield item + if l > 0: + self.info() supported_image_types = [] @@ -265,8 +271,8 @@ class Builder(object): msg, length, iterator = self.env.update(self.config, self.srcdir, self.doctreedir, self.app) self.info(msg) - for docname in self.status_iterator(iterator, length, - 'reading sources... ', purple): + for docname in self.status_iterator(iterator, 'reading sources... ', + purple, length): updated_docnames.add(docname) # nothing further to do, the environment has already # done the reading @@ -337,8 +343,8 @@ class Builder(object): # write target files warnings = [] self.env.set_warnfunc(lambda *args: warnings.append(args)) - for docname in self.status_iterator(sorted(docnames), len(docnames), - 'writing output... ', darkgreen): + for docname in self.status_iterator( + sorted(docnames), 'writing output... ', darkgreen, len(docnames)): doctree = self.env.get_and_resolve_doctree(docname, self) self.write_doc(docname, doctree) for warning in warnings: diff --git a/sphinx/util/console.py b/sphinx/util/console.py index 724dee10..083fc6f4 100644 --- a/sphinx/util/console.py +++ b/sphinx/util/console.py @@ -16,25 +16,26 @@ codes = {} def get_terminal_width(): """Borrowed from the py lib.""" try: - import os, termios, fcntl, struct - call = fcntl.ioctl(0, termios.TIOCGWINSZ, "\000"*8) - height, width = struct.unpack("hhhh", call)[:2] + import termios, fcntl, struct + call = fcntl.ioctl(0, termios.TIOCGWINSZ, + struct.pack('hhhh', 0, 0, 0, 0)) + height, width = struct.unpack('hhhh', call)[:2] terminal_width = width except (SystemExit, KeyboardInterrupt): raise except: # FALLBACK - terminal_width = int(os.environ.get('COLUMNS', 80))-1 + terminal_width = int(os.environ.get('COLUMNS', 80)) - 1 return terminal_width _tw = get_terminal_width() -def print_and_backspace(text, func): +def term_width_line(text): if not codes: # if no coloring, don't output fancy backspaces - func(text) + return text + '\n' else: - func(text.ljust(_tw) + _tw * "\b") + return text.ljust(_tw) + '\r' def color_terminal(): if 'COLORTERM' in os.environ: -- cgit v1.2.1 From a80c9aa2d4dad5dfd9dff44dd729795ca1aa94ab Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 9 Mar 2009 09:42:05 +0100 Subject: Mark up. --- README | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README b/README index 31eb6842..bb2dea9d 100644 --- a/README +++ b/README @@ -1,3 +1,5 @@ +.. -*- restructuredtext -*- + ================= README for Sphinx ================= -- cgit v1.2.1 From 22fb71059ba1fd72c6eee0a9a2038c2bc34929bd Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 9 Mar 2009 09:47:10 +0100 Subject: Fix node class name. --- doc/ext/tutorial.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/ext/tutorial.rst b/doc/ext/tutorial.rst index 5f24c0fc..c44748d2 100644 --- a/doc/ext/tutorial.rst +++ b/doc/ext/tutorial.rst @@ -289,7 +289,7 @@ emitted at the end of phase 3 and allows custom resolving to be done:: def process_todo_nodes(app, doctree, fromdocname): if not app.config.todo_include_todos: - for node in doctree.traverse(todo_node): + for node in doctree.traverse(todo): node.parent.remove(node) # Replace all todolist nodes with a list of the collected todos. -- cgit v1.2.1 From 460f36a9868d789fbefbe3f40e8c82add6c2da95 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 9 Mar 2009 15:04:32 +0100 Subject: Encode graphviz input to utf-8. --- sphinx/ext/graphviz.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py index 084797b7..d51e2ed5 100644 --- a/sphinx/ext/graphviz.py +++ b/sphinx/ext/graphviz.py @@ -115,6 +115,9 @@ def render_dot(self, code, options, format, prefix='graphviz'): self.builder.config.graphviz_dot) self.builder._graphviz_warned_dot = True return None + # graphviz expects UTF-8 by default + if isinstance(code, unicode): + code = code.encode('utf-8') stdout, stderr = p.communicate(code) if p.returncode != 0: raise GraphvizError('dot exited with error:\n[stderr]\n%s\n' -- cgit v1.2.1 From 68a77dd93ffb50c4712bbd8aeb85977b67f63859 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 9 Mar 2009 18:51:55 +0100 Subject: Add PyLit. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 2f7365d2..9eb0b0ce 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -40,6 +40,7 @@ included, please mail to `the Google group * PyCuda: http://documen.tician.de/pycuda/ * PyEphem: http://rhodesmill.org/pyephem/ * Pyevolve: http://pyevolve.sourceforge.net/ +* PyLit: http://pylit.berlios.de/ * Pylo: http://documen.tician.de/pylo/ * Pylons: http://docs.pylonshq.com/ * PyMOTW: http://www.doughellmann.com/PyMOTW/ -- cgit v1.2.1 From 45deb642412529c9f00ae41ad39fd5a9c6a9c762 Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sat, 14 Mar 2009 21:08:52 +0100 Subject: Work a bit on coding style of autosummary. --- sphinx-autogen.py | 15 +++ sphinx/ext/autosummary/__init__.py | 160 +++++++++++++------------ sphinx/ext/autosummary/generate.py | 172 +++++++++++++++------------ sphinx/ext/autosummary/templates/module | 39 ++++++ sphinx/ext/autosummary/templates/module.html | 39 ------ 5 files changed, 236 insertions(+), 189 deletions(-) create mode 100755 sphinx-autogen.py create mode 100644 sphinx/ext/autosummary/templates/module delete mode 100644 sphinx/ext/autosummary/templates/module.html diff --git a/sphinx-autogen.py b/sphinx-autogen.py new file mode 100755 index 00000000..494f4d85 --- /dev/null +++ b/sphinx-autogen.py @@ -0,0 +1,15 @@ +#!/usr/bin/env python +# -*- coding: utf-8 -*- +""" + Sphinx - Python documentation toolchain + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + :copyright: 2007-2009 by Georg Brandl. + :license: BSD. +""" + +import sys + +if __name__ == '__main__': + from sphinx.ext.autosummary.generate import main + sys.exit(main(sys.argv)) diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index f26c4676..8775fe86 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -1,80 +1,73 @@ +# -*- coding: utf-8 -*- """ -=========== -autosummary -=========== + sphinx.ext.autosummary + ~~~~~~~~~~~~~~~~~~~~~~ -Sphinx extension that adds an autosummary:: directive, which can be -used to generate function/method/attribute/etc. summary lists, similar -to those output eg. by Epydoc and other API doc generation tools. + Sphinx extension that adds an autosummary:: directive, which can be + used to generate function/method/attribute/etc. summary lists, similar + to those output eg. by Epydoc and other API doc generation tools. -An :autolink: role is also provided. + An :autolink: role is also provided. -autosummary directive ---------------------- + autosummary directive + --------------------- -The autosummary directive has the form:: + The autosummary directive has the form:: - .. autosummary:: - :nosignatures: - :toctree: generated/ - - module.function_1 - module.function_2 - ... + .. autosummary:: + :nosignatures: + :toctree: generated/ -and it generates an output table (containing signatures, optionally) + module.function_1 + module.function_2 + ... - ======================== ============================================= - module.function_1(args) Summary line from the docstring of function_1 - module.function_2(args) Summary line from the docstring - ... - ======================== ============================================= + and it generates an output table (containing signatures, optionally) -If the :toctree: option is specified, files matching the function names -are inserted to the toctree with the given prefix: + ======================== ============================================= + module.function_1(args) Summary line from the docstring of function_1 + module.function_2(args) Summary line from the docstring + ... + ======================== ============================================= - generated/module.function_1 - generated/module.function_2 - ... + If the :toctree: option is specified, files matching the function names + are inserted to the toctree with the given prefix: -Note: The file names contain the module:: or currentmodule:: prefixes. + generated/module.function_1 + generated/module.function_2 + ... -.. seealso:: autosummary_generate.py + Note: The file names contain the module:: or currentmodule:: prefixes. + .. seealso:: autosummary_generate.py -autolink role -------------- -The autolink role functions as ``:obj:`` when the name referred can be -resolved to a Python object, and otherwise it becomes simple emphasis. -This can be used as the default role to make links 'smart'. + autolink role + ------------- + The autolink role functions as ``:obj:`` when the name referred can be + resolved to a Python object, and otherwise it becomes simple emphasis. + This can be used as the default role to make links 'smart'. + + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ -import sys, os, posixpath, re + +import os +import re +import sys +import inspect +import posixpath from docutils.parsers.rst import directives from docutils.statemachine import ViewList from docutils import nodes -import sphinx.addnodes, sphinx.roles, sphinx.builder +from sphinx import addnodes, roles from sphinx.util import patfilter -import inspect - -def setup(app): - app.add_directive('autosummary', autosummary_directive, True, (0, 0, False), - toctree=directives.unchanged, - nosignatures=directives.flag) - app.add_role('autolink', autolink_role) - - app.add_node(autosummary_toc, - html=(autosummary_toc_visit_html, autosummary_toc_depart_noop), - latex=(autosummary_toc_visit_latex, autosummary_toc_depart_noop)) - app.connect('doctree-read', process_autosummary_toc) -#------------------------------------------------------------------------------ -# autosummary_toc node -#------------------------------------------------------------------------------ +# -- autosummary_toc node ------------------------------------------------------ class autosummary_toc(nodes.comment): pass @@ -83,7 +76,6 @@ def process_autosummary_toc(app, doctree): """ Insert items described in autosummary:: to the TOC tree, but do not generate the toctree:: list. - """ env = app.builder.env crawled = {} @@ -92,7 +84,7 @@ def process_autosummary_toc(app, doctree): for j, subnode in enumerate(node): try: if (isinstance(subnode, autosummary_toc) - and isinstance(subnode[0], sphinx.addnodes.toctree)): + and isinstance(subnode[0], addnodes.toctree)): env.note_toctree(env.docname, subnode[0]) continue except IndexError: @@ -104,19 +96,18 @@ def process_autosummary_toc(app, doctree): crawl_toc(doctree) def autosummary_toc_visit_html(self, node): - """Hide autosummary toctree list in HTML output""" + """Hide autosummary toctree list in HTML output.""" raise nodes.SkipNode def autosummary_toc_visit_latex(self, node): - """Show autosummary toctree (= put the referenced pages here) in Latex""" + """Show autosummary toctree (= put the referenced pages here) in Latex.""" pass def autosummary_toc_depart_noop(self, node): pass -#------------------------------------------------------------------------------ -# .. autosummary:: -#------------------------------------------------------------------------------ + +# -- .. autosummary:: ---------------------------------------------------------- def autosummary_directive(dirname, arguments, options, content, lineno, content_offset, block_text, state, state_machine): @@ -155,7 +146,7 @@ def autosummary_directive(dirname, arguments, options, content, lineno, line=lineno)) docnames.append(docname) - tocnode = sphinx.addnodes.toctree() + tocnode = addnodes.toctree() tocnode['includefiles'] = docnames tocnode['maxdepth'] = -1 tocnode['glob'] = None @@ -165,6 +156,7 @@ def autosummary_directive(dirname, arguments, options, content, lineno, else: return warnings + [node] + def get_autosummary(names, state, no_signatures=False): """ Generate a proper table node for autosummary:: directive. @@ -175,10 +167,10 @@ def get_autosummary(names, state, no_signatures=False): Names of Python objects to be imported and added to the table. document : document Docutils document object - + """ document = state.document - + real_names = {} warnings = [] @@ -209,14 +201,14 @@ def get_autosummary(names, state, no_signatures=False): except ImportError: warnings.append(document.reporter.warning( 'failed to import %s' % name)) - append_row(":obj:`%s`" % name, "") + append_row(':obj:`%s`' % name, '') continue real_names[name] = real_name - title = "" + title = '' qualifier = 'obj' - col1 = ":"+qualifier+":`%s <%s>`" % (name, real_name) + col1 = ':'+qualifier+':`%s <%s>`' % (name, real_name) col2 = title append_row(col1, col2) @@ -240,7 +232,7 @@ def import_by_name(name, prefixes=[None]): The imported object name Name of the imported object (useful if `prefixes` was used) - + """ for prefix in prefixes: try: @@ -254,9 +246,18 @@ def import_by_name(name, prefixes=[None]): raise ImportError def _import_by_name(name): - """Import a Python object given its full name""" + """Import a Python object given its full name.""" try: + # try first interpret `name` as MODNAME.OBJ name_parts = name.split('.') + try: + modname = '.'.join(name_parts[:-1]) + __import__(modname) + return getattr(sys.modules[modname], name_parts[-1]) + except (ImportError, IndexError, AttributeError): + pass + + # ... then as MODNAME, MODNAME.OBJ1, MODNAME.OBJ1.OBJ2, ... last_j = 0 modname = None for j in reversed(range(1, len(name_parts)+1)): @@ -279,20 +280,19 @@ def _import_by_name(name): except (ValueError, ImportError, AttributeError, KeyError), e: raise ImportError(e) -#------------------------------------------------------------------------------ -# :autolink: (smart default role) -#------------------------------------------------------------------------------ + +# -- :autolink: (smart default role) ------------------------------------------- def autolink_role(typ, rawtext, etext, lineno, inliner, options={}, content=[]): """ Smart linking role. - Expands to ":obj:`text`" if `text` is an object that can be imported; - otherwise expands to "*text*". + Expands to ':obj:`text`' if `text` is an object that can be imported; + otherwise expands to '*text*'. """ - r = sphinx.roles.xfileref_role('obj', rawtext, etext, lineno, inliner, - options, content) + r = roles.xfileref_role('obj', rawtext, etext, lineno, inliner, + options, content) pnode = r[0][0] prefixes = [None] @@ -304,3 +304,15 @@ def autolink_role(typ, rawtext, etext, lineno, inliner, r[0][0] = nodes.emphasis(rawtext, content[0].astext(), classes=content['classes']) return r + + +def setup(app): + app.add_directive('autosummary', autosummary_directive, True, (0, 0, False), + toctree=directives.unchanged, + nosignatures=directives.flag) + app.add_role('autolink', autolink_role) + + app.add_node(autosummary_toc, + html=(autosummary_toc_visit_html, autosummary_toc_depart_noop), + latex=(autosummary_toc_visit_latex, autosummary_toc_depart_noop)) + app.connect('doctree-read', process_autosummary_toc) diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index ce9e4c2d..178a2870 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -1,85 +1,91 @@ +# -*- coding: utf-8 -*- """ -autosummary_generate.py OPTIONS FILES + sphinx.ext.autosummary.generate + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Generate automatic RST source files for items referred to in -autosummary:: directives. + Usable as a library or script to generate automatic RST source files for + items referred to in autosummary:: directives. -Each generated RST file contains a single auto*:: directive which -extracts the docstring of the referred item. + Each generated RST file contains a single auto*:: directive which + extracts the docstring of the referred item. -Example Makefile rule:: + Example Makefile rule:: - generate: - sphinx-autogen source/*.rst source/generated + generate: + sphinx-autogen source/*.rst source/generated + :copyright: Copyright 2007-2009 by the Sphinx team, see AUTHORS. + :license: BSD, see LICENSE for details. """ -import glob, re, inspect, os, optparse +import os +import re +import sys +import glob +import inspect + +from jinja2 import Environment, PackageLoader + from sphinx.ext.autosummary import import_by_name +from sphinx.util import ensuredir -from jinja import Environment, PackageLoader -env = Environment(loader=PackageLoader('sphinx.ext.autosummary', 'templates')) +# create our own templating environment, for module template only +env = Environment(loader=PackageLoader('sphinx.ext.autosummary', 'templates')) -def main(): - p = optparse.OptionParser(__doc__.strip()) - options, args = p.parse_args() - - if len(args) <2: - p.error("wrong number of arguments") - print 'generating docs from:', args[:-1] - generate_autosummary_docs(args[:-1], args[-1]) - -def generate_autosummary_docs(source_dir, output_dir): +def generate_autosummary_docs(sources, output_dir=None): # read names = {} - for name, loc in get_documented(source_dir).items(): + for name, loc in get_documented(sources).items(): for (filename, sec_title, keyword, toctree) in loc: if toctree is not None: path = os.path.join(os.path.dirname(filename), toctree) names[name] = os.path.abspath(path) - + # write for name, path in sorted(names.items()): - path = output_dir - - if not os.path.isdir(path): - os.makedirs(path) + if output_dir is not None: + path = output_dir + + ensuredir(path) try: obj, name = import_by_name(name) except ImportError, e: - print "Failed to import '%s': %s" % (name, e) + print >>sys.stderr, 'Failed to import %r: %s' % (name, e) continue fn = os.path.join(path, '%s.rst' % name) - - if os.path.exists(fn): - # skip + # skip it if it exists + if os.path.isfile(fn): continue f = open(fn, 'w') - try: - if inspect.ismodule(obj): - tmpl = env.get_template('module.html') - functions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isfunction(getattr(obj, item))] - classes = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and not issubclass(getattr(obj, item), Exception)] - exceptions = [getattr(obj, item).__name__ for item in dir(obj) if inspect.isclass(getattr(obj, item)) and issubclass(getattr(obj, item), Exception)] - rendered = tmpl.render(name=name, - functions=functions, - classes=classes, - exceptions=exceptions, + tmpl = env.get_template('module') + functions = [getattr(obj, item).__name__ + for item in dir(obj) + if inspect.isfunction(getattr(obj, item))] + classes = [getattr(obj, item).__name__ + for item in dir(obj) + if inspect.isclass(getattr(obj, item)) + and not issubclass(getattr(obj, item), Exception)] + exceptions = [getattr(obj, item).__name__ + for item in dir(obj) + if inspect.isclass(getattr(obj, item)) + and issubclass(getattr(obj, item), Exception)] + rendered = tmpl.render(name=name, + functions=functions, + classes=classes, + exceptions=exceptions, len_functions=len(functions), len_classes=len(classes), - len_exceptions=len(exceptions) - - ) + len_exceptions=len(exceptions)) f.write(rendered) else: f.write('%s\n%s\n\n' % (name, '='*len(name))) - + if inspect.isclass(obj): if issubclass(obj, Exception): f.write(format_modulemember(name, 'autoexception')) @@ -96,40 +102,40 @@ def generate_autosummary_docs(source_dir, output_dir): finally: f.close() + def format_modulemember(name, directive): parts = name.split('.') mod, name = '.'.join(parts[:-1]), parts[-1] - return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) + return '.. currentmodule:: %s\n\n.. %s:: %s\n' % (mod, directive, name) + def format_classmember(name, directive): parts = name.split('.') mod, name = '.'.join(parts[:-2]), '.'.join(parts[-2:]) - return ".. currentmodule:: %s\n\n.. %s:: %s\n" % (mod, directive, name) + return '.. currentmodule:: %s\n\n.. %s:: %s\n' % (mod, directive, name) + + +title_underline_re = re.compile('^[-=*_^#]{3,}\s*$') +autodoc_re = re.compile(r'.. auto(function|method|attribute|class|exception' + '|module)::\s*([A-Za-z0-9_.]+)\s*$') +autosummary_re = re.compile(r'^\.\.\s+autosummary::\s*') +module_re = re.compile(r'^\.\.\s+(current)?module::\s*([a-zA-Z0-9_.]+)\s*$') +autosummary_item_re = re.compile(r'^\s+([_a-zA-Z][a-zA-Z0-9_.]*)\s*') +toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') def get_documented(filenames): """ - Find out what items are documented in source/*.rst - - Returns - ------- - documented : dict of list of (filename, title, keyword, toctree) - Dictionary whose keys are documented names of objects. - The value is a list of locations where the object was documented. - Each location is a tuple of filename, the current section title, - the name of the directive, and the value of the :toctree: argument - (if present) of the directive. + Find out what items are documented in the given filenames. + Returns a dict of list of (filename, title, keyword, toctree) Keys are + documented names of objects. The value is a list of locations where the + object was documented. Each location is a tuple of filename, the current + section title, the name of the directive, and the value of the :toctree: + argument (if present) of the directive. """ - - title_underline_re = re.compile("^[-=*_^#]{3,}\s*$") - autodoc_re = re.compile(".. auto(function|method|attribute|class|exception|module)::\s*([A-Za-z0-9_.]+)\s*$") - autosummary_re = re.compile(r'^\.\.\s+autosummary::\s*') - module_re = re.compile(r'^\.\.\s+(current)?module::\s*([a-zA-Z0-9_.]+)\s*$') - autosummary_item_re = re.compile(r'^\s+([_a-zA-Z][a-zA-Z0-9_.]*)\s*') - toctree_arg_re = re.compile(r'^\s+:toctree:\s*(.*?)\s*$') - + documented = {} - + for filename in filenames: current_title = [] last_line = None @@ -150,32 +156,34 @@ def get_documented(filenames): continue # skip options m = autosummary_item_re.match(line) - + if m: name = m.group(1).strip() - if current_module and not name.startswith(current_module + '.'): - name = "%s.%s" % (current_module, name) + if current_module and \ + not name.startswith(current_module + '.'): + name = '%s.%s' % (current_module, name) documented.setdefault(name, []).append( (filename, current_title, 'autosummary', toctree)) continue if line.strip() == '': continue in_autosummary = False - + m = autosummary_re.match(line) if m: in_autosummary = True continue - + m = autodoc_re.search(line) if m: name = m.group(2).strip() - if current_module and not name.startswith(current_module + '.'): - name = "%s.%s" % (current_module, name) - if m.group(1) == "module": + if current_module and \ + not name.startswith(current_module + '.'): + name = '%s.%s' % (current_module, name) + if m.group(1) == 'module': current_module = name documented.setdefault(name, []).append( - (filename, current_title, "auto" + m.group(1), None)) + (filename, current_title, 'auto' + m.group(1), None)) continue m = title_underline_re.match(line) @@ -191,5 +199,17 @@ def get_documented(filenames): last_line = line return documented -if __name__ == "__main__": + +def main(args=None): + if args is None: + args = sys.argv[1:] + + if len(args) < 2: + print >>sys.stderr, 'usage: %s sourcefile ... outputdir' % sys.argv[0] + + print 'generating docs from:', ', '.join(args[:-1]) + generate_autosummary_docs(args[:-1], args[-1]) + + +if __name__ == '__main__': main() diff --git a/sphinx/ext/autosummary/templates/module b/sphinx/ext/autosummary/templates/module new file mode 100644 index 00000000..34dd8100 --- /dev/null +++ b/sphinx/ext/autosummary/templates/module @@ -0,0 +1,39 @@ +:mod:`{{name}}` +=============================================================================================================================================== + + +.. automodule:: {{name}} + +{% if len_functions > 0 %} +Functions +---------- +{% for item in functions %} +.. autofunction:: {{item}} +{% endfor %} +{% endif %} + +{% if len_classes > 0 %} +Classes +-------- +{% for item in classes %} +.. autoclass:: {{item}} + :show-inheritance: + :members: + :inherited-members: + :undoc-members: + +{% endfor %} +{% endif %} + +{% if len_exceptions > 0 %} +Exceptions +------------ +{% for item in exceptions %} +.. autoclass:: {{item}} + :show-inheritance: + :members: + :inherited-members: + :undoc-members: + +{% endfor %} +{% endif %} \ No newline at end of file diff --git a/sphinx/ext/autosummary/templates/module.html b/sphinx/ext/autosummary/templates/module.html deleted file mode 100644 index 34dd8100..00000000 --- a/sphinx/ext/autosummary/templates/module.html +++ /dev/null @@ -1,39 +0,0 @@ -:mod:`{{name}}` -=============================================================================================================================================== - - -.. automodule:: {{name}} - -{% if len_functions > 0 %} -Functions ----------- -{% for item in functions %} -.. autofunction:: {{item}} -{% endfor %} -{% endif %} - -{% if len_classes > 0 %} -Classes --------- -{% for item in classes %} -.. autoclass:: {{item}} - :show-inheritance: - :members: - :inherited-members: - :undoc-members: - -{% endfor %} -{% endif %} - -{% if len_exceptions > 0 %} -Exceptions ------------- -{% for item in exceptions %} -.. autoclass:: {{item}} - :show-inheritance: - :members: - :inherited-members: - :undoc-members: - -{% endfor %} -{% endif %} \ No newline at end of file -- cgit v1.2.1 From 9d1d3c7b014f1078c2d952626c4d596d12c1d07b Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sat, 14 Mar 2009 21:16:20 +0100 Subject: Remove extra autosummary license since Sphinx now uses 2-clause BSD as well. --- AUTHORS | 4 +++- sphinx/ext/autosummary/LICENSE.txt | 31 ------------------------------- 2 files changed, 3 insertions(+), 32 deletions(-) delete mode 100644 sphinx/ext/autosummary/LICENSE.txt diff --git a/AUTHORS b/AUTHORS index 73ec5ed2..259c0949 100644 --- a/AUTHORS +++ b/AUTHORS @@ -14,10 +14,12 @@ Other contributors, listed alphabetically, are: * Dave Kuhlman -- original LaTeX writer * Thomas Lamb -- linkcheck builder * Will Maier -- directory HTML builder +* Christopher Perkins -- autosummary integration * Benjamin Peterson -- unittests * Stefan Seefeld -- toctree improvements * Antonio Valentino -- qthelp builder -* Pauli Virtanen -- autodoc improvements +* Pauli Virtanen -- autodoc improvements, autosummary extension +* Stefan van der Walt -- autosummary extension * Sebastian Wiesner -- image handling, distutils support Many thanks for all contributions! diff --git a/sphinx/ext/autosummary/LICENSE.txt b/sphinx/ext/autosummary/LICENSE.txt deleted file mode 100644 index aa1bf333..00000000 --- a/sphinx/ext/autosummary/LICENSE.txt +++ /dev/null @@ -1,31 +0,0 @@ - The files - - __init__.py - - generate.py - - templates/module.html - - have the following license: - -Copyright (C) 2008 Stefan van der Walt , Pauli Virtanen , Christopher Perkins - -Redistribution and use in source and binary forms, with or without -modification, are permitted provided that the following conditions are -met: - - 1. Redistributions of source code must retain the above copyright - notice, this list of conditions and the following disclaimer. - 2. Redistributions in binary form must reproduce the above copyright - notice, this list of conditions and the following disclaimer in - the documentation and/or other materials provided with the - distribution. - -THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR -IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED -WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE -DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, -INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES -(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR -SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) -HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, -STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING -IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE -POSSIBILITY OF SUCH DAMAGE. -- cgit v1.2.1 From 0756f1fc6cb5d8c9291ca62c8c0809bff962b5cc Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sat, 14 Mar 2009 21:34:59 +0100 Subject: Document setup_extension(). --- doc/ext/appapi.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst index fba1d945..6864d6ba 100644 --- a/doc/ext/appapi.rst +++ b/doc/ext/appapi.rst @@ -10,6 +10,11 @@ This function is called at initialization time with one argument, the application object representing the Sphinx process. This application object has the following public API: +.. method:: Sphinx.setup_extension(name) + + Load the extension given by the module *name*. Use this if your extension + needs the features provided by another extension. + .. method:: Sphinx.add_builder(builder) Register a new builder. *builder* must be a class that inherits from -- cgit v1.2.1 From b00608241e1406c19d572c43b70d3018274274ff Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sun, 15 Mar 2009 18:36:00 +0100 Subject: Work on autodoc: move -g command-line argument to config value, make directive up to new API. --- sphinx/application.py | 6 +- sphinx/cmdline.py | 14 --- sphinx/ext/autosummary/__init__.py | 148 +++++++++++++++++--------------- sphinx/ext/autosummary/generate.py | 46 +++++++--- sphinx/ext/autosummary/templates/module | 4 +- 5 files changed, 115 insertions(+), 103 deletions(-) diff --git a/sphinx/application.py b/sphinx/application.py index 9c467066..e8e9fad6 100644 --- a/sphinx/application.py +++ b/sphinx/application.py @@ -82,6 +82,9 @@ class Sphinx(object): self._events = events.copy() + # say hello to the world + self.info(bold('Running Sphinx v%s' % sphinx.__released__)) + # status code for command-line application self.statuscode = 0 @@ -105,9 +108,6 @@ class Sphinx(object): if buildername not in self.builderclasses: raise SphinxError('Builder name %s not registered' % buildername) - self.info(bold('Sphinx v%s, building %s' % (sphinx.__released__, - buildername))) - builderclass = self.builderclasses[buildername] if isinstance(builderclass, tuple): # builtin builder diff --git a/sphinx/cmdline.py b/sphinx/cmdline.py index 79bd9751..813661bb 100644 --- a/sphinx/cmdline.py +++ b/sphinx/cmdline.py @@ -43,8 +43,6 @@ new and changed files -C -- use no config file at all, only -D options -D -- override a setting in configuration -A -- pass a value into the templates, for HTML builder - -g -- auto-generate docs with sphinx.ext.autosummary - for autosummary directives in sources found in path -N -- do not do colored output -q -- no output on stdout, just warnings on stderr -Q -- no output at all, not even warnings @@ -145,18 +143,6 @@ def main(argv): except ValueError: pass htmlcontext[key] = val - elif opt == '-g': - # XXX XXX XXX - source_filenames = [path.join(srcdir, f) - for f in os.listdir(srcdir) if f.endswith('.rst')] - if val is None: - print >>sys.stderr, \ - 'Error: you must provide a destination directory ' \ - 'for autodoc generation.' - return 1 - p = path.abspath(val) - from sphinx.ext.autosummary.generate import generate_autosummary_docs - generate_autosummary_docs(source_filenames, p) elif opt == '-N': nocolor() elif opt == '-E': diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 8775fe86..4fe64dd0 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -58,6 +58,7 @@ import re import sys import inspect import posixpath +from os import path from docutils.parsers.rst import directives from docutils.statemachine import ViewList @@ -65,6 +66,7 @@ from docutils import nodes from sphinx import addnodes, roles from sphinx.util import patfilter +from sphinx.util.compat import Directive # -- autosummary_toc node ------------------------------------------------------ @@ -103,70 +105,75 @@ def autosummary_toc_visit_latex(self, node): """Show autosummary toctree (= put the referenced pages here) in Latex.""" pass -def autosummary_toc_depart_noop(self, node): +def autosummary_noop(self, node): pass # -- .. autosummary:: ---------------------------------------------------------- -def autosummary_directive(dirname, arguments, options, content, lineno, - content_offset, block_text, state, state_machine): +class Autosummary(Directive): """ Pretty table containing short signatures and summaries of functions etc. autosummary also generates a (hidden) toctree:: node. - """ - names = [] - names += [x.strip() for x in content if x.strip()] - - table, warnings, real_names = get_autosummary(names, state, - 'nosignatures' in options) - node = table - - env = state.document.settings.env - suffix = env.config.source_suffix - all_docnames = env.found_docs.copy() - dirname = posixpath.dirname(env.docname) - - if 'toctree' in options: - tree_prefix = options['toctree'].strip() - docnames = [] - for name in names: - name = real_names.get(name, name) - - docname = tree_prefix + name - if docname.endswith(suffix): - docname = docname[:-len(suffix)] - docname = posixpath.normpath(posixpath.join(dirname, docname)) - if docname not in env.found_docs: - warnings.append(state.document.reporter.warning( - 'toctree references unknown document %r' % docname, - line=lineno)) - docnames.append(docname) - - tocnode = addnodes.toctree() - tocnode['includefiles'] = docnames - tocnode['maxdepth'] = -1 - tocnode['glob'] = None - - tocnode = autosummary_toc('', '', tocnode) - return warnings + [node] + [tocnode] - else: - return warnings + [node] + required_arguments = 0 + optional_arguments = 0 + final_argument_whitespace = False + has_content = True + option_spec = { + 'toctree': directives.unchanged, + 'nosignatures': directives.flag, + } + + def run(self): + names = [] + names += [x.strip() for x in self.content if x.strip()] + + table, warnings, real_names = get_autosummary( + names, self.state, 'nosignatures' in self.options) + node = table + + env = self.state.document.settings.env + suffix = env.config.source_suffix + all_docnames = env.found_docs.copy() + dirname = posixpath.dirname(env.docname) + + if 'toctree' in self.options: + tree_prefix = self.options['toctree'].strip() + docnames = [] + for name in names: + name = real_names.get(name, name) + + docname = posixpath.join(tree_prefix, name) + if docname.endswith(suffix): + docname = docname[:-len(suffix)] + docname = posixpath.normpath(posixpath.join(dirname, docname)) + if docname not in env.found_docs: + warnings.append(self.state.document.reporter.warning( + 'toctree references unknown document %r' % docname, + line=self.lineno)) + docnames.append(docname) + + tocnode = addnodes.toctree() + tocnode['includefiles'] = docnames + tocnode['entries'] = [(None, docname) for docname in docnames] + tocnode['maxdepth'] = -1 + tocnode['glob'] = None + + tocnode = autosummary_toc('', '', tocnode) + return warnings + [node] + [tocnode] + else: + return warnings + [node] def get_autosummary(names, state, no_signatures=False): """ Generate a proper table node for autosummary:: directive. - Parameters - ---------- - names : list of str - Names of Python objects to be imported and added to the table. - document : document - Docutils document object + *names* is a list of names of Python objects to be imported and added to the + table. *document* is the Docutils document object. """ document = state.document @@ -216,23 +223,8 @@ def get_autosummary(names, state, no_signatures=False): def import_by_name(name, prefixes=[None]): """ - Import a Python object that has the given name, under one of the prefixes. - - Parameters - ---------- - name : str - Name of a Python object, eg. 'numpy.ndarray.view' - prefixes : list of (str or None), optional - Prefixes to prepend to the name (None implies no prefix). - The first prefixed name that results to successful import is used. - - Returns - ------- - obj - The imported object - name - Name of the imported object (useful if `prefixes` was used) - + Import a Python object that has the given *name*, under one of the + *prefixes*. The first name that succeeds is used. """ for prefix in prefixes: try: @@ -306,13 +298,27 @@ def autolink_role(typ, rawtext, etext, lineno, inliner, return r -def setup(app): - app.add_directive('autosummary', autosummary_directive, True, (0, 0, False), - toctree=directives.unchanged, - nosignatures=directives.flag) - app.add_role('autolink', autolink_role) +def process_generate_options(app): + genfiles = app.config.autosummary_generate + if not genfiles: + return + from sphinx.ext.autosummary.generate import generate_autosummary_docs + ext = app.config.source_suffix + genfiles = [path.join(app.srcdir, genfile + + (not genfile.endswith(ext) and ext or '')) + for genfile in genfiles] + generate_autosummary_docs(genfiles, warn=app.warn, info=app.info) + + +def setup(app): + # I need autodoc + app.setup_extension('sphinx.ext.autodoc') app.add_node(autosummary_toc, - html=(autosummary_toc_visit_html, autosummary_toc_depart_noop), - latex=(autosummary_toc_visit_latex, autosummary_toc_depart_noop)) + html=(autosummary_toc_visit_html, autosummary_noop), + latex=(autosummary_toc_visit_latex, autosummary_noop)) + app.add_directive('autosummary', Autosummary) + app.add_role('autolink', autolink_role) app.connect('doctree-read', process_autosummary_toc) + app.connect('builder-inited', process_generate_options) + app.add_config_value('autosummary_generate', [], True) diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py index 178a2870..b4c2482c 100644 --- a/sphinx/ext/autosummary/generate.py +++ b/sphinx/ext/autosummary/generate.py @@ -20,7 +20,7 @@ import os import re import sys -import glob +import getopt import inspect from jinja2 import Environment, PackageLoader @@ -32,7 +32,17 @@ from sphinx.util import ensuredir env = Environment(loader=PackageLoader('sphinx.ext.autosummary', 'templates')) -def generate_autosummary_docs(sources, output_dir=None): +def _simple_info(msg): + print msg + +def _simple_warn(msg): + print >>sys.stderr, 'WARNING: ' + msg + +def generate_autosummary_docs(sources, output_dir=None, + warn=_simple_warn, info=_simple_info): + info('generating autosummary for: %s' % ', '.join(sources)) + if output_dir: + info('writing to %s' % output_dir) # read names = {} for name, loc in get_documented(sources).items(): @@ -43,15 +53,13 @@ def generate_autosummary_docs(sources, output_dir=None): # write for name, path in sorted(names.items()): - if output_dir is not None: - path = output_dir - + path = output_dir or path ensuredir(path) try: obj, name = import_by_name(name) except ImportError, e: - print >>sys.stderr, 'Failed to import %r: %s' % (name, e) + warn('failed to import %r: %s' % (name, e)) continue fn = os.path.join(path, '%s.rst' % name) @@ -63,6 +71,7 @@ def generate_autosummary_docs(sources, output_dir=None): try: if inspect.ismodule(obj): + # XXX replace this with autodoc's API? tmpl = env.get_template('module') functions = [getattr(obj, item).__name__ for item in dir(obj) @@ -76,6 +85,7 @@ def generate_autosummary_docs(sources, output_dir=None): if inspect.isclass(getattr(obj, item)) and issubclass(getattr(obj, item), Exception)] rendered = tmpl.render(name=name, + underline='='*len(name), functions=functions, classes=classes, exceptions=exceptions, @@ -177,6 +187,7 @@ def get_documented(filenames): m = autodoc_re.search(line) if m: name = m.group(2).strip() + # XXX look in newer generate.py if current_module and \ not name.startswith(current_module + '.'): name = '%s.%s' % (current_module, name) @@ -200,15 +211,24 @@ def get_documented(filenames): return documented -def main(args=None): - if args is None: - args = sys.argv[1:] +def main(argv): + usage = 'usage: %s [-o output_dir] sourcefile ...' % sys.argv[0] + try: + opts, args = getopt.getopt(argv[1:], 'o:') + except getopt.error: + print >>sys.stderr, usage + return 1 + + output_dir = None + for opt, val in opts: + if opt == '-o': + output_dir = val - if len(args) < 2: - print >>sys.stderr, 'usage: %s sourcefile ... outputdir' % sys.argv[0] + if len(args) < 1: + print >>sys.stderr, usage + return 1 - print 'generating docs from:', ', '.join(args[:-1]) - generate_autosummary_docs(args[:-1], args[-1]) + generate_autosummary_docs(args, output_dir) if __name__ == '__main__': diff --git a/sphinx/ext/autosummary/templates/module b/sphinx/ext/autosummary/templates/module index 34dd8100..0cbc8266 100644 --- a/sphinx/ext/autosummary/templates/module +++ b/sphinx/ext/autosummary/templates/module @@ -1,5 +1,5 @@ :mod:`{{name}}` -=============================================================================================================================================== +======{{ underline }}= .. automodule:: {{name}} @@ -36,4 +36,4 @@ Exceptions :undoc-members: {% endfor %} -{% endif %} \ No newline at end of file +{% endif %} -- cgit v1.2.1 From 227fcafb65129ee5565cd932b29de5a667f41f01 Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sun, 15 Mar 2009 18:42:56 +0100 Subject: Improve ImportError message. --- sphinx/ext/autosummary/__init__.py | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 4fe64dd0..01160cd6 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -226,6 +226,7 @@ def import_by_name(name, prefixes=[None]): Import a Python object that has the given *name*, under one of the *prefixes*. The first name that succeeds is used. """ + tried = [] for prefix in prefixes: try: if prefix: @@ -234,8 +235,8 @@ def import_by_name(name, prefixes=[None]): prefixed_name = name return _import_by_name(prefixed_name), prefixed_name except ImportError: - pass - raise ImportError + tried.append(prefixed_name) + raise ImportError('no module named %s' % ' or '.join(tried)) def _import_by_name(name): """Import a Python object given its full name.""" @@ -270,7 +271,7 @@ def _import_by_name(name): else: return sys.modules[modname] except (ValueError, ImportError, AttributeError, KeyError), e: - raise ImportError(e) + raise ImportError(*e.args) # -- :autolink: (smart default role) ------------------------------------------- -- cgit v1.2.1 From b2013b7124bb47a02e3021a92767741b6805107f Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sun, 15 Mar 2009 19:02:37 +0100 Subject: Add autosummary to tests. --- tests/root/autosummary.txt | 5 +++++ tests/root/conf.py | 5 ++++- tests/root/contents.txt | 1 + 3 files changed, 10 insertions(+), 1 deletion(-) create mode 100644 tests/root/autosummary.txt diff --git a/tests/root/autosummary.txt b/tests/root/autosummary.txt new file mode 100644 index 00000000..d05dffec --- /dev/null +++ b/tests/root/autosummary.txt @@ -0,0 +1,5 @@ +Autosummary test +================ + +.. autosummary:: sphinx.application + :toctree: xyz diff --git a/tests/root/conf.py b/tests/root/conf.py index 85e9f468..fd82be7d 100644 --- a/tests/root/conf.py +++ b/tests/root/conf.py @@ -5,7 +5,8 @@ import sys, os sys.path.append(os.path.abspath('.')) extensions = ['ext', 'sphinx.ext.autodoc', 'sphinx.ext.jsmath', - 'sphinx.ext.coverage', 'sphinx.ext.todo'] + 'sphinx.ext.coverage', 'sphinx.ext.todo', + 'sphinx.ext.autosummary'] jsmath_path = 'dummy.js' @@ -50,6 +51,8 @@ value_from_conf_py = 84 coverage_c_path = ['special/*.h'] coverage_c_regexes = {'cfunction': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'} +autosummary_generate = ['autosummary'] + # modify tags from conf.py tags.add('confpytag') diff --git a/tests/root/contents.txt b/tests/root/contents.txt index 0e52593e..24d790a5 100644 --- a/tests/root/contents.txt +++ b/tests/root/contents.txt @@ -19,6 +19,7 @@ Contents: desc math autodoc + autosummary Python -- cgit v1.2.1 From 558af5109a10a5351a45e810bfe3b84285bb1b4a Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sun, 15 Mar 2009 19:04:02 +0100 Subject: Fix test_env after update() API change. --- tests/test_env.py | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/tests/test_env.py b/tests/test_env.py index 0b944c50..a06656d6 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -37,8 +37,7 @@ def warning_emitted(file, text): # afford to not run update() in the setup but in its own test def test_first_update(): - it = env.update(app.config, app.srcdir, app.doctreedir, app) - msg = it.next() + msg, num, it = env.update(app.config, app.srcdir, app.doctreedir, app) assert msg.endswith('%d added, 0 changed, 0 removed' % len(env.found_docs)) docnames = set() for docname in it: # the generator does all the work @@ -80,8 +79,7 @@ def test_second_update(): # the contents.txt toctree; otherwise section numbers would shift (root / 'autodoc.txt').unlink() (root / 'new.txt').write_text('New file\n========\n') - it = env.update(app.config, app.srcdir, app.doctreedir, app) - msg = it.next() + msg, num, it = env.update(app.config, app.srcdir, app.doctreedir, app) assert '1 added, 3 changed, 1 removed' in msg docnames = set() for docname in it: -- cgit v1.2.1 From 0da45a6b8fb1ca6d6df260c11d6a734ac306ab9c Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sun, 15 Mar 2009 19:06:57 +0100 Subject: Fix attribute reference error. --- sphinx/builders/latex.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx/builders/latex.py b/sphinx/builders/latex.py index 96d70e3e..bc2f1ba5 100644 --- a/sphinx/builders/latex.py +++ b/sphinx/builders/latex.py @@ -123,7 +123,7 @@ class LaTeXBuilder(Builder): except Exception: self.warn('toctree contains ref to nonexisting ' 'file %r' % includefile, - self.builder.env.doc2path(docname)) + self.env.doc2path(docname)) else: sof = addnodes.start_of_file(docname=includefile) sof.children = subtree.children -- cgit v1.2.1 From d1c289ca4035464bb97de15d5251f940febf9d10 Mon Sep 17 00:00:00 2001 From: gbrandl Date: Sun, 15 Mar 2009 19:55:48 +0100 Subject: Fix test. --- sphinx/ext/autosummary/__init__.py | 3 ++- tests/root/autosummary.txt | 6 ++++-- 2 files changed, 6 insertions(+), 3 deletions(-) diff --git a/sphinx/ext/autosummary/__init__.py b/sphinx/ext/autosummary/__init__.py index 01160cd6..8fdeefe7 100644 --- a/sphinx/ext/autosummary/__init__.py +++ b/sphinx/ext/autosummary/__init__.py @@ -317,7 +317,8 @@ def setup(app): app.setup_extension('sphinx.ext.autodoc') app.add_node(autosummary_toc, html=(autosummary_toc_visit_html, autosummary_noop), - latex=(autosummary_toc_visit_latex, autosummary_noop)) + latex=(autosummary_toc_visit_latex, autosummary_noop), + text=(autosummary_noop, autosummary_noop)) app.add_directive('autosummary', Autosummary) app.add_role('autolink', autolink_role) app.connect('doctree-read', process_autosummary_toc) diff --git a/tests/root/autosummary.txt b/tests/root/autosummary.txt index d05dffec..e4b75167 100644 --- a/tests/root/autosummary.txt +++ b/tests/root/autosummary.txt @@ -1,5 +1,7 @@ Autosummary test ================ -.. autosummary:: sphinx.application - :toctree: xyz +.. autosummary:: + :toctree: generated + + sphinx.application -- cgit v1.2.1 From a72d904ded8d922732728d97f212b7820f03f5f1 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 15 Mar 2009 23:29:10 +0100 Subject: Note ``autosummary`` extension. --- CHANGES | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGES b/CHANGES index cd0c82fb..a632759d 100644 --- a/CHANGES +++ b/CHANGES @@ -145,6 +145,9 @@ New features added - New ``inheritance_diagram`` extension to embed... inheritance diagrams! + - New ``autosummary`` extension that generates summaries of + modules and automatic documentation of modules. + - Autodoc now has a reusable Python API, which can be used to create custom types of objects to auto-document (e.g. Zope interfaces). See also ``Sphinx.add_autodocumenter()``. -- cgit v1.2.1 From 38b67d02693c8ca897ee22a8b68c7413365b3ace Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 15 Mar 2009 23:34:19 +0100 Subject: #123: The ``glossary`` directive now supports a ``:sorted:`` flag that sorts glossary entries alphabetically. --- CHANGES | 3 +++ doc/markup/para.rst | 16 ++++++++++------ sphinx/directives/other.py | 13 +++++++++++-- 3 files changed, 24 insertions(+), 8 deletions(-) diff --git a/CHANGES b/CHANGES index a632759d..74838c61 100644 --- a/CHANGES +++ b/CHANGES @@ -55,6 +55,9 @@ New features added the directive -- this allows you to define your document structure, but place the links yourself. + - #123: The ``glossary`` directive now supports a ``:sorted:`` + flag that sorts glossary entries alphabetically. + - Paths to images, literal include files and download files can now be absolute (like ``/images/foo.png``). They are treated as relative to the top source directory. diff --git a/doc/markup/para.rst b/doc/markup/para.rst index 2ea2fd2d..e8adc75c 100644 --- a/doc/markup/para.rst +++ b/doc/markup/para.rst @@ -203,14 +203,18 @@ Glossary .. glossary:: environment - A structure where information about all documents under the root is saved, - and used for cross-referencing. The environment is pickled after the - parsing stage, so that successive runs only need to read and parse new and - changed documents. + A structure where information about all documents under the root is + saved, and used for cross-referencing. The environment is pickled + after the parsing stage, so that successive runs only need to read + and parse new and changed documents. source directory - The directory which, including its subdirectories, contains all source - files for one Sphinx project. + The directory which, including its subdirectories, contains all + source files for one Sphinx project. + + .. versionadded:: 0.6 + You can now give the glossary directive a ``:sorted:`` flag that will + automatically sort the entries alphabetically. Grammar production displays diff --git a/sphinx/directives/other.py b/sphinx/directives/other.py index bc9a54df..80c88f5f 100644 --- a/sphinx/directives/other.py +++ b/sphinx/directives/other.py @@ -414,7 +414,9 @@ class Glossary(Directive): required_arguments = 0 optional_arguments = 0 final_argument_whitespace = False - option_spec = {} + option_spec = { + 'sorted': directives.flag, + } def run(self): env = self.state.document.settings.env @@ -426,8 +428,10 @@ class Glossary(Directive): dls = [child for child in node if isinstance(child, nodes.definition_list)] # now, extract definition terms to enable cross-reference creation + new_dl = nodes.definition_list() + new_dl['classes'].append('glossary') + items = [] for dl in dls: - dl['classes'].append('glossary') for li in dl.children: if not li.children or not isinstance(li[0], nodes.term): continue @@ -443,6 +447,11 @@ class Glossary(Directive): indexnode = addnodes.index() indexnode['entries'] = [('single', termtext, new_id, termtext)] li.insert(0, indexnode) + items.append((termtext, li)) + if 'sorted' in self.options: + items.sort() + new_dl.extend(item[1] for item in items) + node.children = [new_dl] return [node] -- cgit v1.2.1 From 223e814b263cb415899408d48d231f6c62e01a02 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 15 Mar 2009 23:43:09 +0100 Subject: Add link to Glenn's SCons script repo. --- doc/faq.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/faq.rst b/doc/faq.rst index ae12cdad..723601f1 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -26,5 +26,9 @@ How do I... There's a third-party extension providing an `api role`_ which refers to Epydoc's API docs for a given identifier. +... use Sphinx with SCons? + Glenn Hutchings has written a SCons build script to build Sphinx + documentation; it is hosted here: http://bitbucket.org/zondo/sphinx-scons + .. _api role: http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py -- cgit v1.2.1 From def22820159c63af6f604a1554d05a5575356c9b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 15 Mar 2009 23:52:48 +0100 Subject: Autodoc can now exclude single members from documentation via the ``exclude-members`` option. --- CHANGES | 3 +++ doc/ext/autodoc.rst | 6 ++++++ sphinx/ext/autodoc.py | 14 +++++++++++++- tests/test_autodoc.py | 6 +++++- 4 files changed, 27 insertions(+), 2 deletions(-) diff --git a/CHANGES b/CHANGES index 74838c61..e15d5280 100644 --- a/CHANGES +++ b/CHANGES @@ -162,6 +162,9 @@ New features added - Autodoc can document classes as functions now if explicitly marked with `autofunction`. + - Autodoc can now exclude single members from documentation + via the ``exclude-members`` option. + - Autodoc can now order members either alphabetically (like previously) or by member type; configurable either with the config value ``autodoc_member_order`` or a ``member-order`` diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst index 17a2766b..ff8d189d 100644 --- a/doc/ext/autodoc.rst +++ b/doc/ext/autodoc.rst @@ -141,6 +141,12 @@ directive. .. versionadded:: 0.6 + * The directives supporting member documentation also have a + ``exclude-members`` option that can be used to exclude single member names + from documentation, if all members are to be documented. + + .. versionadded:: 0.6 + .. note:: In an :dir:`automodule` directive with the ``members`` option set, only diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 43c4b26a..5c1a0653 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -79,6 +79,12 @@ def members_option(arg): return ALL return [x.strip() for x in arg.split(',')] +def members_set_option(arg): + """Used to convert the :members: option to auto directives.""" + if arg is None: + return ALL + return set(x.strip() for x in arg.split(',')) + def bool_option(arg): """Used to convert flag options to auto directives. (Instead of directives.flag(), which returns None.)""" @@ -549,6 +555,11 @@ class Documenter(object): # find out which members are documentable members_check_module, members = self.get_object_members(want_all) + # remove members given by exclude-members + if self.options.exclude_members: + members = [(membername, member) for (membername, member) in members + if membername not in self.options.exclude_members] + # document non-skipped members memberdocumenters = [] for (mname, member, isattr) in self.filter_members(members, want_all): @@ -666,7 +677,7 @@ class ModuleDocumenter(Documenter): 'noindex': bool_option, 'inherited-members': bool_option, 'show-inheritance': bool_option, 'synopsis': identity, 'platform': identity, 'deprecated': bool_option, - 'member-order': identity, + 'member-order': identity, 'exclude-members': members_set_option, } @classmethod @@ -818,6 +829,7 @@ class ClassDocumenter(ModuleLevelDocumenter): 'members': members_option, 'undoc-members': bool_option, 'noindex': bool_option, 'inherited-members': bool_option, 'show-inheritance': bool_option, 'member-order': identity, + 'exclude-members': members_set_option, } @classmethod diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index a9e030fe..d7e2f4ef 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -37,6 +37,7 @@ def setup_module(): deprecated = False, members = [], member_order = 'alphabetic', + exclude_members = set(), ) directive = Struct( @@ -375,6 +376,7 @@ def test_generate(): assert_processes(should, 'class', 'Class') should.extend([('method', 'test_autodoc.Class.meth')]) options.members = ['meth'] + options.exclude_members = set(['excludemeth']) assert_processes(should, 'class', 'Class') should.extend([('attribute', 'test_autodoc.Class.prop'), ('attribute', 'test_autodoc.Class.attr'), @@ -458,7 +460,9 @@ class Class(Base): def skipmeth(self): """Method that should be skipped.""" - pass + + def excludemeth(self): + """Method that should be excluded.""" # should not be documented skipattr = 'foo' -- cgit v1.2.1 From 125f29cfc23baabfe708669d45f50d4d3773edee Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 15 Mar 2009 23:55:05 +0100 Subject: Update MapServer URL. --- EXAMPLES | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/EXAMPLES b/EXAMPLES index 9eb0b0ce..709a6f76 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -22,7 +22,7 @@ included, please mail to `the Google group * Hedge: http://documen.tician.de/hedge/ * IFM: http://fluffybunny.memebot.com/ifm-docs/index.html * Jinja: http://jinja.pocoo.org/2/documentation/ -* MapServer: http://mapserver.osgeo.org/ +* MapServer: http://mapserver.org/ * Matplotlib: http://matplotlib.sourceforge.net/ * Mayavi: http://code.enthought.com/projects/mayavi/docs/development/html/mayavi * MeshPy: http://documen.tician.de/meshpy/ -- cgit v1.2.1 From 9ac2f1ad4ee44bb7455cc1e979d3f38c84c9960e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 16 Mar 2009 01:11:33 +0100 Subject: Add Sage. --- EXAMPLES | 1 + 1 file changed, 1 insertion(+) diff --git a/EXAMPLES b/EXAMPLES index 709a6f76..41b5774a 100644 --- a/EXAMPLES +++ b/EXAMPLES @@ -53,6 +53,7 @@ included, please mail to `the Google group * Quex: http://quex.sourceforge.net/ * Reteisi: http://docs.argolinux.org/reteisi/ * Roundup: http://www.roundup-tracker.org/ +* Sage: http://sagemath.org/doc/ * Satchmo: http://www.satchmoproject.com/docs/svn/ * Scapy: http://www.secdev.org/projects/scapy/doc/ * Self: http://selflanguage.org/ -- cgit v1.2.1 From d7fa65d4bbc99358bbf0eea0040ff0168d3cf094 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 16 Mar 2009 01:30:09 +0100 Subject: Add autosummary doc stub. --- doc/ext/autosummary.rst | 9 +++++++++ doc/extensions.rst | 1 + 2 files changed, 10 insertions(+) create mode 100644 doc/ext/autosummary.rst diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst new file mode 100644 index 00000000..a9255857 --- /dev/null +++ b/doc/ext/autosummary.rst @@ -0,0 +1,9 @@ +.. highlight:: rest + +:mod:`sphinx.ext.autosummary` -- Generate autodoc summaries +=========================================================== + +.. module:: sphinx.ext.autosummary + :synopsis: Generate autodoc summaries + +TBW. diff --git a/doc/extensions.rst b/doc/extensions.rst index 21ba0fd8..5eb26c14 100644 --- a/doc/extensions.rst +++ b/doc/extensions.rst @@ -41,6 +41,7 @@ These extensions are built in and can be activated by respective entries in the .. toctree:: ext/autodoc + ext/autosummary ext/doctest ext/intersphinx ext/math -- cgit v1.2.1 From b7ba1a3be7b22d45d6d044c3010bca7fa5701588 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 16 Mar 2009 12:07:23 +0100 Subject: Fix test_env. --- tests/test_env.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_env.py b/tests/test_env.py index a06656d6..94e7af93 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -80,7 +80,7 @@ def test_second_update(): (root / 'autodoc.txt').unlink() (root / 'new.txt').write_text('New file\n========\n') msg, num, it = env.update(app.config, app.srcdir, app.doctreedir, app) - assert '1 added, 3 changed, 1 removed' in msg + assert '1 added, 4 changed, 1 removed' in msg docnames = set() for docname in it: docnames.add(docname) -- cgit v1.2.1 From 76fe43679a3aa2a2e1941ef04140c569478254cb Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 16 Mar 2009 21:15:26 +0100 Subject: Fix for graphviz map files from Sebastian Wiesner. --- sphinx/ext/graphviz.py | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/sphinx/ext/graphviz.py b/sphinx/ext/graphviz.py index d51e2ed5..ea7b206d 100644 --- a/sphinx/ext/graphviz.py +++ b/sphinx/ext/graphviz.py @@ -91,7 +91,7 @@ def render_dot(self, code, options, format, prefix='graphviz'): outfn = path.join(self.builder.outdir, fname) if path.isfile(outfn): - return relfn + return relfn, outfn if hasattr(self.builder, '_graphviz_warned_dot') or \ hasattr(self.builder, '_graphviz_warned_ps2pdf'): @@ -122,12 +122,12 @@ def render_dot(self, code, options, format, prefix='graphviz'): if p.returncode != 0: raise GraphvizError('dot exited with error:\n[stderr]\n%s\n' '[stdout]\n%s' % (stderr, stdout)) - return relfn + return relfn, outfn def render_dot_html(self, node, code, options, prefix='graphviz', imgcls=None): try: - fname = render_dot(self, code, options, 'png', prefix) + fname, outfn = render_dot(self, code, options, 'png', prefix) except GraphvizError, exc: self.builder.warn('dot code %r: ' % code + str(exc)) raise nodes.SkipNode @@ -136,9 +136,11 @@ def render_dot_html(self, node, code, options, prefix='graphviz', imgcls=None): if fname is None: self.body.append(self.encode(code)) else: - mapfile = open(path.join(self.builder.outdir, fname) + '.map', 'rb') - imgmap = mapfile.readlines() - mapfile.close() + mapfile = open(outfn + '.map', 'rb') + try: + imgmap = mapfile.readlines() + finally: + mapfile.close() imgcss = imgcls and 'class="%s"' % imgcls or '' if len(imgmap) == 2: # nothing in image map (the lines are and ) -- cgit v1.2.1 From b1d5b3540860d02654a9992bcb3b8e13c0543a60 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 16 Mar 2009 23:30:17 +0100 Subject: Do proper cleanup of generated files. --- tests/test_env.py | 1 + tests/test_i18n.py | 4 ++++ tests/test_theming.py | 4 ++++ 3 files changed, 9 insertions(+) diff --git a/tests/test_env.py b/tests/test_env.py index a06656d6..ba0a916f 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -26,6 +26,7 @@ def setup_module(): def teardown_module(): app.cleanup() + (test_root / 'generated').rmtree() def warning_emitted(file, text): for warning in warnings: diff --git a/tests/test_i18n.py b/tests/test_i18n.py index 94648727..61dbef84 100644 --- a/tests/test_i18n.py +++ b/tests/test_i18n.py @@ -11,6 +11,10 @@ from util import * +def teardown_module(): + (test_root / '_build').rmtree() + (test_root / 'generated').rmtree() + @with_app(confoverrides={'language': 'de'}) def test_i18n(app): diff --git a/tests/test_theming.py b/tests/test_theming.py index 349a9ce4..cf450c02 100644 --- a/tests/test_theming.py +++ b/tests/test_theming.py @@ -16,6 +16,10 @@ from util import * from sphinx.theming import Theme, ThemeError +def teardown_module(): + (test_root / '_build').rmtree() + (test_root / 'generated').rmtree() + @with_app(confoverrides={'html_theme': 'ziptheme', 'html_theme_options.testopt': 'foo'}) -- cgit v1.2.1 From dad7f3eaf3fe59ed30825ee2adf7d0d77da01b02 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 16 Mar 2009 23:46:58 +0100 Subject: Restore 2.4 compatibility and fix removing the generated file properly. --- sphinx/ext/autodoc.py | 7 ++++++- tests/test_autodoc.py | 3 ++- tests/test_build.py | 3 +-- tests/test_env.py | 1 - tests/test_i18n.py | 4 ---- tests/test_theming.py | 4 ---- tests/util.py | 2 +- 7 files changed, 10 insertions(+), 14 deletions(-) diff --git a/sphinx/ext/autodoc.py b/sphinx/ext/autodoc.py index 5c1a0653..72d50029 100644 --- a/sphinx/ext/autodoc.py +++ b/sphinx/ext/autodoc.py @@ -853,7 +853,12 @@ class ClassDocumenter(ModuleLevelDocumenter): if initmeth is None or initmeth is object.__init__ or not \ (inspect.ismethod(initmeth) or inspect.isfunction(initmeth)): return None - argspec = inspect.getargspec(initmeth) + try: + argspec = inspect.getargspec(initmeth) + except TypeError: + # still not possible: happens e.g. for old-style classes + # with __init__ in C + return None if argspec[0] and argspec[0][0] in ('cls', 'self'): del argspec[0][0] return inspect.formatargspec(*argspec) diff --git a/tests/test_autodoc.py b/tests/test_autodoc.py index d7e2f4ef..8e011438 100644 --- a/tests/test_autodoc.py +++ b/tests/test_autodoc.py @@ -470,9 +470,10 @@ class Class(Base): #: should be documented -- süß attr = 'bar' - @property def prop(self): """Property.""" + # stay 2.4 compatible (docstring!) + prop = property(prop, doc="Property.") docattr = 'baz' """should likewise be documented -- süß""" diff --git a/tests/test_build.py b/tests/test_build.py index 18c78499..7b33dc09 100644 --- a/tests/test_build.py +++ b/tests/test_build.py @@ -31,8 +31,7 @@ from sphinx.writers.latex import LaTeXTranslator def teardown_module(): - (test_root / '_build').rmtree() - (test_root / 'generated').rmtree() + (test_root / '_build').rmtree(True) html_warnfile = StringIO() diff --git a/tests/test_env.py b/tests/test_env.py index ba0a916f..a06656d6 100644 --- a/tests/test_env.py +++ b/tests/test_env.py @@ -26,7 +26,6 @@ def setup_module(): def teardown_module(): app.cleanup() - (test_root / 'generated').rmtree() def warning_emitted(file, text): for warning in warnings: diff --git a/tests/test_i18n.py b/tests/test_i18n.py index 61dbef84..94648727 100644 --- a/tests/test_i18n.py +++ b/tests/test_i18n.py @@ -11,10 +11,6 @@ from util import * -def teardown_module(): - (test_root / '_build').rmtree() - (test_root / 'generated').rmtree() - @with_app(confoverrides={'language': 'de'}) def test_i18n(app): diff --git a/tests/test_theming.py b/tests/test_theming.py index cf450c02..349a9ce4 100644 --- a/tests/test_theming.py +++ b/tests/test_theming.py @@ -16,10 +16,6 @@ from util import * from sphinx.theming import Theme, ThemeError -def teardown_module(): - (test_root / '_build').rmtree() - (test_root / 'generated').rmtree() - @with_app(confoverrides={'html_theme': 'ziptheme', 'html_theme_options.testopt': 'foo'}) diff --git a/tests/util.py b/tests/util.py index 2c9d3176..4bb6a653 100644 --- a/tests/util.py +++ b/tests/util.py @@ -105,7 +105,7 @@ class TestApp(application.Sphinx): application.CONFIG_FILENAME = confname - self.cleanup_trees = [] + self.cleanup_trees = [test_root / 'generated'] if srcdir is None: srcdir = test_root -- cgit v1.2.1 From a1691a3424ae6b91743db7f37cf4fe86f7c93760 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 16 Mar 2009 23:50:34 +0100 Subject: Update version info for 0.6b1. --- sphinx/__init__.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sphinx/__init__.py b/sphinx/__init__.py index e0d8813f..0e37bf15 100644 --- a/sphinx/__init__.py +++ b/sphinx/__init__.py @@ -13,8 +13,8 @@ import sys from os import path __revision__ = '$Revision$' -__version__ = '0.6' -__released__ = '0.6 (hg)' +__version__ = '0.6b1' +__released__ = '0.6b1' package_dir = path.abspath(path.dirname(__file__)) -- cgit v1.2.1