merge with stable

CHANGES

@@ -27,12 +27,12 @@ Bugs fixed
 
 * #1337: Fix autodoc with ``autoclass_content="both"`` uses useless
   ``object.__init__`` docstring when class does not have ``__init__``.
-  This caused by a change for #1138.
+  This was caused by a change for #1138.
 
 * #1340: Can't search alphabetical words on the HTML quick search generated
   with language='ja'.
 
-* #1319: Do not crash if the ``html_logo`` file does not exist.
+* #1319: Do not crash if the :confval:`html_logo` file does not exist.
 
 * #603: Do not use the HTML-ized title for building the search index (that
   resulted in "literal" being found on every page with a literal in the
@@ -47,8 +47,8 @@ Bugs fixed
 
 * #932: autodoc: Do not crash if ``__doc__`` is not a string.
 
-* #933: Do not crash if an ``:option:`` value is malformed (contains spaces
-  but no option name).
+* #933: Do not crash if an :rst:role:`option` value is malformed (contains
+  spaces but no option name).
 
 * #908: On Python 3, handle error messages from LaTeX correctly in the pngmath
   extension.
@@ -58,7 +58,7 @@ Bugs fixed
 
 * #923: Take the entire LaTeX document into account when caching
   pngmath-generated images.  This rebuilds them correctly when
-  ``pngmath_latex_preamble`` changes.
+  :confval:`pngmath_latex_preamble` changes.
 
 * #901: Emit a warning when using docutils' new "math" markup without a Sphinx
   math extension active.
@@ -68,6 +68,21 @@ Bugs fixed
 
 * #929: Support parsed-literal blocks in LaTeX output correctly.
 
+* #949: Update the tabulary.sty packed with Sphinx.
+
+* #1050: Add anonymous labels into ``objects.inv`` to be referenced via
+  :mod:`~sphinx.ext.intersphinx`.
+
+* #1095: Fix print-media stylesheet being included always in the "scrolls"
+  theme.
+
+* #1085: Fix current classname not getting set if class description has
+  ``:noindex:`` set.
+
+* #1181: Report option errors in autodoc directives more gracefully.
+
+* #1155: Fix autodocumenting C-defined methods as attributes in Python 3.
+
 Documentation
 -------------
 

doc/_templates/index.html

@@ -21,7 +21,7 @@
   </p>
   <ul>
     <li>{%trans%}<b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for
-      printable PDF versions), Texinfo, manual pages, plain text{%endtrans%}</li>
+      printable PDF versions), ePub, Texinfo, manual pages, plain text{%endtrans%}</li>
     <li>{%trans%}<b>Extensive cross-references:</b> semantic markup and automatic links
       for functions, classes, citations, glossary terms and similar pieces of
       information{%endtrans%}</li>
@@ -85,7 +85,16 @@
     of this documentation, thanks to the Japanese Sphinx user group.{%endtrans%}</p>
   <p>{%trans%}A Japanese book about Sphinx has been published by O'Reilly:
     <a href="http://www.oreilly.co.jp/books/9784873116488/">Sphinxをはじめよう /
-      Learning Sphinx</a>:{%endtrans%}</p>
-  <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p>
+      Learning Sphinx</a>.{%endtrans%}</p>
+  <!-- <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p> -->
+
+
+  <h2>{%trans%}Hosting{%endtrans%}</h2>
+
+  <p>{%trans%}Need a place to host your Sphinx docs?
+    <a href="http://readthedocs.org">readthedocs.org</a> hosts a lot of Sphinx docs
+    already, and integrates well with projects' source control.  It also features a
+    powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based
+    offline search.{%endtrans%}</p>
 
 {% endblock %}

doc/config.rst

@@ -472,8 +472,8 @@ that use Sphinx' HTMLWriter class.
    The "title" for HTML documentation generated with Sphinx' own templates.
    This is appended to the ``<title>`` tag of individual pages, and used in the
    navigation bar as the "topmost" element.  It defaults to :samp:`'{<project>}
-   v{<revision>} documentation'`, where the placeholders are replaced by the
-   config values of the same name.
+   v{<revision>} documentation'` (with the values coming from the config
+   values).
 
 .. confval:: html_short_title
 

doc/intro.rst

@@ -16,6 +16,10 @@ Though there is support for that kind of docs as well (which is intended to be
 freely mixed with hand-written content), if you need pure API docs have a look
 at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST.
 
+For a great "introduction" to writing docs in general -- the whys and hows, see
+also `Write the docs <http://write-the-docs.readthedocs.org/>`_, written by Eric
+Holscher.
+
 
 Conversion from other systems
 -----------------------------
@@ -66,12 +70,3 @@ Usage
 
 See :doc:`tutorial` for an introduction.  It also contains links to more
 advanced sections in this manual for the topics it discusses.
-
-
-Hosting
--------
-
-Need a place to host your Sphinx docs? `readthedocs.org
-<http://readthedocs.org>`_ hosts a lot of Sphinx docs already, and integrates
-well with projects' source control.  It also features a powerful built-in search
-that exceeds the possibilities of Sphinx' JavaScript-based offline search.

doc/man/sphinx-build.rst

@@ -32,6 +32,13 @@ List of available builders:
 html
    HTML file generation.  This is the default builder.
 
+dirhtml
+   HTML file generation with every HTML file named "index.html" in a separate
+   directory.
+
+singlehtml
+   HTML file generation with all content in a single HTML file.
+
 htmlhelp
    Generates files for CHM (compiled help files) generation.
 
@@ -51,9 +58,15 @@ texinfo
    Generates Texinfo output that can be processed by :program:`makeinfo` to
    generate an Info document.
 
+epub
+   Generates an ePub e-book version of the HTML output.
+
 text
    Generates a plain-text version of the documentation.
 
+gettext
+   Generates Gettext message catalogs for content translation.
+
 changes
    Generates HTML files listing changed/added/deprecated items for
    the current version of the documented project.
@@ -81,20 +94,24 @@ Options
                       output for new and changed files is generated.
 -E                    Ignore cached files, forces to re-read all source files
                       from disk.
+-d <path>             Path to cached files; defaults to <outdir>/.doctrees.
+-j <N>                Build in parallel with N processes where possible.
 -c <path>             Locate the conf.py file in the specified path instead of
                       <sourcedir>.
 -C                    Specify that no conf.py file at all is to be used.
                       Configuration can only be set with the -D option.
 -D <setting=value>    Override a setting from the configuration file.
--d <path>             Path to cached files; defaults to <outdir>/.doctrees.
+-t <tag>              Define *tag* for use in "only" blocks.
 -A <name=value>       Pass a value into the HTML templates (only for HTML builders).
 -n                    Run in nit-picky mode, warn about all missing references.
+-v                    Increase verbosity (can be repeated).
 -N                    Prevent colored output.
 -q                    Quiet operation, just print warnings and errors on stderr.
 -Q                    Very quiet operation, don't print anything except for errors.
 -w <file>             Write warnings and errors into the given file, in addition
                       to stderr.
 -W                    Turn warnings into errors.
+-T                    Show full traceback on exception.
 -P                    Run Pdb on exception.
 
 

doc/markup/toctree.rst

@@ -68,8 +68,8 @@ tables of contents.  The ``toctree`` directive is the central element.
 
    **Section numbering**
 
-   If you want to have section numbers even in HTML output, give the toctree a
-   ``numbered`` option.  For example::
+   If you want to have section numbers even in HTML output, give the
+   **toplevel** toctree a ``numbered`` option.  For example::
 
       .. toctree::
          :numbered:

doc/rest.rst

@@ -373,6 +373,8 @@ For instance, if the file name ``gnu.*`` was given and two files :file:`gnu.pdf`
 and :file:`gnu.png` existed in the source tree, the LaTeX builder would choose
 the former, while the HTML builder would prefer the latter.
 
+Note that image file names should not contain spaces.
+
 .. versionchanged:: 0.4
    Added the support for file names ending in an asterisk.
 

doc/templating.rst

@@ -251,7 +251,8 @@ in the future.
 
 .. data:: docstitle
 
-   The title of the documentation (the value of :confval:`html_title`).
+   The title of the documentation (the value of :confval:`html_title`), except
+   when the "single-file" builder is used, when it is set to ``None``.
 
 .. data:: embedded
 

sphinx/builders/html.py

@@ -620,6 +620,7 @@ class StandaloneHTMLBuilder(Builder):
                 self.warn('html_extra_path entry %r does not exist' % entry)
                 continue
             copy_static_entry(entry, self.outdir, self)
+        self.info('done')
 
     def write_buildinfo(self):
         # write build info file

sphinx/directives/__init__.py

@@ -149,11 +149,12 @@ class ObjectDescription(Directive):
                 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
+            if name not in self.names:
                 self.names.append(name)
-                self.add_target_and_index(name, sig, signode)
+                if not noindex:
+                    # only add target and index entry if this is the first
+                    # description of the object with this name in this desc block
+                    self.add_target_and_index(name, sig, signode)
 
         contentnode = addnodes.desc_content()
         node.append(contentnode)

sphinx/domains/std.py

@@ -612,6 +612,11 @@ class StandardDomain(Domain):
                    self.object_types[type].attrs['searchprio'])
         for name, info in self.data['labels'].iteritems():
             yield (name, info[2], 'label', info[0], info[1], -1)
