title: Doing a sphinx extension that folds sections in the body
body: <p>I try to do an extension in Sphinx, the idea would be that the extension detects the title of sections and then transform them into a fold section, ie that sphinx render a title with a prefix button that helps to display or not the content of the section.</p>
  
  <pre><code>test_fold
  =============
  
  .. fold:: 
  
      * First Section 
          Hae duae provinciae bello quondam piratico catervis mixtae praedonum 
          a Servilio pro consule missae sub iugum factae sunt vectigales. 
          et hae quidem regiones velut in prominenti terrarum lingua positae 
          ob orbe eoo monte Amano disparantur.
  
      * Second Section
          Itaque tum Scaevola cum in eam ipsam mentionem incidisset, exposuit 
          nobis sermonem Laeli de amicitia habitum ab illo secum et cum altero 
          genero, C. Fannio Marci filio, paucis diebus post mortem Africani. 
          Eius disputationis sententias memoriae mandavi, quas hoc libro 
          exposui arbitratu meo; quasi enim ipsos induxi loquentes, ne 
          'inquam' et 'inquit' saepius interponeretur, atque ut tamquam 
          a praesentibus coram haberi sermo videretur.
  
      * Third Section
          Et interdum acciderat, ut siquid in penetrali secreto nullo citerioris 
          vitae ministro praesente paterfamilias uxori susurrasset in aurem, 
          velut Amphiarao referente aut Marcio, quondam vatibus inclitis, 
          postridie disceret imperator. ideoque etiam parietes arcanorum 
          soli conscii timebantur.
  </code></pre>
  
  <p>I began to write an extension like this : </p>
  
  <pre><code>from docutils.nodes import raw
  from docutils.parsers.rst import Directive
  
  FOLD = "*"
  foldSize = len(FOLD)
  
  def removeSpace(_str):
      if _str[0]==" ":
          return removeSpace(_str[1:])
      else:
          return _str
  
  class FoldDirective(Directive):
  
     # this enables content in the directive
     has_content = True
  
     def run(self):
  
      titles = []
      mains = []
      newMain = ""
  
      #loop
      for indexInt in xrange(len(self.content)):
  
          #get
          string = self.content[indexInt]
          if indexInt&gt;0:
              previousString = self.content[indexInt-1]
          else:
              previousString = ""
  
          #Check
          if len(string)&gt;0:
              if string[0] == FOLD:
                  titles.append(string[foldSize:])
                  if indexInt&gt;0:
                      mains.append(newMain)
                  newMain = ""
              elif previousString[0] == FOLD:
                  newMain = string
              else:
                  newMain += string
  
      #append the last
      mains.append(newMain)
  
      #return
      return [raw('',"&lt;table&gt;&lt;tr&gt;",format='html')]+map(
          lambda title,main:
          raw('',"&lt;td&gt;&lt;button/&gt;&lt;/td&gt;&lt;td&gt;&lt;div&gt;"+str(title)+"&lt;/div&gt;&lt;td&gt;     &lt;tr&gt;&lt;td&gt;&lt;/td&gt;&lt;td&gt;&lt;div&gt;"+str(main)+"&lt;/div&gt;&lt;/td&gt;&lt;/tr&gt;",format='html'),
          titles,mains
      )+[raw('',"&lt;/tr&gt;&lt;/table&gt;",format='html')]
  
  def setup(app):
      app.add_directive('fold', FoldDirective)
  </code></pre>
  
  <p>But the problem here : 
  - I don't know to bind the buttons with an onClick function that would make disappear the main on click.
  - The main are just dropped in to a raw html, which is not optimal, because if they content also sub directives they would not be treated.
  - The documentation of sphinx is really difficult to understand if I have to choose therefore in that case some calls of a nodes.General instances, but I don't know what precisely.</p>
  
  <p>Thanks</p>