merge with stable

doc/markup/misc.rst

@@ -182,13 +182,6 @@ Including content based on tags
    The format of the current builder (``html``, ``latex`` or ``text``) is always
    set as a tag.
 
-   .. note::
-
-      Due to docutils' specifics of parsing of directive content, you cannot put
-      a section with the same level as the main document heading inside an
-      ``only`` directive.  Such sections will appear to be ignored in the parsed
-      document.
-
    .. versionadded:: 0.6
 
 

sphinx/directives/other.py

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

sphinx/environment.py

@@ -66,6 +66,7 @@ default_settings = {
     'doctitle_xform': False,
     'sectsubtitle_xform': False,
     'halt_level': 5,
+    'file_insertion_enabled': True,
 }
 
 # This is increased every time an environment attribute is added

sphinx/ext/autodoc.py

@@ -866,7 +866,7 @@ class DocstringSignatureMixin(object):
     """
 
     def _find_signature(self, encoding=None):
-        docstrings = Documenter.get_doc(self, encoding, 2)
+        docstrings = Documenter.get_doc(self, encoding)
         if len(docstrings) != 1:
             return
         doclines = docstrings[0]
@@ -881,6 +881,9 @@ class DocstringSignatureMixin(object):
         # the base name must match ours
         if not self.objpath or base != self.objpath[-1]:
             return
+        # re-prepare docstring to ignore indentation after signature
+        docstrings = Documenter.get_doc(self, encoding, 2)
+        doclines = docstrings[0]
         # ok, now jump over remaining empty lines and set the remaining
         # lines as the new doclines
         i = 1

sphinx/highlighting.py

@@ -207,6 +207,8 @@ class PygmentsBridge(object):
             if self.dest == 'html':
                 return hlsource
             else:
+                if not isinstance(hlsource, unicode):  # Py2 / Pygments < 1.6
+                    hlsource = hlsource.decode()
                 return hlsource.translate(tex_hl_escape_map_new)
         except ErrorToken:
             # this is most probably not the selected language,

tests/root/contents.txt

@@ -27,6 +27,7 @@ Contents:
    doctest
    extensions
    versioning/index
+   only
 
    Python <http://python.org/>
 

tests/root/only.txt

@@ -0,0 +1,203 @@
+
+1. Sections in only directives
+==============================
+
+Testing sections in only directives.
+
+.. only:: nonexisting_tag
+
+   Skipped Section
+   ---------------
+   Should not be here.
+
+.. only:: not nonexisting_tag
+
+   1.1. Section
+   ------------
+   Should be here.
+
+1.2. Section
+------------
+
+.. only:: not nonexisting_tag
+
+   1.2.1. Subsection
+   ~~~~~~~~~~~~~~~~~
+   Should be here.
+
+.. only:: nonexisting_tag
+
+   Skipped Subsection
+   ~~~~~~~~~~~~~~~~~~
+   Should not be here.
+
+1.3. Section
+------------
+
+1.3.1. Subsection
+~~~~~~~~~~~~~~~~~
+Should be here.
+
+1.4. Section
+------------
+
+.. only:: not nonexisting_tag
+
+   1.4.1. Subsection
+   ~~~~~~~~~~~~~~~~~
+   Should be here.
+
+1.5. Section
+------------
+
+.. only:: not nonexisting_tag
+
+   1.5.1. Subsection
+   ~~~~~~~~~~~~~~~~~
+   Should be here.
+
+1.5.2. Subsection
+~~~~~~~~~~~~~~~~~
+Should be here.
+
+1.6. Section
+------------
+
+1.6.1. Subsection
+~~~~~~~~~~~~~~~~~
+Should be here.
+
+.. only:: not nonexisting_tag
+
+   1.6.2. Subsection
+   ~~~~~~~~~~~~~~~~~
+   Should be here.
+
+1.6.3. Subsection
+~~~~~~~~~~~~~~~~~
+Should be here.
+
+1.7. Section
+------------
+
+1.7.1. Subsection
+~~~~~~~~~~~~~~~~~
+Should be here.
+
+.. only:: not nonexisting_tag
+
+   1.7.1.1. Subsubsection
+   ......................
+   Should be here.
+
+1.8. Section
+------------
+
+1.8.1. Subsection
+~~~~~~~~~~~~~~~~~
+Should be here.
+
+1.8.1.1. Subsubsection
+......................
+Should be here.
+
+.. only:: not nonexisting_tag
+
+   1.8.1.2. Subsubsection
+   ......................
+   Should be here.
+
+1.9. Section
+------------
+
+.. only:: nonexisting_tag
+
+   Skipped Subsection
+   ~~~~~~~~~~~~~~~~~~
+
+1.9.1. Subsection
+~~~~~~~~~~~~~~~~~
+Should be here.
+
+1.9.1.1. Subsubsection
+......................
+Should be here.
+
+.. only:: not nonexisting_tag
+
+   1.10. Section
+   -------------
+   Should be here.
+
+1.11. Section
+-------------
+
+Text before subsection 11.1.
+
+.. only:: not nonexisting_tag
+
+   More text before subsection 11.1.
+
+   1.11.1. Subsection
+   ~~~~~~~~~~~~~~~~~~
+   Should be here.
+
+Text after subsection 11.1.
+
+.. only:: not nonexisting_tag
+
+   1.12. Section
+   -------------
+   Should be here.
+
+   1.12.1. Subsection
+   ~~~~~~~~~~~~~~~~~~
+   Should be here.
+
+   1.13. Section
+   -------------
+   Should be here.
+
+.. only:: not nonexisting_tag
+
+   1.14. Section
+   -------------
+   Should be here.
+
+   .. only:: not nonexisting_tag
+
+      1.14.1. Subsection
+      ~~~~~~~~~~~~~~~~~~
+      Should be here.
+
+   1.15. Section
+   -------------
+   Should be here.
+
+.. only:: nonexisting_tag
+
+   Skipped document level heading
+   ==============================
+   Should not be here.
+
+.. only:: not nonexisting_tag
+
+   2. Included document level heading
+   ==================================
+   Should be here.
+
+3. Document level heading
+=========================
+Should be here.
+
+.. only:: nonexisting_tag
+
+   Skipped document level heading
+   ==============================
+   Should not be here.
+
+.. only:: not nonexisting_tag
+
+   4. Another included document level heading
+   ==========================================
+   Should be here.

tests/test_autodoc.py

@@ -518,6 +518,12 @@ def test_generate():
         'test_autodoc.DocstringSig.meth')
     assert_result_contains(
         '   rest of docstring', 'method', 'test_autodoc.DocstringSig.meth')
+    assert_result_contains(
+        '.. py:method:: DocstringSig.meth2()', 'method',
+        'test_autodoc.DocstringSig.meth2')
+    assert_result_contains(
+        '       indented line', 'method',
+        'test_autodoc.DocstringSig.meth2')
     assert_result_contains(
         '.. py:classmethod:: Class.moore(a, e, f) -> happiness', 'method',
         'test_autodoc.Class.moore')
@@ -660,6 +666,13 @@ First line of docstring
         rest of docstring
         """
 
