Takayuki Shimizukawa avatar Takayuki Shimizukawa committed 5091e0d Draft Merge

merge heads

Comments (0)

Files changed (157)

+language: python
+python:
+  - "2.7"
+  - "3.3"
+script: make test
+install:
+  - python setup.py -q install
 Release 1.2 (in development)
 ============================
 
+* PR#25: In inheritance diagrams, the first line of the class docstring
+  is now the tooltip for the class.
+
+* PR#47: Added :mod:`sphinx.ext.linkcode` extension.
+
+* PR#75: Added ``--follow-links`` option to sphinx-apidoc.
+
 * PR#45: The linkcheck builder now checks ``#anchor``\ s for existence.
 
 * PR#28: Added Hungarian translation.
 
 * PR#54: Added Norwegian bokmaal translation.
 
+* PR#52: ``special_members`` flag to autodoc now behaves like ``members``.
+
+* #955: Fix i18n transformation.
+
+* Handle duplicate domain indices in texinfo.
+
+* PR#74: Fix some Russian translation.
+
 * Update to jQuery 1.7.1 and Underscore.js 1.3.1.
 
-
-Release 1.1.4 (in development)
-==============================
+* #1015: Stop overriding jQuery contains() in the JavaScript.
+
+* #1028: Fix line block output in the text builder.
+
+* #1018: Fix "container" directive handling in the text builder.
+
+* #1012: Update Estonian translation.
+
+* #1010: Make pngmath images transparent by default; IE7+ should handle it.
+
+* #440: Fix coarse timestamp resolution in some filesystem generate wrong outdated file-list.
+
+* #1008: Fix test failures with Python 3.3.
+
+* #1029: Fix intersphinx_mapping values are not stable if mapping have plural key/value set with Python 3.3.
+
+* #920: Rescue PIL packaging issue that allow import Image without PIL namespace. Thanks to Marc Schlaich.
+
+* #1024: Improve Makefile/make.bat error message if Sphinx is not found. Thanks to anatoly techtonik.
+
+* #1037: Fix typos in Polish translation. Thanks to Jakub Wilk.
+
+* #1038: Fix cpp domain parser fails to parse C+11 "static constexpr" declarations. Thanks to Jakub Wilk.
+
+* #1043: Fix sphinx-quickstart asks again and again Y|N because input() return value with extra '\r' on Python-3.2.0 + Windows. Thanks to Régis Décamps.
+
+* #1041: Fix cpp domain parser fails to parse a const type with a modifier.
+
+* PR#88: Added the "Sphinx Developer's Guide" (:file:`doc/devguide.rst`)
+  which outlines the basic development process of the Sphinx project.
+
+* Added the Docutils-native XML and pseudo-XML builders.  See
+  :class:`XMLBuilder` and :class:`PseudoXMLBuilder`.
 
 
 Release 1.1.3 (Mar 10, 2012)
 This is an (incomplete) alphabetic list of projects that use Sphinx or
 are experimenting with using it for their documentation.  If you like to
 be included, please mail to `the Google group
-<http://groups.google.com/group/sphinx-dev>`_.
+<http://groups.google.com/group/sphinx-users>`_.
 
 I've grouped the list into sections to make it easier to find
 interesting examples.
 * Chaco: http://code.enthought.com/projects/chaco/docs/html/
 * Djagios: http://djagios.org/
 * GetFEM++: http://home.gna.org/getfem/
+* Google or-tools: https://or-tools.googlecode.com/svn/trunk/documentation/user_manual/index.html
 * GPAW: https://wiki.fysik.dtu.dk/gpaw/
 * Grok: http://grok.zope.org/doc/current/
 * IFM: http://fluffybunny.memebot.com/ifm-docs/index.html
   http://www.tango-controls.org/static/PyTango/latest/doc/html/index.html
 * Reteisi: http://www.reteisi.org/contents.html
 * Satchmo: http://www.satchmoproject.com/docs/dev/
-* Sphinx: http://sphinx.pocoo.org/
+* Sphinx: http://sphinx-doc.org/
 * Sqlkit: http://sqlkit.argolinux.org/
 * Tau: http://www.tango-controls.org/static/tau/latest/doc/html/index.html
 * Total Open Station: http://tops.berlios.de/
+* Turbulenz: http://docs.turbulenz.com/
 * WebFaction: http://docs.webfaction.com/
 
 
   (agogo)
 * Sylli: http://sylli.sourceforge.net/ (nature)
 * libLAS: http://liblas.org/ (nature)
+* Valence: http://docs.valence.desire2learn.com/ (haiku)
 
 
 Documentation using a custom theme/integrated in a site
 
 * Blender: http://www.blender.org/documentation/250PythonDoc/
 * Blinker: http://discorporate.us/projects/Blinker/docs/
-* Classy: classy: http://classy.pocoo.org/
+* Classy: http://classy.pocoo.org/
+* DEAP: http://deap.gel.ulaval.ca/doc/0.8/index.html
 * Django: http://docs.djangoproject.com/
 * e-cidadania: http://e-cidadania.readthedocs.org/en/latest/
 * Flask: http://flask.pocoo.org/docs/
 * Gameduino: http://excamera.com/sphinx/gameduino/
 * GeoServer: http://docs.geoserver.org/
 * Glashammer: http://glashammer.org/
+* Istihza (Turkish Python documentation project): http://www.istihza.com/py2/icindekiler_python.html
+* MathJax: http://docs.mathjax.org/en/latest/
 * MirrorBrain: http://mirrorbrain.org/docs/
 * nose: http://somethingaboutorange.com/mrl/projects/nose/
 * ObjectListView: http://objectlistview.sourceforge.net/python
 * Open ERP: http://doc.openerp.com/
+* OpenCV: http://docs.opencv.org/
 * OpenLayers: http://docs.openlayers.org/
 * PyEphem: http://rhodesmill.org/pyephem/
 * German Plone 4.0 user manual: http://www.hasecke.com/plone-benutzerhandbuch/4.0/
+* PSI4: http://sirius.chem.vt.edu/psi4manual/latest/index.html
 * Pylons: http://pylonshq.com/docs/en/0.9.7/
 * PyMOTW: http://www.doughellmann.com/PyMOTW/
 * pypol: http://pypol.altervista.org/ (celery)
 * SQLAlchemy: http://www.sqlalchemy.org/docs/
 * tinyTiM: http://tinytim.sourceforge.net/docs/2.0/
 * tipfy: http://www.tipfy.org/docs/
+* Ubuntu packaging guide: http://developer.ubuntu.com/packaging/html/
 * Werkzeug: http://werkzeug.pocoo.org/docs/
 * WFront: http://discorporate.us/projects/WFront/
 
 
 Then, direct your browser to ``_build/html/index.html``.
 
-Or read them online at <http://sphinx.pocoo.org/>.
+Or read them online at <http://sphinx-doc.org/>.
 
 
 Testing

distribute_setup.py

 This file can also be run as a script to install or upgrade setuptools.
 """
 import os
+import shutil
 import sys
 import time
 import fnmatch
 import tempfile
 import tarfile
+import optparse
+
 from distutils import log
 
 try:
             args = [quote(arg) for arg in args]
         return os.spawnl(os.P_WAIT, sys.executable, *args) == 0
 
-DEFAULT_VERSION = "0.6.13"
+DEFAULT_VERSION = "0.6.30"
 DEFAULT_URL = "http://pypi.python.org/packages/source/d/distribute/"
 SETUPTOOLS_FAKED_VERSION = "0.6c11"
 
 """ % SETUPTOOLS_FAKED_VERSION
 
 
-def _install(tarball):
+def _install(tarball, install_args=()):
     # extracting the tarball
     tmpdir = tempfile.mkdtemp()
     log.warn('Extracting in %s', tmpdir)
 
         # installing
         log.warn('Installing Distribute')
