[Python-checkins] r65124 - in doctools/trunk: Makefile TODO sphinx/init.py sphinx/builder.py sphinx/environment.py sphinx/ext/autodoc.py sphinx/latexwriter.py sphinx/quickstart.py sphinx/roles.py sphinx/templates/genindex-split.html sphinx/templates/genindex.html sphinx/util/init.py sphinx/util/console.py tests/path.py tests/test_quickstart.py tests/util.py utils/check_sources.py

Sat Jul 19 00:56:28 CEST 2008

Author: georg.brandl
Date: Sat Jul 19 00:55:36 2008
New Revision: 65124
Log:
Merged revisions 64808,65013,65076,65100-65101,65119,65121-65123 via svnmerge from 
svn+ssh://pythondev@svn.python.org/doctools/branches/0.4.x
........
 r64808 | georg.brandl | 2008年07月08日 21:39:33 +0200 (2008年7月08日) | 2 lines
 
 Allow relocation of source and doctree dir.
........
 r65013 | georg.brandl | 2008年07月16日 15:25:30 +0200 (2008年7月16日) | 2 lines
 
 Remove curious quote.
........
 r65076 | georg.brandl | 2008年07月17日 22:43:01 +0200 (2008年7月17日) | 2 lines
 
 Add a test for sphinx.quickstart.
........
 r65100 | georg.brandl | 2008年07月18日 14:41:54 +0200 (2008年7月18日) | 2 lines
 
 Fix phony targets.
........
 r65101 | georg.brandl | 2008年07月18日 14:55:03 +0200 (2008年7月18日) | 2 lines
 
 Fix problems in "make check".
........
 r65119 | georg.brandl | 2008年07月18日 23:06:42 +0200 (2008年7月18日) | 2 lines
 
 Emit a more precise error message in autodoc.
........
 r65121 | georg.brandl | 2008年07月18日 23:41:35 +0200 (2008年7月18日) | 2 lines
 
 Warn if a toctree-included document doesn't contain a title.
........
 r65122 | georg.brandl | 2008年07月18日 23:51:28 +0200 (2008年7月18日) | 2 lines
 
 Don't use \samp{} for code with whitespaces, only for :samp:`code`.
........
 r65123 | georg.brandl | 2008年07月19日 00:49:46 +0200 (2008年7月19日) | 2 lines
 
 Put inheritance info always on its own line.
........
Added:
 doctools/trunk/tests/test_quickstart.py
 - copied unchanged from r65123, /doctools/branches/0.4.x/tests/test_quickstart.py
Modified:
 doctools/trunk/ (props changed)
 doctools/trunk/Makefile
 doctools/trunk/TODO
 doctools/trunk/sphinx/__init__.py
 doctools/trunk/sphinx/builder.py
 doctools/trunk/sphinx/environment.py
 doctools/trunk/sphinx/ext/autodoc.py
 doctools/trunk/sphinx/latexwriter.py
 doctools/trunk/sphinx/quickstart.py
 doctools/trunk/sphinx/roles.py
 doctools/trunk/sphinx/templates/genindex-split.html
 doctools/trunk/sphinx/templates/genindex.html
 doctools/trunk/sphinx/util/__init__.py
 doctools/trunk/sphinx/util/console.py
 doctools/trunk/tests/path.py
 doctools/trunk/tests/util.py
 doctools/trunk/utils/check_sources.py
Modified: doctools/trunk/Makefile
==============================================================================

--- doctools/trunk/Makefile	(original)
+++ doctools/trunk/Makefile	Sat Jul 19 00:55:36 2008
@@ -2,7 +2,7 @@
 
 export PYTHONPATH = $(shell echo "$$PYTHONPATH"):./sphinx
 
-.PHONY: all check clean clean-pyc pylint reindent testserver
+.PHONY: all check clean clean-pyc clean-patchfiles pylint reindent test
 
 all: clean-pyc check
 
Modified: doctools/trunk/TODO
==============================================================================
--- doctools/trunk/TODO	(original)
+++ doctools/trunk/TODO	Sat Jul 19 00:55:36 2008
@@ -1,6 +1,10 @@
 Sphinx TODO
 ===========
 
