Commits

Anonymous committed 83b2cf4 Merge

Comments (0)

Files changed (165)

 878a1874a8e63f1b5a6b939ed86b6c120bf168c6 1.0.5
 48688502e78b09c03b877910b64368c5db9bb4ff 1.0.6
 f7f069b6d1e5cc2d4394420be9a4a3efc0cb4d47 1.0.7
+61cb589edeba5800c2bb9a4159c5986451d90a08 1.0.8
+0a63129ab59bf013068ea9da3382e567ed5400c3 1.1
+e753d03451a6eddc1ad3876bd383a12c50aa4cf2 1.1.1
+7d389fe78ee953f32dcece8ef39b1f7136666f6a 1.1.2
 * John Waltman -- Texinfo builder
 * Barry Warsaw -- setup command improvements
 * Sebastian Wiesner -- image handling, distutils support
+* Joel Wurtz -- cellspanning support in LaTeX
 
 Many thanks for all contributions!
 
-Release 1.1 (in development)
+Release 1.2 (in development)
 ============================
 
+* PR#28: Added Hungarian translation.
+
+* PR#35: Added Slovak translation.
+
+
+Release 1.1.3 (in development)
+==============================
+
+* PR#40: Fix ``safe_repr`` function to decode bytestrings with non-ASCII
+  characters correctly.
+
+* PR#37: Allow configuring sphinx-apidoc via ``SPHINX_APIDOC_OPTIONS``.
+
+* PR#34: Restore Python 2.4 compatibility.
+
+* PR#36: Make the "bibliography to TOC" fix in LaTeX output specific to
+  the document class.
+
+
+Release 1.1.2 (Nov 1, 2011) -- 1.1.1 is a silly version number anyway!
+======================================================================
+
+* #809: Include custom fixers in the source distribution.
+
+
+Release 1.1.1 (Nov 1, 2011)
+===========================
+
+* #791: Fix QtHelp, DevHelp and HtmlHelp index entry links.
+
+* #792: Include "sphinx-apidoc" in the source distribution.
+
+* #797: Don't crash on a misformatted glossary.
+
+* #801: Make intersphinx work properly without SSL support.
+
+* #805: Make the ``Sphinx.add_index_to_domain`` method work correctly.
+
+* #780: Fix Python 2.5 compatibility.
+
+
+Release 1.1 (Oct 9, 2011)
+=========================
+
 Incompatible changes
 --------------------
 
   value anymore.  (It was the only thing that the directive did output, and
   therefore quite inconsistent.)
 
+* Removed support for old dependency versions; requirements are now:
+
+  - Pygments >= 1.2
+  - Docutils >= 0.7
+  - Jinja2   >= 2.3
+
 Features added
 --------------
 
 
 * Markup:
 
-  - #138: Add an :rst:role:`index` role, to make inline index entries.
-  - #454: Add more index markup capabilities: marking see/seealso entries,
+  - #138: Added an :rst:role:`index` role, to make inline index entries.
+  - #454: Added more index markup capabilities: marking see/seealso entries,
     and main entries for a given key.
-  - #460: Allow limiting the depth of section numbers for HTML using the
+  - #460: Allowed limiting the depth of section numbers for HTML using the
     :rst:dir:`toctree`\'s ``numbered`` option.
   - #586: Implemented improved :rst:dir:`glossary` markup which allows
     multiple terms per definition.
   - #478: Added :rst:dir:`py:decorator` directive to describe decorators.
   - C++ domain now supports array definitions.
+  - C++ domain now supports doc fields (``:param x:`` inside directives).
   - Section headings in :rst:dir:`only` directives are now correctly
     handled.
+  - Added ``emphasize-lines`` option to source code directives.
+  - #678: C++ domain now supports superclasses.
 
 * HTML builder:
 
     requests and allow configuring the timeout.  New config values:
     :confval:`linkcheck_timeout` and :confval:`linkcheck_workers`.
   - #521: Added :confval:`linkcheck_ignore` config value.
+  - #28: Support row/colspans in tables in the LaTeX builder.
 
 * Configuration and extensibility:
 
   - #537: Added :confval:`nitpick_ignore`.
   - #306: Added :event:`env-get-outdated` event.
+  - :meth:`.Application.add_stylesheet` now accepts full URIs.
 
 * Autodoc:
 
   - #367: Added automatic exclusion of hidden members in inheritance
     diagrams, and an option to selectively enable it.
   - Added :confval:`pngmath_add_tooltips`.
+  - The math extension displaymath directives now support ``name`` in
+    addition to ``label`` for giving the equation label, for compatibility
+    with Docutils.
 
 * New locales:
 
   - #221: Added Swedish locale.
   - #526: Added Iranian locale.
   - #694: Added Latvian locale.
-
-
-Release 1.0.8 (in development)
-==============================
+  - Added Nepali locale.
+  - #714: Added Korean locale.
+  - #766: Added Estonian locale.
+
+* Bugs fixed:
+
+  - #778: Fix "hide search matches" link on pages linked by search.
+  - Fix the source positions referenced by the "viewcode" extension.
+
+
+Release 1.0.8 (Sep 23, 2011)
+============================
+
+* #627: Fix tracebacks for AttributeErrors in autosummary generation.
+
+* Fix the ``abbr`` role when the abbreviation has newlines in it.
+
+* #727: Fix the links to search results with custom object types.
+
+* #648: Fix line numbers reported in warnings about undefined
+  references.
+
+* #696, #666: Fix C++ array definitions and template arguments
+  that are not type names.
+
+* #633: Allow footnotes in section headers in LaTeX output.
+
+* #616: Allow keywords to be linked via intersphinx.
+
+* #613: Allow Unicode characters in production list token names.
+
+* #720: Add dummy visitors for graphviz nodes for text and man.
+
+* #704: Fix image file duplication bug.
+
+* #677: Fix parsing of multiple signatures in C++ domain.
+
+* #637: Ignore Emacs lock files when looking for source files.
+
+* #544: Allow .pyw extension for importable modules in autodoc.
+
+* #700: Use ``$(MAKE)`` in quickstart-generated Makefiles.
+
+* #734: Make sidebar search box width consistent in browsers.
+
+* #644: Fix spacing of centered figures in HTML output.
+
+* #767: Safely encode SphinxError messages when printing them to
+  sys.stderr.
+
+* #611: Fix LaTeX output error with a document with no sections but
+  a link target.
+
+* Correctly treat built-in method descriptors as methods in autodoc.
+
+* #706: Stop monkeypatching the Python textwrap module.
 
 * #657: viewcode now works correctly with source files that have
   non-ASCII encoding.
 
 * #647: Do not apply SmartyPants in parsed-literal blocks.
 
+* C++ domain now supports array definitions.
+
 
 Release 1.0.7 (Jan 15, 2011)
 ============================
 * CodePy: http://documen.tician.de/codepy/
 * Cython: http://docs.cython.org/
 * C\\C++ Python language binding project: http://language-binding.net/index.html
+* Cormoran: http://cormoran.nhopkg.org/docs/
 * Director: http://packages.python.org/director/
 * Dirigible: http://www.projectdirigible.com/documentation/
+* Elemental: http://elemental.googlecode.com/hg/doc/build/html/index.html
 * F2py: http://f2py.sourceforge.net/docs/
 * GeoDjango: http://geodjango.org/docs/