-        if not _python_cmd('setup.py', 'install'):
+        if not _python_cmd('setup.py', 'install', *install_args):
             log.warn('Something went wrong during the installation.')
             log.warn('See the error message above.')
+            # exitcode will be 2
+            return 2
     finally:
         os.chdir(old_wd)
+        shutil.rmtree(tmpdir)
 
 
 def _build_egg(egg, tarball, to_dir):
 
     finally:
         os.chdir(old_wd)
+        shutil.rmtree(tmpdir)
     # returning the result
     log.warn(egg)
     if not os.path.exists(egg):
         except ImportError:
             return _do_download(version, download_base, to_dir, download_delay)
         try:
-            pkg_resources.require("distribute>="+version)
+            pkg_resources.require("distribute>=" + version)
             return
         except pkg_resources.VersionConflict:
             e = sys.exc_info()[1]
         if not no_fake:
             _create_fake_setuptools_pkg_info(to_dir)
 
+
 def download_setuptools(version=DEFAULT_VERSION, download_base=DEFAULT_URL,
                         to_dir=os.curdir, delay=15):
     """Download distribute from a specified location and return its filename
                 dst.close()
     return os.path.realpath(saveto)
 
+
 def _no_sandbox(function):
     def __no_sandbox(*args, **kw):
         try:
 
     return __no_sandbox
 
+
 def _patch_file(path, content):
     """Will backup the file then patch it"""
     existing_content = open(path).read()
 
 _patch_file = _no_sandbox(_patch_file)
 
+
 def _same_content(path, content):
     return open(path).read() == content
 
+
 def _rename_path(path):
     new_name = path + '.OLD.%s' % time.time()
-    log.warn('Renaming %s into %s', path, new_name)
+    log.warn('Renaming %s to %s', path, new_name)
     os.rename(path, new_name)
     return new_name
 
+
 def _remove_flat_installation(placeholder):
     if not os.path.isdir(placeholder):
         log.warn('Unkown installation at %s', placeholder)
         log.warn('Could not locate setuptools*.egg-info')
         return
 
-    log.warn('Removing elements out of the way...')
+    log.warn('Moving elements out of the way...')
     pkg_info = os.path.join(placeholder, file)
     if os.path.isdir(pkg_info):
         patched = _patch_egg_dir(pkg_info)
 
 _remove_flat_installation = _no_sandbox(_remove_flat_installation)
 
+
 def _after_install(dist):
     log.warn('After install bootstrap.')
     placeholder = dist.get_command_obj('install').install_purelib
     _create_fake_setuptools_pkg_info(placeholder)
 
+
 def _create_fake_setuptools_pkg_info(placeholder):
     if not placeholder or not os.path.exists(placeholder):
         log.warn('Could not find the install location')
         return
 
     log.warn('Creating %s', pkg_info)
-    f = open(pkg_info, 'w')
+    try:
+        f = open(pkg_info, 'w')
+    except EnvironmentError:
+        log.warn("Don't have permissions to write %s, skipping", pkg_info)
+        return
     try:
         f.write(SETUPTOOLS_PKG_INFO)
     finally:
     finally:
         f.close()
 
-_create_fake_setuptools_pkg_info = _no_sandbox(_create_fake_setuptools_pkg_info)
+_create_fake_setuptools_pkg_info = _no_sandbox(
+    _create_fake_setuptools_pkg_info
+)
+
 
 def _patch_egg_dir(path):
     # let's check if it's already patched
 
 _patch_egg_dir = _no_sandbox(_patch_egg_dir)
 
+
 def _before_install():
     log.warn('Before install bootstrap.')
     _fake_setuptools()
 def _under_prefix(location):
     if 'install' not in sys.argv:
         return True
-    args = sys.argv[sys.argv.index('install')+1:]
+    args = sys.argv[sys.argv.index('install') + 1:]
     for index, arg in enumerate(args):
         for option in ('--root', '--prefix'):
             if arg.startswith('%s=' % option):
                 return location.startswith(top_dir)
             elif arg == option:
                 if len(args) > index:
-                    top_dir = args[index+1]
+                    top_dir = args[index + 1]
                     return location.startswith(top_dir)
         if arg == '--user' and USER_SITE is not None:
             return location.startswith(USER_SITE)
         return
     ws = pkg_resources.working_set
     try:
-        setuptools_dist = ws.find(pkg_resources.Requirement.parse('setuptools',
-                                  replacement=False))
+        setuptools_dist = ws.find(
+            pkg_resources.Requirement.parse('setuptools', replacement=False)
+            )
     except TypeError:
         # old distribute API
-        setuptools_dist = ws.find(pkg_resources.Requirement.parse('setuptools'))
+        setuptools_dist = ws.find(
+            pkg_resources.Requirement.parse('setuptools')
+        )
 
     if setuptools_dist is None:
         log.warn('No setuptools distribution found')
         res = _patch_egg_dir(setuptools_location)
         if not res:
             return
-    log.warn('Patched done.')
+    log.warn('Patching complete.')
     _relaunch()
 
 
     log.warn('Relaunching...')
     # we have to relaunch the process
     # pip marker to avoid a relaunch bug
-    if sys.argv[:3] == ['-c', 'install', '--single-version-externally-managed']:
+    _cmd1 = ['-c', 'install', '--single-version-externally-managed']
+    _cmd2 = ['-c', 'install', '--record']
+    if sys.argv[:3] == _cmd1 or sys.argv[:3] == _cmd2:
         sys.argv[0] = 'setup.py'
     args = [sys.executable] + sys.argv
     sys.exit(subprocess.call(args))
             # Extract directories with a safe mode.
             directories.append(tarinfo)
             tarinfo = copy.copy(tarinfo)
-            tarinfo.mode = 448 # decimal for oct 0700
+            tarinfo.mode = 448  # decimal for oct 0700
         self.extract(tarinfo, path)
 
     # Reverse sort directories.
                 self._dbg(1, "tarfile: %s" % e)
 
 
-def main(argv, version=DEFAULT_VERSION):
+def _build_install_args(options):
+    """
+    Build the arguments to 'python setup.py install' on the distribute package
+    """
+    install_args = []
+    if options.user_install:
+        if sys.version_info < (2, 6):
+            log.warn("--user requires Python 2.6 or later")
+            raise SystemExit(1)
+        install_args.append('--user')
+    return install_args
+
+def _parse_args():
+    """
+    Parse the command line for options
+    """
+    parser = optparse.OptionParser()
+    parser.add_option(
+        '--user', dest='user_install', action='store_true', default=False,
+        help='install in user site package (requires Python 2.6 or later)')
+    parser.add_option(
+        '--download-base', dest='download_base', metavar="URL",
+        default=DEFAULT_URL,
+        help='alternative URL from where to download the distribute package')
+    options, args = parser.parse_args()
+    # positional arguments are ignored
+    return options
+
+def main(version=DEFAULT_VERSION):
     """Install or upgrade setuptools and EasyInstall"""
-    tarball = download_setuptools()
-    _install(tarball)
-
+    options = _parse_args()
+    tarball = download_setuptools(download_base=options.download_base)
+    return _install(tarball, _build_install_args(options))
 
 if __name__ == '__main__':
-    main(sys.argv[1:])
+    sys.exit(main())
 I18NSPHINXOPTS   = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(O) .
 
 .PHONY: help clean html dirhtml singlehtml text man pickle json htmlhelp \
-	qthelp devhelp epub latex latexpdf changes linkcheck doctest
+	qthelp devhelp epub latex latexpdf changes linkcheck doctest xml \
+	pseudoxml
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "Running Texinfo files through makeinfo..."
 	make -C _build/texinfo info
 	@echo "makeinfo finished; the Info files are in _build/texinfo."
+
+xml:
+	$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) _build/xml
+	@echo
+	@echo "Build finished. The XML files are in _build/XML."
+
+pseudoxml:
+	$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) _build/pseudoxml
+	@echo
+	@echo "Build finished. The pseudo-XML files are in _build/pseudoxml."

doc/_templates/index.html

 
   <p>
     You can also download PDF versions of the Sphinx documentation:
-    a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from
+    a <a href="http://sphinx-doc.org/sphinx.pdf">version</a> generated from
     the LaTeX Sphinx produces, and
-    a <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated
+    a <a href="http://sphinx-doc.org/sphinx-rst2pdf.pdf">version</a> generated
     by rst2pdf.
   </p>
 

doc/_templates/indexsidebar.html

 <p>Get Sphinx from the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
 Index</a>, or install it with:</p>
 <pre>easy_install -U Sphinx</pre>
-<p>Latest <a href="http://sphinx.pocoo.org/latest/">development version docs</a>
+<p>Latest <a href="http://sphinx-doc.org/latest/">development version docs</a>
 are also available.</p>
 {% endif %}
 
 <h3>Questions? Suggestions?</h3>
 
-<p>Join the <a href="http://groups.google.com/group/sphinx-dev">Google group</a>:</p>
-<form action="http://groups.google.com/group/sphinx-dev/boxsubscribe"
+<p>Join the <a href="http://groups.google.com/group/sphinx-users">Google group</a>:</p>
+<form action="http://groups.google.com/group/sphinx-users/boxsubscribe"
       style="padding-left: 1em">
   <input type="text" name="email" value="your@email"/>
   <input type="submit" name="sub" value="Subscribe" />
 
    Its name is ``linkcheck``.
 
+.. module:: sphinx.builders.xml
+.. class:: XMLBuilder
+
+   This builder produces Docutils-native XML files.  The output can be
+   transformed with standard XML tools such as XSLT processors into arbitrary
+   final forms.
+
+   Its name is ``xml``.
+
+   .. versionadded:: 1.2
+
+.. class:: PseudoXMLBuilder
+
+   This builder is used for debugging the Sphinx/Docutils "Reader to Transform
+   to Writer" pipeline. It produces compact pretty-printed "pseudo-XML", files
+   where nesting is indicated by indentation (no end-tags). External
+   attributes for all elements are output, and internal attributes for any
+   leftover "pending" elements are also given.
+
+   Its name is ``pseudoxml``.
+
+   .. versionadded:: 1.2
+
 
 Built-in Sphinx extensions that offer more builders are:
 
 html_static_path = ['_static']
 html_sidebars = {'index': ['indexsidebar.html', 'searchbox.html']}
 html_additional_pages = {'index': 'index.html'}
-html_use_opensearch = 'http://sphinx.pocoo.org'
+html_use_opensearch = 'http://sphinx-doc.org'
 
 htmlhelp_basename = 'Sphinxdoc'
 
 epub_theme = 'epub'
 epub_basename = 'sphinx'
 epub_author = 'Georg Brandl'
-epub_publisher = 'http://sphinx.pocoo.org/'
+epub_publisher = 'http://sphinx-doc.org/'
 epub_scheme = 'url'
 epub_identifier = epub_publisher
 epub_pre_files = [('index.html', 'Welcome')]
    * ``ko`` -- Korean
    * ``lt`` -- Lithuanian
    * ``lv`` -- Latvian
+   * ``nb_NO`` -- Norwegian Bokmal
    * ``ne`` -- Nepali
    * ``nl`` -- Dutch
    * ``pl`` -- Polish
    .. versionadded:: 1.2
 
 
+Options for the XML builder
+---------------------------
+
+.. confval:: xml_pretty
+
+   If True, pretty-print the XML.  Default is ``True``.
+
+   .. versionadded:: 1.2
+
+
 .. rubric:: Footnotes
 
 .. [1] A note on available globbing syntax: you can use the standard shell
 
    faq
    glossary
+   devguide
    changes
    examples
 
+Sphinx Developer's Guide
+========================
+
+.. topic:: Abstract
+
+   This document describes the development process of Sphinx, a documentation
+   system used by developers to document systems used by other developers to
+   develop other systems that may also be documented using Sphinx.
+
+The Sphinx source code is managed using `Mercurial`_ and is hosted on
+`BitBucket`_.
+
+    hg clone https://bitbucket.org/birkenfeld/sphinx
+
+.. rubric:: Community
+
+sphinx-users <sphinx-users@googlegroups.com>
+    Mailing list for user support.
+
+sphinx-dev <sphinx-dev@googlegroups.com>
+    Mailing list for development related discussions.
+
+#pocoo on irc.freenode.net
+    IRC channel for development questions and user support.
+
+    This channel is shared with other Pocoo projects.  Archived logs are
+    available `here <http://dev.pocoo.org/irclogs/>`_.
+
+.. _`BitBucket`: http://bitbucket.org
+.. _`Mercurial`: http://mercurial.selenic.com/
+
+
+Bug Reports and Feature Requests
+--------------------------------
+
+If you have encountered a problem with Sphinx or have an idea for a new
+feature, please submit it to the `issue tracker`_ on BitBucket or discuss it
+on the sphinx-dev mailing list.
+
+For bug reports, please include the output produced during the build process
+and also the log file Sphinx creates after it encounters an un-handled
+exception.  The location of this file should be shown towards the end of the
+error message.
+
+Including or providing a link to the source files involved may help us fix the
+issue.  If possible, try to create a minimal project that produces the error
+and post that instead.
+
+.. _`issue tracker`: http://bitbucket.org/birkenfeld/sphinx/issues
+
+
+Contributing to Sphinx
+----------------------
+
+The recommended way for new contributors to submit code to Sphinx is to fork
+the Mercurial repository on BitBucket and then submit a pull request after
+committing the changes.  The pull request will then need to be approved by one
+of the core developers before it is merged into the main repository.
+
+
+Getting Started
+~~~~~~~~~~~~~~~
+
+These are the basic steps needed to start developing on Sphinx.
+
+#. Create an account on BitBucket.
+
+#. Fork the main Sphinx repository (`birkenfeld/sphinx
+   <https://bitbucket.org/birkenfeld/sphinx>`_) using the BitBucket interface.
+
+#. Clone the forked repository to your machine. ::
+
+       hg clone https://bitbucket.org/USERNAME/sphinx-fork
+       cd sphinx-fork
+
+#. Checkout the appropriate branch.
+
+   For changes that should be included in the next minor release (namely bug
+   fixes), use the ``stable`` branch. ::
+
+       hg checkout stable
+
+   For new features or other substantial changes that should wait until the
+   next major release, use the ``default`` branch.
+
+#. Setup your Python environment. ::
+
+       virtualenv ~/sphinxenv
+       . ~/sphinxenv/bin/activate
+       pip install -e .
+
+#. Hack, hack, hack.
+
+   For tips on working with the code, see the `Coding Guide`_.
+
+#. Test, test, test.
+
+   Run the unit tests::
+
+       pip install nose
+       make test
+
+   Build the documentation and check the output for different builders::
+
+       cd docs
+       make clean html text man info latexpdf
+
+   Run the unit tests under different Python environments using
+   :program:`tox`::
+
+       pip install tox
+       tox -v
+
+   Add a new unit test in the ``tests`` directory if you can.
+
+   For bug fixes, first add a test that fails without your changes and passes
+   after they are applied.
+
+#. Commit your changes. ::
+
+       hg commit -m 'Add useful new feature that does this.'
+
+   BitBucket recognizes `certain phrases`__ that can be used to automatically
+   update the issue tracker.
+
+   For example::
+
+       hg commit -m 'Closes #42: Fix invalid markup in docstring of Foo.bar.'
+
+   would close issue #42.
+
+   __ https://confluence.atlassian.com/display/BITBUCKET/Automatically+Resolving+Issues+when+Users+Push+Code
+
+#. Push changes to your forked repository on BitBucket. ::
+
+       hg push
+
+#. Submit a pull request from your repository to ``birkenfeld/sphinx`` using
+   the BitBucket interface.
+
+#. Wait for a core developer to review your changes.
+
+
+Core Developers
+~~~~~~~~~~~~~~~
+
+The core developers of Sphinx have write access to the main repository.  They
+can commit changes, accept/reject pull requests, and manage items on the issue
+tracker.
+
+You do not need to be a core developer or have write access to be involved in
+the development of Sphinx.  You can submit patches or create pull requests
+from forked repositories and have a core developer add the changes for you.
+
+The following are some general guidelines for core developers:
+
+* Questionable or extensive changes should be submitted as a pull request
+  instead of being committed directly to the main repository.  The pull
+  request should be reviewed by another core developer before it is merged.
+
+* Trivial changes can be committed directly but be sure to keep the repository
+  in a good working state and that all tests pass before pushing your changes.
+
+* When committing code written by someone else, please attribute the original
+  author in the commit message and any relevant :file:`CHANGES` entry.
+
+* Using Mercurial named branches other than ``default`` and ``stable`` is not
+  encouraged.
+
+
+Coding Guide
+------------
+
+* Try to use the same code style as used in the rest of the project.  See the
+  `Pocoo Styleguide`__ for more information.
+
+  __ http://flask.pocoo.org/docs/styleguide/
+
+* For non-trivial changes, please update the :file:`CHANGES` file.  If your
+  changes alter existing behavior, please document this.
+
+* New features should be documented.  Include examples and use cases where
+  appropriate.  If possible, include a sample that is displayed in the
+  generated output.
+
+* When adding a new configuration variable, be sure to document it and update
+  :file:`sphinx/quickstart.py`.
+
+* Use the included :program:`utils/check_sources.py` script to check for
+  common formatting issues (trailing whitespace, lengthy lines, etc).
+
+* Add appropriate unit tests.
+
+
+Debugging Tips
+~~~~~~~~~~~~~~
+
+* Delete the build cache before building documents if you make changes in the
+  code by running the command ``make clean`` or using the
+  :option:`sphinx-build -E` option.
+
+* Use the :option:`sphinx-build -P` option to run Pdb on exceptions.
+
+* Use ``node.pformat()`` and ``node.asdom().toxml()`` to generate a printable
+  representation of the document structure.
+
+* Set the configuration variable :confval:`keep_warnings` to True so warnings
+  will be displayed in the generated output.
+
+* Set the configuration variable :confval:`nitpicky` to True so that Sphinx
+  will complain about references without a known target.
+
+* Set the debugging options in the `Docutils configuration file
+  <http://docutils.sourceforge.net/docs/user/config.html>`_.
 ------------
 
 The sphinx-contrib_ repository contains more domains available as extensions;
-currently Ada, Erlang, HTTP, PHP, and Ruby domains.
+currently Ada, CoffeeScript_, Erlang_, HTTP_, Jinja_, PHP_, Ruby, and Scala_
+domains.
 
 
 .. _sphinx-contrib: https://bitbucket.org/birkenfeld/sphinx-contrib/
+
+.. _CoffeeScript: http://pypi.python.org/pypi/sphinxcontrib-coffee
+.. _Erlang: http://pypi.python.org/pypi/sphinxcontrib-erlangdomain
+.. _HTTP: http://pypi.python.org/pypi/sphinxcontrib-httpdomain
+.. _Jinja: http://pypi.python.org/pypi/sphinxcontrib-jinjadomain
+.. _Scala: http://pypi.python.org/pypi/sphinxcontrib-scaladomain
+.. _PHP: http://pypi.python.org/pypi/sphinxcontrib-phpdomain

doc/ext/autodoc.rst

 
      .. versionadded:: 1.1
 
+     .. versionchanged:: 1.2
+        The option can now take arguments, i.e. the special members to document.
+
    * For classes and exceptions, members inherited from base classes will be
      left out when documenting all members, unless you give the
      ``inherited-members`` flag option, in addition to ``members``::
                    automethod
                    autoattribute
 
-   These work exactly like :rst:dir:`autoclass` etc., but do not offer the options
-   used for automatic member documentation.
+   These work exactly like :rst:dir:`autoclass` etc., but do not offer the
+   options used for automatic member documentation.
 
    For module data members and class attributes, documentation can either be put
-   into a special-formatted comment, or in a docstring *after* the definition.
-   Comments need to be either on a line of their own *before* the definition, or
+   into a comment with special formatting (using a ``#:`` to start the comment
+   instead of just ``#``), or in a docstring *after* the definition.  Comments
+   need to be either on a line of their own *before* the definition, or
    immediately after the assignment *on the same line*.  The latter form is
    restricted to one line only.
 

doc/ext/linkcode.rst

+:mod:`sphinx.ext.linkcode` -- Add external links to source code
+===============================================================
+
+.. module:: sphinx.ext.linkcode
+   :synopsis: Add external links to source code.
+.. moduleauthor:: Pauli Virtanen
+
+.. versionadded:: 1.2
+
+This extension looks at your object descriptions (``.. class::``,
+``.. function::`` etc.) and adds external links to code hosted
+somewhere on the web. The intent is similar to the
+``sphinx.ext.viewcode`` extension, but assumes the source code can be
+found somewhere on the Internet.
+
+In your configuration, you need to specify a :confval:`linkcode_resolve`
+function that returns an URL based on the object.
+
+.. confval:: linkcode_resolve
+
+   This is a function ``linkcode_resolve(domain, info)``,
+   which should return the URL to source code corresponding to
+   the object in given domain with given information.
+
+   The function should return ``None`` if no link is to be added.
+
+   The argument ``domain`` specifies the language domain the object is
+   in. ``info`` is a dictionary with the following keys guaranteed to
+   be present (dependent on the domain):
+
+   - ``py``: ``module`` (name of the module), ``fullname`` (name of the object)
+   - ``c``: ``names`` (list of names for the object)
+   - ``cpp``: ``names`` (list of names for the object)
+   - ``javascript``: ``object`` (name of the object), ``fullname`` (name of the item)
+
+   Example:
+
+   .. code-block:: python
+
+      def linkcode_resolve(domain, info):
+          if domain != 'py':
+              return None
+          if not info['module']:
+              return None
+          filename = info['module'].replace('.', '/')
+          return "http://somesite/sourcerepo/%s.py" % filename
 .. confval:: pngmath_dvipng_args
 
    Additional arguments to give to dvipng, as a list.  The default value is
-   ``['-gamma 1.5', '-D 110']`` which makes the image a bit darker and larger
-   then it is by default.
+   ``['-gamma', '1.5', '-D', '110', '-bg', 'Transparent']`` which makes the
+   image a bit darker and larger then it is by default, and produces PNGs with a
+   transparent background.
 
-   An arguments you might want to add here is e.g. ``'-bg Transparent'``,
-   which produces PNGs with a transparent background.  This is not enabled by
-   default because some Internet Explorer versions don't like transparent PNGs.
-
-   .. note::
-
-      When you "add" an argument, you need to reproduce the default arguments if
-      you want to keep them; that is, like this::
-
-         pngmath_dvipng_args = ['-gamma 1.5', '-D 110', '-bg Transparent']
+   .. versionchanged:: 1.2
+      Now includes ``-bg Transparent`` by default.
 
 .. confval:: pngmath_use_preview
 

doc/extensions.rst

    ext/todo
    ext/extlinks
    ext/viewcode
+   ext/linkcode
    ext/oldcmarkup
 
 
 Prerequisites
 -------------
 
-Sphinx needs at least **Python 2.4** or **Python 3.1** to run, as well as the
+Sphinx needs at least **Python 2.5** or **Python 3.1** to run, as well as the
 docutils_ and Jinja2_ libraries.  Sphinx should work with docutils version 0.7
 or some (not broken) SVN trunk snapshot.  If you like to have source code
 highlighting support, you must also install the Pygments_ library.
 
-If you use **Python 2.4** you also need uuid_.
-
 .. _reStructuredText: http://docutils.sf.net/rst.html
 .. _docutils: http://docutils.sf.net/
 .. _Jinja2: http://jinja.pocoo.org/
 .. _Pygments: http://pygments.org/
-.. The given homepage is only a directory listing so I'm using the pypi site.
-.. _uuid: http://pypi.python.org/pypi/uuid/
 
 
 Usage

doc/invocation.rst

 
    This sets the maximum depth of the table of contents, if one is generated.
 
+.. option:: -l, --follow-links
+
+   This option makes sphinx-apidoc follow symbolic links when recursing the
+   filesystem to discover packages and modules. You may need it if you want
+   to generate documentation from a source directory managed by
+   `collective.recipe.omelette
+   <http://pypi.python.org/pypi/collective.recipe.omelette/>`_.
+   By default, symbolic links are skipped.
+
+   .. versionadded:: 1.2
+
 .. option:: -T, --no-toc
 
    This prevents the generation of a table-of-contents file ``modules.rst``.

doc/markup/misc.rst

    The format of the current builder (``html``, ``latex`` or ``text``) is always
    set as a tag.
 
-   .. note::
-
-      Due to docutils' specifics of parsing of directive content, you cannot put
-      a section with the same level as the main document heading inside an
-      ``only`` directive.  Such sections will appear to be ignored in the parsed
-      document.
-
    .. versionadded:: 0.6
 
 
 
 requires = ['Pygments>=1.2', 'Jinja2>=2.3', 'docutils>=0.7']
 
-if sys.version_info < (2, 4):
-    print('ERROR: Sphinx requires at least Python 2.4 to run.')
+if sys.version_info[:3] >= (3, 3, 0):
+    requires[2] = 'docutils>=0.10'
+
+if sys.version_info < (2, 5):
+    print('ERROR: Sphinx requires at least Python 2.5 to run.')
     sys.exit(1)
 
-if sys.version_info < (2, 5):
-    # Python 2.4's distutils doesn't automatically install an egg-info,
-    # so an existing docutils install won't be detected -- in that case,
-    # remove the dependency from setup.py
-    try:
-        import docutils
-        if int(docutils.__version__[2]) < 4:
-            raise ValueError('docutils not recent enough')
-    except:
-        pass
-    else:
-        del requires[-1]
-
-    # The uuid module is new in the stdlib in 2.5
-    requires.append('uuid>=1.30')
-
+# tell distribute to use 2to3 with our own fixers
+extra = {}
+if sys.version_info >= (3, 0):
+    extra.update(
+        use_2to3=True,
+        use_2to3_fixers=['custom_fixers']
+    )
 
 # Provide a "compile_catalog" command that also creates the translated
 # JavaScript files if Babel is available.
 setup(
     name='Sphinx',
     version=sphinx.__version__,
-    url='http://sphinx.pocoo.org/',
+    url='http://sphinx-doc.org/',
     download_url='http://pypi.python.org/pypi/Sphinx',
     license='BSD',
     author='Georg Brandl',
     },
     install_requires=requires,
     cmdclass=cmdclass,
-    use_2to3=True,
-    use_2to3_fixers=['custom_fixers'],
+    **extra
 )

sphinx/__init__.py

 
 def main(argv=sys.argv):
     """Sphinx build "main" command-line entry."""
-    if sys.version_info[:3] < (2, 4, 0):
+    if sys.version_info[:3] < (2, 5, 0):
         sys.stderr.write('Error: Sphinx requires at least '
-                         'Python 2.4 to run.\n')
+                         'Python 2.5 to run.\n')
         return 1
-
+    if sys.version_info[:3] >= (3, 3, 0):
+        try:
+            import docutils
+            x, y = docutils.__version__.split('.')[:2]
+            if (int(x), int(y)) < (0, 10):
+                sys.stderr.write('Error: Sphinx requires at least '
+                                 'Docutils 0.10 for Python 3.3 and above.\n')
+                return 1
+        except Exception:
+            pass
     try:
         from sphinx import cmdline
     except ImportError:
         root_package = None
 
     toplevels = []
-    for root, subs, files in os.walk(rootpath):
+    followlinks = getattr(opts, 'followlinks', False)
+    for root, subs, files in os.walk(rootpath, followlinks=followlinks):
         if is_excluded(root, excludes):
             del subs[:]
             continue
                       '(default: 4)', type='int', default=4)
     parser.add_option('-f', '--force', action='store_true', dest='force',
                       help='Overwrite all files')
+    parser.add_option('-l', '--follow-links', action='store_true',
+                      dest='followlinks', default=False,
+                      help='Follow symbolic links. Powerful when combined '
+                      'with collective.recipe.omelette.')
     parser.add_option('-n', '--dry-run', action='store_true', dest='dryrun',
                       help='Run the script without creating files')
     parser.add_option('-T', '--no-toc', action='store_true', dest='notoc',

sphinx/application.py

         if domain.name not in self.domains:
             raise ExtensionError('domain %s not yet registered' % domain.name)
         if not issubclass(domain, self.domains[domain.name]):
-            raise ExtensionError('new domain not a subclass of registered '
+            raise ExtensionError('new domain not a subclass of registered %s '
                                  'domain' % domain.name)
         self.domains[domain.name] = domain
 

sphinx/builders/__init__.py

     'linkcheck':  ('linkcheck', 'CheckExternalLinksBuilder'),
     'websupport': ('websupport', 'WebSupportBuilder'),
     'gettext':    ('gettext', 'MessageCatalogBuilder'),
+    'xml':        ('xml', 'XMLBuilder'),
+    'pseudoxml':  ('xml', 'PseudoXMLBuilder'),
 }

sphinx/builders/html.py

         """
         Builder.post_process_images(self, doctree)
         for node in doctree.traverse(nodes.image):
