Merged in dcmouser/sphinx-fork-dcmouser (pull request #161)

Added option to apidoc to write each module to standalone page instead of combining all modules in a package on one page.

8 files changed, 112 insertions, 36 deletions

diff --git a/doc/_static/bookcover.png b/doc/_static/bookcover.png
new file mode 100644
index 00000000..1c91f91f
--- /dev/null
+++ b/doc/_static/bookcover.png
diff --git a/doc/_templates/index.html b/doc/_templates/index.html
index d1955cac..0739191e 100644
--- a/doc/_templates/index.html
+++ b/doc/_templates/index.html
@@ -81,7 +81,11 @@
     create a customized documentation using Sphinx written by the matplotlib
     developers.{%endtrans%}</p>
 
-  <p>{%trans%}There is a <a href="http://sphinx-users.jp/doc10/">Japanese translation</a>
-    of this documentation, thanks to Yoshiki Shibukawa.{%endtrans%}</p>
+  <p>{%trans%}There is a <a href="http://docs.sphinx-users.jp/">Japanese translation</a>
+    of this documentation, thanks to the Japanese Sphinx user group.{%endtrans%}</p>
+  <p>{%trans%}A Japanese book about Sphinx has been published by O'Reilly:
+    <a href="http://www.oreilly.co.jp/books/9784873116488/">Sphinxをはじめよう /
+      Learning Sphinx</a>:{%endtrans%}</p>
+  <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p>
 
 {% endblock %}
diff --git a/doc/_templates/indexsidebar.html b/doc/_templates/indexsidebar.html
index 7805b942..70107eb5 100644
--- a/doc/_templates/indexsidebar.html
+++ b/doc/_templates/indexsidebar.html
@@ -27,6 +27,6 @@ are also available.{%endtrans%}</p>
          onfocus="$(this).val('');"/>
   <input type="submit" name="sub" value="Subscribe" style="font-size: 90%; width: 70px"/>
 </form>
-<p>{%trans%}or come to the <tt>#pocoo</tt> channel on FreeNode.{%endtrans%}</p>
+<p>{%trans%}or come to the <tt>#sphinx-doc</tt> channel on FreeNode.{%endtrans%}</p>
 <p>{%trans%}You can also open an issue at the
   <a href="http://www.bitbucket.org/birkenfeld/sphinx/issues/">tracker</a>.{%endtrans%}</p>
diff --git a/doc/config.rst b/doc/config.rst
index 24334f36..70ebacb4 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -379,17 +379,20 @@ documentation on :ref:`intl` for details.
    * ``fr`` -- French
    * ``hr`` -- Croatian
    * ``hu`` -- Hungarian
+   * ``id`` -- Indonesian
    * ``it`` -- Italian
    * ``ja`` -- Japanese
    * ``ko`` -- Korean
    * ``lt`` -- Lithuanian
    * ``lv`` -- Latvian
+   * ``mk`` -- Macedonian
    * ``nb_NO`` -- Norwegian Bokmal
    * ``ne`` -- Nepali
    * ``nl`` -- Dutch
    * ``pl`` -- Polish
    * ``pt_BR`` -- Brazilian Portuguese
    * ``ru`` -- Russian
+   * ``si`` -- Sinhala
    * ``sk`` -- Slovak
    * ``sl`` -- Slovenian
    * ``sv`` -- Swedish
@@ -509,10 +512,11 @@ that use Sphinx' HTMLWriter class.
 
 .. confval:: html_static_path
 
-   A list of paths that contain custom static files (such as style sheets or
-   script files).  Relative paths are taken as relative to the configuration
-   directory.  They are copied to the output directory after the theme's static
-   files, so a file named :file:`default.css` will overwrite the theme's
+   A list of paths that contain custom static files (such as style
+   sheets or script files).  Relative paths are taken as relative to
+   the configuration directory.  They are copied to the output's
+   :file:`_static` directory after the theme's static files, so a file
+   named :file:`default.css` will overwrite the theme's
    :file:`default.css`.
 
    .. versionchanged:: 0.4
@@ -521,6 +525,19 @@ that use Sphinx' HTMLWriter class.
    .. versionchanged:: 1.0
       The entries in :confval:`html_static_path` can now be single files.
 
+.. confval:: html_extra_path
+
+   A list of paths that contain extra files not directly related to
+   the documentation, such as :file:`robots.txt` or :file:`.htaccess`.
+   Relative paths are taken as relative to the configuration
+   directory.  They are copied to the output directory.  They will
+   overwrite any existing file of the same name.
+
+   As these files are not meant to be built, they are automatically added to
+   :confval:`exclude_patterns`.
+
+   .. versionadded:: 1.2
+
 .. confval:: html_last_updated_fmt
 
    If this is not the empty string, a 'Last updated on:' timestamp is inserted
diff --git a/doc/devguide.rst b/doc/devguide.rst
index cc3c8248..0e3563b8 100644
--- a/doc/devguide.rst
+++ b/doc/devguide.rst
@@ -20,12 +20,9 @@ sphinx-users <sphinx-users@googlegroups.com>
 sphinx-dev <sphinx-dev@googlegroups.com>
     Mailing list for development related discussions.
 
-#pocoo on irc.freenode.net
+#sphinx-doc 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/
 
diff --git a/doc/domains.rst b/doc/domains.rst
index bd99a4c5..e75d3e5e 100644
--- a/doc/domains.rst
+++ b/doc/domains.rst
@@ -316,35 +316,41 @@ The field names must consist of one of these keywords and an argument (except
 for ``returns`` and ``rtype``, which do not need an argument).  This is best
 explained by an example::
 
-   .. py:function:: format_exception(etype, value, tb[, limit=None])
+   .. py:function:: send_message(sender, recipient, message_body, [priority=1])
 
-      Format the exception with a traceback.
+      Send a message to a recipient
 
-      :param etype: exception type
-      :param value: exception value
-      :param tb: traceback object
-      :param limit: maximum number of stack frames to show
-      :type limit: integer or None
-      :rtype: list of strings
+      :param str sender: The person sending the message
+      :param str recipient: The recipient of the message
+      :param str message_body: The body of the message
+      :param priority: The priority of the message, can be a number 1-5
+      :type priority: integer or None
+      :return: the message id
+      :rtype: int
+      :raises ValueError: if the message_body exceeds 160 characters
+      :raises TypeError: if the message_body is not a basestring
 
 This will render like this:
 
-   .. py:function:: format_exception(etype, value, tb[, limit=None])
+   .. py:function:: send_message(sender, recipient, message_body, [priority=1])
       :noindex:
 
-      Format the exception with a traceback.
+      Send a message to a recipient
 
-      :param etype: exception type
-      :param value: exception value
-      :param tb: traceback object
-      :param limit: maximum number of stack frames to show
-      :type limit: integer or None
-      :rtype: list of strings
+      :param str sender: The person sending the message
+      :param str recipient: The recipient of the message
+      :param str message_body: The body of the message
+      :param priority: The priority of the message, can be a number 1-5
+      :type priority: integer or None
+      :return: the message id
+      :rtype: int
+      :raises ValueError: if the message_body exceeds 160 characters
+      :raises TypeError: if the message_body is not a basestring
 
 It is also possible to combine parameter type and description, if the type is a
 single word, like this::
 
-   :param integer limit: maximum number of stack frames to show
+   :param int priority: The priority of the message, can be a number 1-5
 
 
 .. _python-roles:
diff --git a/doc/ext/autodoc.rst b/doc/ext/autodoc.rst
index 7f9a6c61..c92fe0c4 100644
--- a/doc/ext/autodoc.rst
+++ b/doc/ext/autodoc.rst
@@ -184,12 +184,16 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
 
      .. versionadded:: 0.6
 
-   .. note::
+   * In an :rst:dir:`automodule` directive with the ``members`` option set, only
+     module members whose ``__module__`` attribute is equal to the module name
+     as given to ``automodule`` will be documented.  This is to prevent
+     documentation of imported classes or functions.  Set the
+     ``imported-members`` option if you want to prevent this behavior and
+     document all available members.  Note that attributes from imported modules
+     will not be documented, because attribute documentation is discovered by
+     parsing the source file of the current module.
 
-      In an :rst:dir:`automodule` directive with the ``members`` option set, only
-      module members whose ``__module__`` attribute is equal to the module name
-      as given to ``automodule`` will be documented.  This is to prevent
-      documentation of imported classes or functions.
+     .. versionadded:: 1.2
 
 
 .. rst:directive:: autofunction
@@ -197,8 +201,23 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
                    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.
+
+   :rst:dir:`autodata` and :rst:dir:`autoattribute` support
+   the ``annotation`` option.
+   Without this option, the representation of the object
+   will be shown in the documentation.
+   When the option is given without arguments,
+   only the name of the object will be printed::
+
+      .. autodata:: CD_DRIVE
+         :annotation:
+
+   You can tell sphinx what should be printed after the name::
+
+      .. autodata:: CD_DRIVE
+         :annotation: = your CD device name
 
    For module data members and class attributes, documentation can either be put
    into a comment with special formatting (using a ``#:`` to start the comment
@@ -234,6 +253,10 @@ inserting them into the page source under a suitable :rst:dir:`py:module`,
    .. versionchanged:: 1.1
       Comment docs are now allowed on the same line after an assignment.
 
+   .. versionchanged:: 1.2
+      :rst:dir:`autodata` and :rst:dir:`autoattribute` have
+      an ``annotation`` option
+
    .. note::
 
       If you document decorated functions or methods, keep in mind that autodoc
diff --git a/doc/theming.rst b/doc/theming.rst
index 0375bc71..73ec9f27 100644
--- a/doc/theming.rst
+++ b/doc/theming.rst
@@ -34,7 +34,7 @@ That would give you the default theme, but with a sidebar on the right side and
 a black background for the relation bar (the bar with the navigation links at
 the page's top and bottom).
 
-If the theme does not come with Sphinx, it can be in two forms: either a
+If the theme does not come with Sphinx, it can be in two static forms: either a
 directory (containing :file:`theme.conf` and other needed files), or a zip file
 with the same contents.  Either of them must be put where Sphinx can find it;
 for this there is the config value :confval:`html_theme_path`.  It gives a list
@@ -46,6 +46,35 @@ file :file:`blue.zip`, you can put it right in the directory containing
     html_theme = "blue"
     html_theme_path = ["."]
 
+The third form provides your theme path dynamically to Sphinx if the
+``setuptools`` package is installed.  You can provide an entry point section
+called ``sphinx_themes`` in your setup.py file and write a ``get_path`` function
+that has to return the directory with themes in it::
+
+    // in your 'setup.py'
+
+    setup(
+        ...
+        entry_points = {
+            'sphinx_themes': [
+                'path = your_package:get_path',
+            ]
+        },
+        ...
+    )
+
+    // in 'your_package.py'
+
+    from os import path
+    package_dir = path.abspath(path.dirname(__file__))
+    template_path = path.join(package_dir, 'themes')
+
+    def get_path():
+        return template_path
+
+.. versionadded:: 1.2
+   'sphinx_themes' entry_points feature.
+
 
 .. _builtin-themes: