title: docutils/sphinx custom directive creating sibling section rather than child
body: <p>Consider a reStructuredText document with this skeleton:</p>
  
  <pre class="lang-none prettyprint-override"><code>Main Title
  ==========
  
  text text text text text
  
  Subsection
  ----------
  
  text text text text text
  
  .. my-import-from:: file1
  .. my-import-from:: file2
  </code></pre>
  
  <p>The <code>my-import-from</code> directive is provided by a document-specific Sphinx extension, which is supposed to read the file provided as its argument, parse reST embedded in it, and inject the result as a section in the current input file.  (Like autodoc, but for a different file format.)  The code I have for that, right now, looks like this:</p>
  
  <pre class="lang-python prettyprint-override"><code>class MyImportFromDirective(Directive):
      required_arguments = 1
      def run(self):
          src, srcline = self.state_machine.get_source_and_line()
          doc_file = os.path.normpath(os.path.join(os.path.dirname(src),
                                                   self.arguments[0]))
          self.state.document.settings.record_dependencies.add(doc_file)
          doc_text  = ViewList()
  
          try:
              doc_text = extract_doc_from_file(doc_file)
          except EnvironmentError as e:
              raise self.error(e.filename + ": " + e.strerror) from e
  
          doc_section = nodes.section()
          doc_section.document = self.state.document
  
          # report line numbers within the nested parse correctly
          old_reporter = self.state.memo.reporter
          self.state.memo.reporter = AutodocReporter(doc_text,
                                                     self.state.memo.reporter)
          nested_parse_with_titles(self.state, doc_text, doc_section)
          self.state.memo.reporter = old_reporter
  
          if len(doc_section) == 1 and isinstance(doc_section[0], nodes.section):
              doc_section = doc_section[0]
  
          # If there was no title, synthesize one from the name of the file.
          if len(doc_section) == 0 or not isinstance(doc_section[0], nodes.title):
              doc_title = nodes.title()
              doc_title.append(make_title_text(doc_file))
              doc_section.insert(0, doc_title)
  
          return [doc_section]
  </code></pre>
  
  <p>This works, <em>except</em> that the new section is injected as a <em>child</em> of the current section, rather than a <em>sibling</em>.  In other words, the example document above produces a TOC tree like this:</p>
  
  <blockquote>
    <ul>
    <li>Main Title
    <ul>
    <li>Subsection
    <ul>
    <li>File1</li>
    <li>File2</li>
    </ul></li>
    </ul></li>
    </ul>
  </blockquote>
  
  <p>instead of the desired</p>
  
  <blockquote>
    <ul>
    <li>Main Title
    <ul>
    <li>Subsection</li>
    <li>File1</li>
    <li>File2</li>
    </ul></li>
    </ul>
  </blockquote>
  
  <p>How do I fix this?  The Docutils documentation is ... inadequate, particularly regarding control of section depth.  One obvious thing I have tried is returning <code>doc_section.children</code> instead of <code>[doc_section]</code>; that completely removes <code>File1</code> and <code>File2</code> from the TOC tree (but does make the section headers in the body of the document <em>appear</em> to be for the right nesting level).</p>