+- specify node visit functions when adding nodes to app
+- allow extensions to add static files
+- decide which static files to include
+- verbose option
 - remove redundant <ul>s in tocs
 - autoattribute in autodoc
 - range and object options for literalinclude
Modified: doctools/trunk/sphinx/__init__.py
==============================================================================
--- doctools/trunk/sphinx/__init__.py	(original)
+++ doctools/trunk/sphinx/__init__.py	Sat Jul 19 00:55:36 2008
@@ -29,7 +29,7 @@
 print >>sys.stderr
 print >>sys.stderr, """\
 Sphinx v%s
-Usage: %s [options] sourcedir outdir [filenames...]"
+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
 -E -- don't use a saved environment, always read all files
Modified: doctools/trunk/sphinx/builder.py
==============================================================================
--- doctools/trunk/sphinx/builder.py	(original)
+++ doctools/trunk/sphinx/builder.py	Sat Jul 19 00:55:36 2008
@@ -211,7 +211,7 @@
 warnings = []
 self.env.set_warnfunc(warnings.append)
 self.info(bold('updating environment: '), nonl=1)
- iterator = self.env.update(self.config, 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... ', purple):
Modified: doctools/trunk/sphinx/environment.py
==============================================================================
--- doctools/trunk/sphinx/environment.py	(original)
+++ doctools/trunk/sphinx/environment.py	Sat Jul 19 00:55:36 2008
@@ -396,7 +396,7 @@
 
 return added, changed, removed
 
- def update(self, config, app=None):
+ 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
@@ -416,6 +416,9 @@
 break
 else:
 msg = ''
+ # the source and doctree directories may have been relocated
+ self.srcdir = srcdir
+ self.doctreedir = doctreedir
 self.find_files(config)
 added, changed, removed = self.get_outdated_files(config_changed)
 msg += '%s added, %s changed, %s removed' % (len(added), len(changed),
@@ -807,10 +810,15 @@
 for includefile in includefiles:
 try:
 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)
 except KeyError:
 # this is raised if the included file does not exist
- self.warn(docname, 'toctree contains ref to nonexisting '
- 'file %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
Modified: doctools/trunk/sphinx/ext/autodoc.py
==============================================================================
--- doctools/trunk/sphinx/ext/autodoc.py	(original)
+++ doctools/trunk/sphinx/ext/autodoc.py	Sat Jul 19 00:55:36 2008
@@ -355,10 +355,11 @@
 modfile = None # e.g. for builtin and C modules
 for part in objpath:
 todoc = getattr(todoc, part)
- except (ImportError, AttributeError):
+ except (ImportError, AttributeError), err:
 warnings.append(document.reporter.warning(
- 'autodoc can\'t import/find %s %r, check your spelling '
- 'and sys.path' % (what, str(fullname)), line=lineno))
+ 'autodoc can\'t import/find %s %r, it reported error: "%s",'
+ 'please check your spelling and sys.path' %
+ (what, str(fullname), err), line=lineno))
 return warnings, result
 
 # check __module__ of object if wanted (for members not given explicitly)
@@ -416,6 +417,7 @@
 u':class:`%s.%s`' % (b.__module__, b.__name__)
 for b in todoc.__bases__]
 result.append(indent + u' Bases: %s' % ', '.join(bases), '<autodoc>')
+ result.append(u'', '<autodoc>')
 
 # the module directive doesn't have content
 if what != 'module':
Modified: doctools/trunk/sphinx/latexwriter.py
==============================================================================
--- doctools/trunk/sphinx/latexwriter.py	(original)
+++ doctools/trunk/sphinx/latexwriter.py	Sat Jul 19 00:55:36 2008
@@ -873,7 +873,7 @@
 content = self.encode(node.astext().strip())
 if self.in_title:
 self.body.append(r'\texttt{%s}' % content)
- elif re.search('[ \t\n]', 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)
Modified: doctools/trunk/sphinx/quickstart.py
==============================================================================
--- doctools/trunk/sphinx/quickstart.py	(original)
+++ doctools/trunk/sphinx/quickstart.py	Sat Jul 19 00:55:36 2008
@@ -16,6 +16,8 @@
 from sphinx.util.console import purple, bold, red, nocolor
 
 
+PROMPT_PREFIX = '> '
+
 QUICKSTART_CONF = '''\
 # -*- coding: utf-8 -*-
 #
@@ -176,7 +178,8 @@
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 latex_documents = [
- ('%(master)s', '%(project_fn)s.tex', '%(project)s Documentation', '%(author)s', 'manual'),
+ ('%(master)s', '%(project_fn)s.tex', '%(project)s Documentation',
+ '%(author)s', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -231,7 +234,8 @@
 # Internal variables.
 PAPEROPT_a4 = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
-ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) %(rsrcdir)s
+ALLSPHINXOPTS = -d %(rbuilddir)s/doctrees $(PAPEROPT_$(PAPER)) \
+$(SPHINXOPTS) %(rsrcdir)s
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck
 
@@ -333,9 +337,9 @@
 def do_prompt(d, key, text, default=None, validator=nonempty):
 while True:
 if default:
- prompt = purple('> %s [%s]: ' % (text, default))
+ prompt = purple(PROMPT_PREFIX + '%s [%s]: ' % (text, default))
 else:
- prompt = purple('> ' + text + ': ')
+ prompt = purple(PROMPT_PREFIX + text + ': ')
 x = raw_input(prompt)
 if default and not x:
 x = default
@@ -364,7 +368,7 @@
 You have two options for placing the build directory for Sphinx output.
 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',
+ do_prompt(d, 'sep', 'Separate source and build directories (y/N)', 'n',
 boolean)
 print '''
 Inside the root directory, two more directories will be created; ".templates"
@@ -399,14 +403,14 @@
 print '''
 Please indicate if you want to use one of the following Sphinx extensions:'''
 do_prompt(d, 'ext_autodoc', 'autodoc: automatically insert docstrings '
- 'from modules (y/n)', 'n', boolean)
+ 'from modules (y/N)', 'n', boolean)
 do_prompt(d, 'ext_doctest', 'doctest: automatically test code snippets '
- 'in doctest blocks (y/n)', 'n', boolean)
+ 'in doctest blocks (y/N)', 'n', boolean)
 print '''
 If you are under Unix, a Makefile 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)',
+ do_prompt(d, 'makefile', 'Create Makefile? (Y/n)',
 os.name == 'posix' and 'y' or 'n', boolean)
 
 d['project_fn'] = make_filename(d['project'])
Modified: doctools/trunk/sphinx/roles.py
==============================================================================
--- doctools/trunk/sphinx/roles.py	(original)
+++ doctools/trunk/sphinx/roles.py	Sat Jul 19 00:55:36 2008
@@ -195,17 +195,17 @@
 
 def emph_literal_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
 text = utils.unescape(text)
- retnodes = []
 pos = 0
+ retnode = nodes.literal(role=typ)
 for m in _litvar_re.finditer(text):
 if m.start() > pos:
 txt = text[pos:m.start()]
- retnodes.append(nodes.literal(txt, txt))
- retnodes.append(nodes.emphasis('', '', nodes.literal(m.group(1), m.group(1))))
+ retnode += nodes.Text(txt, txt)
+ retnode += nodes.emphasis(m.group(1), m.group(1))
 pos = m.end()
 if pos < len(text):
- retnodes.append(nodes.literal(text[pos:], text[pos:]))
- return retnodes, []
+ retnode += nodes.Text(text[pos:], text[pos:])
+ return [retnode], []
 
 
 specific_docroles = {
Modified: doctools/trunk/sphinx/templates/genindex-split.html
==============================================================================
--- doctools/trunk/sphinx/templates/genindex-split.html	(original)
+++ doctools/trunk/sphinx/templates/genindex-split.html	Sat Jul 19 00:55:36 2008
@@ -5,7 +5,7 @@
 <h1 id="index">Index</h1>
 
 <p>Index pages by letter:</p>
- 
+
 <p>{% for key, dummy in genindexentries -%}
 <a href="{{ pathto('genindex-' + key) }}"><strong>{{ key }}</strong></a>
 {% if not loop.last %}| {% endif %}
@@ -25,5 +25,5 @@
 {%- endfor %}</p>
 
 <p><a href="{{ pathto('genindex-all') }}"><strong>Full index on one page</strong></a></p>
-{% endif %} 
+{% endif %}
 {% endblock %}
Modified: doctools/trunk/sphinx/templates/genindex.html
==============================================================================
--- doctools/trunk/sphinx/templates/genindex.html	(original)
+++ doctools/trunk/sphinx/templates/genindex.html	Sat Jul 19 00:55:36 2008
@@ -52,5 +52,5 @@
 {%- endfor %}</p>
 
 <p><a href="{{ pathto('genindex-all') }}"><strong>Full index on one page</strong></a></p>
-{% endif %} 
+{% endif %}
 {% endblock %}
Modified: doctools/trunk/sphinx/util/__init__.py
==============================================================================
--- doctools/trunk/sphinx/util/__init__.py	(original)
+++ doctools/trunk/sphinx/util/__init__.py	Sat Jul 19 00:55:36 2008
@@ -250,7 +250,7 @@
 Adapted from fnmatch module.
 """
 result = []
