Commits

Zoom Quiet committed 0c89f2c Merge

merged owerner @first

  • Participants
  • Parent commits a725ee1, 8ca644b

Comments (0)

Files changed (66)

 ~$
 ^utils/.*3\.py$
 ^distribute-
+^tests/root/_build/*
+^tests/root/generated/*
 
 * #460: Allow limiting the depth of section numbers for HTML.
 
+* #564: Add :confval:`autodoc_docstring_signature` which retrieves
+  the signature from the first line of the docstring, if it is
+  found there.
+
+* #176: Provide ``private-members`` option for autodoc directives.
+
+* #520: Provide ``special-members`` option for autodoc directives.
+
 * #138: Add an ``index`` role, to make inline index entries.
 
 * #443: Allow referencing external graphviz files.
 
 * #526: Added Iranian translation.
 
+* #559: :confval:`html_add_permalinks` is now a string giving the
+  text to display in permalinks.
 
-Release 1.0.5 (in development)
+* #553: Added :rst:dir:`testcleanup` blocks in the doctest extension.
+
+
+Release 1.0.6 (in development)
 ==============================
 
+* #574: Add special code for better support of Japanese documents
+  in the LaTeX builder.
+
+* Regression of #77: If there is only one parameter given with
+  ``:param:`` markup, the bullet list is now suppressed again.
+
+* #556: Fix missing paragraph breaks in LaTeX output in certain
+  situations.
+
+* #567: Emit the ``autodoc-process-docstring`` event even for objects
+  without a docstring so that it can add content.
+
+* #565: In the LaTeX builder, not only literal blocks require different
+  table handling, but also quite a few other list-like block elements.
+
+* #515: Fix tracebacks in the viewcode extension for Python objects
+  that do not have a valid signature.
+
+* Fix strange reportings of line numbers for warnings generated from
+  autodoc-included docstrings, due to different behavior depending
+  on docutils version.
+
+* Several fixes to the C++ domain.
+
+
+Release 1.0.5 (Nov 12, 2010)
+============================
+
+* #557: Add CSS styles required by docutils 0.7 for aligned images
+  and figures.
+
+* In the Makefile generated by LaTeX output, do not delete pdf files
+  on clean; they might be required images.
+
 * #535: Fix LaTeX output generated for line blocks.
 
 * #544: Allow ``.pyw`` as a source file extension.
 
 .. 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``.
+   Sphinx will add "permalinks" for each heading and description environment as
+   paragraph signs that become visible when the mouse hovers over them.
+
+   This value determines the text for the permalink; it defaults to ``"¶"``.
+   Set it to ``None`` or the empty string to disable permalinks.
 
    .. versionadded:: 0.6
       Previously, this was always activated.
 
+   .. versionchanged:: 1.1
+      This can now be a string to select the actual text of the link.
+      Previously, only boolean values were accepted.
+
 .. confval:: html_sidebars
 
    Custom sidebar templates, must be a dictionary that maps document names to
       :type limit: integer or None
       :rtype: list of strings
 
-It is also possible to combine parameter type and description, if the type is a
-single word, like this::
-
-   :param integer limit: maximum number of stack frames to show
-
 This will render like this:
 
    .. py:function:: format_exception(etype, value, tb[, limit=None])
       :type limit: integer or None
       :rtype: list of strings
 
+It is also possible to combine parameter type and description, if the type is a
+single word, like this::
+
+   :param integer limit: maximum number of stack frames to show
+
 
 Cross-referencing Python objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/ext/autodoc.rst

         .. autoclass:: Noodle
            :members: eat, slurp
 
-   * If you want to make the ``members`` option the default, see
-     :confval:`autodoc_default_flags`.
+   * If you want to make the ``members`` option (or other flag options described
+     below) the default, see :confval:`autodoc_default_flags`.
 
    * Members without docstrings will be left out, unless you give the
      ``undoc-members`` flag option::
            :members:
            :undoc-members:
 
+   * "Private" members (that is, those named like ``_private`` or ``__private``)
+     will be included if the ``private-members`` flag option is given.
+
+     .. versionadded:: 1.1
+
+   * Python "special" members (that is, those named like ``__special__``) will
+     be included if the ``special-members`` flag option is given::
+
+        .. autoclass:: my.Class
+           :members:
+           :private-members:
+           :special-members:
+
+     would document both "private" and "special" members of the class.
+
+     .. versionadded:: 1.1
+
    * For classes and exceptions, members inherited from base classes will be
      left out, unless you give the ``inherited-members`` flag option, in
      addition to ``members``::
 
      .. versionadded:: 0.5
 
-   * :rst:dir:`automodule` and :rst:dir:`autoclass` also has an ``member-order`` option
-     that can be used to override the global value of
+   * :rst:dir:`automodule` and :rst: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
 
 
 .. rst:directive:: autofunction
-               autodata
-               automethod
-               autoattribute
+                   autodata
+                   automethod
+                   autoattribute
 
    These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
    used for automatic member documentation.
 
           baz = 2
           """Docstring for class attribute Foo.baz."""
-          
+
           def __init__(self):
               #: Doc comment for instance attribute qux.
               self.qux = 3
-              
+
               self.spam = 4
               """Docstring for instance attribute spam."""
 
 
    This value is a list of autodoc directive flags that should be automatically
    applied to all autodoc directives.  The supported flags are ``'members'``,
-   ``'undoc-members'``, ``'inherited-members'`` and ``'show-inheritance'``.
+   ``'undoc-members'``, ``'private-members'``, ``'special-members'``,
+   ``'inherited-members'`` and ``'show-inheritance'``.
 
    If you set one of these flags in this config value, you can use a negated
    form, :samp:`'no-{flag}'`, in an autodoc directive, to disable it once.
 
    .. versionadded:: 1.0
 
+.. confval:: autodoc_docstring_signature
+
+   Functions imported from C modules cannot be introspected, and therefore the
+   signature for such functions cannot be automatically determined.  However, it
+   is an often-used convention to put the signature into the first line of the
+   function's docstring.
+
+   If this boolean value is set to ``True`` (which is the default), autodoc will
+   look at the first line of the docstring for functions and methods, and if it
+   looks like a signature, use the line as the signature and remove it from the
+   docstring content.
+
+   .. versionadded:: 1.1
+
 
 Docstring preprocessing
 -----------------------

doc/ext/doctest.rst

    but executed before the doctests of the group(s) it belongs to.
 
 
+.. rst:directive:: .. testcleanup:: [group]
+
+   A cleanup code block.  This code is not shown in the output for other
+   builders, but executed after the doctests of the group(s) it belongs to.
+
+   .. versionadded:: 1.1
+
+
 .. rst:directive:: .. doctest:: [group]
 
    A doctest-style code block.  You can use standard :mod:`doctest` flags for
 
    .. versionadded:: 0.6
 
+.. confval:: doctest_global_cleanup
+
+   Python code that is treated like it were put in a ``testcleanup`` directive
+   for *every* file that is tested, and for every group.  You can use this to
+   e.g. remove any temporary files that the tests leave behind.
+
+   .. versionadded:: 1.1
+
 .. confval:: doctest_test_doctest_blocks
 
    If this is a nonempty string (the default is ``'default'``), standard reST
    Sphinx documentation to the PyPI package documentation area at
    http://packages.python.org/.
 
-github pages
-   You can use `Michael Jones' sphinx-to-github tool
-   <http://github.com/michaeljones/sphinx-to-github/tree/master>`_ to prepare
-   Sphinx HTML output.
+GitHub Pages
+   Directories starting with underscores are ignored by default which breaks
+   static files in Sphinx.  GitHub's preprocessor can be `disabled
+   <https://github.com/blog/572-bypassing-jekyll-on-github-pages>`_ to support
+   Sphinx HTML output properly.
 
 Google Analytics
    You can use a custom ``layout.html`` template, like this:

doc/markup/misc.rst

 
    :fieldname: Field content
 
-A field list at the very top of a file is parsed by docutils as the "docinfo",
+A field list near the top of a file is parsed by docutils as the "docinfo"
 which is normally used to record the author, date of publication and other
-metadata.  *In Sphinx*, the docinfo is used as metadata, too, but not displayed
-in the output.
+metadata.  *In Sphinx*, a field list preceding any other markup is moved from
+the docinfo to the Sphinx environment as document metadata and is not displayed
+in the output; a field list appearing after the document title will be part of
+the docinfo as normal and will be displayed in the output.
 
 At the moment, these metadata fields are recognized:
 
 
 .. warning::
 
-   Tables that contain literal blocks cannot be set with ``tabulary``.  They are
-   therefore set with the standard LaTeX ``tabular`` environment.  Also, the
-   verbatim environment used for literal blocks only works in ``p{width}``
-   columns, which means that by default, Sphinx generates such column specs for
-   such tables.  Use the :rst:dir:`tabularcolumns` directive to get finer control
-   over such tables.
+   Tables that contain list-like elements such as object descriptions,
+   blockquotes or any kind of lists cannot be set out of the box with
+   ``tabulary``.  They are therefore set with the standard LaTeX ``tabular``
+   environment if you don't give a ``tabularcolumns`` directive.  If you do, the
+   table will be set with ``tabulary``, but you must use the ``p{width}``
+   construct for the columns that contain these elements.
+
+   Literal blocks do not work with ``tabulary`` at all, so tables containing a
+   literal block are always set with ``tabular``.  Also, the verbatim
+   environment used for literal blocks only works in ``p{width}`` columns, which
+   means that by default, Sphinx generates such column specs for such tables.
+   Use the :rst:dir:`tabularcolumns` directive to get finer control over such
+   tables.

doc/markup/para.rst

    Similar to :rst:dir:`versionadded`, but describes when and what changed in
    the named feature in some way (new parameters, changed side effects, etc.).
 
-.. rst:directive:: .. deprecated:: vesion
+.. rst:directive:: .. deprecated:: version
 
    Similar to :rst:dir:`versionchanged`, but describes when the feature was
    deprecated.  An explanation can also be given, for example to inform the
 * 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.
+  output static 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:

doc/web/quickstart.rst

                                  username=username, proposal=proposal,
                                  displayed=False)
 
-You can then create two new views to handle the moderation of comments.  The
-first will be called when a moderator decides a comment should be accepted and
+You can then create a new view to handle the moderation of comments.  It
+will be called when a moderator decides a comment should be accepted and
 displayed::
 
    @app.route('/docs/accept_comment', methods=['POST'])
        support.accept_comment(comment_id, moderator=moderator)
        return 'OK'
 
-The next is very similar, but used when rejecting a comment::
-
-   @app.route('/docs/reject_comment', methods=['POST'])
-   def reject_comment():
-       moderator = g.user.moderator if g.user else False
-       comment_id = request.form.get('id')
-       support.reject_comment(comment_id, moderator=moderator)
-       return 'OK'
+Rejecting comments happens via comment deletion.
 
 To perform a custom action (such as emailing a moderator) when a new comment is
 added but not displayed, you can pass callable to the :class:`~.WebSupport`

doc/web/storagebackends.rst

 .. automethod:: StorageBackend.update_username
 
 .. automethod:: StorageBackend.accept_comment
-
-.. automethod:: StorageBackend.reject_comment

sphinx/__init__.py

File contents unchanged.

sphinx/builders/changes.py

 
     def init(self):
         self.create_template_bridge()
-        Theme.init_themes(self)
+        Theme.init_themes(self.confdir, self.config.html_theme_path,
+                          warn=self.warn)
         self.theme = Theme('default')
         self.templates.init(self, self.theme)
 

sphinx/builders/html.py

         return self.config.html_theme, self.config.html_theme_options
 
     def init_templates(self):
-        Theme.init_themes(self)
+        Theme.init_themes(self.confdir, self.config.html_theme_path,
+                          warn=self.warn)
         themename, themeoptions = self.get_theme_config()
         self.theme = Theme(themename)
         self.theme_options = themeoptions.copy()
     def load_indexer(self, docnames):
         keep = set(self.env.all_docs) - set(docnames)
         try:
-            f = open(path.join(self.outdir, self.searchindex_filename), 'rb')
+            searchindexfn = path.join(self.outdir, self.searchindex_filename)
+            if self.indexer_dumps_unicode:
+                f = codecs.open(searchindexfn, 'r', encoding='utf-8')
+            else:
+                f = open(searchindexfn, 'rb')
             try:
                 self.indexer.load(f, self.indexer_format)
             finally:
             return uri
         ctx['pathto'] = pathto
         ctx['hasdoc'] = lambda name: name in self.env.all_docs
-        ctx['encoding'] = encoding = self.config.html_output_encoding
+        if self.name != 'htmlhelp':
+            ctx['encoding'] = encoding = self.config.html_output_encoding
+        else:
+            ctx['encoding'] = encoding = self.encoding
         ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw)
         self.add_sidebars(pagename, ctx)
         ctx.update(addctx)
         # outfilename's path is in general different from self.outdir
         ensuredir(path.dirname(outfilename))
         try:
-            f = codecs.open(outfilename, 'w', encoding)
+            f = codecs.open(outfilename, 'w', encoding, 'xmlcharrefreplace')
             try:
                 f.write(output)
             finally:
     #: (pickle, simplejson etc.)
     implementation = None
     implementation_dumps_unicode = False
+    #: additional arguments for dump()
+    additional_dump_args = ()
 
     #: the filename for the global context file
     globalcontext_filename = None
         else:
             f = open(filename, 'wb')
         try:
-            # XXX: the third argument is pickle-specific!
-            self.implementation.dump(context, f, 2)
+            self.implementation.dump(context, f, *self.additional_dump_args)
         finally:
             f.close()
 
     """
     implementation = pickle
     implementation_dumps_unicode = False
+    additional_dump_args = (pickle.HIGHEST_PROTOCOL,)
     indexer_format = pickle
     indexer_dumps_unicode = False
     name = 'pickle'

sphinx/builders/htmlhelp.py

             def write_index(title, refs, subitems):
                 def write_param(name, value):
                     item = '    <param name="%s" value="%s">\n' % (name, value)
-                    f.write(item.encode('ascii', 'xmlcharrefreplace')
-                            .decode('ascii'))
+                    f.write(item.encode(self.encoding, 'xmlcharrefreplace')
+                            .decode(self.encoding))
                 title = cgi.escape(title)
                 f.write('<LI> <OBJECT type="text/sitemap">\n')
                 write_param('Keyword', title)

sphinx/builders/versioning.py

     :license: BSD, see LICENSE for details.
 """
 import os
-import pickle
+import cPickle as pickle
 
 from docutils.utils import Reporter
 

sphinx/builders/websupport.py

     :license: BSD, see LICENSE for details.
 """
 
-import cPickle as pickle
 from os import path
-from cgi import escape
 import posixpath
 import shutil
 
 from docutils.io import StringOutput
 
+from sphinx.jinja2glue import BuiltinTemplateLoader
 from sphinx.util.osutil import os_path, relative_uri, ensuredir, copyfile
-from sphinx.util.jsonimpl import dumps as dump_json
 from sphinx.util.websupport import is_commentable
-from sphinx.builders.html import StandaloneHTMLBuilder
+from sphinx.builders.html import PickleHTMLBuilder
 from sphinx.builders.versioning import VersioningBuilderMixin
 from sphinx.writers.websupport import WebSupportTranslator
 
 
-class WebSupportBuilder(StandaloneHTMLBuilder, VersioningBuilderMixin):
+class WebSupportBuilder(PickleHTMLBuilder, VersioningBuilderMixin):
     """
     Builds documents for the web support package.
     """
     name = 'websupport'
-    out_suffix = '.fpickle'
 
     def init(self):
-        StandaloneHTMLBuilder.init(self)
+        PickleHTMLBuilder.init(self)
         VersioningBuilderMixin.init(self)
+        # templates are needed for this builder, but the serializing
+        # builder does not initialize them
+        self.init_templates()
+        if not isinstance(self.templates, BuiltinTemplateLoader):
+            raise RuntimeError('websupport builder must be used with '
+                               'the builtin templates')
+        # add our custom JS
+        self.script_files.append('_static/websupport.js')
+
+    def set_webinfo(self, staticdir, virtual_staticdir, search, storage):
+        self.staticdir = staticdir
+        self.virtual_staticdir = virtual_staticdir
+        self.search = search
+        self.storage = storage
 
     def init_translator_class(self):
         self.translator_class = WebSupportTranslator
 
+    def prepare_writing(self, docnames):
+        PickleHTMLBuilder.prepare_writing(self, docnames)
+        self.globalcontext['no_search_suffix'] = True
+
     def write_doc(self, docname, doctree):
         destination = StringOutput(encoding='utf-8')
         doctree.settings = self.docsettings
 
         self.cur_docname = docname
         self.secnumbers = self.env.toc_secnumbers.get(docname, {})
-        self.imgpath = '/' + posixpath.join(self.app.staticdir, '_images')
+        self.imgpath = '/' + posixpath.join(self.virtual_staticdir, '_images')
         self.post_process_images(doctree)
-        self.dlpath = '/' + posixpath.join(self.app.staticdir, '_downloads')
+        self.dlpath = '/' + posixpath.join(self.virtual_staticdir, '_downloads')
         self.docwriter.write(doctree, destination)
         self.docwriter.assemble_parts()
         body = self.docwriter.parts['fragment']
         self.index_page(docname, doctree, ctx.get('title', ''))
         self.handle_page(docname, ctx, event_arg=doctree)
 
-    def get_target_uri(self, docname, typ=None):
-        return docname
-
     def load_indexer(self, docnames):
-        self.indexer = self.app.search
+        self.indexer = self.search
         self.indexer.init_indexing(changed=docnames)
 
-    def handle_page(self, pagename, addctx, templatename='page.html',
-                    outfilename=None, event_arg=None):
+    def _render_page(self, pagename, addctx, templatename, event_arg=None):
         # This is mostly copied from StandaloneHTMLBuilder. However, instead
         # of rendering the template and saving the html, create a context
         # dict and pickle it.
 
         def pathto(otheruri, resource=False,
                    baseuri=self.get_target_uri(pagename)):
-            if not resource:
+            if resource and '://' in otheruri:
+                return otheruri
+            elif not resource:
                 otheruri = self.get_target_uri(otheruri)
                 return relative_uri(baseuri, otheruri) or '#'
             else:
-                return '/' + posixpath.join(self.app.staticdir, otheruri)
+                return '/' + posixpath.join(self.virtual_staticdir, otheruri)
         ctx['pathto'] = pathto
         ctx['hasdoc'] = lambda name: name in self.env.all_docs
-        ctx['encoding'] = encoding = self.config.html_output_encoding
+        ctx['encoding'] = self.config.html_output_encoding
         ctx['toctree'] = lambda **kw: self._get_local_toctree(pagename, **kw)
         self.add_sidebars(pagename, ctx)
         ctx.update(addctx)
         self.app.emit('html-page-context', pagename, templatename,
                       ctx, event_arg)
 
-        # Create a dict that will be pickled and used by webapps.
-        css = '<link rel="stylesheet" href="%s" type=text/css />' % \
-            pathto('_static/pygments.css', 1)
-        doc_ctx = {'body': ctx.get('body', ''),
-                   'title': ctx.get('title', ''),
-                   'css': css,
-                   'js': self._make_js(ctx)}
-        # Partially render the html template to proved a more useful ctx.
+        # create a dict that will be pickled and used by webapps
+        doc_ctx = {
+            'body': ctx.get('body', ''),
+            'title': ctx.get('title', ''),
+        }
+        # partially render the html template to get at interesting macros
         template = self.templates.environment.get_template(templatename)
         template_module = template.make_module(ctx)
-        if hasattr(template_module, 'sidebar'):
-            doc_ctx['sidebar'] = template_module.sidebar()
-        if hasattr(template_module, 'relbar'):
-            doc_ctx['relbar'] = template_module.relbar()
+        for item in ['sidebar', 'relbar', 'script', 'css']:
+            if hasattr(template_module, item):
+                doc_ctx[item] = getattr(template_module, item)()
+
+        return ctx, doc_ctx
+
+    def handle_page(self, pagename, addctx, templatename='page.html',
+                    outfilename=None, event_arg=None):
+        ctx, doc_ctx = self._render_page(pagename, addctx,
+                                         templatename, event_arg)
 
         if not outfilename:
             outfilename = path.join(self.outdir, 'pickles',
                                     os_path(pagename) + self.out_suffix)
-
         ensuredir(path.dirname(outfilename))
-        f = open(outfilename, 'wb')
-        try:
-            pickle.dump(doc_ctx, f, pickle.HIGHEST_PROTOCOL)
-        finally:
-            f.close()
+        self.dump_context(doc_ctx, outfilename)
 
         # if there is a source file, copy the source file for the
         # "show source" link
         if ctx.get('sourcename'):
-            source_name = path.join(self.app.builddir, self.app.staticdir,
+            source_name = path.join(self.staticdir,
                                     '_sources',  os_path(ctx['sourcename']))
             ensuredir(path.dirname(source_name))
             copyfile(self.env.doc2path(pagename), source_name)
 
     def handle_finish(self):
-        StandaloneHTMLBuilder.handle_finish(self)
+        # get global values for css and script files
+        _, doc_ctx = self._render_page('tmp', {}, 'page.html')
+        self.globalcontext['css'] = doc_ctx['css']
+        self.globalcontext['script'] = doc_ctx['script']
+
+        PickleHTMLBuilder.handle_finish(self)
         VersioningBuilderMixin.finish(self)
+
+        # move static stuff over to separate directory
         directories = ['_images', '_static']
         for directory in directories:
             src = path.join(self.outdir, directory)
-            dst = path.join(self.app.builddir, self.app.staticdir, directory)
+            dst = path.join(self.staticdir, directory)
             if path.isdir(src):
                 if path.isdir(dst):
                     shutil.rmtree(dst)
 
     def dump_search_index(self):
         self.indexer.finish_indexing()
-
-    def _make_js(self, ctx):
-        def make_script(file):
-            path = ctx['pathto'](file, 1)
-            return '<script type="text/javascript" src="%s"></script>' % path
-
-        opts = {
-            'URL_ROOT': ctx.get('url_root', ''),
-            'VERSION': ctx['release'],
-            'COLLAPSE_INDEX': False,
-            'FILE_SUFFIX': '',
-            'HAS_SOURCE': ctx['has_source']
-        }
-        scripts = [make_script(file) for file in ctx['script_files']]
-        scripts.append(make_script('_static/websupport.js'))
-        return '\n'.join([
-            '<script type="text/javascript">'
-            'var DOCUMENTATION_OPTIONS = %s;' % dump_json(opts),
-            '</script>'
-        ] + scripts)
         html_additional_pages = ({}, 'html'),
         html_use_modindex = (True, 'html'),  # deprecated
         html_domain_indices = (True, 'html'),
-        html_add_permalinks = (True, 'html'),
+        html_add_permalinks = (u'\u00B6', 'html'),
         html_use_index = (True, 'html'),
         html_split_index = (False, 'html'),
         html_copy_source = (True, 'html'),

sphinx/domains/c.py

                 self._parse_type(param, arg)
             else:
                 self._parse_type(param, ctype)
-                param += nodes.emphasis(' '+argname, ' '+argname)
+                # separate by non-breaking space in the output
+                param += nodes.emphasis(' '+argname, u'\xa0'+argname)
             paramlist += param
         signode += paramlist
         if const:

sphinx/domains/cpp.py

 from sphinx.util.compat import Directive
 
 
-_identifier_re = re.compile(r'\b(~?[a-zA-Z_][a-zA-Z0-9_]*)\b')
+_identifier_re = re.compile(r'(~?\b[a-zA-Z_][a-zA-Z0-9_]*)\b')
 _whitespace_re = re.compile(r'\s+(?u)')
 _string_re = re.compile(r"[LuU8]?('([^'\\]*(?:\\.[^'\\]*)*)'"
                         r'|"([^"\\]*(?:\\.[^"\\]*)*)")', re.S)
         return self.type.get_id()
 
     def __unicode__(self):
-        return (self.type is not None and u'%s %s' % (self.type, self.name)
-                or unicode(self.name)) + (self.default is not None and
-                                          u'=%s' % self.default or u'')
+        return (u'%s %s' % (self.type or u'', self.name or u'')).strip() + \
+               (self.default is not None and u'=%s' % self.default or u'')
 
 
 class NamedDefExpr(DefExpr):
         'mutable':      None,
         'const':        None,
         'typename':     None,
-        'unsigned':     set(('char', 'int', 'long')),
-        'signed':       set(('char', 'int', 'long')),
-        'short':        set(('int', 'short')),
+        'unsigned':     set(('char', 'short', 'int', 'long')),
+        'signed':       set(('char', 'short', 'int', 'long')),
+        'short':        set(('int',)),
         'long':         set(('int', 'long', 'double'))
     }
 
                     self.fail('expected comma between arguments')
                 self.skip_ws()
 
-            argname = self._parse_type()
-            argtype = default = None
+            argtype = self._parse_type()
+            argname = default = None
             self.skip_ws()
             if self.skip_string('='):
                 self.pos += 1
                 default = self._parse_default_expr()
             elif self.current_char not in ',)':
-                argtype = argname
                 argname = self._parse_name()
                 self.skip_ws()
                 if self.skip_string('='):

sphinx/domains/python.py

         TypedField('parameter', label=l_('Parameters'),
                    names=('param', 'parameter', 'arg', 'argument',
                           'keyword', 'kwarg', 'kwparam'),
-                   typerolename='obj', typenames=('paramtype', 'type')),
+                   typerolename='obj', typenames=('paramtype', 'type'),
+                   can_collapse=True),
         TypedField('variable', label=l_('Variables'), rolename='obj',
                    names=('var', 'ivar', 'cvar'),
-                   typerolename='obj', typenames=('vartype',)),
+                   typerolename='obj', typenames=('vartype',),
+                   can_collapse=True),
         GroupedField('exceptions', label=l_('Raises'), rolename='exc',
                      names=('raises', 'raise', 'exception', 'except'),
                      can_collapse=True),

sphinx/environment.py

         # fetch translations
         dirs = [path.join(env.srcdir, x)
                 for x in env.config.locale_dirs]
-        catalog, empty = init_locale(dirs, env.config.language, section)
-        if not empty:
+        catalog, has_catalog = init_locale(dirs, env.config.language, section)
+        if not has_catalog:
             return
 
         parser = RSTParser()
 
         for node, msg in extract_messages(self.document):
-            # XXX ctx not used
-            #ctx = node.parent
             patch = new_document(source, settings)
             msgstr = catalog.gettext(msg)
             # XXX add marker to untranslated parts
                 continue
             parser.parse(msgstr, patch)
             patch = patch[0]
-            assert isinstance(patch, nodes.paragraph)
+            #XXX doctest and other block markup
+            if not isinstance(patch, nodes.paragraph):
+                continue # skip for now
             for child in patch.children: # update leaves
                 child.parent = node
             node.children = patch.children
                 self.clear_doc(docname)
 
             # read all new and changed files
-            to_read = added | changed
-            for docname in sorted(to_read):
+            for docname in sorted(added | changed):
                 yield docname
                 self.read_doc(docname, app=app)
 

sphinx/ext/autodoc.py

         return getattr(self.reporter, name)
 
     def system_message(self, level, message, *children, **kwargs):
-        if 'line' in kwargs:
+        if 'line' in kwargs and 'source' not in kwargs:
             try:
                 source, line = self.viewlist.items[kwargs['line']]
             except IndexError:
             # etc. don't support a prepended module name
             self.add_line(u'   :module: %s' % self.modname, '<autodoc>')
 
-    def get_doc(self, encoding=None):
+    def get_doc(self, encoding=None, ignore=1):
         """Decode and return lines of the docstring(s) for the object."""
         docstring = self.get_attr(self.object, '__doc__', None)
         # make sure we have Unicode docstrings, then sanitize and split
         # into lines
         if isinstance(docstring, unicode):
-            return [prepare_docstring(docstring)]
+            return [prepare_docstring(docstring, ignore)]
         elif docstring:
-            return [prepare_docstring(force_decode(docstring, encoding))]
+            return [prepare_docstring(force_decode(docstring, encoding), ignore)]
         return []
 
     def process_doc(self, docstrings):
         if not no_docstring:
             encoding = self.analyzer and self.analyzer.encoding
             docstrings = self.get_doc(encoding)
+            if not docstrings:
+                # append at least a dummy docstring, so that the event
+                # autodoc-process-docstring is fired and can add some
+                # content if desired
+                docstrings.append([])
             for i, line in enumerate(self.process_doc(docstrings)):
                 self.add_line(line, sourcename, i)
 
 
         Members are skipped if
 
-        - they are private (except if given explicitly)
-        - they are undocumented (except if undoc-members is given)
+        - they are private (except if given explicitly or the private-members
+          option is set)
+        - they are special methods (except if given explicitly or the
+          special-members option is set)
+        - they are undocumented (except if the undoc-members option is set)
 
         The user can override the skipping decision by connecting to the
         ``autodoc-skip-member`` event.
             # if isattr is True, the member is documented as an attribute
             isattr = False
 
-            if want_all and membername.startswith('_'):
+            if want_all and membername.startswith('__') and \
+                   membername.endswith('__') and len(membername) > 4:
+                # special __methods__
+                skip = not self.options.special_members
+            elif want_all and membername.startswith('_'):
                 # ignore members whose name starts with _ by default
-                skip = True
+                skip = not self.options.private_members
             elif (namespace, membername) in attr_docs:
                 # keep documented attributes
                 skip = False
         # 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.add_line(u'', '')
+        self.add_line(u'', '<autodoc>')
 
         # format the object's signature, if any
         sig = self.format_signature()
         'show-inheritance': bool_option, 'synopsis': identity,
         'platform': identity, 'deprecated': bool_option,
         'member-order': identity, 'exclude-members': members_set_option,
+        'private-members': bool_option, 'special-members': bool_option,
     }
 
     @classmethod
         return modname, parents + [base]
 
 
-class FunctionDocumenter(ModuleLevelDocumenter):
+class DocstringSignatureMixin(object):
+    """
+    Mixin for FunctionDocumenter and MethodDocumenter to provide the
+    feature of reading the signature from the docstring.
+    """
+
+    def _find_signature(self, encoding=None):
+        docstrings = Documenter.get_doc(self, encoding, 2)
+        if len(docstrings) != 1:
+            return
+        doclines = docstrings[0]
+        setattr(self, '__new_doclines', doclines)
+        if not doclines:
+            return
+        # match first line of docstring against signature RE
+        match = py_ext_sig_re.match(doclines[0])
+        if not match:
+            return
+        exmod, path, base, args, retann = match.groups()
+        # the base name must match ours
+        if not self.objpath or base != self.objpath[-1]:
+            return
+        # ok, now jump over remaining empty lines and set the remaining
+        # lines as the new doclines
+        i = 1
+        while i < len(doclines) and not doclines[i].strip():
+            i += 1
+        setattr(self, '__new_doclines', doclines[i:])
+        return args, retann
+
+    def get_doc(self, encoding=None, ignore=1):
+        lines = getattr(self, '__new_doclines', None)
+        if lines is not None:
+            return [lines]
+        return Documenter.get_doc(self, encoding, ignore)
+
+    def format_signature(self):
+        if self.args is None and self.env.config.autodoc_docstring_signature:
+            # only act if a signature is not explicitly given already, and if
+            # the feature is enabled
+            result = self._find_signature()
+            if result is not None:
+                self.args, self.retann = result
+        return Documenter.format_signature(self)
+
+
+class FunctionDocumenter(DocstringSignatureMixin, ModuleLevelDocumenter):
     """
     Specialized Documenter subclass for functions.
     """
     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
+            # cannot introspect arguments of a C function or method
+            pass
         try:
             argspec = inspect.getargspec(self.object)
         except TypeError:
         'noindex': bool_option, 'inherited-members': bool_option,
         'show-inheritance': bool_option, 'member-order': identity,
         'exclude-members': members_set_option,
+        'private-members': bool_option, 'special-members': bool_option,
     }
 
     @classmethod
                 self.add_line(_(u'   Bases: %s') % ', '.join(bases),
                               '<autodoc>')
 
-    def get_doc(self, encoding=None):
+    def get_doc(self, encoding=None, ignore=1):
         content = self.env.config.autoclass_content
 
         docstrings = []
-        docstring = self.get_attr(self.object, '__doc__', None)
-        if docstring:
-            docstrings.append(docstring)
+        attrdocstring = self.get_attr(self.object, '__doc__', None)
+        if attrdocstring:
+            docstrings.append(attrdocstring)
 
         # for classes, what the "docstring" is can be controlled via a
         # config value; the default is only the class docstring
         pass
 
 
-class MethodDocumenter(ClassLevelDocumenter):
+class MethodDocumenter(DocstringSignatureMixin, ClassLevelDocumenter):
     """
     Specialized Documenter subclass for methods (normal, static and class).
     """
     _special_attrgetters = {}
 
     # flags that can be given in autodoc_default_flags
-    _default_flags = set(['members', 'undoc-members', 'inherited-members',
-                          'show-inheritance'])
+    _default_flags = set([
+        'members', 'undoc-members', 'inherited-members', 'show-inheritance',
+        'private-members', 'special-members',
+    ])
 
     # standard docutils directive settings
     has_content = True
     app.add_config_value('autoclass_content', 'class', True)
     app.add_config_value('autodoc_member_order', 'alphabetic', True)
     app.add_config_value('autodoc_default_flags', [], True)
+    app.add_config_value('autodoc_docstring_signature', True, True)
     app.add_event('autodoc-process-docstring')
     app.add_event('autodoc-process-signature')
     app.add_event('autodoc-skip-member')

sphinx/ext/doctest.py

                     test = code
                 code = doctestopt_re.sub('', code)
         nodetype = nodes.literal_block
-        if self.name == 'testsetup' or 'hide' in self.options:
+        if self.name in ('testsetup', 'testcleanup') or 'hide' in self.options:
             nodetype = nodes.comment
         if self.arguments:
             groups = [x.strip() for x in self.arguments[0].split(',')]
 class TestsetupDirective(TestDirective):
     option_spec = {}
 
+class TestcleanupDirective(TestDirective):
+    option_spec = {}
+
 class DoctestDirective(TestDirective):
     option_spec = {
         'hide': directives.flag,
         self.name = name
         self.setup = []
         self.tests = []
+        self.cleanup = []
 
     def add_code(self, code, prepend=False):
         if code.type == 'testsetup':
                 self.setup.insert(0, code)
             else:
                 self.setup.append(code)
+        elif code.type == 'testcleanup':
+            self.cleanup.append(code)
         elif code.type == 'doctest':
             self.tests.append([code])
         elif code.type == 'testcode':
             raise RuntimeError('invalid TestCode type')
 
     def __repr__(self):
-        return 'TestGroup(name=%r, setup=%r, tests=%r)' % (
-            self.name, self.setup, self.tests)
+        return 'TestGroup(name=%r, setup=%r, cleanup=%r, tests=%r)' % (
+            self.name, self.setup, self.cleanup, self.tests)
 
 
 class TestCode(object):
         self.total_tries = 0
         self.setup_failures = 0
         self.setup_tries = 0
+        self.cleanup_failures = 0
+        self.cleanup_tries = 0
 
         date = time.strftime('%Y-%m-%d %H:%M:%S')
 
 %5d test%s
 %5d failure%s in tests
 %5d failure%s in setup code
+%5d failure%s in cleanup code
 ''' % (self.total_tries, s(self.total_tries),
        self.total_failures, s(self.total_failures),
-       self.setup_failures, s(self.setup_failures)))
+       self.setup_failures, s(self.setup_failures),
+       self.cleanup_failures, s(self.cleanup_failures)))
         self.outfile.close()
 
-        if self.total_failures or self.setup_failures:
+        if self.total_failures or self.setup_failures or self.cleanup_failures:
             self.app.statuscode = 1
 
     def write(self, build_docnames, updated_docnames, method='update'):
                                                 optionflags=self.opt)
         self.test_runner = SphinxDocTestRunner(verbose=False,
                                                optionflags=self.opt)
+        self.cleanup_runner = SphinxDocTestRunner(verbose=False,
+                                                  optionflags=self.opt)
 
         self.test_runner._fakeout = self.setup_runner._fakeout
+        self.cleanup_runner._fakeout = self.setup_runner._fakeout
 
         if self.config.doctest_test_doctest_blocks:
             def condition(node):
                             'testsetup', lineno=0)
             for group in groups.itervalues():
                 group.add_code(code, prepend=True)
+        if self.config.doctest_global_cleanup:
+            code = TestCode(self.config.doctest_global_cleanup,
+                            'testcleanup', lineno=0)
+            for group in groups.itervalues():
+                group.add_code(code)
         if not groups:
             return
 
             res_f, res_t = self.test_runner.summarize(self._out, verbose=True)
             self.total_failures += res_f
             self.total_tries += res_t
+        if self.cleanup_runner.tries:
+            res_f, res_t = self.cleanup_runner.summarize(self._out, verbose=True)
+            self.cleanup_failures += res_f
+            self.cleanup_tries += res_t
 
     def compile(self, code, name, type, flags, dont_inherit):
         return compile(code, name, self.type, flags, dont_inherit)
 
     def test_group(self, group, filename):
         ns = {}
-        setup_examples = []
-        for setup in group.setup:
-            setup_examples.append(doctest.Example(setup.code, '',
-                                                  lineno=setup.lineno))
-        if setup_examples:
-            # simulate a doctest with the setup code
-            setup_doctest = doctest.DocTest(setup_examples, {},
-                                            '%s (setup code)' % group.name,
-                                            filename, 0, None)
-            setup_doctest.globs = ns
-            old_f = self.setup_runner.failures
+
+        def run_setup_cleanup(runner, testcodes, what):
+            examples = []
+            for testcode in testcodes:
+                examples.append(doctest.Example(testcode.code, '',
+                                                lineno=testcode.lineno))
+            if not examples:
+                return
+            # simulate a doctest with the code
+            sim_doctest = doctest.DocTest(examples, {},
+                                          '%s (%s code)' % (group.name, what),
+                                          filename, 0, None)
+            sim_doctest.globs = ns
+            old_f = runner.failures
             self.type = 'exec' # the snippet may contain multiple statements
-            self.setup_runner.run(setup_doctest, out=self._warn_out,
-                                  clear_globs=False)
-            if self.setup_runner.failures > old_f:
-                # don't run the group
-                return
+            runner.run(sim_doctest, out=self._warn_out, clear_globs=False)
+            if runner.failures > old_f:
+                return False
+            return True
+
+        # run the setup code
+        if not run_setup_cleanup(self.setup_runner, group.setup, 'setup'):
+            # if setup failed, don't run the group
+            return
+
+        # run the tests
         for code in group.tests:
             if len(code) == 1:
                 # ordinary doctests (code/output interleaved)
             # also don't clear the globs namespace after running the doctest
             self.test_runner.run(test, out=self._warn_out, clear_globs=False)
 
+        # run the cleanup
+        run_setup_cleanup(self.cleanup_runner, group.cleanup, 'cleanup')
+
 
 def setup(app):
     app.add_directive('testsetup', TestsetupDirective)
+    app.add_directive('testcleanup', TestcleanupDirective)
     app.add_directive('doctest', DoctestDirective)
     app.add_directive('testcode', TestcodeDirective)
     app.add_directive('testoutput', TestoutputDirective)
     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)
+    app.add_config_value('doctest_global_cleanup', '', False)

sphinx/ext/viewcode.py

             modname = signode.get('module')
             if not modname:
                 continue
-            fullname = signode['fullname']
+            fullname = signode.get('fullname')
             if not has_tag(modname, fullname, env.docname):
                 continue
             if fullname in names:

sphinx/locale/pl/LC_MESSAGES/sphinx.mo

Binary file modified.

sphinx/locale/pl/LC_MESSAGES/sphinx.po

 "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: 2010-08-26 11:45+0000\n"
-"Last-Translator: Michał Kandulski <Michal.Kandulski@poczta.onet.pl>\n"
+"PO-Revision-Date: 2010-12-17 13:36+0100\n"
+"Last-Translator: Michał Kandulski <michal.kandulski@gmail.com>\n"
 "Language-Team: \n"
 "Plural-Forms: nplurals=3; plural=(n==1 ? 0 : n%10>=2 && n%10<=4 && "
 "(n%100<10 || n%100>=20) ? 1 : 2)\n"
 #: sphinx/directives/other.py:139
 #, fuzzy
 msgid "Code author: "
-msgstr "Autor modułu: "
+msgstr "Autor kodu: "
 
 #: sphinx/directives/other.py:141
 msgid "Author: "
 #: sphinx/domains/__init__.py:242
 #, python-format
 msgid "%s %s"
-msgstr ""
+msgstr "%s %s"
 
 #: sphinx/domains/c.py:51 sphinx/domains/python.py:94
 msgid "Parameters"
 
 #: sphinx/domains/c.py:173
 msgid "macro"
-msgstr ""
+msgstr "makro"
 
 #: sphinx/domains/c.py:174 sphinx/domains/cpp.py:1041
 msgid "type"
 #: sphinx/domains/c.py:175
 #, fuzzy
 msgid "variable"
-msgstr "Zmienna"
+msgstr "zmienna"
 
 #: sphinx/domains/cpp.py:883
 #, python-format
 msgid "%s (C++ class)"
-msgstr "%s (klasie C++)"
+msgstr "%s (klasa C++)"
 
 #: sphinx/domains/cpp.py:898
 #, python-format
 #: sphinx/domains/cpp.py:1038 sphinx/domains/javascript.py:162
 #: sphinx/domains/python.py:525
 msgid "class"
-msgstr "klasie"
+msgstr "klasa"
 
 #: sphinx/domains/javascript.py:105 sphinx/domains/python.py:244
 #, python-format
 #: sphinx/domains/javascript.py:108
 #, fuzzy, python-format
 msgid "%s() (class)"
-msgstr "%s (klasie C++)"
+msgstr "%s() (klasa)"
 
 #: sphinx/domains/javascript.py:110
 #, python-format
 msgid "%s (global variable or constant)"
-msgstr ""
+msgstr "%s (zmienna lub stała globalna)"
 
 #: sphinx/domains/javascript.py:112 sphinx/domains/python.py:346
 #, python-format
 #: sphinx/domains/javascript.py:121
 #, fuzzy
 msgid "Arguments"
-msgstr "Parametry"
+msgstr "Argumenty"
 
 #: sphinx/domains/javascript.py:124
 msgid "Throws"
-msgstr ""
+msgstr "Wyrzuca"
 
 #: sphinx/domains/javascript.py:163 sphinx/domains/python.py:524
 msgid "data"
-msgstr ""
+msgstr "dane"
 
 #: sphinx/domains/javascript.py:164 sphinx/domains/python.py:530
 msgid "attribute"
 #: sphinx/domains/python.py:98
 #, fuzzy
 msgid "Variables"
-msgstr "Zmienna"
+msgstr "Zmienne"
 
 #: sphinx/domains/python.py:101
 msgid "Raises"
 #: sphinx/domains/python.py:266
 #, python-format
 msgid "%s (class in %s)"
-msgstr "%s (w klasie %s)"
+msgstr "%s (klasa w module %s)"
 
 #: sphinx/domains/python.py:306
 #, python-format
 #: sphinx/domains/python.py:318
 #, python-format
 msgid "%s() (%s.%s static method)"
-msgstr "%s() (%s.%s statyczna metoda)"
+msgstr "%s() (%s.%s metoda statyczna)"
 
 #: sphinx/domains/python.py:321
 #, python-format
 msgid "%s() (%s static method)"
-msgstr "%s() (%s statyczna metoda)"
+msgstr "%s() (%s metoda statyczna)"
 
 #: sphinx/domains/python.py:331
 #, fuzzy, python-format
 msgid "%s() (%s.%s class method)"
-msgstr "%s() (%s.%s metoda)"
+msgstr "%s() (%s.%s metoda klasy)"
 
 #: sphinx/domains/python.py:334
 #, fuzzy, python-format
 msgid "%s() (%s class method)"
-msgstr "%s() (%s metoda)"
+msgstr "%s() (%s metoda klasy)"
 
 #: sphinx/domains/python.py:344
 #, python-format
 msgid "%s (%s.%s attribute)"
-msgstr "%s (%s.%s atrybut)"
+msgstr "%s (atrybut %s.%s)"
 
 #: sphinx/domains/python.py:392
 msgid "Platforms: "
 #: sphinx/domains/python.py:455
 #, fuzzy
 msgid "Python Module Index"
-msgstr "Indeks modułów"
+msgstr "Indeks modułów pythona"
 
 #: sphinx/domains/python.py:456
 msgid "modules"
 
 #: sphinx/domains/python.py:527
 msgid "method"
-msgstr ""
+msgstr "metoda"
 
 #: sphinx/domains/python.py:528
 #, fuzzy
 msgid "class method"
-msgstr "%s() (%s metoda)"
+msgstr "metoda klasy"
 
 #: sphinx/domains/python.py:529
 msgid "static method"
 #: sphinx/domains/python.py:657
 #, fuzzy
 msgid " (deprecated)"
-msgstr "Niezalecane"
+msgstr " (niezalecane)"
 
 #: sphinx/domains/rst.py:55
 #, python-format
 msgid "%s (directive)"
-msgstr ""
+msgstr "%s (dyrektywa)"
 
 #: sphinx/domains/rst.py:57
 #, fuzzy, python-format
 msgid "%s (role)"
-msgstr "%s (moduł)"
+msgstr "%s (rola)"
 
 #: sphinx/domains/rst.py:106
 msgid "directive"
-msgstr ""
+msgstr "dyrektywa"
 
 #: sphinx/domains/rst.py:107
 #, fuzzy
 msgid "role"
-msgstr "moduł"
+msgstr "rola"
 
 #: sphinx/domains/std.py:68 sphinx/domains/std.py:84
 #, python-format
 
 #: sphinx/domains/std.py:328
 msgid "glossary term"
-msgstr ""
+msgstr "termin glosariusza"
 
 #: sphinx/domains/std.py:329
 msgid "grammar token"
-msgstr ""
+msgstr "symbol gramatyki"
 
 #: sphinx/domains/std.py:330
 msgid "reference label"
-msgstr ""
+msgstr "etykieta odsyłacza"
 
 #: sphinx/domains/std.py:331
 msgid "environment variable"
 
 #: sphinx/domains/std.py:332
 msgid "program option"
-msgstr ""
+msgstr "opcja programu"
 
 #: sphinx/domains/std.py:360 sphinx/themes/basic/genindex-single.html:11
 #: sphinx/themes/basic/genindex-split.html:11
 
 #: sphinx/ext/todo.py:41
 msgid "Todo"
-msgstr "Do zrobienia"
+msgstr "Todo"
 
 #: sphinx/ext/todo.py:109
 #, fuzzy, python-format
 msgid "(The <<original entry>> is located in  %s, line %d.)"
-msgstr ""
-"(Oryginalny wpis znajduje się w pliku %s, w linii %d i może być "
-"odnaleziony "
+msgstr "(<<Oryginalny wpis>> znajduje się w pliku %s, w linii %d.)"
 
 #: sphinx/ext/todo.py:117
 msgid "original entry"
-msgstr ""
+msgstr "oryginalny wpis"
 
 #: sphinx/ext/viewcode.py:70
 msgid "[source]"
-msgstr ""
+msgstr "[źródło]"
 
 #: sphinx/ext/viewcode.py:117
 msgid "[docs]"
-msgstr ""
+msgstr "[dokumenty]"
 
 #: sphinx/ext/viewcode.py:131
 #, fuzzy
 msgid "Module code"
-msgstr "moduł"
+msgstr "Kod modułu"
 
 #: sphinx/ext/viewcode.py:137
 #, python-format
 msgid "<h1>Source code for %s</h1>"
-msgstr ""
+msgstr "<h1>Kod źródłowy modułu %s</h1>"
 
 #: sphinx/ext/viewcode.py:164
 msgid "Overview: module code"
-msgstr ""
+msgstr "Przeglądanie: kod modułu"
 
 #: sphinx/ext/viewcode.py:165
 msgid "<h1>All modules for which code is available</h1>"
-msgstr ""
+msgstr "<h1>Wszystkie moduły, dla których jest dostępny kod</h1>"
 
 #: sphinx/locale/__init__.py:155
 msgid "Attention"
 
 #: sphinx/themes/basic/defindex.html:24
 msgid "lists all sections and subsections"
-msgstr "wymień wszystkie rozdziały i podrozdziały"
+msgstr "wszystkie rozdziały i podrozdziały"
 
 #: sphinx/themes/basic/defindex.html:26
 msgid "search this documentation"
-msgstr "wyszukaj w dokumentacji"
+msgstr "przyszukaj  dokumentację"
 
 #: sphinx/themes/basic/defindex.html:28
 msgid "Global Module Index"
-msgstr "Indeks modułów"
+msgstr "Globalny indeks modułów"
 
 #: sphinx/themes/basic/defindex.html:29
 msgid "quick access to all modules"
 
 #: sphinx/themes/basic/search.html:36
 msgid "search"
-msgstr "Szukaj"
+msgstr "szukaj"
 
 #: sphinx/themes/basic/search.html:40
 #: sphinx/themes/basic/static/searchtools.js:504
 "are spelled correctly and that you've selected enough categories."
 msgstr ""
 "Nie znaleziono żadnych pasujących dokumentów. Upewnij się, że wszystkie "
-"słowa są poprawnie wpisane i że wybrałeś wystarczającąliczbę kategorii."
+"słowa są poprawnie wpisane i że wybrałeś wystarczającą liczbę kategorii."
 
 #: sphinx/themes/basic/static/searchtools.js:508
 #, python-format
 
 #: sphinx/themes/default/static/sidebar.js:66
 msgid "Expand sidebar"
-msgstr ""
+msgstr "Rozwiń pasek boczny"
 
 #: sphinx/themes/default/static/sidebar.js:79
 #: sphinx/themes/default/static/sidebar.js:107
 msgid "Collapse sidebar"
-msgstr ""
+msgstr "Zwiń pasek boczny"
 
 #: sphinx/themes/haiku/layout.html:26
 msgid "Contents"
-msgstr ""
+msgstr "Treść"
 
 #: sphinx/writers/latex.py:172
 msgid "Release"
 
 #: sphinx/writers/text.py:422
 msgid "[image]"
-msgstr "[obrazek]"
+msgstr "[obraz]"
 

sphinx/pycode/pgen2/driver.py

         head, tail = os.path.splitext(gt)
         if tail == ".txt":
             tail = ""
-        gp = head + tail + ".".join(map(str, sys.version_info)) + ".pickle"
+        gp = head + tail + ".".join(map(str, sys.version_info[:2])) + ".pickle"
     if force or not _newer(gp, gt):
         logger.info("Generating grammar tables from %s", gt)
         g = pgen.generate_grammar(gt)

sphinx/quickstart.py

     if not color_terminal():
         nocolor()
 
+    if len(args) > 3:
+        print 'Usage: sphinx-quickstart [root]'
+        sys.exit(1)
+    elif len(args) == 2:
+        d['path'] = args[1]
+
     print bold('Welcome to the Sphinx %s quickstart utility.') % __version__
     print '''
 Please enter values for the following settings (just press Enter to
 accept a default value, if one is given in brackets).'''
 
-    print '''
+    if 'path' in d:
+        print bold('''
+Selected root path: %s''' % d['path'])
+    else:
+        print '''
 Enter the root path for documentation.'''
-    do_prompt(d, 'path', 'Root path for the documentation', '.', is_path)
+        do_prompt(d, 'path', 'Root path for the documentation', '.', is_path)
 
     while path.isfile(path.join(d['path'], 'conf.py')) or \
           path.isfile(path.join(d['path'], 'source', 'conf.py')):

sphinx/setup_command.py

             build = self.get_finalized_command('build')
             self.build_dir = os.path.join(build.build_base, 'sphinx')
             self.mkpath(self.build_dir)
-        self.ensure_dirname('build_dir')
         self.doctree_dir = os.path.join(self.build_dir, 'doctrees')
         self.mkpath(self.doctree_dir)
         self.builder_target_dir = os.path.join(self.build_dir, self.builder)

sphinx/texinputs/Makefile

 all-dvi: $(ALLDVI)
 all-ps: all-dvi
 	for f in *.dvi; do dvips $$f; done
+all-pdf-ja: $(wildcard *.tex)
+	ebb $(wildcard *.pdf *.png *.gif *.jpeg)
+	platex -kanji=utf8 $(LATEXOPTS) '$<'
+	platex -kanji=utf8 $(LATEXOPTS) '$<'
+	platex -kanji=utf8 $(LATEXOPTS) '$<'
+	-mendex -U -f -d '$(basename $<).dic' -s python.ist '$(basename $<).idx'
+	platex -kanji=utf8 $(LATEXOPTS) '$<'
+	platex -kanji=utf8 $(LATEXOPTS) '$<'
+	dvipdfmx '$(basename $<).dvi'
 
 zip: all-$(FMT)
 	mkdir $(ARCHIVEPREFIX)docs-$(FMT)
 	pdflatex $(LATEXOPTS) '$<'
 
 clean:
-	rm -f *.pdf *.dvi *.ps
-	rm -f *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla
+	rm -f *.dvi *.log *.ind *.aux *.toc *.syn *.idx *.out *.ilg *.pla
 
 .PHONY: all all-pdf all-dvi all-ps clean
 

sphinx/themes/agogo/static/agogo.css_t

 
 /* Styles copied from basic theme */
 