+* Genomedata: http://noble.gs.washington.edu/proj/genomedata/doc/1.2.2/genomedata.html
 * gevent: http://www.gevent.org/
 * Google Wave API: http://wave-robot-python-client.googlecode.com/svn/trunk/pydocs/index.html
 * GSL Shell: http://www.nongnu.org/gsl-shell/
 * PyUblas: http://documen.tician.de/pyublas/
 * Quex: http://quex.sourceforge.net/doc/html/main.html
 * Scapy: http://www.secdev.org/projects/scapy/doc/
+* Segway: http://noble.gs.washington.edu/proj/segway/doc/1.1.0/segway.html
 * SimPy: http://simpy.sourceforge.net/SimPyDocs/index.html
 * SymPy: http://docs.sympy.org/
 * WTForms: http://wtforms.simplecodes.com/docs/
 * C/C++ Development with Eclipse: http://eclipsebook.in/ (agogo)
 * Distribute: http://packages.python.org/distribute/ (nature)
 * Jinja: http://jinja.pocoo.org/ (scrolls)
+* jsFiddle: http://doc.jsfiddle.net/ (nature)
 * pip: http://pip.openplans.org/ (nature)
 * Programmieren mit PyGTK und Glade (German):
   http://www.florian-diesch.de/doc/python-und-glade/online/ (agogo)
-* pypol: http://pypol.altervista.org/ (nature)
 * Spring Python: http://springpython.webfactional.com/current/sphinx/index.html
   (nature)
 * sqlparse: http://python-sqlparse.googlecode.com/svn/docs/api/index.html
   (agogo)
+* Sylli: http://sylli.sourceforge.net/ (nature)
 * libLAS: http://liblas.org/ (nature)
 
 
 * Blinker: http://discorporate.us/projects/Blinker/docs/
 * Classy: classy: http://classy.pocoo.org/
 * Django: http://docs.djangoproject.com/
+* e-cidadania: http://e-cidadania.readthedocs.org/en/latest/
 * Flask: http://flask.pocoo.org/docs/
 * Flask-OpenID: http://packages.python.org/Flask-OpenID/
+* Gameduino: http://excamera.com/sphinx/gameduino/
 * GeoServer: http://docs.geoserver.org/
 * Glashammer: http://glashammer.org/
 * MirrorBrain: http://mirrorbrain.org/docs/
 * German Plone 4.0 user manual: http://www.hasecke.com/plone-benutzerhandbuch/4.0/
 * Pylons: http://pylonshq.com/docs/en/0.9.7/
 * PyMOTW: http://www.doughellmann.com/PyMOTW/
+* pypol: http://pypol.altervista.org/ (celery)
 * qooxdoo: http://manual.qooxdoo.org/current
 * Roundup: http://www.roundup-tracker.org/
 * Selenium: http://seleniumhq.org/docs/
 * A personal page: http://www.dehlia.in/
 * Benoit Boissinot: http://bboissin.appspot.com/
 * lunarsite: http://lunaryorn.de/
+* Red Hot Chili Python: http://redhotchilipython.com/
 * The Wine Cellar Book: http://www.thewinecellarbook.com/doc/en/
 * VOR: http://www.vor-cycling.be/
 
 OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 ----------------------------------------------------------------------
+
+The included Underscore JavaScript library is available under the MIT
+license:
+
+----------------------------------------------------------------------
+Copyright (c) 2009 Jeremy Ashkenas, DocumentCloud
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
 include sphinx-autogen.py
 include sphinx-build.py
 include sphinx-quickstart.py
+include sphinx-apidoc.py
 
 recursive-include sphinx/texinputs *
 recursive-include sphinx/themes *
 recursive-include sphinx/ext/autosummary/templates *
 recursive-include tests *
 recursive-include utils *
+recursive-include custom_fixers *
 include sphinx/pycode/Grammar.txt
 
 recursive-include doc *
      '', 1),
     ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
      'template generator', '', 1),