- if not pat in _pat_cache:
+ if pat not in _pat_cache:
 _pat_cache[pat] = re.compile(_translate_pattern(pat))
 match = _pat_cache[pat].match
 return filter(match, names)
Modified: doctools/trunk/sphinx/util/console.py
==============================================================================
--- doctools/trunk/sphinx/util/console.py	(original)
+++ doctools/trunk/sphinx/util/console.py	Sat Jul 19 00:55:36 2008
@@ -38,6 +38,9 @@
 def nocolor():
 codes.clear()
 
+def coloron():
+ codes.update(_orig_codes)
+
 def colorize(name, text):
 return codes.get(name, '') + text + codes.get('reset', '')
 
@@ -73,5 +76,7 @@
 codes[dark] = '\x1b[%im' % (i+30)
 codes[light] = '\x1b[%i;01m' % (i+30)
 
+_orig_codes = codes.copy()
+
 for _name in codes:
 create_color_func(_name)
Modified: doctools/trunk/tests/path.py
==============================================================================
--- doctools/trunk/tests/path.py	(original)
+++ doctools/trunk/tests/path.py	Sat Jul 19 00:55:36 2008
@@ -353,7 +353,7 @@
 whose names match the given pattern. For example,
 d.files('*.pyc').
 """
- 
+
 return [p for p in self.listdir(pattern) if p.isfile()]
 
 def walk(self, pattern=None, errors='strict'):
Modified: doctools/trunk/tests/util.py
==============================================================================
--- doctools/trunk/tests/util.py	(original)
+++ doctools/trunk/tests/util.py	Sat Jul 19 00:55:36 2008
@@ -19,7 +19,7 @@
 __all__ = [
 'raises', 'raises_msg',
 'ErrorOutput', 'TestApp',
- 'with_tempdir', 'write_file',
+ 'path', 'with_tempdir', 'write_file',
 ]
 
 
Modified: doctools/trunk/utils/check_sources.py
==============================================================================
--- doctools/trunk/utils/check_sources.py	(original)
+++ doctools/trunk/utils/check_sources.py	Sat Jul 19 00:55:36 2008
@@ -7,7 +7,7 @@
 Make sure each Python file has a correct file header
 including copyright and license information.
 
- :copyright: 2006-2007 by Georg Brandl.
+ :copyright: 2006-2008 by Georg Brandl.
 :license: GNU GPL, see LICENSE for more details.
 """
 
@@ -57,15 +57,17 @@
 for lno, line in enumerate(lines):
 if len(line) > 90:
 yield lno+1, "line too long"
+ if lno < 2:
+ co = coding_re.search(line)
+ if co:
+ encoding = co.group(1)
+ if line.strip().startswith('#'):
+ continue
 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'
- if lno < 2:
- co = coding_re.search(line)
- if co:
- encoding = co.group(1)
 try:
 line.decode(encoding)
 except UnicodeDecodeError, err:
