Regenerating Pycco's documentation

1 files changed, 124 insertions, 55 deletions

diff --git a/index.html b/index.html
index 88b78de..76b3924 100644
--- a/index.html
+++ b/index.html
@@ -71,12 +71,12 @@ up into comment/code sections, highlighting them for the appropriate language,
 and merging them into an HTML template.</p>
       </td>
       <td class=code>
-        <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">generate_documentation</span><span class="p">(</span><span class="n">source</span><span class="p">):</span>
+        <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">generate_documentation</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
     <span class="n">fh</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="s">&quot;r&quot;</span><span class="p">)</span>
     <span class="n">sections</span> <span class="o">=</span> <span class="n">parse</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">fh</span><span class="o">.</span><span class="n">read</span><span class="p">())</span>
     <span class="n">highlight</span><span class="p">(</span><span class="n">source</span><span class="p">,</span>
               <span class="n">sections</span><span class="p">)</span>
-    <span class="n">generate_html</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">sections</span><span class="p">)</span></pre></div></pre></div>
+    <span class="n">generate_html</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">sections</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="n">options</span><span class="p">)</span></pre></div></pre></div>
       </td>
     </tr><tr id='section-4'>
       <td class=docs>
@@ -104,6 +104,12 @@ Sections take the form:</p>
     <span class="k">if</span> <span class="n">lines</span><span class="p">[</span><span class="mi">0</span><span class="p">]</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">&quot;#!&quot;</span><span class="p">):</span>
         <span class="n">lines</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span>
 