+        # add anonymous-only labels as well
+        non_anon_labels = set(self.data['labels'])
+        for name, info in self.data['anonlabels'].iteritems():
+            if name not in non_anon_labels:
+                yield (name, name, 'label', info[0], info[1], -1)
 
     def get_type_name(self, type, primary=False):
         # never prepend "Default"

sphinx/ext/autodoc.py

@@ -1244,7 +1244,8 @@ class AttributeDocumenter(ClassLevelDocumenter):
     def can_document_member(cls, member, membername, isattr, parent):
         isdatadesc = isdescriptor(member) and not \
                      isinstance(member, cls.method_types) and not \
-                     type(member).__name__ in ("type", "method_descriptor")
+                     type(member).__name__ in ("type", "method_descriptor",
+                                               "instancemethod")
         return isdatadesc or (not isinstance(parent, ModuleDocumenter)
                               and not inspect.isroutine(member)
                               and not isinstance(member, class_types))
@@ -1384,8 +1385,15 @@ class AutoDirective(Directive):
                not negated:
                 self.options[flag] = None
         # process the options with the selected documenter's option_spec
-        self.genopt = Options(assemble_option_dict(
-            self.options.items(), doc_class.option_spec))
+        try:
+            self.genopt = Options(assemble_option_dict(
+                self.options.items(), doc_class.option_spec))
+        except (KeyError, ValueError, TypeError), err:
+            # an option is either unknown or has a wrong type
+            msg = self.reporter.error('An option to %s is either unknown or '
+                                      'has an invalid value: %s' % (self.name, err),
+                                      line=self.lineno)
+            return [msg]
         # generate the output
         documenter = doc_class(self, self.arguments[0])
         documenter.generate(more_content=self.content)

sphinx/texinputs/tabulary.sty

@@ -8,13 +8,13 @@
 %% DRAFT VERSION
 %%
 %% File `tabulary.dtx'.
-%% Copyright (C) 1995 1996 2003 David Carlisle
+%% Copyright (C) 1995 1996 2003 2008 David Carlisle
 %% This file may be distributed under the terms of the LPPL.
 %% See 00readme.txt for details.
 %%
 \NeedsTeXFormat{LaTeX2e}
 \ProvidesPackage{tabulary}
-          [2007/10/02 v0.9 tabulary package (DPC)]
+          [2008/12/01 v0.9 tabulary package (DPC)]
 \RequirePackage{array}
 \catcode`\Z=14
 \DeclareOption{debugshow}{\catcode`\Z=9\relax}
@@ -109,8 +109,6 @@ Z        \string\tymax: \the\tymax^^J}%
   \global\advance\TY@linewidth-#1\relax}
 \def\endtabulary{%
   \gdef\@halignto{}%
-  \let\TY@footnote\footnote%
-  \def\footnote{}% prevent footnotes from doing anything
   \expandafter\TY@tab\the\toks@
   \crcr\omit
   {\xdef\TY@save@row{}%
@@ -174,7 +172,6 @@ Z        \message{> tymin}%
     \TY@checkmin
     \TY@count\z@
     \let\TY@box\TY@box@v
-    \let\footnote\TY@footnote % restore footnotes
   {\expandafter\TY@final\the\toks@\endTY@final}%
   \count@\z@
   \@tempswatrue
@@ -195,7 +192,7 @@ Z        \message{> tymin}%
   \let\TY@checkmin\relax
 \ifdim\TY@tablewidth>\z@
   \Gscale@div\TY@ratio\TY@linewidth\TY@tablewidth
- \ifdim\TY@tablewidth <\linewidth
+ \ifdim\TY@tablewidth <\TY@linewidth
    \def\TY@ratio{1}%
  \fi
 \else

sphinx/themes/haiku/layout.html

@@ -8,8 +8,6 @@
     :license: BSD, see LICENSE for details.
 #}
 {%- extends "basic/layout.html" %}
-{% set script_files = script_files + ['_static/theme_extras.js'] %}
-{% set css_files = css_files + ['_static/print.css'] %}
 
 {# do not display relbars #}
 {% block relbar1 %}{% endblock %}

sphinx/themes/scrolls/static/print.css

@@ -1,5 +1,7 @@
-div.header, div.relnav, #toc { display: none; }
-#contentwrapper { padding: 0; margin: 0; border: none; }
-body { color: black; background-color: white; }
-div.footer { border-top: 1px solid #888; color: #888; margin-top: 1cm; }
-div.footer a { text-decoration: none; }
+@media print {
+    div.header, div.relnav, #toc { display: none; }
+    #contentwrapper { padding: 0; margin: 0; border: none; }
+    body { color: black; background-color: white; }
+    div.footer { border-top: 1px solid #888; color: #888; margin-top: 1cm; }
+    div.footer a { text-decoration: none; }
+}