-            if not node.has_key('scale') or \
+            scale_keys = ('scale', 'width', 'height')
+            if not any((key in node) for key in scale_keys) or \
                isinstance(node.parent, nodes.reference):
                 # docutils does unfortunately not preserve the
                 # ``target`` attribute on images, so we need to check

sphinx/builders/linkcheck.py

 
         def check():
             # check for various conditions without bothering the network
-            if len(uri) == 0 or uri[0] == '#' or uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:':
+            if len(uri) == 0 or uri[0] == '#' or \
+               uri[0:7] == 'mailto:' or uri[0:4] == 'ftp:':
                 return 'unchecked', ''
             elif not (uri[0:5] == 'http:' or uri[0:6] == 'https:'):
                 return 'local', ''

sphinx/builders/xml.py

+# -*- coding: utf-8 -*-
+"""
+    sphinx.builders.xml
+    ~~~~~~~~~~~~~~~~~~~
+
+    Docutils-native XML and pseudo-XML builders.
+
+    :copyright: Copyright 2007-2012 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import codecs
+from os import path
+
+from docutils.io import StringOutput
+
+from sphinx.builders import Builder
+from sphinx.util.osutil import ensuredir, os_path
+from sphinx.writers.xml import XMLWriter, PseudoXMLWriter
+
+class XMLBuilder(Builder):
+    """
+    Builds Docutils-native XML.
+    """
+    name = 'xml'
+    format = 'xml'
+    out_suffix = '.xml'
+
+    _writer_class = XMLWriter
+
+    def init(self):
+        pass
+
+    def get_outdated_docs(self):
+        for docname in self.env.found_docs:
+            if docname not in self.env.all_docs:
+                yield docname
+                continue
+            targetname = self.env.doc2path(docname, self.outdir,
+                                           self.out_suffix)
+            try:
+                targetmtime = path.getmtime(targetname)
+            except Exception:
+                targetmtime = 0
+            try:
+                srcmtime = path.getmtime(self.env.doc2path(docname))
+                if srcmtime > targetmtime:
+                    yield docname
+            except EnvironmentError:
+                # source doesn't exist anymore
+                pass
+
+    def get_target_uri(self, docname, typ=None):
+        return ''
+
+    def prepare_writing(self, docnames):
+        self.writer = self._writer_class(self)
+
+    def write_doc(self, docname, doctree):
+        destination = StringOutput(encoding='utf-8')
+        self.writer.write(doctree, destination)
+        outfilename = path.join(self.outdir, os_path(docname) + self.out_suffix)
+        ensuredir(path.dirname(outfilename))
+        try:
+            f = codecs.open(outfilename, 'w', 'utf-8')
+            try:
+                f.write(self.writer.output)
+            finally:
+                f.close()
+        except (IOError, OSError), err:
+            self.warn("error writing file %s: %s" % (outfilename, err))
+
+    def finish(self):
+        pass
+
+
+class PseudoXMLBuilder(XMLBuilder):
+    """
+    Builds pseudo-XML for display purposes.
+    """
+    name = 'pseudoxml'
+    format = 'pseudoxml'
+    out_suffix = '.pseudoxml'
+
+    _writer_class = PseudoXMLWriter

sphinx/cmdline.py

                                 'can be provided next time.')
                 print >>error, (
                     'Either send bugs to the mailing list at '
-                    '<http://groups.google.com/group/sphinx-dev/>,\n'
+                    '<http://groups.google.com/group/sphinx-users/>,\n'
                     'or report them in the tracker at '
                     '<http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!')
             return 1
 
         # gettext options
         gettext_compact = (True, 'gettext'),
+
+        # XML options
+        xml_pretty = (True, 'env'),
     )
 
     def __init__(self, dirname, filename, overrides, tags):

sphinx/directives/other.py

         node.document = self.state.document
         set_source_info(self, node)
         node['expr'] = self.arguments[0]
-        self.state.nested_parse(self.content, self.content_offset, node,
-                                match_titles=1)
-        return [node]
+
+        # Same as util.nested_parse_with_titles but try to handle nested
+        # sections which should be raised higher up the doctree.
+        surrounding_title_styles = self.state.memo.title_styles
+        surrounding_section_level = self.state.memo.section_level
+        self.state.memo.title_styles = []
+        self.state.memo.section_level = 0
+        try:
+            result = self.state.nested_parse(self.content, self.content_offset,
+                                             node, match_titles=1)
+            title_styles = self.state.memo.title_styles
+            if (not surrounding_title_styles
+                or not title_styles
+                or title_styles[0] not in surrounding_title_styles
+                or not self.state.parent):
+                # No nested sections so no special handling needed.
+                return [node]
+            # Calculate the depths of the current and nested sections.
+            current_depth = 0
+            parent = self.state.parent
+            while parent:
+                current_depth += 1
+                parent = parent.parent
+            current_depth -= 2
+            title_style = title_styles[0]
+            nested_depth = len(surrounding_title_styles)
+            if title_style in surrounding_title_styles:
+                nested_depth = surrounding_title_styles.index(title_style)
+            # Use these depths to determine where the nested sections should
+            # be placed in the doctree.
+            n_sects_to_raise = current_depth - nested_depth + 1
+            parent = self.state.parent
+            for i in xrange(n_sects_to_raise):
+                if parent.parent:
+                    parent = parent.parent
+            parent.append(node)
+            return []
+        finally:
+            self.state.memo.title_styles = surrounding_title_styles
+            self.state.memo.section_level = surrounding_section_level
 
 
 class Include(BaseInclude):

sphinx/domains/cpp.py

         except ValueError:
             return False
 
-    def _parse_builtin(self, modifier):
-        path = [modifier]
+    def _parse_builtin(self, modifiers):
+        modifier = modifiers[-1]
+        path = modifiers
         following = self._modifiers[modifier]
         while 1:
             self.skip_ws()
                     # impossible for a template to follow, so what
                     # we do is go to a different function that just
                     # eats types
+                    modifiers.append(modifier)
                     if following is not None:
-                        return self._parse_builtin(modifier)
-                    modifiers.append(modifier)
+                        return self._parse_builtin(modifiers)
+                    self.skip_ws()
                 else:
                     self.backout()
                     break
         self.skip_ws()
         if self.match(_string_re):
             return self.matched_text
-        idx1 = self.definition.find(',', self.pos)
-        idx2 = self.definition.find(')', self.pos)
-        if idx1 < 0:
-            idx = idx2
-        elif idx2 < 0:
-            idx = idx1
-        else:
-            idx = min(idx1, idx2)
-        if idx < 0:
-            self.fail('unexpected end in default expression')
-        rv = self.definition[self.pos:idx]
+        paren_stack_depth = 0
+        max_pos = len(self.definition)
+        rv_start = self.pos
+        while 1:
+            idx0 = self.definition.find('(', self.pos)
+            idx1 = self.definition.find(',', self.pos)
+            idx2 = self.definition.find(')', self.pos)
+            if idx0 < 0:
+                idx0 = max_pos
+            if idx1 < 0:
+                idx1 = max_pos
+            if idx2 < 0:
+                idx2 = max_pos
+            idx = min(idx0, idx1, idx2)
+            if idx >= max_pos:
+                self.fail('unexpected end in default expression')
+            if idx == idx0:
+                paren_stack_depth += 1
+            elif idx == idx2:
+                paren_stack_depth -= 1
+                if paren_stack_depth < 0:
+                    break
+            elif paren_stack_depth == 0:
+                break
+            self.pos = idx+1
+
+        rv = self.definition[rv_start:idx]
         self.pos = idx
         return rv
 
         visibility = 'public'
         if self.match(_visibility_re):
             visibility = self.matched_text
-        static = self.skip_word('static')
+        static = self.skip_word_and_ws('static')
         return visibility, static
 
     def parse_type(self):

sphinx/environment.py

     'doctitle_xform': False,
     'sectsubtitle_xform': False,
     'halt_level': 5,
+    'file_insertion_enabled': True,
 }
 
 # This is increased every time an environment attribute is added
     Replace translatable nodes with their translated doctree.
     """
     default_priority = 0