+    <span class="k">if</span> <span class="n">language</span><span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">]</span> <span class="o">==</span> <span class="s">&quot;python&quot;</span><span class="p">:</span>
+        <span class="k">for</span> <span class="n">linenum</span><span class="p">,</span> <span class="n">line</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">lines</span><span class="p">[:</span><span class="mi">2</span><span class="p">]):</span>
+            <span class="k">if</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s">r&#39;coding[:=]\s*([-\w.]+)&#39;</span><span class="p">,</span> <span class="n">lines</span><span class="p">[</span><span class="n">linenum</span><span class="p">]):</span>
+                <span class="n">lines</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="n">linenum</span><span class="p">)</span>
+                <span class="k">break</span>
+
     <span class="k">def</span> <span class="nf">save</span><span class="p">(</span><span class="n">docs</span><span class="p">,</span> <span class="n">code</span><span class="p">):</span>
         <span class="n">sections</span><span class="o">.</span><span class="n">append</span><span class="p">({</span>
             <span class="s">&quot;docs_text&quot;</span><span class="p">:</span> <span class="n">docs</span><span class="p">,</span>
@@ -127,7 +133,49 @@ Sections take the form:</p>
         <div class="octowrap">
           <a class="octothorpe" href="#section-5">#</a>
         </div>
-        <p>Highlights a single chunk of code using the <strong>Pygments</strong> module, and runs the
+        <p><a name="Preprocessing"><em> Preprocessing the comments </em></a>
+Add cross-references before having the text processed by markdown.
+It's possible to reference another file, like this : <a href="pycco.html">pycco.py</a> or a specific section of
+another file, like this: <a href="pycco.html#Highlighting">pycco.py</a>. Of course, sections have to be manually declared before,
+A section name is written on a single line, and surrounded by equals signs, === like this === </p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">preprocess</span><span class="p">(</span><span class="n">comment</span><span class="p">,</span> <span class="n">section_nr</span><span class="p">):</span>
+	<span class="k">def</span> <span class="nf">sanitize_section_name</span><span class="p">(</span><span class="n">name</span><span class="p">):</span>
+		<span class="k">return</span> <span class="n">name</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&quot; &quot;</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span>
+
+	<span class="k">def</span> <span class="nf">replace_crossref</span><span class="p">(</span><span class="n">match</span><span class="p">):</span></pre></div></pre></div>
+      </td>
+    </tr><tr id='section-6'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-6">#</a>
+        </div>
+        <p>Check if the match contains an anchor</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><div class="highlight"><pre>		<span class="k">if</span> <span class="s">&#39;#&#39;</span> <span class="ow">in</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">):</span>
+			<span class="n">name</span><span class="p">,</span> <span class="n">anchor</span> <span class="o">=</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">&#39;#&#39;</span><span class="p">)</span>
+			<span class="k">return</span> <span class="s">&quot;[</span><span class="si">%s</span><span class="s">](</span><span class="si">%s</span><span class="s">#</span><span class="si">%s</span><span class="s">)&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">name</span><span class="p">,</span> <span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">destination</span><span class="p">(</span><span class="n">name</span><span class="p">)),</span> <span class="n">anchor</span><span class="p">)</span>
+
+		<span class="k">else</span><span class="p">:</span>
+			<span class="k">return</span> <span class="s">&quot;[</span><span class="si">%s</span><span class="s">](</span><span class="si">%s</span><span class="s">)&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">),</span> <span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">destination</span><span class="p">(</span><span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">))))</span>
+
+	<span class="k">def</span> <span class="nf">replace_section_name</span><span class="p">(</span><span class="n">match</span><span class="p">):</span>
+		<span class="k">return</span> <span class="s">&#39;&lt;a name=&quot;</span><span class="si">%s</span><span class="s">&quot;&gt;*</span><span class="si">%s</span><span class="s">*&lt;/a&gt;&#39;</span> <span class="o">%</span> <span class="p">(</span><span class="n">sanitize_section_name</span><span class="p">(</span><span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)),</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span>
+
+	<span class="n">comment</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s">&#39;===(.+)===</span><span class="se">\\</span><span class="s">n&#39;</span><span class="p">,</span> <span class="n">replace_section_name</span><span class="p">,</span> <span class="n">comment</span><span class="p">)</span> 
+	<span class="n">comment</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s">&#39;\[\[(.+)\]\]&#39;</span><span class="p">,</span> <span class="n">replace_crossref</span><span class="p">,</span> <span class="n">comment</span><span class="p">)</span> 
+
+	<span class="k">return</span> <span class="n">comment</span></pre></div></pre></div>
+      </td>
+    </tr><tr id='section-7'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-7">#</a>
+        </div>
+        <p><a name="Highlighting"><em> Highlighting the source code </em></a>
+Highlights a single chunk of code using the <strong>Pygments</strong> module, and runs the
 text of its corresponding comment through <strong>Markdown</strong>.</p>
 <p>We process the entire file in a single call to Pygments by inserting little
 marker comments between each section and then splitting the result string
@@ -145,114 +193,130 @@ wherever our markers occur.</p>
     <span class="n">fragments</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">language</span><span class="p">[</span><span class="s">&quot;divider_html&quot;</span><span class="p">],</span> <span class="n">output</span><span class="p">)</span>
     <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">section</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">sections</span><span class="p">):</span>
         <span class="n">section</span><span class="p">[</span><span class="s">&quot;code_html&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">highlight_start</span> <span class="o">+</span> <span class="n">shift</span><span class="p">(</span><span class="n">fragments</span><span class="p">,</span> <span class="s">&quot;&quot;</span><span class="p">)</span> <span class="o">+</span> <span class="n">highlight_end</span>
-        <span class="n">section</span><span class="p">[</span><span class="s">&quot;docs_html&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">markdown</span><span class="p">(</span><span class="n">section</span><span class="p">[</span><span class="s">&quot;docs_text&quot;</span><span class="p">])</span>
+        <span class="n">section</span><span class="p">[</span><span class="s">&quot;docs_html&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">markdown</span><span class="p">(</span><span class="n">preprocess</span><span class="p">(</span><span class="n">section</span><span class="p">[</span><span class="s">&quot;docs_text&quot;</span><span class="p">],</span> <span class="n">i</span><span class="p">))</span>
         <span class="n">section</span><span class="p">[</span><span class="s">&quot;num&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-6'>
+    </tr><tr id='section-8'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-6">#</a>
+          <a class="octothorpe" href="#section-8">#</a>
         </div>
-        <p>Once all of the code is finished highlighting, we can generate the HTML file
+        <p><a name="HTML"><em> HTML Code generation </em></a>Once all of the code is finished highlighting, we can generate the HTML file
 and write out the documentation. Pass the completed sections into the template
 found in <code>resources/pycco.html</code></p>
       </td>
       <td class=code>
-        <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">generate_html</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">sections</span><span class="p">):</span>
+        <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">generate_html</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">sections</span><span class="p">,</span> <span class="n">options</span><span class="p">):</span>
     <span class="n">title</span> <span class="o">=</span> <span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">source</span><span class="p">)</span>
-    <span class="n">dest</span> <span class="o">=</span> <span class="n">destination</span><span class="p">(</span><span class="n">source</span><span class="p">)</span>
+    <span class="n">dest</span> <span class="o">=</span> <span class="n">destination</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">options</span><span class="o">.</span><span class="n">paths</span><span class="p">)</span>
     <span class="n">html</span> <span class="o">=</span> <span class="n">pycco_template</span><span class="p">({</span>
         <span class="s">&quot;title&quot;</span><span class="p">:</span>       <span class="n">title</span><span class="p">,</span>
+        <span class="s">&quot;stylesheet&quot;</span><span class="p">:</span>  <span class="n">path</span><span class="o">.</span><span class="n">relpath</span><span class="p">(</span><span class="s">&#39;docs/pycco.css&#39;</span><span class="p">,</span> <span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">dest</span><span class="p">)[</span><span class="mi">0</span><span class="p">]),</span>
         <span class="s">&quot;sections&quot;</span><span class="p">:</span>    <span class="n">sections</span><span class="p">,</span>
         <span class="s">&quot;sources&quot;</span><span class="p">:</span>     <span class="n">sources</span><span class="p">,</span>
         <span class="s">&quot;path&quot;</span><span class="p">:</span>        <span class="n">path</span><span class="p">,</span>
         <span class="s">&quot;destination&quot;</span><span class="p">:</span> <span class="n">destination</span>
     <span class="p">})</span>
     <span class="k">print</span> <span class="s">&quot;pycco = </span><span class="si">%s</span><span class="s"> -&gt; </span><span class="si">%s</span><span class="s">&quot;</span> <span class="o">%</span> <span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">dest</span><span class="p">)</span>
+    <span class="k">try</span><span class="p">:</span>
+        <span class="n">os</span><span class="o">.</span><span class="n">makedirs</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">dest</span><span class="p">)[</span><span class="mi">0</span><span class="p">])</span>
+    <span class="k">except</span> <span class="ne">OSError</span><span class="p">:</span>
+        <span class="k">pass</span>
     <span class="n">fh</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="s">&quot;w&quot;</span><span class="p">)</span>
-    <span class="n">fh</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">html</span><span class="p">)</span>
+    <span class="n">fh</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">getpreferredencoding</span><span class="p">()))</span>
     <span class="n">fh</span><span class="o">.</span><span class="n">close</span><span class="p">()</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-7'>
+    </tr><tr id='section-9'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-7">#</a>
+          <a class="octothorpe" href="#section-9">#</a>
         </div>
         <h3>Helpers &amp; Setup</h3>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div>
       </td>
-    </tr><tr id='section-8'>
+    </tr><tr id='section-10'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-8">#</a>
+          <a class="octothorpe" href="#section-10">#</a>
         </div>
         <p>This module contains all of our static resources.</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pycco_resources</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-9'>
+    </tr><tr id='section-11'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-9">#</a>
+          <a class="octothorpe" href="#section-11">#</a>
         </div>
         <p>Import our external dependencies.</p>
       </td>
       <td class=code>
-        <div class='highlight'><pre><div class="highlight"><pre><span class="kn">import</span> <span class="nn">pygments</span>
+        <div class='highlight'><pre><div class="highlight"><pre><span class="kn">import</span> <span class="nn">optparse</span>
+<span class="kn">import</span> <span class="nn">os</span>
+<span class="kn">import</span> <span class="nn">pygments</span>
 <span class="kn">import</span> <span class="nn">pystache</span>
 <span class="kn">import</span> <span class="nn">re</span>
 <span class="kn">import</span> <span class="nn">sys</span>
 <span class="kn">from</span> <span class="nn">markdown</span> <span class="kn">import</span> <span class="n">markdown</span>
 <span class="kn">from</span> <span class="nn">os</span> <span class="kn">import</span> <span class="n">path</span>
 <span class="kn">from</span> <span class="nn">pygments</span> <span class="kn">import</span> <span class="n">lexers</span><span class="p">,</span> <span class="n">formatters</span>
-<span class="kn">from</span> <span class="nn">subprocess</span> <span class="kn">import</span> <span class="n">Popen</span><span class="p">,</span> <span class="n">PIPE</span></pre></div></pre></div>
+<span class="kn">from</span> <span class="nn">subprocess</span> <span class="kn">import</span> <span class="n">Popen</span><span class="p">,</span> <span class="n">PIPE</span>
+<span class="kn">from</span> <span class="nn">locale</span> <span class="kn">import</span> <span class="n">getpreferredencoding</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-10'>
+    </tr><tr id='section-12'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-10">#</a>
+          <a class="octothorpe" href="#section-12">#</a>
         </div>
         <p>A list of the languages that Pycco supports, mapping the file extension to
 the name of the Pygments lexer and the symbol that indicates a comment. To
 add another language to Pycco's repertoire, add it here.</p>
       </td>
       <td class=code>
-        <div class='highlight'><pre><div class="highlight"><pre><span class="n">languages</span> <span class="o">=</span> <span class="p">{</span>
-    <span class="s">&quot;.coffee&quot;</span><span class="p">:</span> <span class="p">{</span> <span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;coffee-script&quot;</span><span class="p">,</span> <span class="s">&quot;symbol&quot;</span><span class="p">:</span> <span class="s">&quot;#&quot;</span> <span class="p">},</span>
-    <span class="s">&quot;.js&quot;</span><span class="p">:</span>     <span class="p">{</span> <span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;javascript&quot;</span><span class="p">,</span>    <span class="s">&quot;symbol&quot;</span><span class="p">:</span> <span class="s">&quot;//&quot;</span> <span class="p">},</span>
+        <div class='highlight'><pre><div class="highlight"><pre><span class="n">languages</span> <span class="o">=</span> <span class="p">{</span></pre></div></pre></div>
+      </td>
+    </tr><tr id='section-13'>
+      <td class=docs>
+        <div class="octowrap">
+          <a class="octothorpe" href="#section-13">#</a>
+        </div>
+        <p>".coffee": { "name": "coffee-script", "symbol": "#" },</p>
+      </td>
+      <td class=code>
+        <div class='highlight'><pre><div class="highlight"><pre>    <span class="s">&quot;.js&quot;</span><span class="p">:</span>     <span class="p">{</span> <span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;javascript&quot;</span><span class="p">,</span>    <span class="s">&quot;symbol&quot;</span><span class="p">:</span> <span class="s">&quot;//&quot;</span> <span class="p">},</span>
     <span class="s">&quot;.rb&quot;</span><span class="p">:</span>     <span class="p">{</span> <span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;ruby&quot;</span><span class="p">,</span>          <span class="s">&quot;symbol&quot;</span><span class="p">:</span> <span class="s">&quot;#&quot;</span> <span class="p">},</span>
     <span class="s">&quot;.py&quot;</span><span class="p">:</span>     <span class="p">{</span> <span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;python&quot;</span><span class="p">,</span>        <span class="s">&quot;symbol&quot;</span><span class="p">:</span> <span class="s">&quot;#&quot;</span> <span class="p">},</span>
     <span class="s">&quot;.scm&quot;</span><span class="p">:</span>    <span class="p">{</span> <span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;scheme&quot;</span><span class="p">,</span>        <span class="s">&quot;symbol&quot;</span><span class="p">:</span> <span class="s">&quot;;;&quot;</span> <span class="p">},</span>
     <span class="s">&quot;.lua&quot;</span><span class="p">:</span>    <span class="p">{</span> <span class="s">&quot;name&quot;</span><span class="p">:</span> <span class="s">&quot;lua&quot;</span><span class="p">,</span>           <span class="s">&quot;symbol&quot;</span><span class="p">:</span> <span class="s">&quot;--&quot;</span> <span class="p">},</span>
 <span class="p">}</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-11'>
+    </tr><tr id='section-14'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-11">#</a>
+          <a class="octothorpe" href="#section-14">#</a>
         </div>
         <p>Build out the appropriate matchers and delimiters for each language.</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre><span class="k">for</span> <span class="n">ext</span><span class="p">,</span> <span class="n">l</span> <span class="ow">in</span> <span class="n">languages</span><span class="o">.</span><span class="n">items</span><span class="p">():</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-12'>
+    </tr><tr id='section-15'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-12">#</a>
+          <a class="octothorpe" href="#section-15">#</a>
         </div>
         <p>Does the line begin with a comment?</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre>    <span class="n">l</span><span class="p">[</span><span class="s">&quot;comment_matcher&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">r&quot;^\s*&quot;</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">&quot;symbol&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="s">&quot;\s?&quot;</span><span class="p">)</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-13'>
+    </tr><tr id='section-16'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-13">#</a>
+          <a class="octothorpe" href="#section-16">#</a>
         </div>
         <p>The dividing token we feed into Pygments, to delimit the boundaries between
 sections.</p>
@@ -260,10 +324,10 @@ sections.</p>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre>    <span class="n">l</span><span class="p">[</span><span class="s">&quot;divider_text&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="s">&quot;</span><span class="se">\n</span><span class="s">&quot;</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">&quot;symbol&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="s">&quot;DIVIDER</span><span class="se">\n</span><span class="s">&quot;</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-14'>
+    </tr><tr id='section-17'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-14">#</a>
+          <a class="octothorpe" href="#section-17">#</a>
         </div>
         <p>The mirror of <code>divider_text</code> that we expect Pygments to return. We can split
 on this to recover the original sections.</p>
@@ -271,20 +335,20 @@ on this to recover the original sections.</p>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre>    <span class="n">l</span><span class="p">[</span><span class="s">&quot;divider_html&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">compile</span><span class="p">(</span><span class="s">r&#39;\n*&lt;span class=&quot;c[1]?&quot;&gt;&#39;</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">&quot;symbol&quot;</span><span class="p">]</span> <span class="o">+</span> <span class="s">&#39;DIVIDER&lt;/span&gt;</span><span class="se">\n</span><span class="s">*&#39;</span><span class="p">)</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-15'>
+    </tr><tr id='section-18'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-15">#</a>
+          <a class="octothorpe" href="#section-18">#</a>
         </div>
         <p>Get the Pygments Lexer for this language.</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre>    <span class="n">l</span><span class="p">[</span><span class="s">&quot;lexer&quot;</span><span class="p">]</span> <span class="o">=</span> <span class="n">lexers</span><span class="o">.</span><span class="n">get_lexer_by_name</span><span class="p">(</span><span class="n">l</span><span class="p">[</span><span class="s">&quot;name&quot;</span><span class="p">])</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-16'>
+    </tr><tr id='section-19'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-16">#</a>
+          <a class="octothorpe" href="#section-19">#</a>
         </div>
         <p>Get the current language we're documenting, based on the extension.</p>
       </td>
@@ -303,26 +367,28 @@ on this to recover the original sections.</p>
         <span class="k">else</span><span class="p">:</span>
             <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s">&quot;Can&#39;t figure out the language!&quot;</span><span class="p">)</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-17'>
+    </tr><tr id='section-20'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-17">#</a>
+          <a class="octothorpe" href="#section-20">#</a>
         </div>
         <p>Compute the destination HTML path for an input source file path. If the source
 is <code>lib/example.py</code>, the HTML will be at <code>docs/example.html</code></p>
       </td>
       <td class=code>
-        <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">destination</span><span class="p">(</span><span class="n">filepath</span><span class="p">):</span>
+        <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">destination</span><span class="p">(</span><span class="n">filepath</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span>
     <span class="k">try</span><span class="p">:</span>
         <span class="n">name</span> <span class="o">=</span> <span class="n">filepath</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">filepath</span><span class="p">[</span> <span class="n">filepath</span><span class="o">.</span><span class="n">rindex</span><span class="p">(</span><span class="s">&quot;.&quot;</span><span class="p">):</span> <span class="p">],</span> <span class="s">&quot;&quot;</span><span class="p">)</span>
     <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span>
         <span class="n">name</span> <span class="o">=</span> <span class="n">filepath</span>
-    <span class="k">return</span> <span class="s">&quot;docs/&quot;</span> <span class="o">+</span> <span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">name</span><span class="p">)</span> <span class="o">+</span> <span class="s">&quot;.html&quot;</span></pre></div></pre></div>
+    <span class="k">if</span> <span class="ow">not</span> <span class="n">preserve_paths</span><span class="p">:</span>
+        <span class="n">name</span> <span class="o">=</span> <span class="n">path</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">name</span><span class="p">)</span>
+    <span class="k">return</span> <span class="s">&quot;docs/</span><span class="si">%s</span><span class="s">.html&quot;</span> <span class="o">%</span> <span class="n">name</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-18'>
+    </tr><tr id='section-21'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-18">#</a>
+          <a class="octothorpe" href="#section-21">#</a>
         </div>
         <p>Shift items off the front of the <code>list</code> until it is empty, then return
 <code>default</code>.</p>
@@ -334,10 +400,10 @@ is <code>lib/example.py</code>, the HTML will be at <code>docs/example.html</cod
     <span class="k">except</span> <span class="ne">IndexError</span><span class="p">:</span>
         <span class="k">return</span> <span class="n">default</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-19'>
+    </tr><tr id='section-22'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-19">#</a>
+          <a class="octothorpe" href="#section-22">#</a>
         </div>
         <p>Ensure that the destination directory exists.</p>
       </td>
@@ -348,57 +414,60 @@ is <code>lib/example.py</code>, the HTML will be at <code>docs/example.html</cod
 <span class="k">def</span> <span class="nf">template</span><span class="p">(</span><span class="n">source</span><span class="p">):</span>
     <span class="k">return</span> <span class="k">lambda</span> <span class="n">context</span><span class="p">:</span> <span class="n">pystache</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">context</span><span class="p">)</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-20'>
+    </tr><tr id='section-23'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-20">#</a>
+          <a class="octothorpe" href="#section-23">#</a>
         </div>
         <p>Create the template that we will use to generate the Pycco HTML page.</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre><span class="n">pycco_template</span> <span class="o">=</span> <span class="n">template</span><span class="p">(</span><span class="n">pycco_resources</span><span class="o">.</span><span class="n">html</span><span class="p">)</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-21'>
+    </tr><tr id='section-24'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-21">#</a>
+          <a class="octothorpe" href="#section-24">#</a>
         </div>
         <p>The CSS styles we"d like to apply to the documentation.</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre><span class="n">pycco_styles</span> <span class="o">=</span> <span class="n">pycco_resources</span><span class="o">.</span><span class="n">css</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-22'>
+    </tr><tr id='section-25'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-22">#</a>
+          <a class="octothorpe" href="#section-25">#</a>
         </div>
         <p>The start of each Pygments highlight block.</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre><span class="n">highlight_start</span> <span class="o">=</span> <span class="s">&quot;&lt;div class=</span><span class="se">\&quot;</span><span class="s">highlight</span><span class="se">\&quot;</span><span class="s">&gt;&lt;pre&gt;&quot;</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-23'>
+    </tr><tr id='section-26'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-23">#</a>
+          <a class="octothorpe" href="#section-26">#</a>
         </div>
         <p>The end of each Pygments highlight block.</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre><span class="n">highlight_end</span> <span class="o">=</span> <span class="s">&quot;&lt;/pre&gt;&lt;/div&gt;&quot;</span></pre></div></pre></div>
       </td>
-    </tr><tr id='section-24'>
+    </tr><tr id='section-27'>
       <td class=docs>
         <div class="octowrap">
-          <a class="octothorpe" href="#section-24">#</a>
+          <a class="octothorpe" href="#section-27">#</a>
         </div>
         <p>Run the script.
 For each source file passed in as an argument, generate the documentation.</p>
       </td>
       <td class=code>
         <div class='highlight'><pre><div class="highlight"><pre><span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">&quot;__main__&quot;</span><span class="p">:</span>
-    <span class="n">sources</span> <span class="o">=</span> <span class="nb">list</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">:])</span>
+    <span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span>
+    <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">&#39;-p&#39;</span><span class="p">,</span> <span class="s">&#39;--paths&#39;</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">&#39;store_true&#39;</span><span class="p">,</span>
+                      <span class="n">help</span><span class="o">=</span><span class="s">&#39;Preserve path structure of original files&#39;</span><span class="p">)</span>
+    <span class="n">opts</span><span class="p">,</span> <span class="n">sources</span> <span class="o">=</span> <span class="n">parser</span><span class="o">.</span><span class="n">parse_args</span><span class="p">()</span>
     <span class="n">sources</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span>
     <span class="k">if</span> <span class="n">sources</span><span class="p">:</span>
         <span class="n">ensure_directory</span><span class="p">()</span>
@@ -407,7 +476,7 @@ For each source file passed in as an argument, generate the documentation.</p>
         <span class="n">css</span><span class="o">.</span><span class="n">close</span><span class="p">()</span>
 
         <span class="k">def</span> <span class="nf">next_file</span><span class="p">():</span>
-            <span class="n">generate_documentation</span><span class="p">(</span><span class="n">sources</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="mi">0</span><span class="p">))</span>
+            <span class="n">generate_documentation</span><span class="p">(</span><span class="n">sources</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="n">options</span><span class="o">=</span><span class="n">opts</span><span class="p">)</span>
             <span class="k">if</span> <span class="n">sources</span><span class="p">:</span>
                 <span class="n">next_file</span><span class="p">()</span>
         <span class="n">next_file</span><span class="p">()</span>