merge with 0.6

18 files changed, 367 insertions, 110 deletions

diff --git a/tests/root/_static/README b/tests/root/_static/README
index d517219b..9e1ec356 100644
--- a/tests/root/_static/README
+++ b/tests/root/_static/README
@@ -1 +1 @@
-This placeholder file is there because Mercurial ignores empty directories.
+This whole directory is there to test html_static_path.
diff --git a/tests/root/_static/excluded.css b/tests/root/_static/excluded.css
new file mode 100644
index 00000000..03c941a4
--- /dev/null
+++ b/tests/root/_static/excluded.css
@@ -0,0 +1 @@
+/* This file should be excluded from being copied over */
diff --git a/tests/root/_static/subdir/foo.css b/tests/root/_static/subdir/foo.css
new file mode 100644
index 00000000..9427981d
--- /dev/null
+++ b/tests/root/_static/subdir/foo.css
@@ -0,0 +1 @@
+/* Stub file */
diff --git a/tests/root/_templates/contentssb.html b/tests/root/_templates/contentssb.html
new file mode 100644
index 00000000..9951d3c3
--- /dev/null
+++ b/tests/root/_templates/contentssb.html
@@ -0,0 +1,2 @@
+{# sidebar only for contents document #}
+<h4>Contents sidebar</h4>
\ No newline at end of file
diff --git a/tests/root/_templates/customsb.html b/tests/root/_templates/customsb.html
new file mode 100644
index 00000000..cc88b8cf
--- /dev/null
+++ b/tests/root/_templates/customsb.html
@@ -0,0 +1,2 @@
+{# custom sidebar template #}
+<h4>Custom sidebar</h4>
diff --git a/tests/root/_templates/layout.html b/tests/root/_templates/layout.html
index 7f290fc1..82125df8 100644
--- a/tests/root/_templates/layout.html
+++ b/tests/root/_templates/layout.html
@@ -1,4 +1,5 @@
 {% extends "!layout.html" %}
+
 {% block extrahead %}
 {# html_context variable from conf.py #}
 <meta name="hc" content="{{ hckey }}" />
@@ -6,3 +7,9 @@
 <meta name="hc_co" content="{{ hckey_co }}" />
 {{ super() }}
 {% endblock %}
+
+{% block sidebartoc %}
+{# display global TOC in addition to local TOC #}
+{{ super() }}
+{{ toctree(collapse=False, maxdepth=-1) }}
+{% endblock %}
\ No newline at end of file
diff --git a/tests/root/conf.py b/tests/root/conf.py
index 19c803c9..9b1249ad 100644
--- a/tests/root/conf.py
+++ b/tests/root/conf.py
@@ -4,9 +4,9 @@ import sys, os
 
 sys.path.append(os.path.abspath('.'))
 
-extensions = ['ext', 'sphinx.ext.autodoc', 'sphinx.ext.jsmath',
-              'sphinx.ext.coverage', 'sphinx.ext.todo',
-              'sphinx.ext.autosummary', 'sphinx.ext.doctest']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.jsmath', 'sphinx.ext.todo',
+              'sphinx.ext.coverage', 'sphinx.ext.autosummary',
+              'sphinx.ext.doctest', 'sphinx.ext.extlinks', 'ext']
 
 jsmath_path = 'dummy.js'
 
@@ -16,24 +16,26 @@ master_doc = 'contents'
 source_suffix = '.txt'
 
 project = 'Sphinx <Tests>'
-copyright = '2008, Georg Brandl & Team'
+copyright = '2010, Georg Brandl & Team'
 # If this is changed, remember to update the versionchanges!
 version = '0.6'
 release = '0.6alpha1'
 today_fmt = '%B %d, %Y'
 #unused_docs = []
-exclude_trees = ['_build']
+exclude_patterns = ['_build', '**/excluded.*']
 keep_warnings = True
 pygments_style = 'sphinx'
+show_authors = True
 
 rst_epilog = '.. |subst| replace:: global substitution'
 
 html_theme = 'testtheme'
 html_theme_path = ['.']
 html_theme_options = {'testopt': 'testoverride'}
-
+html_sidebars = {'**': 'customsb.html',
+                 'contents': ['contentssb.html', 'localtoc.html'] }
 html_style = 'default.css'
-html_static_path = ['_static']
+html_static_path = ['_static', 'templated.css_t']
 html_last_updated_fmt = '%b %d, %Y'
 html_context = {'hckey': 'hcval', 'hckey_co': 'wrong_hcval_co'}
 
@@ -49,14 +51,22 @@ latex_additional_files = ['svgimg.svg']
 value_from_conf_py = 84
 
 coverage_c_path = ['special/*.h']
-coverage_c_regexes = {'cfunction': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'}
+coverage_c_regexes = {'function': r'^PyAPI_FUNC\(.*\)\s+([^_][\w_]+)'}
 
 autosummary_generate = ['autosummary']
 
+extlinks = {'issue': ('http://bugs.python.org/issue%s', 'issue '),
+            'pyurl': ('http://python.org/%s', None)}
+
 # modify tags from conf.py
 tags.add('confpytag')
 
+
+# -- extension API
+
+from docutils import nodes
 from sphinx import addnodes
+from sphinx.util.compat import Directive
 
 def userdesc_parse(env, sig, signode):
     x, y = sig.split(':')
@@ -65,7 +75,18 @@ def userdesc_parse(env, sig, signode):
     signode[-1] += addnodes.desc_parameter(y, y)
     return x
 
+def functional_directive(name, arguments, options, content, lineno,
+                         content_offset, block_text, state, state_machine):
+    return [nodes.strong(text='from function: %s' % options['opt'])]
+
+class ClassDirective(Directive):
+    option_spec = {'opt': lambda x: x}
+    def run(self):
+        return [nodes.strong(text='from class: %s' % self.options['opt'])]
+
 def setup(app):
     app.add_config_value('value_from_conf_py', 42, False)
-    app.add_description_unit('userdesc', 'userdescrole', '%s (userdesc)',
-                             userdesc_parse)
+    app.add_directive('funcdir', functional_directive, opt=lambda x: x)
+    app.add_directive('clsdir', ClassDirective)
+    app.add_object_type('userdesc', 'userdescrole', '%s (userdesc)',
+                        userdesc_parse, objname='user desc')
diff --git a/tests/root/contents.txt b/tests/root/contents.txt
index 503cb5e1..e052e04b 100644
--- a/tests/root/contents.txt
+++ b/tests/root/contents.txt
@@ -11,16 +11,19 @@ Contents:
    :maxdepth: 2
    :numbered:
 
+   extapi
    images
    subdir/images
    subdir/includes
    includes
    markup
-   desc
+   objects
    bom
    math
    autodoc
    autosummary
+   metadata
+   extensions
    doctest
    extensions
 
diff --git a/tests/root/desc.txt b/tests/root/desc.txt
deleted file mode 100644
index d6915dc2..00000000
--- a/tests/root/desc.txt
+++ /dev/null
@@ -1,71 +0,0 @@
-Testing description units
-=========================
-
-.. function:: func_without_module(a, b, *c[, d])
-
-   Does something.
-
-.. function:: func_without_body()
-
-.. function:: func_noindex
-   :noindex:
-
-
-.. module:: mod
-   :synopsis: Module synopsis.
-   :platform: UNIX
-
-.. function:: func_in_module
-
-.. class:: Cls
-
-   .. method:: meth1
-
-   .. staticmethod:: meths
-
-   .. attribute:: attr
-
-.. explicit class given
-.. method:: Cls.meth2
-
-.. explicit module given
-.. exception:: Error(arg1, arg2)
-   :module: errmod
-
-.. data:: var
-
-
-.. currentmodule:: None
-
-.. function:: func_without_module2() -> annotation
-
-
-C items
-=======
-
-.. cfunction:: Sphinx_DoSomething()
-
-.. cmember:: SphinxStruct.member
-
-.. cmacro:: SPHINX_USE_PYTHON
-
-.. ctype:: SphinxType
-
-.. cvar:: sphinx_global
-
-
-Testing references
-==================
-
-Referencing :class:`mod.Cls` or :Class:`mod.Cls` should be the same.
-
-
-User markup
-===========
-
-.. userdesc:: myobj:parameter
-
-   Description of userdesc.
-
-
-Referencing :userdescrole:`myobj`.
diff --git a/tests/root/extapi.txt b/tests/root/extapi.txt
new file mode 100644
index 00000000..4728e3de
--- /dev/null
+++ b/tests/root/extapi.txt
@@ -0,0 +1,10 @@
+Extension API tests
+===================
+
+Testing directives:
+
+.. funcdir::
+   :opt: Foo
+
+.. clsdir::
+   :opt: Bar
diff --git a/tests/root/extensions.txt b/tests/root/extensions.txt
index 70c8959f..96b1f8ef 100644
--- a/tests/root/extensions.txt
+++ b/tests/root/extensions.txt
@@ -1,6 +1,13 @@
 Test for diverse extensions
 ===========================
 
+extlinks
+--------
+
+Test diverse links: :issue:`1000` and :pyurl:`dev/`, also with
+:issue:`explicit caption <1042>`.
+
+
 todo
 ----
 
@@ -19,4 +26,3 @@ list of all todos
 ^^^^^^^^^^^^^^^^^
 
 .. todolist::
-
diff --git a/tests/root/includes.txt b/tests/root/includes.txt
index 4fe13ed6..85cf1970 100644
--- a/tests/root/includes.txt
+++ b/tests/root/includes.txt
@@ -44,12 +44,27 @@ Literalinclude options
    :start-after: coding: utf-8
    :end-before: class Foo
 
+.. cssclass:: inc-preappend
+.. literalinclude:: literal.inc
+   :prepend: START CODE
+   :append: END CODE
+
 .. literalinclude:: literal.inc
    :start-after: utf-8
 
 .. literalinclude:: literal.inc
    :end-before: class Foo
 
+.. cssclass:: inc-tab3
+.. literalinclude:: tabs.inc
+   :tab-width: 3
+   :language: text
+
+.. cssclass:: inc-tab8
+.. literalinclude:: tabs.inc
+   :tab-width: 8
+   :language: python
+
 Test if dedenting before parsing works.
 
 .. highlight:: python
diff --git a/tests/root/markup.txt b/tests/root/markup.txt
index cdb8c5fc..65156e7e 100644
--- a/tests/root/markup.txt
+++ b/tests/root/markup.txt
@@ -5,7 +5,11 @@
 Testing various markup
 ======================
 
+Meta markup
+-----------
+
 .. sectionauthor:: Georg Brandl
+.. moduleauthor:: Georg Brandl
 
 .. contents:: TOC
 
@@ -13,7 +17,11 @@ Testing various markup
    :author: Me
    :keywords: docs, sphinx
 
-A |subst|.
+
+Generic reST
+------------
+
+A |subst| (the definition is in rst_epilog).
 
 .. _label:
 
@@ -21,22 +29,14 @@ A |subst|.
 
    some code
 
-Admonitions
------------
-
-.. note:: Note
-   Note text.
-
-.. warning:: Warning
-
-   Warning text.
+Option list:
 
-.. tip::
-   Tip text.
+-h              help
+--help          also help
 
 
 Body directives
----------------
+^^^^^^^^^^^^^^^
 
 .. topic:: Title
 
@@ -69,7 +69,67 @@ Body directives
 
    b
 
-   
+
+Admonitions
+^^^^^^^^^^^
+
+.. admonition:: My Admonition
+
+   Admonition text.
+
+.. note::
+   Note text.
+
+.. warning::
+
+   Warning text.
+
+.. tip::
+   Tip text.
+
+
+Inline markup
+-------------
+
+*Generic inline markup*
+
+* :command:`command`
+* :dfn:`dfn`
+* :guilabel:`guilabel`
+* :kbd:`kbd`
+* :mailheader:`mailheader`
+* :makevar:`makevar`
+* :manpage:`manpage`
+* :mimetype:`mimetype`
+* :newsgroup:`newsgroup`
+* :program:`program`
+* :regexp:`regexp`
+* :menuselection:`File --> Close`
+* :file:`a/{varpart}/b`
+* :samp:`print {i}`
+
+*Linking inline markup*
+
+* :pep:`8`
+* :rfc:`1`
+* :envvar:`HOME`
+* :keyword:`with`
+* :token:`try statement <try_stmt>`
+* :doc:`subdir/includes`
+* ``:download:`` is tested in includes.txt
+* :option:`Python -c option <python -c>`
+
+Test :abbr:`abbr (abbreviation)` and another :abbr:`abbr (abbreviation)`.
+
+
+.. _with:
+
+With
+----
+
+(Empty section.)
+
+
 Tables
 ------
 
@@ -96,6 +156,17 @@ Version markup
    Boring stuff.
 
 
+Code blocks
+-----------
+
+.. code-block:: ruby
+   :linenos:
+
+   def ruby?
+       false
+   end
+
+
 Misc stuff
 ----------
 
@@ -124,11 +195,6 @@ This is a side note.
 
 This tests :CLASS:`role names in uppercase`.
 
-Option list:
-
--h              help
---help          also help
-
 .. centered:: LICENSE AGREEMENT
 
 .. acks::
@@ -146,7 +212,7 @@ Option list:
       Particle with half-integer spin.
 
 .. productionlist::
-   try_stmt: try1_stmt | try2_stmt
+   try_stmt: `try1_stmt` | `try2_stmt`
    try1_stmt: "try" ":" `suite`
             : ("except" [`expression` ["," `target`]] ":" `suite`)+
             : ["else" ":" `suite`]
@@ -154,7 +220,6 @@ Option list:
    try2_stmt: "try" ":" `suite`
             : "finally" ":" `suite`
 
-Test :abbr:`abbr (abbreviation)` and another :abbr:`abbr (abbreviation)`.
 
 Index markup
 ------------
@@ -180,11 +245,6 @@ Invalid index markup...
 Testing öäü...
 
 
-Object markup
--------------
-
-:cfunc:`CFunction`.
-
 Only directive
 --------------
 
@@ -208,3 +268,4 @@ Only directive
 .. rubric:: Footnotes
 
 .. [#] Like footnotes.
+
diff --git a/tests/root/metadata.txt b/tests/root/metadata.txt
new file mode 100644
index 00000000..9b3044ba
--- /dev/null
+++ b/tests/root/metadata.txt
@@ -0,0 +1,53 @@
+:Author: David Goodger
+:Address: 123 Example Street
+          Example, EX  Canada
+          A1B 2C3
+:Contact: goodger@python.org
+:Authors: Me; Myself; I
+:organization: humankind
+:date: $Date: 2006-05-21 22:44:42 +0200 (Son, 21 Mai 2006) $
+:status: This is a "work in progress"
+:revision: $Revision: 4564 $
+:version: 1
+:copyright: This document has been placed in the public domain. You
+            may do with it as you wish. You may copy, modify,
+            redistribute, reattribute, sell, buy, rent, lease,
+            destroy, or improve it, quote it at length, excerpt,
+            incorporate, collate, fold, staple, or mutilate it, or do
+            anything else to it that your or anyone else's heart
+            desires.
+:field name: This is a generic bibliographic field.
+:field name 2:
+    Generic bibliographic fields may contain multiple body elements.
+
+    Like this.
+
+:Dedication:
+
+    For Docutils users & co-developers.
+
+:abstract:
+
+    This document is a demonstration of the reStructuredText markup
+    language, containing examples of all basic reStructuredText
+    constructs and many advanced constructs.
+
+.. meta::
+   :keywords: reStructuredText, demonstration, demo, parser
+   :description lang=en: A demonstration of the reStructuredText
+       markup language, containing examples of all basic
+       constructs and many advanced constructs.
+
+================================
+ reStructuredText Demonstration
+================================
+
+.. Above is the document title, and below is the subtitle.
+   They are transformed from section titles after parsing.
+
+--------------------------------
+ Examples of Syntax Constructs
+--------------------------------
+
+.. bibliographic fields (which also require a transform):
+
diff --git a/tests/root/objects.txt b/tests/root/objects.txt
new file mode 100644
index 00000000..6b392f36
--- /dev/null
+++ b/tests/root/objects.txt
@@ -0,0 +1,137 @@
+Testing object descriptions
+===========================
+
+.. function:: func_without_module(a, b, *c[, d])
+
+   Does something.
+
+.. function:: func_without_body()
+
+.. function:: func_noindex
+   :noindex:
+
+.. function:: func_with_module
+   :module: foolib
+
+.. module:: mod
+   :synopsis: Module synopsis.
+   :platform: UNIX
+
+.. function:: func_in_module
+
+.. class:: Cls
+
+   .. method:: meth1
+
+   .. staticmethod:: meths
+
+   .. attribute:: attr
+
+.. explicit class given
+.. method:: Cls.meth2
+
+.. explicit module given
+.. exception:: Error(arg1, arg2)
+   :module: errmod
+
+.. data:: var
+
+
+.. currentmodule:: None
+
+.. function:: func_without_module2() -> annotation
+
+.. class:: TimeInt
+
+.. class:: Time(hour, minute, isdst)
+
+   :param hour: The year.
+   :type hour: TimeInt
+   :param TimeInt minute: The minute.
+   :param isdst: whether it's DST
+   :type isdst: * some complex
+                * expression
+   :returns: a new :class:`Time` instance
+   :rtype: :class:`Time`
+   :raises ValueError: if the values are out of range
+   :ivar int hour: like *hour*
+   :ivar minute: like *minute*
+   :vartype minute: int
+
+
+C items
+=======
+
+.. c:function:: Sphinx_DoSomething()
+
+.. c:member:: SphinxStruct.member
+
+.. c:macro:: SPHINX_USE_PYTHON
+
+.. c:type:: SphinxType
+
+.. c:var:: sphinx_global
+
+
+Javascript items
+================
+
+.. js:function:: foo()
+
+.. js:data:: bar
+
+.. documenting the method of any object
+.. js:function:: bar.baz(href, callback[, errback])
+
+   :param string href: The location of the resource.
+   :param callback: Get's called with the data returned by the resource.
+   :throws InvalidHref: If the `href` is invalid.
+   :returns: `undefined`
+
+.. js:attribute:: bar.spam
+
+References
+==========
+
+Referencing :class:`mod.Cls` or :Class:`mod.Cls` should be the same.
+
+With target: :c:func:`Sphinx_DoSomething()` (parentheses are handled),
+:c:member:`SphinxStruct.member`, :c:macro:`SPHINX_USE_PYTHON`,
+:c:type:`SphinxType *` (pointer is handled), :c:data:`sphinx_global`.
+
+Without target: :c:func:`CFunction`. :c:func:`!malloc`.
+
+:js:func:`foo()`
+:js:func:`foo`
+
+:js:data:`bar`
+:js:func:`bar.baz()`
+:js:func:`bar.baz`
+:js:func:`~bar.baz()`
+
+:js:attr:`bar.baz`
+
+
+Others
+======
+
+.. envvar:: HOME
+
+.. program:: python
+
+.. cmdoption:: -c command
+
+.. program:: perl
+
+.. cmdoption:: -c
+
+
+User markup
+===========
+
+.. userdesc:: myobj:parameter
+
+   Description of userdesc.
+
+
+Referencing :userdescrole:`myobj`.
diff --git a/tests/root/subdir/excluded.txt b/tests/root/subdir/excluded.txt
new file mode 100644
index 00000000..5df3139b
--- /dev/null
+++ b/tests/root/subdir/excluded.txt
@@ -0,0 +1,2 @@
+Excluded file -- should *not* be read as source
+-----------------------------------------------
diff --git a/tests/root/tabs.inc b/tests/root/tabs.inc
new file mode 100644
index 00000000..20b51820
--- /dev/null
+++ b/tests/root/tabs.inc
@@ -0,0 +1,5 @@
+Tabs include file test
+----------------------
+
+The next line has a tab:
+-|	|-
diff --git a/tests/root/templated.css_t b/tests/root/templated.css_t
new file mode 100644
index 00000000..72ddb807
--- /dev/null
+++ b/tests/root/templated.css_t
@@ -0,0 +1,2 @@
+/* Stub file, templated */
+{{ sphinx_version }}