+
     def apply(self):
         env = self.document.settings.env
         settings, source = self.document.settings, self.document['source']
         parser = RSTParser()
 
         for node, msg in extract_messages(self.document):
-            patch = new_document(source, settings)
             msgstr = catalog.gettext(msg)
             # XXX add marker to untranslated parts
             if not msgstr or msgstr == msg: # as-of-yet untranslated
                 continue
+
+            patch = new_document(source, settings)
             parser.parse(msgstr, patch)
             patch = patch[0]
             # XXX doctest and other block markup
             if not isinstance(patch, nodes.paragraph):
                 continue # skip for now
-            for child in patch.children: # update leaves
+
+            # auto-numbered foot note reference should use original 'ids'.
+            is_autonumber_footnote_ref = lambda node: \
+                    isinstance(node, nodes.footnote_reference) \
+                    and node.get('auto') == 1
+            old_foot_refs = node.traverse(is_autonumber_footnote_ref)
+            new_foot_refs = patch.traverse(is_autonumber_footnote_ref)
+            if len(old_foot_refs) != len(new_foot_refs):
+                env.warn_node('inconsistent footnote references in '
+                              'translated message', node)
+            for old, new in zip(old_foot_refs, new_foot_refs):
+                new['ids'] = old['ids']
+                self.document.autofootnote_refs.remove(old)
+                self.document.note_autofootnote_ref(new)
+
+            # reference should use original 'refname'.
+            # * reference target ".. _Python: ..." is not translatable.
+            # * section refname is not translatable.
+            # * inline reference "`Python <...>`_" has no 'refname'.
+            is_refnamed_ref = lambda node: \
+                    isinstance(node, nodes.reference) \
+                    and 'refname' in node
+            old_refs = node.traverse(is_refnamed_ref)
+            new_refs = patch.traverse(is_refnamed_ref)
+            applied_refname_map = {}
+            if len(old_refs) != len(new_refs):
+                env.warn_node('inconsistent references in '
+                              'translated message', node)
+            for new in new_refs:
+                if new['refname'] in applied_refname_map:
+                    # 2nd appearance of the reference
+                    new['refname'] = applied_refname_map[new['refname']]
+                elif old_refs:
+                    # 1st appearance of the reference in old_refs
+                    old = old_refs.pop(0)
+                    refname = old['refname']
+                    new['refname'] = refname
+                    applied_refname_map[new['refname']] = refname
+                else:
+                    # the reference is not found in old_refs
+                    applied_refname_map[new['refname']] = new['refname']
+
+                self.document.note_refname(new)
+
+            # update leaves
+            for child in patch.children:
                 child.parent = node
             node.children = patch.children
 
             app.emit('doctree-read', doctree)
 
         # store time of build, for outdated files detection