+    ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool',
+     '', 1),
 ]
 
 texinfo_documents = [
    * ``de`` -- German
    * ``en`` -- English
    * ``es`` -- Spanish
+   * ``et`` -- Estonian
    * ``fa`` -- Iranian
    * ``fi`` -- Finnish
    * ``fr`` -- French
    * ``hr`` -- Croatian
+   * ``hu`` -- Hungarian
    * ``it`` -- Italian
    * ``ja`` -- Japanese
+   * ``ko`` -- Korean
    * ``lt`` -- Lithuanian
    * ``lv`` -- Latvian
+   * ``ne`` -- Nepali
    * ``nl`` -- Dutch
    * ``pl`` -- Polish
    * ``pt_BR`` -- Brazilian Portuguese
    * ``ru`` -- Russian
+   * ``sk`` -- Slovak
    * ``sl`` -- Slovenian
    * ``sv`` -- Swedish
    * ``tr`` -- Turkish
    add the directory :file:`./locale` to this settting, the message catalogs
    (compiled from ``.po`` format using :program:`msgfmt`) must be in
    :file:`./locale/{language}/LC_MESSAGES/sphinx.mo`.  The text domain of
-   individual documents depends on their docname if they are top-level project
-   files and on their base directory otherwise.
+   individual documents depends on :confval:`gettext_compact`.
 
    The default is ``[]``.
 
+.. confval:: gettext_compact
+
+   .. versionadded:: 1.1
+
+   If true, a document's text domain is its docname if it is a top-level
+   project file and its very base directory otherwise.
+
+   By default, the document ``markup/code.rst`` ends up in the ``markup`` text
+   domain.  With this option set to ``False``, it is ``markup/code``.
+
 
 .. _html-options:
 
 
          Describe a casting operator here.
 
+      .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
+
+         Describe a constexpr function here.
+
       .. cpp:member:: std::string theclass::name
 
+      .. cpp:member:: std::string theclass::name[N][M]
+
       .. cpp:type:: theclass::const_iterator
 
    Will be rendered like this:
 
          Describe a casting operator here.
 
+      .. cpp:function:: constexpr void foo(std::string &bar[2]) noexcept
+
+         Describe a constexpr function here.
+
       .. cpp:member:: std::string theclass::name
 
+      .. cpp:member:: std::string theclass::name[N][M]
+
       .. cpp:type:: theclass::const_iterator
 
 .. rst:directive:: .. cpp:namespace:: namespace

doc/ext/appapi.rst

      <http://docutils.sourceforge.net/docs/howto/rst-directives.html>`_ for
      details.
 
-     The directive class normally must inherit from the class
-     ``docutils.parsers.rst.Directive``.  When writing a directive for usage in
-     a Sphinx extension, you inherit from ``sphinx.util.compat.Directive``
-     instead which does the right thing even on docutils 0.4 (which doesn't
-     support directive classes otherwise).
+     The directive class must inherit from the class
+     ``docutils.parsers.rst.Directive``.
 
    For example, the (already existing) :rst:dir:`literalinclude` directive would be
    added like this:
 
    Add *filename* to the list of CSS files that the default HTML template will
    include.  Like for :meth:`add_javascript`, the filename must be relative to
-   the HTML static path.
+   the HTML static path, or a full URI with scheme.
 
    .. versionadded:: 1.0
 

doc/ext/autosummary.rst

    contain links to the documented items, and short summary blurbs extracted
    from their docstrings.
 
-2. The convenience script :program:`sphinx-autogen` or the new
+2. Optionally, the convenience script :program:`sphinx-autogen` or the new
    :confval:`autosummary_generate` config value can be used to generate short
    "stub" files for the entries listed in the :rst:dir:`autosummary` directives.
-   These by default contain only the corresponding :mod:`sphinx.ext.autodoc`
-   directive.
+   These files by default contain only the corresponding :mod:`sphinx.ext.autodoc`
+   directive, but can be customized with templates.
 
 
 .. rst:directive:: autosummary
 
    Insert a table that contains links to documented items, and a short summary
-   blurb (the first sentence of the docstring) for each of them.  The
-   :rst:dir:`autosummary` directive can also optionally serve as a :rst:dir:`toctree`
-   entry for the included items.
+   blurb (the first sentence of the docstring) for each of them.
+
+   The :rst:dir:`autosummary` directive can also optionally serve as a
+   :rst:dir:`toctree` entry for the included items. Optionally, stub
+   ``.rst`` files for these items can also be automatically generated.
 
    For example, ::
 
 ======================
 
 .. module:: sphinx.ext.mathbase
-   :synopsis: Common math support for pngmath and jsmath.
+   :synopsis: Common math support for pngmath and mathjax / jsmath.
 
 .. versionadded:: 0.5
 
 Since mathematical notation isn't natively supported by HTML in any way, Sphinx
-supports math in documentation with two extensions.
+supports math in documentation with several extensions.
 
-The basic math support that is common to both extensions is contained in
-:mod:`sphinx.ext.mathbase`.  Other math support extensions should,
-if possible, reuse that support too.
+The basic math support is contained in :mod:`sphinx.ext.mathbase`. Other math
+support extensions should, if possible, reuse that support too.
 
 .. note::
 
    :mod:`.mathbase` is not meant to be added to the :confval:`extensions` config
    value, instead, use either :mod:`sphinx.ext.pngmath` or
-   :mod:`sphinx.ext.jsmath` as described below.
+   :mod:`sphinx.ext.mathjax` as described below.
 
 The input language for mathematics is LaTeX markup.  This is the de-facto
 standard for plain-text math notation and has the added advantage that no
       .. math:: (a + b)^2 = a^2 + 2ab + b^2
 
    Normally, equations are not numbered.  If you want your equation to get a
-   number, use the ``label`` option.  When given, it selects a label for the
-   equation, by which it can be cross-referenced, and causes an equation number
-   to be issued.  See :rst:role:`eqref` for an example.  The numbering style depends
-   on the output format.
+   number, use the ``label`` option.  When given, it selects an internal label
+   for the equation, by which it can be cross-referenced, and causes an equation
+   number to be issued.  See :rst:role:`eqref` for an example.  The numbering
+   style depends on the output format.
 
    There is also an option ``nowrap`` that prevents any wrapping of the given
    math in a math environment.  When you give this option, you must make sure
 course means that the computer where the docs are built must have both programs
 available.
 
-There are various config values you can set to influence how the images are built:
+There are various config values you can set to influence how the images are
+built:
 
 .. confval:: pngmath_latex
 
 .. confval:: mathjax_path
 
    The path to the JavaScript file to include in the HTML files in order to load
-   JSMath.
+   MathJax.
 
    The default is the ``http://`` URL that loads the JS files from the `MathJax
    CDN <http://www.mathjax.org/docs/1.1/start.html>`_.  If you want MathJax to
    The path can be absolute or relative; if it is relative, it is relative to
    the ``_static`` directory of the built docs.
 
-   For example, if you put JSMath into the static path of the Sphinx docs, this
+   For example, if you put MathJax into the static path of the Sphinx docs, this
    value would be ``MathJax/MathJax.js``.  If you host more than one Sphinx
    documentation set on one server, it is advisable to install MathJax in a
    shared location.
 Read the Docs
     http://readthedocs.org is a documentation hosting service based around Sphinx.
     They will host sphinx documentation, along with supporting a number of other
-    features including version support, PDF generation, and more. The `Getting 
+    features including version support, PDF generation, and more. The `Getting
     Started <http://read-the-docs.readthedocs.org/en/latest/getting_started.html>`_
     guide is a good place to start.
 
 up automatically.
 
 An example: you have a document ``usage.rst`` in your Sphinx project.  The
-gettext builder will put its messages into ``usage.pot``.  Image you have
+gettext builder will put its messages into ``usage.pot``.  Imagine you have
 Spanish translations [2]_ on your hands in ``usage.po`` --- for your builds to
 be translated you need to follow these instructions:
 
 to reStructuredText/Sphinx from other documentation systems.
 
 * Gerard Flanagan has written a script to convert pure HTML to reST; it can be
-  found at `BitBucket
-  <https://bitbucket.org/djerdo/musette/src/tip/musette/html/html2rest.py>`_.
+  found at the `Python Package Index <http://pypi.python.org/pypi/html2rest>`_.
 
 * For converting the old Python docs to Sphinx, a converter was written which
   can be found at `the Python SVN repository
 * Marcin Wojdyr has written a script to convert Docbook to reST with Sphinx
   markup; it is at `Google Code <http://code.google.com/p/db2rst/>`_.
 
+* Christophe de Vienne wrote a tool to convert from Open/LibreOffice documents
+  to Sphinx: `odt2sphinx <http://pypi.python.org/pypi/odt2sphinx/>`_.
+
+* To convert different markups, `Pandoc <http://johnmacfarlane.net/pandoc/>`_ is
+  a very helpful tool.
+
 
 Use with other systems
 ----------------------
 -------------
 
 Sphinx needs at least **Python 2.4** or **Python 3.1** to run, as well as the
-docutils_ and Jinja2_ libraries.  Sphinx should work with docutils version 0.5
+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.
 

doc/invocation.rst

 
 The :program:`sphinx-build` script has several options:
 
+.. program:: sphinx-build
+
 .. option:: -b buildername
 
    The most important option: it selects a builder.  The most common builders
 .. describe:: SPHINXOPTS
 
    Additional options for :program:`sphinx-build`.
+
+
+.. _invocation-apidoc:
+
+Invocation of sphinx-apidoc
+===========================
+
+The :program:`sphinx-apidoc` generates completely automatic API documentation
+for a Python package.  It is called like this::
+
+     $ sphinx-apidoc [options] -o outputdir packagedir [pathnames]
+
+where *packagedir* is the path to the package to document, and *outputdir* is
+the directory where the generated sources are placed.  Any *pathnames* given
+are paths to be excluded ignored during generation.
+
+The :program:`sphinx-apidoc` script has several options:
+
+.. program:: sphinx-apidoc
+
+.. option:: -o outputdir
+
+   Gives the directory in which to place the generated output.
+
+.. option:: -f, --force
+
+   Normally, sphinx-apidoc does not overwrite any files.  Use this option to
+   force the overwrite of all files that it generates.
+
+.. option:: -n, --dry-run
+
+   With this option given, no files will be written at all.
+
+.. option:: -s suffix
+
+   This option selects the file name suffix of output files.  By default, this
+   is ``rst``.
+
+.. option:: -d maxdepth
+
+   This sets the maximum depth of the table of contents, if one is generated.
+
+.. option:: -T, --no-toc
+
+   This prevents the generation of a table-of-contents file ``modules.rst``.
+   This has no effect when :option:`--full` is given.
+
+.. option:: -F, --full
+
+   This option makes sphinx-apidoc create a full Sphinx project, using the same
+   mechanism as :program:`sphinx-quickstart`.  Most configuration values are set
+   to default values, but you can influence the most important ones using the
+   following options.
+
+.. option:: -H project
+
+   Sets the project name to put in generated files (see :confval:`project`).
+
+.. option:: -A author
+
+   Sets the author name(s) to put in generated files (see :confval:`copyright`).
+
+.. option:: -V version
+
+   Sets the project version to put in generated files (see :confval:`version`).
+
+.. option:: -R release
+
+   Sets the project release to put in generated files (see :confval:`release`).

doc/man/sphinx-apidoc.rst

+:orphan:
+
+sphinx-apidoc manual page
+=========================
+
+Synopsis
+--------
+
+**sphinx-apidoc** [*options*] -o <*outputdir*> <*sourcedir*> [*pathnames* ...]
+
+
+Description
+-----------
+
+:program:`sphinx-apidoc` is a tool for automatic generation of Sphinx sources
+that, using the autodoc extension, document a whole package in the style of
+other automatic API documentation tools.
+
+*sourcedir* must point to a Python package.  Any *pathnames* given are paths to
+be excluded from the generation.
+
+
+Options
+-------
+
+-o <outputdir>  Directory to place the output files.  If it does not exist,
+                it is created.
+-f, --force     Usually, apidoc does not overwrite files, unless this option
+                is given.
+-n, --dry-run   If given, apidoc does not create any files.
+-s <suffix>     Suffix for the source files generated, default is ``rst``.
+-d <maxdepth>   Maximum depth for the generated table of contents file.
+-T, --no-toc    Do not create a table of contents file.
+-F, --full      If given, a full Sphinx project is generated (``conf.py``,
+                ``Makefile`` etc.) using sphinx-quickstart.
+
+These options are used with ``-F``:
+
+-H <project>    Project name to put into the configuration.
+-A <author>     Author name(s) to put into the configuration.
+-V <version>    Project version.
+-R <release>    Project release.
+
+
+See also
+--------
+
+:manpage:`sphinx-build(1)`
+
+
+Author
+------
+
+Etienne Desautels, <etienne.desautels@gmail.com>, Georg Brandl
+<georg@python.org> et al.

doc/markup/code.rst

 
       Some more Ruby code.
 
+Additionally, an ``emphasize-lines`` option can be given to have Pygments
+emphasize particular lines::
+
+    .. code-block:: python
+       :emphasize-lines: 3,5
+
+       def some_function():
+           interesting = False
+           print 'This line is highlighted.'
+           print 'This one is not...'
+           print '...but this one is.'
+
+.. versionchanged:: 1.1
+   ``emphasize-lines`` has been added.
+
 
 Includes
 ^^^^^^^^
    desired tab width.
 
    The directive also supports the ``linenos`` flag option to switch on line
-   numbers, and a ``language`` option to select a language different from the
-   current file's standard language.  Example with options::
+   numbers, the ``emphasize-lines`` option to emphasize particular lines, and
+   a ``language`` option to select a language different from the current
+   file's standard language.  Example with options::
 
       .. literalinclude:: example.rb
          :language: ruby
+         :emphasize-lines: 12,15-18
          :linenos:
 
    Include files are assumed to be encoded in the :confval:`source_encoding`.

doc/markup/para.rst

 subdocuments, is described in :ref:`toctree-directive`.
 
 For local tables of contents, use the standard reST :dudir:`contents directive
-<contents>`.
+<table-of-contents>`.
 
 
 Glossary

doc/markup/toctree.rst

 relations between the single files the documentation is made of, as well as
 tables of contents.  The ``toctree`` directive is the central element.
 
+.. note::
+
+   Simple "inclusion" of one file in another can be done with the
+   :dudir:`include` directive.
+
 .. rst:directive:: toctree
 
    This directive inserts a "TOC tree" at the current location, using the
 
 * Additional body elements:
 
-  - :dudir:`contents` (a local, i.e. for the current file only, table of
-    contents)
+  - :dudir:`contents <table-of-contents>` (a local, i.e. for the current file
+    only, table of contents)
   - :dudir:`container` (a container with a custom class, useful to generate an
     outer ``<div>`` in HTML)
   - :dudir:`rubric` (a heading without relation to the document sectioning)
 
 and answer its questions.  (Be sure to say yes to the "autodoc" extension.)
 
+There is also an automatic "API documentation" generator called
+:program:`sphinx-apidoc`; see :ref:`invocation-apidoc` for details.
+
 
 Defining document structure
 ---------------------------
 to build HTML docs in the build directory you chose.  Execute ``make`` without
 an argument to see which targets are available.
 
+.. admonition:: How do I generate PDF documents?
+
+   ``make latexpdf`` runs the :mod:`LaTeX builder
+   <sphinx.builders.latex.LaTeXBuilder>` and readily invokes the pdfTeX
+   toolchain for you.
+
 
 Documenting objects
 -------------------
 <http://bitbucket.org/birkenfeld/sphinx/get/tip.gz#egg=Sphinx-dev>`_.
 '''
 
-requires = ['Pygments>=0.8', 'Jinja2>=2.2', 'docutils>=0.5']
+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.')
         'Operating System :: OS Independent',
         'Programming Language :: Python',
         'Programming Language :: Python :: 2',
+        'Programming Language :: Python :: 3',
         'Topic :: Documentation',
         'Topic :: Text Processing',
         'Topic :: Utilities',
     ],
     platforms='any',
-    packages=find_packages(),
+    packages=find_packages(exclude=['custom_fixers', 'test']),
     include_package_data=True,
     entry_points={
         'console_scripts': [

sphinx/__init__.py

 import sys
 from os import path
 
-__version__  = '1.1pre'
-__released__ = '1.1 (hg)'  # used when Sphinx builds its own docs
+__version__  = '1.2pre'
+__released__ = '1.2 (hg)'  # used when Sphinx builds its own docs
 
 package_dir = path.abspath(path.dirname(__file__))
 
     creates a modules index (named modules.<suffix>).
 
     This is derived from the "sphinx-autopackage" script, which is:
-    Copyright 2008 Société des arts technologiques (SAT), http://www.sat.qc.ca/.
+    Copyright 2008 Société des arts technologiques (SAT),
+    http://www.sat.qc.ca/
 
-    :copyright: 2007-2011 by the Sphinx team, see AUTHORS.
+    :copyright: Copyright 2007-2011 by the Sphinx team, see AUTHORS.
     :license: BSD, see LICENSE for details.
 """
 import os
 from os import path
 
 # automodule options
-OPTIONS = [
-    'members',
-    'undoc-members',
-    # 'inherited-members', # disabled because there's a bug in sphinx
-    'show-inheritance',
-]
+if 'SPHINX_APIDOC_OPTIONS' in os.environ:
+    OPTIONS = os.environ['SPHINX_APIDOC_OPTIONS'].split(',')
+else:
+    OPTIONS = [
+        'members',
+        'undoc-members',
+        # 'inherited-members', # disabled because there's a bug in sphinx
+        'show-inheritance',
+    ]
 
 INITPY = '__init__.py'
 
+
 def makename(package, module):
     """Join package and module with a dot."""
     # Both package and module can be None/empty.
         name = module
     return name
 
+
 def write_file(name, text, opts):
     """Write the output file for module/package <name>."""
-    fname = path.join(opts.destdir, "%s.%s" % (name, opts.suffix))
+    fname = path.join(opts.destdir, '%s.%s' % (name, opts.suffix))
     if opts.dryrun:
         print 'Would create file %s.' % fname
         return
         finally:
             f.close()
 
+
 def format_heading(level, text):
     """Create a heading of <level> [1, 2 or 3 supported]."""
     underlining = ['=', '-', '~', ][level-1] * len(text)
     return '%s\n%s\n\n' % (text, underlining)
 
+
 def format_directive(module, package=None):
     """Create the automodule directive and add the options."""
     directive = '.. automodule:: %s\n' % makename(package, module)
         directive += '    :%s:\n' % option
     return directive
 
+
 def create_module_file(package, module, opts):
     """Build the text of the file and write the file."""
     text = format_heading(1, '%s Module' % module)
     text += format_directive(module, package)
     write_file(makename(package, module), text, opts)
 
+
 def create_package_file(root, master_package, subroot, py_files, opts, subs):
     """Build the text of the file and write the file."""
     package = path.split(root)[-1]
 
     write_file(makename(master_package, subroot), text, opts)
 
-def create_modules_toc_file(master_package, modules, opts, name='modules'):
-    """
-    Create the module's index.
-    """
-    text = format_heading(1, '%s Modules' % opts.header)
+
+def create_modules_toc_file(modules, opts, name='modules'):
+    """Create the module's index."""
+    text = format_heading(1, '%s' % opts.header)
     text += '.. toctree::\n'
     text += '   :maxdepth: %s\n\n' % opts.maxdepth
 
 
     write_file(name, text, opts)
 
+
 def shall_skip(module):
-    """
-    Check if we want to skip this module.
-    """
-    # skip it, if there is nothing (or just \n or \r\n) in the file
-    return path.getsize(module) < 3
+    """Check if we want to skip this module."""
+    # skip it if there is nothing (or just \n or \r\n) in the file
+    return path.getsize(module) <= 2
+
 
 def recurse_tree(rootpath, excludes, opts):
     """
     """
     # use absolute path for root, as relative paths like '../../foo' cause
     # 'if "/." in root ...' to filter out *all* modules otherwise
-    rootpath = os.path.abspath(rootpath)
-    # check if the base directory is a package and get is name
+    rootpath = path.normpath(path.abspath(rootpath))
+    # check if the base directory is a package and get its name
     if INITPY in os.listdir(rootpath):
-        package_name = rootpath.split(path.sep)[-1]
+        root_package = rootpath.split(path.sep)[-1]
     else:
-        package_name = None
+        # otherwise, the base is a directory with packages
+        root_package = None
 
-    toc = []
-    tree = os.walk(rootpath, False)
-    for root, subs, files in tree:
-        # keep only the Python script files
-        py_files =  sorted([f for f in files if path.splitext(f)[1] == '.py'])
-        if INITPY in py_files:
+    toplevels = []
+    for root, subs, files in os.walk(rootpath):
+        if is_excluded(root, excludes):
+            del subs[:]
+            continue
+        # document only Python module files
+        py_files = sorted([f for f in files if path.splitext(f)[1] == '.py'])
+        is_pkg = INITPY in py_files
+        if is_pkg:
             py_files.remove(INITPY)
             py_files.insert(0, INITPY)
+        elif root != rootpath:
+            # only accept non-package at toplevel
+            del subs[:]
+            continue
         # remove hidden ('.') and private ('_') directories
-        subs = sorted([sub for sub in subs if sub[0] not in ['.', '_']])
-        # check if there are valid files to process
-        # TODO: could add check for windows hidden files
-        if "/." in root or "/_" in root \
-               or not py_files \
-               or is_excluded(root, excludes):
-            continue
-        if INITPY in py_files:
-            # we are in package ...
-            if (# ... with subpackage(s)
-                subs
-                or
-                # ... with some module(s)
-                len(py_files) > 1
-                or
-                # ... with a not-to-be-skipped INITPY file
-                not shall_skip(path.join(root, INITPY))
-               ):
-                subroot = root[len(rootpath):].lstrip(path.sep).\
-                          replace(path.sep, '.')
-                create_package_file(root, package_name, subroot,
+        subs[:] = sorted(sub for sub in subs if sub[0] not in ['.', '_'])
+
+        if is_pkg:
+            # we are in a package with something to document
+            if subs or len(py_files) > 1 or not \
+                shall_skip(path.join(root, INITPY)):
+                subpackage = root[len(rootpath):].lstrip(path.sep).\
+                    replace(path.sep, '.')
+                create_package_file(root, root_package, subpackage,
                                     py_files, opts, subs)
-                toc.append(makename(package_name, subroot))
-        elif root == rootpath:
+                toplevels.append(makename(root_package, subpackage))
+        else:
             # if we are at the root level, we don't require it to be a package
+            assert root == rootpath and root_package is None
             for py_file in py_files:
                 if not shall_skip(path.join(rootpath, py_file)):
                     module = path.splitext(py_file)[0]
-                    create_module_file(package_name, module, opts)
-                    toc.append(makename(package_name, module))
+                    create_module_file(root_package, module, opts)
+                    toplevels.append(module)
 
-    # create the module's index
-    if not opts.notoc:
-        create_modules_toc_file(package_name, toc, opts)
+    return toplevels
+
 
 def normalize_excludes(rootpath, excludes):
     """
     * otherwise it is joined with rootpath
     * with trailing slash
     """
-    sep = path.sep
     f_excludes = []
     for exclude in excludes:
         if not path.isabs(exclude) and not exclude.startswith(rootpath):
             exclude = path.join(rootpath, exclude)
-        if not exclude.endswith(sep):
-            exclude += sep
-        f_excludes.append(exclude)
+        f_excludes.append(path.normpath(exclude) + path.sep)
     return f_excludes
 
+
 def is_excluded(root, excludes):
     """
     Check if the directory is in the exclude list.
             return True
     return False
 
+
 def main(argv=sys.argv):
     """
     Parse and check the command line arguments.
 usage: %prog [options] -o <output_path> <module_path> [exclude_paths, ...]
 
 Look recursively in <module_path> for Python modules and packages and create
-a reST file with automodule directives per package in the <output_path>.
+one reST file with automodule directives per package in the <output_path>.
 
 Note: By default this script will not overwrite already created files.""")
 
                       help='Maximum depth of submodules to show in the TOC '
                       '(default: 4)', type='int', default=4)
     parser.add_option('-f', '--force', action='store_true', dest='force',
-                      help='Overwrite all the files')
+                      help='Overwrite all files')
     parser.add_option('-n', '--dry-run', action='store_true', dest='dryrun',
-                      help='Run the script without creating the files')
+                      help='Run the script without creating files')
     parser.add_option('-T', '--no-toc', action='store_true', dest='notoc',
-                      help='Don\'t create the table of contents file')
-    parser.add_option('-H', '--doc-header', action='store', dest='header',
-                      help='Documentation Header (default: Project)',
-                      default='Project')
+                      help='Don\'t create a table of contents file')
     parser.add_option('-s', '--suffix', action='store', dest='suffix',
                       help='file suffix (default: rst)', default='rst')
+    parser.add_option('-F', '--full', action='store_true', dest='full',
+                      help='Generate a full project with sphinx-quickstart')
+    parser.add_option('-H', '--doc-project', action='store', dest='header',
+                      help='Project name (default: root module name)')
+    parser.add_option('-A', '--doc-author', action='store', dest='author',
+                      type='str',
+                      help='Project author(s), used when --full is given')
+    parser.add_option('-V', '--doc-version', action='store', dest='version',
+                      help='Project version, used when --full is given')
+    parser.add_option('-R', '--doc-release', action='store', dest='release',
+                      help='Project release, used when --full is given, '
+                      'defaults to --doc-version')
 
     (opts, args) = parser.parse_args(argv[1:])
 
     if not args:
         parser.error('A package path is required.')
+
+    rootpath, excludes = args[0], args[1:]
     if not opts.destdir:
         parser.error('An output directory is required.')
-    rootpath, excludes = args[0], args[1:]
+    if opts.header is None:
+        opts.header = path.normpath(rootpath).split(path.sep)[-1]
+    if opts.suffix.startswith('.'):
+        opts.suffix = opts.suffix[1:]
     if not path.isdir(rootpath):
         print >>sys.stderr, '%s is not a directory.' % rootpath
         sys.exit(1)
     if not path.isdir(opts.destdir):
-        print '%s is not a valid output directory.' % opts.destdir
-        sys.exit(1)
+        if not opts.dryrun:
+            os.makedirs(opts.destdir)
     excludes = normalize_excludes(rootpath, excludes)
-    recurse_tree(rootpath, excludes, opts)
+    modules = recurse_tree(rootpath, excludes, opts)
+    if opts.full:
+        from sphinx import quickstart as qs
+        modules.sort()
+        prev_module = ''
+        text = ''
+        for module in modules:
+            if module.startswith(prev_module + '.'):
+                continue
+            prev_module = module
+            text += '   %s\n' % module
+        d = dict(
+            path = opts.destdir,
+            sep  = False,
+            dot  = '_',
+            project = opts.header,
+            author = opts.author or 'Author',
+            version = opts.version or '',
+            release = opts.release or opts.version or '',
+            suffix = '.' + opts.suffix,
+            master = 'index',
+            epub = True,
+            ext_autodoc = True,
+            ext_viewcode = True,
+            makefile = True,
+            batchfile = True,
+            mastertocmaxdepth = opts.maxdepth,
+            mastertoctree = text,
+        )
+        if not opts.dryrun:
+            qs.generate(d, silent=True, overwrite=opts.force)
+    elif not opts.notoc:
+        create_modules_toc_file(modules, opts)

sphinx/application.py

             raise ExtensionError('domain %s not yet registered' % domain)
         self.domains[domain].roles[name] = role
 
-    def add_index_to_domain(self, domain, name, localname, shortname, func):
+    def add_index_to_domain(self, domain, index):
         if domain not in self.domains:
             raise ExtensionError('domain %s not yet registered' % domain)
-        self.domains[domain].indices.append((name, localname, shortname))
-        setattr(self.domains[domain], 'get_%s_index' % name, func)
+        self.domains[domain].indices.append(index)
 
     def add_object_type(self, directivename, rolename, indextemplate='',
                         parse_node=None, ref_nodeclass=None, objname='',
 
     def add_stylesheet(self, filename):
         from sphinx.builders.html import StandaloneHTMLBuilder
-        StandaloneHTMLBuilder.css_files.append(
-            posixpath.join('_static', filename))
+        if '://' in filename:
+            StandaloneHTMLBuilder.css_files.append(filename)
+        else:
+            StandaloneHTMLBuilder.css_files.append(
+                posixpath.join('_static', filename))
 
     def add_lexer(self, alias, lexer):
         from sphinx.highlighting import lexers

sphinx/builders/devhelp.py

                 pass
             elif len(refs) == 1:
                 etree.SubElement(functions, 'function',
-                                 name=title, link=refs[0])
+                                 name=title, link=refs[0][1])
             else:
                 for i, ref in enumerate(refs):
                     etree.SubElement(functions, 'function',
                                      name="[%d] %s" % (i, title),
-                                     link=ref)
+                                     link=ref[1])
 
             if subitems:
                 parent_title = re.sub(r'\s*\(.*\)\s*$', '', title)

sphinx/builders/gettext.py

 from datetime import datetime
 from collections import defaultdict
 
-from docutils import nodes
-
 from sphinx.builders import Builder
 from sphinx.util.nodes import extract_messages
-from sphinx.util.osutil import SEP, copyfile
+from sphinx.util.osutil import SEP, safe_relpath, ensuredir, find_catalog
 from sphinx.util.console import darkgreen
 
 POHEADER = ur"""
 #, fuzzy
 msgid ""
 msgstr ""
-"Project-Id-Version: %(version)s\n"
+"Project-Id-Version: %(project)s %(version)s\n"
 "Report-Msgid-Bugs-To: \n"
 "POT-Creation-Date: %(ctime)s\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 """[1:]
 
 
+class Catalog(object):
+    """Catalog of translatable messages."""
+
+    def __init__(self):
+        self.messages = []  # retain insertion order, a la OrderedDict
+        self.metadata = {}  # msgid -> file, line, uid
+
+    def add(self, msg, origin):
+        if msg not in self.metadata:  # faster lookup in hash
+            self.messages.append(msg)
+            self.metadata[msg] = []
+        self.metadata[msg].append((origin.source, origin.line, origin.uid))
+
+
 class I18nBuilder(Builder):
     """
     General i18n builder.
 
     def init(self):
         Builder.init(self)
-        self.catalogs = defaultdict(dict)
+        self.catalogs = defaultdict(Catalog)
 
     def get_target_uri(self, docname, typ=None):
         return ''
         return
 
     def write_doc(self, docname, doctree):
-        catalog = self.catalogs[docname.split(SEP, 1)[0]]
+        catalog = self.catalogs[find_catalog(docname,
+                                             self.config.gettext_compact)]
 
         for node, msg in extract_messages(doctree):
-            if not msg in catalog:
-                catalog[msg] = []
-            if node.source and node.line:
-                position = {"source": node.source,
-                            "line": node.line}
-                catalog[msg].append(position)
+            catalog.add(msg, node)
 
 
 class MessageCatalogBuilder(I18nBuilder):
             # XXX should supply tz
             ctime = datetime.now().strftime('%Y-%m-%d %H:%M%z'),
         )
-        for section, messages in self.status_iterator(
+        for textdomain, catalog in self.status_iterator(
                 self.catalogs.iteritems(), "writing message catalogs... ",
-                lambda (section, _):darkgreen(section), len(self.catalogs)):
+                lambda (textdomain, _): darkgreen(textdomain),
+                                        len(self.catalogs)):
 
-            pofn = path.join(self.outdir, section + '.pot')
+            # noop if config.gettext_compact is set
+            ensuredir(path.join(self.outdir, path.dirname(textdomain)))
+
+            pofn = path.join(self.outdir, textdomain + '.pot')
             pofile = open(pofn, 'w', encoding='utf-8')
             try:
                 pofile.write(POHEADER % data)
-                for message, positions in messages.iteritems():
+
+                for message in catalog.messages:
+                    positions = catalog.metadata[message]
+
+                    # generate "#: file1:line1\n#: file2:line2 ..."
+                    pofile.write(u"#: %s\n" % "\n#: ".join("%s:%s" %
+                        (safe_relpath(source, self.outdir), line)
+                        for source, line, _ in positions))
+                    # generate "# uuid1\n# uuid2\n ..."
+                    pofile.write(u"# %s\n" % "\n# ".join(uid for _, _, uid
+                        in positions))
+
                     # message contains *one* line of text ready for translation
                     message = message.replace(u'\\', ur'\\'). \
                                       replace(u'"', ur'\"')
-                    for position in positions:
-                        source = path.relpath(position["source"], self.outdir)
-                        line = position["line"]
-                        pofile.write(u'#: %s:%d\n' % (source, line))
                     pofile.write(u'msgid "%s"\nmsgstr ""\n\n' % message)
+
             finally:
                 pofile.close()

sphinx/builders/html.py

         old_config_hash = old_tags_hash = ''
         try:
             fp = open(path.join(self.outdir, '.buildinfo'))
-            version = fp.readline()
-            if version.rstrip() != '# Sphinx build info version 1':
-                raise ValueError
-            fp.readline()  # skip commentary
-            cfg, old_config_hash = fp.readline().strip().split(': ')
-            if cfg != 'config':
-                raise ValueError
-            tag, old_tags_hash = fp.readline().strip().split(': ')
-            if tag != 'tags':
-                raise ValueError
-            fp.close()
+            try:
+                version = fp.readline()
+                if version.rstrip() != '# Sphinx build info version 1':
+                    raise ValueError
+                fp.readline()  # skip commentary
+                cfg, old_config_hash = fp.readline().strip().split(': ')
+                if cfg != 'config':
+                    raise ValueError
+                tag, old_tags_hash = fp.readline().strip().split(': ')
+                if tag != 'tags':
+                    raise ValueError
+            finally:
+                fp.close()
         except ValueError:
             self.warn('unsupported build info format in %r, building all' %
                       path.join(self.outdir, '.buildinfo'))

sphinx/builders/htmlhelp.py

             f.write('<UL>\n')
             def write_index(title, refs, subitems):
                 def write_param(name, value):
-                    item = '    <param name="%s" value="%s">\n' % (name, value)
+                    item = '    <param name="%s" value="%s">\n' % \
+                        (name, value[1])
                     f.write(item)
                 title = cgi.escape(title)
                 f.write('<LI> <OBJECT type="text/sitemap">\n')

sphinx/builders/qthelp.py

             groupdict = matchobj.groupdict()
             shortname = groupdict['title']
             id = groupdict.get('id')
-#            descr = groupdict.get('descr')
+            #descr = groupdict.get('descr')
             if shortname.endswith('()'):
                 shortname = shortname[:-2]
             id = '%s.%s' % (id, shortname)
 
         if id:
             item = ' '*12 + '<keyword name="%s" id="%s" ref="%s"/>' % (
-                                                                name, id, ref)
+                name, id, ref[1])
         else:
-            item = ' '*12 + '<keyword name="%s" ref="%s"/>' % (name, ref)
+            item = ' '*12 + '<keyword name="%s" ref="%s"/>' % (name, ref[1])
         item.encode('ascii', 'xmlcharrefreplace')
         return item
 

sphinx/cmdline.py

 from sphinx.application import Sphinx
 from sphinx.util import Tee, format_exception_cut_frames, save_traceback
 from sphinx.util.console import red, nocolor, color_terminal
+from sphinx.util.pycompat import terminal_safe
 
 
 def usage(argv, msg=None):
     except KeyboardInterrupt:
         if use_pdb:
             import pdb
-            print >>error, red('Interrupted while building, '
-                                   'starting debugger:')
+            print >>error, red('Interrupted while building, starting debugger:')
             traceback.print_exc()
             pdb.post_mortem(sys.exc_info()[2])
         return 1
         if use_pdb:
             import pdb
             print >>error, red('Exception occurred while building, '
-                                   'starting debugger:')
+                               'starting debugger:')
             traceback.print_exc()
             pdb.post_mortem(sys.exc_info()[2])
         else:
             print >>error
             if isinstance(err, SystemMessage):
                 print >>error, red('reST markup error:')
-                print >>error, err.args[0].encode('ascii', 'backslashreplace')
+                print >>error, terminal_safe(err.args[0])
             elif isinstance(err, SphinxError):
                 print >>error, red('%s:' % err.category)
-                print >>error, err
+                print >>error, terminal_safe(unicode(err))
             else:
                 print >>error, red('Exception occurred:')
                 print >>error, format_exception_cut_frames().rstrip()
 from os import path
 
 from sphinx.errors import ConfigError
+from sphinx.locale import l_
 from sphinx.util.osutil import make_filename
 from sphinx.util.pycompat import bytes, b, convert_with_2to3
 
         html_theme = ('default', 'html'),
         html_theme_path = ([], 'html'),
         html_theme_options = ({}, 'html'),
-        html_title = (lambda self: '%s %s documentation' %
+        html_title = (lambda self: l_('%s %s documentation') %
                                    (self.project, self.release),
                       'html'),
         html_short_title = (lambda self: self.html_title, 'html'),
         linkcheck_ignore = ([], None),
         linkcheck_timeout = (None, None),
         linkcheck_workers = (5, None),
+
+        # gettext options
+        gettext_compact = (True, 'gettext'),
     )
 
     def __init__(self, dirname, filename, overrides, tags):
                 # config file is executed
                 os.chdir(dirname)
                 # get config source
-                f = open(config_file, 'rb')
+                f = open(config_file, 'rU')
                 try:
                     source = f.read()
                 finally:

sphinx/directives/code.py

 
 from sphinx import addnodes
 from sphinx.util import parselinenos
+from sphinx.util.nodes import set_source_info
 
 
 class Highlight(Directive):
     final_argument_whitespace = False
     option_spec = {
         'linenos': directives.flag,
+        'emphasize-lines': directives.unchanged_required,
     }
 
     def run(self):
         code = u'\n'.join(self.content)
+
+        linespec = self.options.get('emphasize-lines')
+        if linespec:
+            try:
+                nlines = len(self.content)
+                hl_lines = [x+1 for x in parselinenos(linespec, nlines)]
+            except ValueError, err:
+                document = self.state.document
+                return [document.reporter.warning(str(err), line=self.lineno)]
+        else:
+            hl_lines = None
+
         literal = nodes.literal_block(code, code)
         literal['language'] = self.arguments[0]
         literal['linenos'] = 'linenos' in self.options
-        literal.line = self.lineno
+        if hl_lines is not None:
+            literal['highlight_args'] = {'hl_lines': hl_lines}
+        set_source_info(self, literal)
         return [literal]
 
 
         'end-before': directives.unchanged_required,
         'prepend': directives.unchanged_required,
         'append': directives.unchanged_required,
+        'emphasize-lines': directives.unchanged_required,
     }
 
     def run(self):
                     'Line spec %r: no lines pulled from include file %r' %
                     (linespec, filename), line=self.lineno)]
 
+        linespec = self.options.get('emphasize-lines')
+        if linespec:
+            try:
+                hl_lines = [x+1 for x in parselinenos(linespec, len(lines))]
+            except ValueError, err:
+                return [document.reporter.warning(str(err), line=self.lineno)]
+        else:
+            hl_lines = None
+
         startafter = self.options.get('start-after')
         endbefore  = self.options.get('end-before')
         prepend    = self.options.get('prepend')
         if self.options.get('tab-width'):
             text = text.expandtabs(self.options['tab-width'])
         retnode = nodes.literal_block(text, text, source=filename)
-        retnode.line = 1
-        retnode.attributes['line_number'] = self.lineno
+        set_source_info(self, retnode)
         if self.options.get('language', ''):
             retnode['language'] = self.options['language']
         if 'linenos' in self.options:
             retnode['linenos'] = True
+        if hl_lines is not None:
+            retnode['highlight_args'] = {'hl_lines': hl_lines}
         env.note_dependency(rel_filename)
         return [retnode]
 

sphinx/directives/other.py

 from sphinx import addnodes
 from sphinx.locale import _
 from sphinx.util import url_re, docname_join
-from sphinx.util.nodes import explicit_title_re, process_index_entry
+from sphinx.util.nodes import explicit_title_re, set_source_info, \
+    process_index_entry
 from sphinx.util.compat import make_admonition
 from sphinx.util.matching import patfilter
 
         subnode['hidden'] = 'hidden' in self.options
         subnode['numbered'] = self.options.get('numbered', 0)
         subnode['titlesonly'] = 'titlesonly' in self.options
+        set_source_info(self, subnode)
         wrappernode = nodes.compound(classes=['toctree-wrapper'])
         wrappernode.append(subnode)
         ret.append(wrappernode)
     def run(self):
         node = addnodes.versionmodified()
         node.document = self.state.document
+        set_source_info(self, node)
         node['type'] = self.name
         node['version'] = self.arguments[0]
         if len(self.arguments) == 2:
         else:
             ret = [node]
         env = self.state.document.settings.env
-        env.note_versionchange(node['type'], node['version'], node, self.lineno)
+        # XXX should record node.source as well
+        env.note_versionchange(node['type'], node['version'], node, node.line)
         return ret
 
 
     def run(self):
         node = addnodes.tabular_col_spec()
         node['spec'] = self.arguments[0]
-        node.line = self.lineno
+        set_source_info(self, node)
         return [node]
 
 
     def run(self):
         node = addnodes.only()
         node.document = self.state.document
-        node.line = self.lineno
+        set_source_info(self, node)
         node['expr'] = self.arguments[0]
         self.state.nested_parse(self.content, self.content_offset, node,
                                 match_titles=1)

sphinx/domains/c.py

             self.state.document.note_explicit_target(signode)
             inv = self.env.domaindata['c']['objects']
             if name in inv:
-                self.env.warn(
-                    self.env.docname,
+                self.state_machine.reporter.warning(
                     'duplicate C object description of %s, ' % name +
                     'other instance in ' + self.env.doc2path(inv[name][0]),
-                    self.lineno)
+                    line=self.lineno)
             inv[name] = (self.env.docname, self.objtype)
 
         indextext = self.get_index_text(name)

sphinx/domains/cpp.py

 from sphinx.directives import ObjectDescription
 from sphinx.util.nodes import make_refnode
 from sphinx.util.compat import Directive
+from sphinx.util.docfields import Field, GroupedField
 
 
 _identifier_re = re.compile(r'(~?\b[a-zA-Z_][a-zA-Z0-9_]*)\b')
 _string_re = re.compile(r"[LuU8]?('([^'\\]*(?:\\.[^'\\]*)*)'"
                         r'|"([^"\\]*(?:\\.[^"\\]*)*)")', re.S)
 _visibility_re = re.compile(r'\b(public|private|protected)\b')
-_array_def_re = re.compile(r'\[\s*(.+?)?\s*\]')
+_array_def_re = re.compile(r'\[\s*([^\]]+?)?\s*\]')
+_template_arg_re = re.compile(r'(%s)|([^,>]+)' % _string_re.pattern, re.S)
 _operator_re = re.compile(r'''(?x)
         \[\s*\]
     |   \(\s*\)
-    |   [!<>=/*%+|&^-]=?
     |   \+\+ | --
-    |   (<<|>>)=? | ~ | && | \| | \|\|
     |   ->\*? | \,
+    |   (<<|>>)=? | && | \|\|
+    |   [!<>=/*%+|&^~-]=?
 ''')
 
 _id_shortwords = {
     def __init__(self, description):
         self.description = description
 
+    def __str__(self):
+        return unicode(self).encode('utf-8')
+
     def __unicode__(self):
         return self.description
 
-    def __str__(self):
-        return unicode(self).encode('utf-8')
-
 
 class DefExpr(object):
 
-    def __unicode__(self):
-        raise NotImplementedError()
-
     def __eq__(self, other):
         if type(self) is not type(other):
             return False
         try:
             for key, value in self.__dict__.iteritems():
-                if value != getattr(other, value):
+                if value != getattr(other, key):
                     return False
         except AttributeError:
             return False
     def __str__(self):
         return unicode(self).encode('utf-8')
 
+    def __unicode__(self):
+        raise NotImplementedError()
+
     def __repr__(self):
         return '<%s %s>' % (self.__class__.__name__, self)
 
         return u'::'.join(map(unicode, self.path))
 
 
+class ArrayTypeSuffixDefExpr(object):
+
+    def __init__(self, size_hint=None):
+        self.size_hint = size_hint
+
+    def get_id_suffix(self):
+        return 'A'
+
+    def __unicode__(self):
+        return u'[%s]' % (
+            self.size_hint is not None and unicode(self.size_hint) or u'',
+        )
+
+
 class TemplateDefExpr(PrimaryDefExpr):
 
     def __init__(self, typename, args):
         return u'%s<%s>' % (self.typename, u', '.join(map(unicode, self.args)))
 
 
+class ConstantTemplateArgExpr(PrimaryDefExpr):
+
+    def __init__(self, arg):
+        self.arg = arg
+
+    def get_id(self):
+        return self.arg.replace(u' ', u'-')
+
+    def __unicode__(self):
+        return unicode(self.arg)
+
+
 class WrappingDefExpr(DefExpr):
 
     def __init__(self, typename):
         return u'%s*' % self.typename
 
 
-class ArrayDefExpr(WrappingDefExpr):
-
-    def __init__(self, typename, size_hint=None):
-        WrappingDefExpr.__init__(self, typename)
-        self.size_hint = size_hint
-
-    def get_id(self):
-        return self.typename.get_id() + u'A'
-
-    def __unicode__(self):
-        return u'%s[%s]' % (
-            self.typename,
-            self.size_hint is not None and unicode(self.size_hint) or u''
-        )
-
-
-class RefDefExpr(WrappingDefExpr):
+class LValRefDefExpr(WrappingDefExpr):
 
     def get_id(self):
         return self.typename.get_id() + u'R'
         return u'%s&' % self.typename
 
 
+class RValRefDefExpr(WrappingDefExpr):
+
+    def get_id(self):
+        return self.typename.get_id() + u'RR'
+
+    def __unicode__(self):
+        return u'%s&&' % self.typename
+
+
 class ConstDefExpr(WrappingDefExpr):
 
     def __init__(self, typename, prefix=False):
 
 class ArgumentDefExpr(DefExpr):
 
-    def __init__(self, type, name, default=None):
+    def __init__(self, type, name, type_suffixes, default=None):
         self.name = name
         self.type = type
+        self.type_suffixes = type_suffixes
         self.default = default
 
     def get_name(self):
         return self.name.get_name()
 
     def get_id(self):
-        if self.type is None:
-            return 'X'
-        return self.type.get_id()
+        buf = []
+        buf.append(self.type and self.type.get_id() or 'X')
+        for suffix in self.type_suffixes:
+            buf.append(suffix.get_id_suffix())
+        return u''.join(buf)
 
     def __unicode__(self):
-        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'')
+        buf = [(u'%s %s' % (self.type or u'', self.name or u'')).strip()]
+        if self.default is not None:
+            buf.append('=%s' % self.default)
+        for suffix in self.type_suffixes:
+            buf.append(unicode(suffix))
+        return u''.join(buf)
 
 
 class NamedDefExpr(DefExpr):
     def get_name(self):
         return self.name.get_name()
 
-    def get_modifiers(self):
+    def get_modifiers(self, visibility='public'):
         rv = []
-        if self.visibility != 'public':
+        if self.visibility != visibility:
             rv.append(self.visibility)
         if self.static:
             rv.append(u'static')
 
 class TypeObjDefExpr(NamedDefExpr):
 
-    def __init__(self, name, visibility, static, typename):
+    def __init__(self, name, visibility, static, typename, type_suffixes):
         NamedDefExpr.__init__(self, name, visibility, static)
         self.typename = typename
+        self.type_suffixes = type_suffixes
 
     def get_id(self):
         if self.typename is None:
-            return self.name.get_id()
-        return u'%s__%s' % (self.name.get_id(), self.typename.get_id())
+            buf = [self.name.get_id()]
+        else:
+            buf = [u'%s__%s' % (self.name.get_id(), self.typename.get_id())]
+        for suffix in self.type_suffixes:
+            buf.append(suffix.get_id_suffix())
+        return u''.join(buf)
 
     def __unicode__(self):
         buf = self.get_modifiers()
             buf.append(unicode(self.name))
         else:
             buf.extend(map(unicode, (self.typename, self.name)))
-        return u' '.join(buf)