+img.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
+.align-left {
+    text-align: left;
+}
+
+.align-center {
+    clear: both;
+    text-align: center;
+}
+
+.align-right {
+    text-align: right;
+}
+
 /* -- search page ----------------------------------------------------------- */
 
 ul.search {

sphinx/themes/basic/layout.html

 {%- set render_sidebar = (not embedded) and (not theme_nosidebar|tobool) and
                          (sidebars != []) %}
 {%- set url_root = pathto('', 1) %}
+{# XXX necessary? #}
 {%- if url_root == '#' %}{% set url_root = '' %}{% endif %}
+{%- if not embedded and docstitle %}
+  {%- set titlesuffix = " &mdash; "|safe + docstitle|e %}
+{%- else %}
+  {%- set titlesuffix = "" %}
+{%- endif %}
 
 {%- macro relbar() %}
     <div class="related">
       {%- endif %}
 {%- endmacro %}
 
-<html xmlns="http://www.w3.org/1999/xhtml">
-  <head>
-    <meta http-equiv="Content-Type" content="text/html; charset={{ encoding }}" />
-    {{ metatags }}
-    {%- if not embedded and docstitle %}
-      {%- set titlesuffix = " &mdash; "|safe + docstitle|e %}
-    {%- else %}
-      {%- set titlesuffix = "" %}
-    {%- endif %}
-    {%- block htmltitle %}
-    <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
-    {%- endblock %}
-    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
-    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
-    {%- for cssfile in css_files %}
-    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
-    {%- endfor %}
-    {%- if not embedded %}
+{%- macro script() %}
     <script type="text/javascript">
       var DOCUMENTATION_OPTIONS = {
         URL_ROOT:    '{{ url_root }}',
     {%- for scriptfile in script_files %}
     <script type="text/javascript" src="{{ pathto(scriptfile, 1) }}"></script>
     {%- endfor %}
+{%- endmacro %}
+
+{%- macro css() %}
+    <link rel="stylesheet" href="{{ pathto('_static/' + style, 1) }}" type="text/css" />
+    <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
+    {%- for cssfile in css_files %}
+    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+    {%- endfor %}
+{%- endmacro %}
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset={{ encoding }}" />
+    {{ metatags }}
+    {%- block htmltitle %}
+    <title>{{ title|striptags|e }}{{ titlesuffix }}</title>
+    {%- endblock %}
+    {{ css() }}
+    {%- if not embedded %}
+    {{ script() }}
     {%- if use_opensearch %}
     <link rel="search" type="application/opensearchdescription+xml"
           title="{% trans docstitle=docstitle|e %}Search within {{ docstitle }}{% endtrans %}"

sphinx/themes/basic/searchresults.html

 {#
     basic/searchresults.html
-    ~~~~~~~~~~~~~~~~~
+    ~~~~~~~~~~~~~~~~~~~~~~~~
 
     Template for the body of the search results page.
 
   <input type="submit" value="search" />
   <span id="search-progress" style="padding-left: 10px"></span>
 </form>
-{% if search_performed %}
-<h2>Search Results</h2>
-{% if not search_results %}
-<p>Your search did not match any results.</p>
-{% endif %}
-{% endif %}
+{%- if search_performed %}
+  <h2>Search Results</h2>
+  {%- if not search_results %}
+  <p>Your search did not match any results.</p>
+  {%- endif %}
+{%- endif %}
 <div id="search-results">
-  {% if search_results %}
+  {%- if search_results %}
   <ul class="search">
     {% for href, caption, context in search_results %}
-    <li><a href="{{ href }}?highlight={{ q }}">{{ caption }}</a>
+    <li><a href="{{ docroot }}{{ href }}/?highlight={{ q }}">{{ caption }}</a>
       <div class="context">{{ context|e }}</div>
     </li>
     {% endfor %}
   </ul>
-  {% endif %}
+  {%- endif %}
 </div>

sphinx/themes/basic/static/basic.css

     font-weight: bold;
 }
 
+img.align-left, .figure.align-left, object.align-left {
+    clear: left;
+    float: left;
+    margin-right: 1em;
+}
+
+img.align-right, .figure.align-right, object.align-right {
+    clear: right;
+    float: right;
+    margin-left: 1em;
+}
+
+img.align-center, .figure.align-center, object.align-center {
+  display: block;
+  margin-left: auto;
+  margin-right: auto;
+}
+
 .align-left {
     text-align: left;
 }

sphinx/themes/basic/static/websupport.js

+/*
+ * websupport.js
+ * ~~~~~~~~~~~~~
+ *
+ * sphinx.websupport utilties for all documentation.
+ *
+ * :copyright: Copyright 2007-2010 by the Sphinx team, see AUTHORS.
+ * :license: BSD, see LICENSE for details.
+ *
+ */
+
 (function($) {
-  $.fn.autogrow = function(){
-    return this.each(function(){
+  $.fn.autogrow = function() {
+    return this.each(function() {
     var textarea = this;
 
     $.fn.autogrow.resize(textarea);
   }
 
   function initEvents() {
-    $('a.comment_close').live("click", function(event) {
+    $('a.comment-close').live("click", function(event) {
+      event.preventDefault();
       hide($(this).attr('id').substring(2));
-      return false;
     });
-    $('.vote').live("click", function() {
+    $('a.vote').live("click", function(event) {
+      event.preventDefault();
       handleVote($(this));
-      return false;
     });
-    $('a.reply').live("click", function() {
+    $('a.reply').live("click", function(event) {
+      event.preventDefault();
       openReply($(this).attr('id').substring(2));
-      return false;
     });
-    $('a.close_reply').live("click", function() {
+    $('a.close-reply').live("click", function(event) {
+      event.preventDefault();
       closeReply($(this).attr('id').substring(2));
-      return false;
     });
-    $('a.sort_option').live("click", function(event) {
+    $('a.sort-option').live("click", function(event) {
+      event.preventDefault();
       handleReSort($(this));
-      return false;
     });
-    $('a.show_proposal').live("click", function() {
+    $('a.show-proposal').live("click", function(event) {
+      event.preventDefault();
       showProposal($(this).attr('id').substring(2));
-      return false;
     });
-    $('a.hide_proposal').live("click", function() {
+    $('a.hide-proposal').live("click", function(event) {
+      event.preventDefault();
       hideProposal($(this).attr('id').substring(2));
-      return false;
     });
-    $('a.show_propose_change').live("click", function() {
+    $('a.show-propose-change').live("click", function(event) {
+      event.preventDefault();
       showProposeChange($(this).attr('id').substring(2));
-      return false;
     });
-    $('a.hide_propose_change').live("click", function() {
+    $('a.hide-propose-change').live("click", function(event) {
+      event.preventDefault();
       hideProposeChange($(this).attr('id').substring(2));
-      return false;
     });
-    $('a.accept_comment').live("click", function() {
+    $('a.accept-comment').live("click", function(event) {
+      event.preventDefault();
       acceptComment($(this).attr('id').substring(2));
-      return false;
     });
-    $('a.reject_comment').live("click", function() {
-      rejectComment($(this).attr('id').substring(2));
-      return false;
+    $('a.delete-comment').live("click", function(event) {
+      event.preventDefault();
+      deleteComment($(this).attr('id').substring(2));
     });
-    $('a.delete_comment').live("click", function() {
-      deleteComment($(this).attr('id').substring(2));
-      return