-        self.all_docs[docname] = time.time()
+        # (Some filesystems have coarse timestamp resolution;
+        # therefore time.time() can be older than filesystem's timestamp.
+        # For example, FAT32 has 2sec timestamp resolution.)
+        self.all_docs[docname] = max(
+                time.time(), path.getmtime(self.doc2path(docname)))
 
         if self.versioning_condition:
             # get old doctree
                 if 'orphan' in self.metadata[docname]:
                     continue
                 self.warn(docname, 'document isn\'t included in any toctree')
-

sphinx/ext/autodoc.py

         If *want_all* is True, return all members.  Else, only return those
         members given by *self.options.members* (which may also be none).
         """
+        analyzed_member_names = set()
+        if self.analyzer:
+            attr_docs = self.analyzer.find_attr_docs()
+            namespace = '.'.join(self.objpath)
+            for item in attr_docs.iteritems():
+                if item[0][0] == namespace:
+                    analyzed_member_names.add(item[0][1])
         if not want_all:
             if not self.options.members:
                 return False, []
             # specific members given
-            ret = []
+            members = []
             for mname in self.options.members:
                 try:
-                    ret.append((mname, self.get_attr(self.object, mname)))
+                    members.append((mname, self.get_attr(self.object, mname)))
                 except AttributeError:
-                    self.directive.warn('missing attribute %s in object %s'
-                                        % (mname, self.fullname))
-            return False, ret
-
-        if self.options.inherited_members:
+                    if mname not in analyzed_member_names:
+                        self.directive.warn('missing attribute %s in object %s'
+                                            % (mname, self.fullname))
+        elif self.options.inherited_members:
             # safe_getmembers() uses dir() which pulls in members from all
             # base classes
             members = safe_getmembers(self.object)
                            for mname in obj_dict.keys()]
         membernames = set(m[0] for m in members)
         # add instance attributes from the analyzer
-        if self.analyzer:
-            attr_docs = self.analyzer.find_attr_docs()
-            namespace = '.'.join(self.objpath)
-            for item in attr_docs.iteritems():
-                if item[0][0] == namespace:
-                    if item[0][1] not in membernames:
-                        members.append((item[0][1], INSTANCEATTR))
+        for aname in analyzed_member_names:
+            if aname not in membernames and \
+               (want_all or aname in self.options.members):
+                members.append((aname, INSTANCEATTR))
         return False, sorted(members)
 
     def filter_members(self, members, want_all):
             if want_all and membername.startswith('__') and \
                    membername.endswith('__') and len(membername) > 4:
                 # special __methods__
-                if self.options.special_members and membername != '__doc__':
+                if self.options.special_members is ALL and \
+                        membername != '__doc__':
+                    keep = has_doc or self.options.undoc_members
+                elif self.options.special_members and \
+                        membername in self.options.special_members:
                     keep = has_doc or self.options.undoc_members
             elif want_all and membername.startswith('_'):
                 # ignore members whose name starts with _ by default
         '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,
+        'private-members': bool_option, 'special-members': members_option,
     }
 
     @classmethod
     """
 
     def _find_signature(self, encoding=None):