+    def meth2(self):
+        """First line, no signature
+        Second line followed by indentation::
+
+            indented line
+        """
+
 class StrRepr(str):
     def __repr__(self):
         return self

tests/test_only_directive.py

@@ -0,0 +1,61 @@
+# -*- coding: utf-8 -*-
+"""
+    test_only_directive
+    ~~~~~~~~~~~~~~~~~~~
+
+    Test the only directive with the test root.
+
+    :copyright: Copyright 2010 by the Sphinx team, see AUTHORS.
+    :license: BSD, see LICENSE for details.
+"""
+
+import re
+
+from docutils import nodes
+
+from util import *
+
+
+def teardown_module():
+    (test_root / '_build').rmtree(True)
+
+
+@with_app(buildername='text')
+def test_sectioning(app):
+
+    def getsects(section):
+        if not isinstance(section, nodes.section):
+            return [getsects(n) for n in section.children]
+        title = section.next_node(nodes.title).astext().strip()
+        subsects = []
+        children = section.children[:]
+        while children:
+            node = children.pop(0)
+            if isinstance(node, nodes.section):
+                subsects.append(node)
+                continue
+            children = list(node.children) + children
+        return [title, [getsects(subsect) for subsect in subsects]]
+
+    def testsects(prefix, sects, indent=0):
+        title = sects[0]
+        parent_num = title.split()[0]
+        assert prefix == parent_num, \
+            'Section out of place: %r' % title
+        for i, subsect in enumerate(sects[1]):
+            num = subsect[0].split()[0]
+            assert re.match('[0-9]+[.0-9]*[.]', num), \
+                'Unnumbered section: %r' % subsect[0]
+            testsects(prefix + str(i+1) + '.', subsect, indent+4)
+
+    app.builder.build(['only'])
+    doctree = app.env.get_doctree('only')
+    app.env.process_only_nodes(doctree, app.builder)
+
+    parts = [getsects(n)
+             for n in filter(lambda n: isinstance(n, nodes.section),
+                             doctree.children)]
+    for i, s in enumerate(parts):
+        testsects(str(i+1) + '.', s, 4)
+    assert len(parts) == 4, 'Expected 4 document level headings, got:\n%s' % \
+        '\n'.join([p[0] for p in parts])