Merge with arlaneenalra/sphinx

15 files changed, 239 insertions, 24 deletions

diff --git a/doc/conf.py b/doc/conf.py
index a1d0e8ce..6b547edd 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -36,7 +36,9 @@ epub_identifier = epub_publisher
 epub_pre_files = [('index.html', 'Welcome')]
 epub_exclude_files = ['_static/opensearch.xml', '_static/doctools.js',
     '_static/jquery.js', '_static/searchtools.js', '_static/underscore.js',
-    '_static/basic.css', 'search.html']
+    '_static/basic.css', 'search.html', '_static/websupport.js']
+epub_fix_images = False
+epub_max_image_width = 0
 
 latex_documents = [('contents', 'sphinx.tex', 'Sphinx Documentation',
                     'Georg Brandl', 'manual', 1)]
@@ -62,6 +64,8 @@ man_pages = [
      '', 1),
     ('man/sphinx-quickstart', 'sphinx-quickstart', 'Sphinx documentation '
      'template generator', '', 1),
+    ('man/sphinx-apidoc', 'sphinx-apidoc', 'Sphinx API doc generator tool',
+     '', 1),
 ]
 
 texinfo_documents = [
diff --git a/doc/config.rst b/doc/config.rst
index 5db7c74b..f840b289 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -372,12 +372,15 @@ documentation on :ref:`intl` for details.
    * ``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
@@ -385,6 +388,7 @@ documentation on :ref:`intl` for details.
    * ``pl`` -- Polish
    * ``pt_BR`` -- Brazilian Portuguese
    * ``ru`` -- Russian
+   * ``sk`` -- Slovak
    * ``sl`` -- Slovenian
    * ``sv`` -- Swedish
    * ``tr`` -- Turkish
@@ -404,11 +408,20 @@ documentation on :ref:`intl` for details.
    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:
 
@@ -772,6 +785,12 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    output is usually not wise.  This defaults to ``'epub'``, a theme designed to
    save visual space.
 
+.. confval:: epub_theme_options
+
+   A dictionary of options that influence the look and feel of the selected
+   theme.  These are theme-specific.  For the options understood by the builtin
+   themes, see :ref:`this section <builtin-themes>`.
+
 .. confval:: epub_title
 
    The title of the document.  It defaults to the :confval:`html_title` option
@@ -871,6 +890,23 @@ the `Dublin Core metadata <http://dublincore.org/>`_.
    depth in one list.  The default value is ``True``.
 
 
+.. confval:: epub_fix_images
+
+   This flag determines if sphinx should try to fix image formats that are not
+   supported by some epub readers.  At the moment palette images with a small
+   color table are upgraded.  You need the Python Image Library (PIL) installed
+   to use this option.  The default value is ``False`` because the automatic
+   conversion may lose information.
+
+.. confval:: epub_max_image_width
+
+   This option specifies the maximum width of images.  If it is set to a value
+   greater than zero, images with a width larger than the given value are
+   scaled accordingly.  If it is zero, no scaling is performed. The default
+   value is ``0``.  You need the Python Image Library (PIL) installed to use
+   this option.
+
+
 .. _latex-options:
 
 Options for LaTeX output
diff --git a/doc/domains.rst b/doc/domains.rst
index a1e7b98e..9894caab 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -535,8 +535,14 @@ The following directives are available:
 
          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:
@@ -557,8 +563,14 @@ The following directives are available:
 
          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
diff --git a/doc/ext/appapi.rst b/doc/ext/appapi.rst
index 643de995..1f5c063c 100644
--- a/doc/ext/appapi.rst
+++ b/doc/ext/appapi.rst
@@ -115,11 +115,8 @@ the following public API:
      <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:
diff --git a/doc/ext/autosummary.rst b/doc/ext/autosummary.rst
index 878a3c2c..e3de1835 100644
--- a/doc/ext/autosummary.rst
+++ b/doc/ext/autosummary.rst
@@ -29,7 +29,7 @@ The :mod:`sphinx.ext.autosummary` extension does this in two parts:
 .. 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.  
+   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
diff --git a/doc/ext/math.rst b/doc/ext/math.rst
index bbefe382..434c657b 100644
--- a/doc/ext/math.rst
+++ b/doc/ext/math.rst
@@ -63,10 +63,10 @@ further translation is necessary when building LaTeX output.
       .. 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
diff --git a/doc/faq.rst b/doc/faq.rst
index 965a1986..bf2327d7 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -45,7 +45,7 @@ Using Sphinx with...
 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.
 
diff --git a/doc/intl.rst b/doc/intl.rst
index 6a5471c4..87068215 100644
--- a/doc/intl.rst
+++ b/doc/intl.rst
@@ -46,7 +46,7 @@ with :confval:`locale_dirs` for your :confval:`language`, Sphinx will pick them
 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:
 
diff --git a/doc/intro.rst b/doc/intro.rst
index 0e6e5247..5d76dd29 100644
--- a/doc/intro.rst
+++ b/doc/intro.rst
@@ -24,8 +24,7 @@ This section is intended to collect helpful hints for those wanting to migrate
 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
@@ -35,6 +34,12 @@ to reStructuredText/Sphinx from other documentation systems.
 * 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
 ----------------------
@@ -46,7 +51,7 @@ Prerequisites
 -------------
 
 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.
 
diff --git a/doc/invocation.rst b/doc/invocation.rst
index c8e9a61f..2c69d32f 100644
--- a/doc/invocation.rst
+++ b/doc/invocation.rst
@@ -14,6 +14,8 @@ you don't need to specify any *filenames*.
 
 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
@@ -183,3 +185,72 @@ variables to customize behavior:
 .. 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`).
diff --git a/doc/man/sphinx-apidoc.rst b/doc/man/sphinx-apidoc.rst
new file mode 100644
index 00000000..e48102de
--- /dev/null
+++ b/doc/man/sphinx-apidoc.rst
@@ -0,0 +1,55 @@
+: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.
diff --git a/doc/markup/code.rst b/doc/markup/code.rst
index eaaf17d0..c0e7e8eb 100644
--- a/doc/markup/code.rst
+++ b/doc/markup/code.rst
@@ -86,6 +86,21 @@ on line numbers for the individual block::
 
       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
 ^^^^^^^^
@@ -107,11 +122,13 @@ 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`.
diff --git a/doc/markup/toctree.rst b/doc/markup/toctree.rst
index 0b6a46c1..625fbb61 100644
--- a/doc/markup/toctree.rst
+++ b/doc/markup/toctree.rst
@@ -11,6 +11,11 @@ documents into multiple output files, Sphinx uses a custom directive to add
 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
diff --git a/doc/theming.rst b/doc/theming.rst
index 802b211f..334f6ffe 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -200,10 +200,14 @@ These themes are:
 * **traditional** -- A theme resembling the old Python documentation.  There are
   currently no options beyond *nosidebar* and *sidebarwidth*.
 
-* **epub** -- A theme for the epub builder.  There are currently no options.
-  This theme tries to save visual space which is a sparse resource on ebook
-  readers.
-
+* **epub** -- A theme for the epub builder.  This theme tries to save visual
+  space which is a sparse resource on ebook readers.  The following options
+  are supported:
+
+  - **relbar1** (true or false, default true): If this is true, the
+    `relbar1` block is inserted in the epub output, otherwise it is omitted.
+  - **footer**  (true or false, default true): If this is true, the
+    `footer` block is inserted in the epub output, otherwise it is ommitted.
 
 Creating themes
 ---------------
diff --git a/doc/tutorial.rst b/doc/tutorial.rst
index fa6ee2ab..b0e1d486 100644
--- a/doc/tutorial.rst
+++ b/doc/tutorial.rst
@@ -26,6 +26,9 @@ configuration values from a few questions it asks you.  Just run ::
 
 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
 ---------------------------
@@ -125,6 +128,12 @@ to run ::
 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
 -------------------