-        docstrings = Documenter.get_doc(self, encoding, 2)
+        docstrings = Documenter.get_doc(self, encoding)
         if len(docstrings) != 1:
             return
         doclines = docstrings[0]
         # the base name must match ours
         if not self.objpath or base != self.objpath[-1]:
             return
+        # re-prepare docstring to ignore indentation after signature
+        docstrings = Documenter.get_doc(self, encoding, 2)
+        doclines = docstrings[0]
         # ok, now jump over remaining empty lines and set the remaining
         # lines as the new doclines
         i = 1
         '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,
+        'private-members': bool_option, 'special-members': members_option,
     }
 
     @classmethod
     """
     objtype = 'method'
     member_order = 50
-    priority = 0
+    priority = 1  # must be more than FunctionDocumenter
 
     @classmethod
     def can_document_member(cls, member, membername, isattr, parent):

sphinx/ext/graphviz.py

               str(self.builder.config.graphviz_dot) + \
               str(self.builder.config.graphviz_dot_args)
               ).encode('utf-8')
-              
+
     fname = '%s-%s.%s' % (prefix, sha(hashkey).hexdigest(), format)
     if hasattr(self.builder, 'imgpath'):
         # HTML
                                  (fname, alt, imgcss))
             else:
                 # has a map: get the name of the map and connect the parts
-                mapname = mapname_re.match(imgmap[0]).group(1)
+                mapname = mapname_re.match(imgmap[0].decode('utf-8')).group(1)
                 self.body.append('<img src="%s" alt="%s" usemap="#%s" %s/>\n' %
                                  (fname, alt, mapname, imgcss))
-                self.body.extend(imgmap)
+                self.body.extend([item.decode('utf-8') for item in imgmap])
         if node.get('caption') and not inline:
             self.body.append('</p>\n<p class="caption">')
             self.body.append(self.encode(node['caption']))

sphinx/ext/inheritance_diagram.py

         for cls in classes:
             recurse(cls)
 
-        return all_classes.values()
+        return all_classes
 
     def class_name(self, cls, parts=0):
         """Given a class object, return a fully-qualified name.
 
     def get_all_class_names(self):
         """Get all of the class names involved in the graph."""
-        return [fullname for (_, fullname, _) in self.class_info]
+        return [fullname for (_, fullname, _) in self.class_info.values()]
 
     # These are the default attrs for graphviz
     default_graph_attrs = {
         'shape': 'box',
         'fontsize': 10,
         'height': 0.25,
-        'fontname': 'Vera Sans, DejaVu Sans, Liberation Sans, '
-                    'Arial, Helvetica, sans',
+        'fontname': '"Vera Sans, DejaVu Sans, Liberation Sans, '
+                    'Arial, Helvetica, sans"',
         'style': '"setlinewidth(0.5)"',
     }
     default_edge_attrs = {
         res.append('digraph %s {\n' % name)
         res.append(self._format_graph_attrs(g_attrs))
 
-        for name, fullname, bases in self.class_info:
+        for cls, (name, fullname, bases) in self.class_info.items():
             # Write the node
             this_node_attrs = n_attrs.copy()
-            url = urls.get(fullname)
-            if url is not None:
-                this_node_attrs['URL'] = '"%s"' % url
+            if fullname in urls:
+                this_node_attrs['URL'] = '"%s"' % urls[fullname]
+            # Use first line of docstring as tooltip, if available
+            if cls.__doc__:
+                doc = cls.__doc__.strip().split("\n")[0]
+                if doc:
+                    this_node_attrs['tooltip'] = '"%s"' % doc
             res.append('  "%s" [%s];\n' %
                        (name, self._format_node_attrs(this_node_attrs)))
 

sphinx/ext/intersphinx.py

     if update:
         env.intersphinx_inventory = {}
         env.intersphinx_named_inventory = {}
-        for name, _, invdata in cache.itervalues():
+        # Duplicate values in different inventories will shadow each
+        # other; which one will override which can vary between builds
+        # since they are specified using an unordered dict.  To make
+        # it more consistent, we sort the named inventories and then
+        # add the unnamed inventories last.  This means that the
+        # unnamed inventories will shadow the named ones but the named
+        # ones can still be accessed when the name is specified.
+        cached_vals = list(cache.itervalues())
+        named_vals = sorted(v for v in cached_vals if v[0])
+        unnamed_vals = [v for v in cached_vals if not v[0]]
+        for name, _, invdata in named_vals + unnamed_vals:
             if name:
                 env.intersphinx_named_inventory[name] = invdata
             for type, objects in invdata.iteritems():

sphinx/ext/linkcode.py

+# -*- coding: utf-8 -*-
+"""
+    sphinx.ext.linkcode
+    ~~~~~~~~~~~~~~~~~~~
+
+    Add external links to module code in Python object descriptions.
+
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+from docutils import nodes
+
+from sphinx import addnodes
+from sphinx.locale import _
+from sphinx.errors import SphinxError
+
+class LinkcodeError(SphinxError):
+    category = "linkcode error"
+
+def doctree_read(app, doctree):
+    env = app.builder.env
+
+    resolve_target = getattr(env.config, 'linkcode_resolve', None)
+    if not callable(env.config.linkcode_resolve):
+        raise LinkcodeError(
+            "Function `linkcode_resolve` is not given in conf.py")
+
+    domain_keys = dict(
+        py=['module', 'fullname'],
+        c=['names'],
+        cpp=['names'],
+        js=['object', 'fullname'],
+    )
+
+    for objnode in doctree.traverse(addnodes.desc):
+        domain = objnode.get('domain')
+        uris = set()
+        for signode in objnode:
+            if not isinstance(signode, addnodes.desc_signature):
+                continue
+
+            # Convert signode to a specified format
+            info = {}
+            for key in domain_keys.get(domain, []):
+                value = signode.get(key)
+                if not value:
+                    value = ''
+                info[key] = value
+            if not info:
+                continue
+
+            # Call user code to resolve the link
+            uri = resolve_target(domain, info)
+            if not uri:
+                # no source
+                continue
+
+            if uri in uris or not uri:
+                # only one link per name, please
+                continue
+            uris.add(uri)
+
+            onlynode = addnodes.only(expr='html')
+            onlynode += nodes.reference('', '', internal=False, refuri=uri)
+            onlynode[0] += nodes.inline('', _('[source]'),
+                                        classes=['viewcode-link'])
+            signode += onlynode
+
+def setup(app):
+    app.connect('doctree-read', doctree_read)
+    app.add_config_value('linkcode_resolve', None, '')

sphinx/ext/oldcmarkup.py

 _warned_oldcmarkup = False
 WARNING_MSG = 'using old C markup; please migrate to new-style markup ' \
               '(e.g. c:function instead of cfunction), see ' \
-              'http://sphinx.pocoo.org/domains.html'
+              'http://sphinx-doc.org/domains.html'
 
 
 class OldCDirective(Directive):

sphinx/ext/pngmath.py

     app.add_config_value('pngmath_latex', 'latex', 'html')
     app.add_config_value('pngmath_use_preview', False, 'html')
     app.add_config_value('pngmath_dvipng_args',
-                         ['-gamma 1.5', '-D 110'], 'html')
+                         ['-gamma', '1.5', '-D', '110', '-bg', 'Transparent'],
+                         'html')
     app.add_config_value('pngmath_latex_args', [], 'html')
     app.add_config_value('pngmath_latex_preamble', '', 'html')
     app.add_config_value('pngmath_add_tooltips', True, 'html')

sphinx/highlighting.py

             # just replace all non-ASCII characters.
             src = src.encode('ascii', 'replace')
 
+        if (3, 0) <= sys.version_info < (3, 2):
+            # Python 3.1 can't process '\r' as linesep.
+            # `parser.suite("print('hello')\r\n")` cause error.
+            if '\r\n' in src:
+                src = src.replace('\r\n', '\n')
+
         if parser is None:
             return True
 
             if self.dest == 'html':
                 return hlsource
             else:
+                if not isinstance(hlsource, unicode):  # Py2 / Pygments < 1.6
+                    hlsource = hlsource.decode()
                 return hlsource.translate(tex_hl_escape_map_new)
         except ErrorToken:
             # this is most probably not the selected language,
Add a comment to this file

sphinx/locale/bn/LC_MESSAGES/sphinx.mo

Binary file modified.

sphinx/locale/bn/LC_MESSAGES/sphinx.po

 #: sphinx/themes/basic/layout.html:198
 #, python-format
 msgid ""
-"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> "
+"Created using <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
 "%(sphinx_version)s."
 msgstr ""
-"<a href=\"http://sphinx.pocoo.org/\">Sphinx</a> %(sphinx_version)s দিয়ে "
+"<a href=\"http://sphinx-doc.org/\">Sphinx</a> %(sphinx_version)s দিয়ে "
 "তৈরী।"
 
 #: sphinx/themes/basic/opensearch.xml:4
Add a comment to this file

sphinx/locale/ca/LC_MESSAGES/sphinx.mo

Binary file modified.

sphinx/locale/ca/LC_MESSAGES/sphinx.po

 #: sphinx/themes/basic/layout.html:198
 #, python-format
 msgid ""
-"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> "
+"Created using <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
 "%(sphinx_version)s."
 msgstr ""
-"Creat amb <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> "
+"Creat amb <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
 "%(sphinx_version)s."
 
 #: sphinx/themes/basic/opensearch.xml:4
Add a comment to this file

sphinx/locale/cs/LC_MESSAGES/sphinx.mo

Binary file modified.

sphinx/locale/cs/LC_MESSAGES/sphinx.po

 #: sphinx/themes/basic/layout.html:198
 #, python-format
 msgid ""
-"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> "
+"Created using <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
 "%(sphinx_version)s."
 msgstr ""
-"Vytvořeno pomocí <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> "
+"Vytvořeno pomocí <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
 "%(sphinx_version)s."
 
 #: sphinx/themes/basic/opensearch.xml:4
Add a comment to this file

sphinx/locale/da/LC_MESSAGES/sphinx.mo

Binary file modified.

sphinx/locale/da/LC_MESSAGES/sphinx.po

 #: sphinx/themes/basic/layout.html:198
 #, python-format
 msgid ""
-"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> "
+"Created using <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
 "%(sphinx_version)s."
 msgstr ""
-"Bygget med <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> "
+"Bygget med <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
 "%(sphinx_version)s."
 
 #: sphinx/themes/basic/opensearch.xml:4
Add a comment to this file

sphinx/locale/de/LC_MESSAGES/sphinx.mo

Binary file modified.

sphinx/locale/de/LC_MESSAGES/sphinx.po

 #: sphinx/themes/basic/layout.html:198
 #, python-format
 msgid ""
-"Created using <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> "
+"Created using <a href=\"http://sphinx-doc.org/\">Sphinx</a> "
 "%(sphinx_version)s."
 msgstr ""
-"Mit <a href=\"http://sphinx.pocoo.org/\">Sphinx</a> %(sphinx_version)s "
+"Mit <a href=\"http://sphinx-doc.org/\">Sphinx</a> %(sphinx_version)s "
 "erstellt."