diff options
| author | Zach Smith <zd@zdsmith.com> | 2015-12-28 12:09:39 -0500 |
|---|---|---|
| committer | Zach Smith <zd@zdsmith.com> | 2015-12-28 12:09:39 -0500 |
| commit | 12f44743da6e969fe9350b616aaf5441fbc6a16e (patch) | |
| tree | d5c24fd58124b8513c008751c04c09d3e7415db5 | |
| parent | 88adf7c32eb64428dee3751a935ca5fa577f083b (diff) | |
| download | pycco-12f44743da6e969fe9350b616aaf5441fbc6a16e.tar.gz | |
(pages) update formatting
| -rw-r--r-- | index.html | 1898 | ||||
| -rw-r--r-- | pycco.css | 92 |
2 files changed, 1125 insertions, 865 deletions
@@ -8,21 +8,16 @@ <body> <div id='container'> <div id="background"></div> - - <table cellspacing=0 cellpadding=0> - <thead> - <tr> - <th class=docs><h1>main.py</h1></th> - <th class=code></th> - </tr> - </thead> - <tbody> - <tr id='section-0'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-0">#</a> - </div> - <p>"<strong>Pycco</strong>" is a Python port of <a href="http://jashkenas.github.com/docco/">Docco</a>: + <div class='section'> + <div class='docs'><h1>main.py</h1></div> + </div> + <div class='clearall'> + <div class='section' id='section-0'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-0'>#</a> + </div> + <p>"<strong>Pycco</strong>" is a Python port of <a href="http://jashkenas.github.com/docco/">Docco</a>: the original quick-and-dirty, hundred-line-long, literate-programming-style documentation generator. It produces HTML that displays your comments alongside your code. Comments are passed through @@ -31,97 +26,138 @@ alongside your code. Comments are passed through passed through <a href="http://pygments.org/">Pygments</a> for syntax highlighting. This page is the result of running Pycco against its own source file.</p> <p>If you install Pycco, you can run it from the command-line:</p> -<p>pycco src/*.py</p> +<pre><code>pycco src/*.py +</code></pre> <p>This will generate linked HTML documentation for the named source files, saving it into a <code>docs</code> folder by default.</p> <p>The <a href="https://github.com/fitzgen/pycco">source for Pycco</a> is available on GitHub, and released under the MIT license.</p> <p>To install Pycco, simply</p> -<p>pip install pycco</p> +<pre><code>pip install pycco +</code></pre> <p>Or, to install the latest source</p> -<p>git clone git://github.com/fitzgen/pycco.git +<pre><code>git clone git://github.com/fitzgen/pycco.git cd pycco -python setup.py install</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> - </td> - </tr><tr id='section-1'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-1">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> - </td> - </tr><tr id='section-2'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-2">#</a> - </div> - <h3><span id="main-documentation-generation-functions" href="main-documentation-generation-functions"> Main Documentation Generation Functions </span></h3> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> - </td> - </tr><tr id='section-3'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-3">#</a> - </div> - <p>Generate the documentation for a source file by reading it in, splitting it +python setup.py install +</code></pre> + </div> + <div class='code'> + <div class="highlight"><pre><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">print_function</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-1'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-1'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-2'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-2'>#</a> + </div> + <h3><span id="main-documentation-generation-functions" href="main-documentation-generation-functions"> Main Documentation Generation Functions </span></h3> + </div> + <div class='code'> + <div class="highlight"><pre></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-3'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-3'>#</a> + </div> + <p>Generate the documentation for a source file by reading it in, splitting it 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> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-4'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-4">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> + </div> + <div class='code'> + <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">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> + <span class="n">language</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s">"utf8"</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-4'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-4'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">"Missing the required 'outdir' keyword argument."</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">"r"</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">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)</span> - <span class="k">return</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> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-5'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-5">#</a> - </div> - <p>Given a string of source code, parse out each comment and the code that + <span class="n">code</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">"rb"</span><span class="p">)</span><span class="o">.</span><span class="n">read</span><span class="p">()</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="n">encoding</span><span class="p">)</span> + <span class="k">return</span> <span class="n">_generate_documentation</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">code</span><span class="p">,</span> <span class="n">outdir</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="p">,</span> <span class="n">language</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-5'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-5'>#</a> + </div> + <p>Helper function to allow documentation generation without file handling.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">_generate_documentation</span><span class="p">(</span><span class="n">file_path</span><span class="p">,</span> <span class="n">code</span><span class="p">,</span> <span class="n">outdir</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="p">,</span> <span class="n">language</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-6'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-6'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">language</span> <span class="o">=</span> <span class="n">get_language</span><span class="p">(</span><span class="n">file_path</span><span class="p">,</span> <span class="n">code</span><span class="p">,</span> <span class="n">language</span><span class="o">=</span><span class="n">language</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">code</span><span class="p">,</span> <span class="n">language</span><span class="p">)</span> + <span class="n">highlight</span><span class="p">(</span><span class="n">sections</span><span class="p">,</span> <span class="n">language</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)</span> + <span class="k">return</span> <span class="n">generate_html</span><span class="p">(</span><span class="n">file_path</span><span class="p">,</span> <span class="n">sections</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-7'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-7'>#</a> + </div> + <p>Given a string of source code, parse out each comment and the code that follows it, and create an individual <strong>section</strong> for it. Sections take the form:</p> -<pre>{ "docs_text": ..., -"docs_html": ..., -"code_text": ..., -"code_html": ..., -"num": ... +<pre><code>{ "docs_text": ..., + "docs_html": ..., + "code_text": ..., + "code_html": ..., + "num": ... } - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">parse</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">code</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> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">lines</span> <span class="o">=</span> <span class="n">code</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">)</span> +</code></pre> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">parse</span><span class="p">(</span><span class="n">code</span><span class="p">,</span> <span class="n">language</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-8'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-8'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">lines</span> <span class="o">=</span> <span class="n">code</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">"</span><span class="se">\n</span><span class="s">"</span><span class="p">)</span> <span class="n">sections</span> <span class="o">=</span> <span class="p">[]</span> - <span class="n">language</span> <span class="o">=</span> <span class="n">get_language</span><span class="p">(</span><span class="n">source</span><span class="p">)</span> <span class="n">has_code</span> <span class="o">=</span> <span class="n">docs_text</span> <span class="o">=</span> <span class="n">code_text</span> <span class="o">=</span> <span class="s">""</span> <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">"#!"</span><span class="p">):</span> @@ -131,121 +167,127 @@ Sections take the form:</p> <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'coding[:=]\s*([-\w.]+)'</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></pre></div></pre></div> - </td> - </tr><tr id='section-7'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-7">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <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="k">break</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-9'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-9'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <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="k">if</span> <span class="n">docs</span> <span class="ow">or</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">"docs_text"</span><span class="p">:</span> <span class="n">docs</span><span class="p">,</span> <span class="s">"code_text"</span><span class="p">:</span> <span class="n">code</span> - <span class="p">})</span></pre></div></pre></div> - </td> - </tr><tr id='section-8'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-8">#</a> - </div> - <p>Setup the variables to get ready to check for multiline comments</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">preformatted</span> <span class="o">=</span> <span class="n">multi_line</span> <span class="o">=</span> <span class="bp">False</span> - <span class="n">last_scope</span> <span class="o">=</span> <span class="mi">0</span> - <span class="n">multi_line_delimiters</span> <span class="o">=</span> <span class="p">[</span><span class="n">language</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"multistart"</span><span class="p">),</span> <span class="n">language</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"multiend"</span><span class="p">)]</span> - - <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">lines</span><span class="p">:</span></pre></div></pre></div> - </td> - </tr><tr id='section-9'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-9">#</a> - </div> - <p>Only go into multiline comments section when one of the delimiters is + <span class="p">})</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-10'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-10'>#</a> + </div> + <p>Setup the variables to get ready to check for multiline comments</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">multi_line</span> <span class="o">=</span> <span class="bp">False</span> + <span class="n">multi_string</span> <span class="o">=</span> <span class="bp">False</span> + <span class="n">multistart</span><span class="p">,</span> <span class="n">multiend</span> <span class="o">=</span> <span class="n">language</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"multistart"</span><span class="p">),</span> <span class="n">language</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"multiend"</span><span class="p">)</span> + <span class="n">comment_matcher</span> <span class="o">=</span> <span class="n">language</span><span class="p">[</span><span class="s">'comment_matcher'</span><span class="p">]</span> + + <span class="k">for</span> <span class="n">line</span> <span class="ow">in</span> <span class="n">lines</span><span class="p">:</span> + <span class="n">process_as_code</span> <span class="o">=</span> <span class="bp">False</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-11'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-11'>#</a> + </div> + <p>Only go into multiline comments section when one of the delimiters is found to be at the start of a line</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="nb">all</span><span class="p">(</span><span class="n">multi_line_delimiters</span><span class="p">)</span> <span class="ow">and</span> <span class="nb">any</span><span class="p">([</span><span class="n">line</span><span class="o">.</span><span class="n">lstrip</span><span class="p">()</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">delim</span><span class="p">)</span> <span class="k">for</span> <span class="n">delim</span> <span class="ow">in</span> <span class="n">multi_line_delimiters</span><span class="p">]):</span> - <span class="k">if</span> <span class="ow">not</span> <span class="n">multi_line</span><span class="p">:</span> - <span class="n">multi_line</span> <span class="o">=</span> <span class="bp">True</span> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="n">multistart</span> <span class="ow">and</span> <span class="n">multiend</span> \ + <span class="ow">and</span> <span class="nb">any</span><span class="p">(</span><span class="n">line</span><span class="o">.</span><span class="n">lstrip</span><span class="p">()</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">delim</span><span class="p">)</span> <span class="ow">or</span> <span class="n">line</span><span class="o">.</span><span class="n">rstrip</span><span class="p">()</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="n">delim</span><span class="p">)</span> + <span class="k">for</span> <span class="n">delim</span> <span class="ow">in</span> <span class="p">(</span><span class="n">multistart</span><span class="p">,</span> <span class="n">multiend</span><span class="p">)):</span> + <span class="n">multi_line</span> <span class="o">=</span> <span class="ow">not</span> <span class="n">multi_line</span> - <span class="k">else</span><span class="p">:</span> + <span class="k">if</span> <span class="n">multi_line</span> \ + <span class="ow">and</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="n">multiend</span><span class="p">)</span> \ + <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">())</span> <span class="o">></span> <span class="nb">len</span><span class="p">(</span><span class="n">multiend</span><span class="p">):</span> <span class="n">multi_line</span> <span class="o">=</span> <span class="bp">False</span> - - <span class="k">if</span> <span class="p">(</span><span class="n">multi_line</span> - <span class="ow">and</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span><span class="o">.</span><span class="n">endswith</span><span class="p">(</span><span class="n">language</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"multiend"</span><span class="p">))</span> - <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">())</span> <span class="o">></span> <span class="nb">len</span><span class="p">(</span><span class="n">language</span><span class="o">.</span><span class="n">get</span><span class="p">(</span><span class="s">"multiend"</span><span class="p">))):</span> - <span class="n">multi_line</span> <span class="o">=</span> <span class="bp">False</span></pre></div></pre></div> - </td> - </tr><tr id='section-10'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-10">#</a> - </div> - <p>Get rid of the delimiters so that they aren't in the final docs</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">line</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="n">re</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="n">language</span><span class="p">[</span><span class="s">"multistart"</span><span class="p">]),</span><span class="s">''</span><span class="p">,</span><span class="n">line</span><span class="p">)</span> - <span class="n">line</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="n">re</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="n">language</span><span class="p">[</span><span class="s">"multiend"</span><span class="p">]),</span><span class="s">''</span><span class="p">,</span><span class="n">line</span><span class="p">)</span> - <span class="n">docs_text</span> <span class="o">+=</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span> <span class="o">+</span> <span class="s">'</span><span class="se">\n</span><span class="s">'</span> - - <span class="k">if</span> <span class="n">has_code</span> <span class="ow">and</span> <span class="n">docs_text</span><span class="o">.</span><span class="n">strip</span><span class="p">():</span> - <span class="n">save</span><span class="p">(</span><span class="n">docs_text</span><span class="p">,</span> <span class="n">code_text</span><span class="p">[:</span><span class="o">-</span><span class="mi">1</span><span class="p">])</span> - <span class="n">code_text</span> <span class="o">=</span> <span class="n">code_text</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">'</span><span class="se">\n</span><span class="s">'</span><span class="p">)[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> - <span class="n">last_scope</span> <span class="o">=</span> <span class="mi">0</span> - <span class="n">has_code</span> <span class="o">=</span> <span class="n">docs_text</span> <span class="o">=</span> <span class="s">''</span> - - <span class="k">elif</span> <span class="n">multi_line</span><span class="p">:</span> - <span class="n">line_striped</span> <span class="o">=</span> <span class="n">line</span><span class="o">.</span><span class="n">rstrip</span><span class="p">()</span> - <span class="n">current_scope</span> <span class="o">=</span> <span class="n">line_striped</span><span class="o">.</span><span class="n">count</span><span class="p">(</span><span class="s">" "</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-11'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-11">#</a> - </div> - <p>This section will parse if the line is indented at least four -places, and if so know to have the final text treat it as a -preformatted text block.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="n">line_striped</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">" "</span><span class="p">)</span> <span class="ow">and</span> <span class="n">last_scope</span><span class="p">:</span> - <span class="k">if</span> <span class="n">current_scope</span> <span class="o">></span> <span class="n">last_scope</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">preformatted</span><span class="p">:</span> - <span class="n">preformatted</span> <span class="o">=</span> <span class="bp">True</span> - <span class="n">docs_text</span> <span class="o">+=</span> <span class="s">"<pre>"</span> + <span class="k">if</span> <span class="ow">not</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">multistart</span><span class="p">)</span> <span class="ow">and</span> <span class="ow">not</span> <span class="n">multi_line</span> \ + <span class="ow">or</span> <span class="n">multi_string</span><span class="p">:</span> + + <span class="n">process_as_code</span> <span class="o">=</span> <span class="bp">True</span> + + <span class="k">if</span> <span class="n">multi_string</span><span class="p">:</span> + <span class="n">multi_line</span> <span class="o">=</span> <span class="bp">False</span> + <span class="n">multi_string</span> <span class="o">=</span> <span class="bp">False</span> + <span class="k">else</span><span class="p">:</span> + <span class="n">multi_string</span> <span class="o">=</span> <span class="bp">True</span> + + <span class="k">else</span><span class="p">:</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-12'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-12'>#</a> + </div> + <p>Get rid of the delimiters so that they aren't in the final +docs</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">line</span> <span class="o">=</span> <span class="n">line</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">multistart</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span> + <span class="n">line</span> <span class="o">=</span> <span class="n">line</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">multiend</span><span class="p">,</span> <span class="s">''</span><span class="p">)</span> + <span class="n">docs_text</span> <span class="o">+=</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span> <span class="o">+</span> <span class="s">'</span><span class="se">\n</span><span class="s">'</span> + <span class="n">indent_level</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s">"\s*"</span><span class="p">,</span> <span class="n">line</span><span class="p">)</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> + + <span class="k">if</span> <span class="n">has_code</span> <span class="ow">and</span> <span class="n">docs_text</span><span class="o">.</span><span class="n">strip</span><span class="p">():</span> + <span class="n">save</span><span class="p">(</span><span class="n">docs_text</span><span class="p">,</span> <span class="n">code_text</span><span class="p">[:</span><span class="o">-</span><span class="mi">1</span><span class="p">])</span> + <span class="n">code_text</span> <span class="o">=</span> <span class="n">code_text</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">'</span><span class="se">\n</span><span class="s">'</span><span class="p">)[</span><span class="o">-</span><span class="mi">1</span><span class="p">]</span> + <span class="n">has_code</span> <span class="o">=</span> <span class="n">docs_text</span> <span class="o">=</span> <span class="s">''</span> + + <span class="k">elif</span> <span class="n">multi_line</span><span class="p">:</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-13'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-13'>#</a> + </div> + <p>Remove leading spaces</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s">r' {{{:d}}}'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="nb">len</span><span class="p">(</span><span class="n">indent_level</span><span class="p">)),</span> <span class="n">line</span><span class="p">):</span> + <span class="n">docs_text</span> <span class="o">+=</span> <span class="n">line</span><span class="p">[</span><span class="nb">len</span><span class="p">(</span><span class="n">indent_level</span><span class="p">):]</span> <span class="o">+</span> <span class="s">'</span><span class="se">\n</span><span class="s">'</span> <span class="k">else</span><span class="p">:</span> - <span class="k">if</span> <span class="n">preformatted</span><span class="p">:</span> - <span class="n">preformatted</span> <span class="o">=</span> <span class="bp">False</span> - <span class="n">docs_text</span> <span class="o">+=</span> <span class="s">"</pre>"</span></pre></div></pre></div> - </td> - </tr><tr id='section-12'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-12">#</a> - </div> - <p>Keep a tracker var to see if the scope increases, that way later -the code can decided if a section is indented more than 4 spaces -from the leading code.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">last_scope</span> <span class="o">=</span> <span class="n">current_scope</span> <span class="k">if</span> <span class="n">current_scope</span> <span class="o">></span> <span class="n">last_scope</span> <span class="k">else</span> <span class="n">last_scope</span> - <span class="n">docs_text</span> <span class="o">+=</span> <span class="n">line</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span> <span class="o">+</span> <span class="s">'</span><span class="se">\n</span><span class="s">'</span> - - <span class="k">elif</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="n">language</span><span class="p">[</span><span class="s">"comment_matcher"</span><span class="p">],</span> <span class="n">line</span><span class="p">):</span> + <span class="n">docs_text</span> <span class="o">+=</span> <span class="n">line</span> <span class="o">+</span> <span class="s">'</span><span class="se">\n</span><span class="s">'</span> + + <span class="k">elif</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="n">comment_matcher</span><span class="p">,</span> <span class="n">line</span><span class="p">):</span> <span class="k">if</span> <span class="n">has_code</span><span class="p">:</span> <span class="n">save</span><span class="p">(</span><span class="n">docs_text</span><span class="p">,</span> <span class="n">code_text</span><span class="p">)</span> <span class="n">has_code</span> <span class="o">=</span> <span class="n">docs_text</span> <span class="o">=</span> <span class="n">code_text</span> <span class="o">=</span> <span class="s">''</span> - <span class="n">docs_text</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="n">language</span><span class="p">[</span><span class="s">"comment_matcher"</span><span class="p">],</span> <span class="s">""</span><span class="p">,</span> <span class="n">line</span><span class="p">)</span> <span class="o">+</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span> + <span class="n">docs_text</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="n">comment_matcher</span><span class="p">,</span> <span class="s">""</span><span class="p">,</span> <span class="n">line</span><span class="p">)</span> <span class="o">+</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span> <span class="k">else</span><span class="p">:</span> - <span class="k">if</span> <span class="n">code_text</span> <span class="ow">and</span> <span class="nb">any</span><span class="p">([</span><span class="n">line</span><span class="o">.</span><span class="n">lstrip</span><span class="p">()</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="p">[</span><span class="s">'class '</span><span class="p">,</span> <span class="s">'def '</span><span class="p">,</span> <span class="s">'@'</span><span class="p">]]):</span> + <span class="n">process_as_code</span> <span class="o">=</span> <span class="bp">True</span> + + <span class="k">if</span> <span class="n">process_as_code</span><span class="p">:</span> + <span class="k">if</span> <span class="n">code_text</span> <span class="ow">and</span> <span class="nb">any</span><span class="p">(</span><span class="n">line</span><span class="o">.</span><span class="n">lstrip</span><span class="p">()</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">x</span><span class="p">)</span> + <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="p">[</span><span class="s">'class '</span><span class="p">,</span> <span class="s">'def '</span><span class="p">,</span> <span class="s">'@'</span><span class="p">]):</span> <span class="k">if</span> <span class="ow">not</span> <span class="n">code_text</span><span class="o">.</span><span class="n">lstrip</span><span class="p">()</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="s">"@"</span><span class="p">):</span> <span class="n">save</span><span class="p">(</span><span class="n">docs_text</span><span class="p">,</span> <span class="n">code_text</span><span class="p">)</span> <span class="n">code_text</span> <span class="o">=</span> <span class="n">has_code</span> <span class="o">=</span> <span class="n">docs_text</span> <span class="o">=</span> <span class="s">''</span> @@ -253,144 +295,175 @@ from the leading code.</p> <span class="n">has_code</span> <span class="o">=</span> <span class="bp">True</span> <span class="n">code_text</span> <span class="o">+=</span> <span class="n">line</span> <span class="o">+</span> <span class="s">'</span><span class="se">\n</span><span class="s">'</span> - <span class="n">save</span><span class="p">(</span><span class="n">docs_text</span><span class="p">,</span> <span class="n">code_text</span><span class="p">)</span> - <span class="k">return</span> <span class="n">sections</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> - <h3><span id="preprocessing-the-comments" href="preprocessing-the-comments"> Preprocessing the comments </span></h3> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> - </td> - </tr><tr id='section-14'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-14">#</a> - </div> - <p></pre>Add cross-references before having the text processed by markdown. It's -possible to reference another file, like this : <code>[[main.py]]</code> which renders <a href="main.html">main.py</a>. You can also reference a specific section of another file, like -this: <code>[[main.py#highlighting-the-source-code]]</code> which renders as <a href="main.html#highlighting-the-source-code">main.py</a>. Sections have to be manually + <span class="k">return</span> <span class="n">sections</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-14'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-14'>#</a> + </div> + <h3><span id="preprocessing-the-comments" href="preprocessing-the-comments"> Preprocessing the comments </span></h3> + </div> + <div class='code'> + <div class="highlight"><pre></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-15'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-15'>#</a> + </div> + <p>Add cross-references before having the text processed by markdown. It's +possible to reference another file, like this : <code>[[main.py]]</code> which renders + <a href="main.html">main.py</a>. You can also reference a specific section of another file, like +this: <code>[[main.py#highlighting-the-source-code]]</code> which renders as + <a href="main.html#highlighting-the-source-code">main.py</a>. Sections have to be manually declared; they are written on a single line, and surrounded by equals signs: <code>=== like this ===</code></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="n">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-15'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-15">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> - <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">"Missing the required 'outdir' keyword argument."</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-16'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-16">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <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="s">"-"</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">name</span><span class="o">.</span><span class="n">lower</span><span class="p">()</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">" "</span><span class="p">))</span></pre></div></pre></div> - </td> - </tr><tr id='section-17'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-17">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <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-18'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-18">#</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">'#'</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> + </div> + <div class='code'> + <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">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-16'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-16'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> + <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">"Missing the required 'outdir' keyword argument."</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-17'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-17'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <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="s">"-"</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">name</span><span class="o">.</span><span class="n">lower</span><span class="p">()</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">" "</span><span class="p">))</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-18'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-18'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <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> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-19'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-19'>#</a> + </div> + <p>Check if the match contains an anchor</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="s">'#'</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">'#'</span><span class="p">)</span> - <span class="k">return</span> <span class="s">" [</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">)"</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">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> - <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)),</span> - <span class="n">anchor</span><span class="p">)</span> + <span class="k">return</span> <span class="s">" [{}]({}#{})"</span><span class="o">.</span><span class="n">format</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">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> + <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</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">" [</span><span class="si">%s</span><span class="s">](</span><span class="si">%s</span><span class="s">)"</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="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> - <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)))</span></pre></div></pre></div> - </td> - </tr><tr id='section-19'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-19">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <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">'</span><span class="si">%(lvl)s</span><span class="s"> <span id="</span><span class="si">%(id)s</span><span class="s">" href="</span><span class="si">%(id)s</span><span class="s">"></span><span class="si">%(name)s</span><span class="s"></span>'</span> <span class="o">%</span> <span class="p">{</span> - <span class="s">"lvl"</span> <span class="p">:</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s">'='</span><span class="p">,</span> <span class="s">'#'</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="s">"id"</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">2</span><span class="p">)),</span> - <span class="s">"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">2</span><span class="p">)</span> - <span class="p">}</span> + <span class="k">return</span> <span class="s">" [{}]({})"</span><span class="o">.</span><span class="n">format</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="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> + <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)))</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-20'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-20'>#</a> + </div> + <p>Replace equals-sign-formatted section names with anchor links.</p> + </div> + <div class='code'> + <div class="highlight"><pre> <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></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-21'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-21'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">return</span> <span class="s">'{lvl} <span id="{id}" href="{id}">{name}</span>'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span> + <span class="n">lvl</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">'='</span><span class="p">,</span> <span class="s">'#'</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="nb">id</span><span class="o">=</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">2</span><span class="p">)),</span> + <span class="n">name</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">2</span><span class="p">)</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">'^([=]+)([^=]+)[=]*\s*$'</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">'[^`]\[\[(.+)\]\]'</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-20'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-20">#</a> - </div> - <h3><span id="highlighting-the-source-code" href="highlighting-the-source-code"> Highlighting the source code </span></h3> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> - </td> - </tr><tr id='section-21'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-21">#</a> - </div> - <p>Highlights a single chunk of code using the <strong>Pygments</strong> module, and runs + <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">'(?<!`)\[\[(.+?)\]\]'</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> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-22'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-22'>#</a> + </div> + <h3><span id="highlighting-the-source-code" href="highlighting-the-source-code"> Highlighting the source code </span></h3> + </div> + <div class='code'> + <div class="highlight"><pre></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-23'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-23'>#</a> + </div> + <p>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 wherever our markers occur.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">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">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-22'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-22">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">highlight</span><span class="p">(</span><span class="n">sections</span><span class="p">,</span> <span class="n">language</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-24'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-24'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">"Missing the required 'outdir' keyword argument."</span><span class="p">)</span> - <span class="n">language</span> <span class="o">=</span> <span class="n">get_language</span><span class="p">(</span><span class="n">source</span><span class="p">)</span> <span class="n">output</span> <span class="o">=</span> <span class="n">pygments</span><span class="o">.</span><span class="n">highlight</span><span class="p">(</span><span class="n">language</span><span class="p">[</span><span class="s">"divider_text"</span><span class="p">]</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">section</span><span class="p">[</span><span class="s">"code_text"</span><span class="p">]</span><span class="o">.</span><span class="n">rstrip</span><span class="p">()</span> <span class="k">for</span> <span class="n">section</span> <span class="ow">in</span> <span class="n">sections</span><span class="p">),</span> <span class="n">language</span><span class="p">[</span><span class="s">"lexer"</span><span class="p">],</span> @@ -404,47 +477,56 @@ wherever our markers occur.</p> <span class="n">docs_text</span> <span class="o">=</span> <span class="nb">unicode</span><span class="p">(</span><span class="n">section</span><span class="p">[</span><span class="s">"docs_text"</span><span class="p">])</span> <span class="k">except</span> <span class="ne">UnicodeError</span><span class="p">:</span> <span class="n">docs_text</span> <span class="o">=</span> <span class="nb">unicode</span><span class="p">(</span><span class="n">section</span><span class="p">[</span><span class="s">"docs_text"</span><span class="p">]</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s">'utf-8'</span><span class="p">))</span> + <span class="k">except</span> <span class="ne">NameError</span><span class="p">:</span> + <span class="n">docs_text</span> <span class="o">=</span> <span class="n">section</span><span class="p">[</span><span class="s">'docs_text'</span><span class="p">]</span> <span class="n">section</span><span class="p">[</span><span class="s">"docs_html"</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">docs_text</span><span class="p">,</span> - <span class="n">i</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">))</span> - <span class="n">section</span><span class="p">[</span><span class="s">"num"</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span></pre></div></pre></div> - </td> - </tr><tr id='section-23'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-23">#</a> - </div> - <h3><span id="html-code-generation" href="html-code-generation"> HTML Code generation </span></h3> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> - </td> - </tr><tr id='section-24'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-24">#</a> - </div> - <p>Once all of the code is finished highlighting, we can generate the HTML file + <span class="n">section</span><span class="p">[</span><span class="s">"num"</span><span class="p">]</span> <span class="o">=</span> <span class="n">i</span> + + <span class="k">return</span> <span class="n">sections</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-25'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-25'>#</a> + </div> + <h3><span id="html-code-generation" href="html-code-generation"> HTML Code generation </span></h3> + </div> + <div class='code'> + <div class="highlight"><pre></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-26'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-26'>#</a> + </div> + <p>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> <p>Pystache will attempt to recursively render context variables, so we must replace any occurences of <code>{{</code>, which is valid in some languages, with a "unique enough" identifier before rendering, and then post-process the rendered template and change the identifier back to <code>{{</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> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-25'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-25">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> + </div> + <div class='code'> + <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">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-27'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-27'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">"Missing the required 'outdir' keyword argument"</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">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)</span> @@ -454,45 +536,51 @@ rendered template and change the identifier back to <code>{{</code>.</p> <span class="n">sect</span><span class="p">[</span><span class="s">"code_html"</span><span class="p">]</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">r"\{\{"</span><span class="p">,</span> <span class="s">r"{{"</span><span class="p">,</span> <span class="n">sect</span><span class="p">[</span><span class="s">"code_html"</span><span class="p">])</span> <span class="n">rendered</span> <span class="o">=</span> <span class="n">pycco_template</span><span class="p">({</span> - <span class="s">"title"</span> <span class="p">:</span> <span class="n">title</span><span class="p">,</span> - <span class="s">"stylesheet"</span> <span class="p">:</span> <span class="n">csspath</span><span class="p">,</span> - <span class="s">"sections"</span> <span class="p">:</span> <span class="n">sections</span><span class="p">,</span> - <span class="s">"source"</span> <span class="p">:</span> <span class="n">source</span><span class="p">,</span> - <span class="s">"path"</span> <span class="p">:</span> <span class="n">path</span><span class="p">,</span> - <span class="s">"destination"</span> <span class="p">:</span> <span class="n">destination</span> + <span class="s">"title"</span><span class="p">:</span> <span class="n">title</span><span class="p">,</span> + <span class="s">"stylesheet"</span><span class="p">:</span> <span class="n">csspath</span><span class="p">,</span> + <span class="s">"sections"</span><span class="p">:</span> <span class="n">sections</span><span class="p">,</span> + <span class="s">"source"</span><span class="p">:</span> <span class="n">source</span><span class="p">,</span> + <span class="s">"path"</span><span class="p">:</span> <span class="n">path</span><span class="p">,</span> + <span class="s">"destination"</span><span class="p">:</span> <span class="n">destination</span> <span class="p">})</span> - <span class="k">return</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s">r"{{"</span><span class="p">,</span> <span class="s">"{{"</span><span class="p">,</span> <span class="n">rendered</span><span class="p">)</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">"utf-8"</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-26'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-26">#</a> - </div> - <h3><span id="helpers-&-setup" href="helpers-&-setup"> Helpers & Setup </span></h3> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> - </td> - </tr><tr id='section-27'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-27">#</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-28'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-28">#</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">optparse</span> + <span class="k">return</span> <span class="n">re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s">r"{{"</span><span class="p">,</span> <span class="s">"{{"</span><span class="p">,</span> <span class="n">rendered</span><span class="p">)</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="s">"utf-8"</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-28'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-28'>#</a> + </div> + <h3><span id="helpers-&-setup" href="helpers-&-setup"> Helpers & Setup </span></h3> + </div> + <div class='code'> + <div class="highlight"><pre></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-29'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-29'>#</a> + </div> + <p>This module contains all of our static resources.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="kn">import</span> <span class="nn">pycco_resources</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-30'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-30'>#</a> + </div> + <p>Import our external dependencies.</p> + </div> + <div class='code'> + <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> @@ -501,310 +589,434 @@ rendered template and change the identifier back to <code>{{</code>.</p> <span class="kn">import</span> <span class="nn">time</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></pre></div></pre></div> - </td> - </tr><tr id='section-29'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-29">#</a> - </div> - <p>A list of the languages that Pycco supports, mapping the file extension to +<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></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-31'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-31'>#</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">".coffee"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"coffee-script"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span> <span class="p">},</span> - - <span class="s">".pl"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"perl"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span> <span class="p">},</span> - - <span class="s">".sql"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"sql"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"--"</span> <span class="p">},</span> - - <span class="s">".c"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"c"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"//"</span><span class="p">},</span> - - <span class="s">".cpp"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"cpp"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"//"</span><span class="p">},</span> - - <span class="s">".js"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"javascript"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"//"</span><span class="p">,</span> - <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"/*"</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"*/"</span><span class="p">},</span> - - <span class="s">".rb"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"ruby"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span><span class="p">,</span> - <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"=begin"</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"=end"</span><span class="p">},</span> - - <span class="s">".py"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"python"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span><span class="p">,</span> - <span class="s">"multistart"</span><span class="p">:</span> <span class="s">'"""'</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">'"""'</span> <span class="p">},</span> - - <span class="s">".scm"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"scheme"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">";;"</span><span class="p">,</span> - <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"#|"</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"|#"</span><span class="p">},</span> - - <span class="s">".lua"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"lua"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"--"</span><span class="p">,</span> - <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"--[["</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"--]]"</span><span class="p">},</span> - - <span class="s">".erl"</span><span class="p">:</span> <span class="p">{</span> <span class="s">"name"</span><span class="p">:</span> <span class="s">"erlang"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"</span><span class="si">%%</span><span class="s">"</span> <span class="p">},</span> -<span class="p">}</span></pre></div></pre></div> - </td> - </tr><tr id='section-30'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-30">#</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-31'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-31">#</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">"comment_matcher"</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"^\s*"</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">"symbol"</span><span class="p">]</span> <span class="o">+</span> <span class="s">"\s?"</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-32'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-32">#</a> - </div> - <p>The dividing token we feed into Pygments, to delimit the boundaries between + </div> + <div class='code'> + <div class="highlight"><pre><span class="n">languages</span> <span class="o">=</span> <span class="p">{</span> + <span class="s">".coffee"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"coffee-script"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span><span class="p">,</span> + <span class="s">"multistart"</span><span class="p">:</span> <span class="s">'###'</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">'###'</span><span class="p">},</span> + + <span class="s">".pl"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"perl"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span><span class="p">},</span> + + <span class="s">".sql"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"sql"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"--"</span><span class="p">},</span> + + <span class="s">".c"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"c"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"//"</span><span class="p">,</span> + <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"/*"</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"*/"</span><span class="p">},</span> + + <span class="s">".cpp"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"cpp"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"//"</span><span class="p">},</span> + + <span class="s">".js"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"javascript"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"//"</span><span class="p">,</span> + <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"/*"</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"*/"</span><span class="p">},</span> + + <span class="s">".rb"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"ruby"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span><span class="p">,</span> + <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"=begin"</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"=end"</span><span class="p">},</span> + + <span class="s">".py"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"python"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span><span class="p">,</span> + <span class="s">"multistart"</span><span class="p">:</span> <span class="s">'"""'</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">'"""'</span><span class="p">},</span> + + <span class="s">".scm"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"scheme"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">";;"</span><span class="p">,</span> + <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"#|"</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"|#"</span><span class="p">},</span> + + <span class="s">".lua"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"lua"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"--"</span><span class="p">,</span> + <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"--[["</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"--]]"</span><span class="p">},</span> + + <span class="s">".erl"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"erlang"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"</span><span class="si">%%</span><span class="s">"</span><span class="p">},</span> + + <span class="s">".tcl"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"tcl"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"#"</span><span class="p">},</span> + + <span class="s">".hs"</span><span class="p">:</span> <span class="p">{</span><span class="s">"name"</span><span class="p">:</span> <span class="s">"haskell"</span><span class="p">,</span> <span class="s">"symbol"</span><span class="p">:</span> <span class="s">"--"</span><span class="p">,</span> + <span class="s">"multistart"</span><span class="p">:</span> <span class="s">"{-"</span><span class="p">,</span> <span class="s">"multiend"</span><span class="p">:</span> <span class="s">"-}"</span><span class="p">},</span> +<span class="p">}</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-32'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-32'>#</a> + </div> + <p>Build out the appropriate matchers and delimiters for each language.</p> + </div> + <div class='code'> + <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> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-33'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-33'>#</a> + </div> + <p>Does the line begin with a comment?</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s">"comment_matcher"</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"^\s*"</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">"symbol"</span><span class="p">]</span> <span class="o">+</span> <span class="s">"\s?"</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-34'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-34'>#</a> + </div> + <p>The dividing token we feed into Pygments, to delimit the boundaries between sections.</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">"divider_text"</span><span class="p">]</span> <span class="o">=</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">"symbol"</span><span class="p">]</span> <span class="o">+</span> <span class="s">"DIVIDER</span><span class="se">\n</span><span class="s">"</span></pre></div></pre></div> - </td> - </tr><tr id='section-33'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-33">#</a> - </div> - <p>The mirror of <code>divider_text</code> that we expect Pygments to return. We can split + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s">"divider_text"</span><span class="p">]</span> <span class="o">=</span> <span class="s">"</span><span class="se">\n</span><span class="s">"</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">"symbol"</span><span class="p">]</span> <span class="o">+</span> <span class="s">"DIVIDER</span><span class="se">\n</span><span class="s">"</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-35'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-35'>#</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> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s">"divider_html"</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'\n*<span class="c[1]?">'</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">"symbol"</span><span class="p">]</span> <span class="o">+</span> <span class="s">'DIVIDER</span></span><span class="se">\n</span><span class="s">*'</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-34'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-34">#</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">"lexer"</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">"name"</span><span class="p">])</span></pre></div></pre></div> - </td> - </tr><tr id='section-35'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-35">#</a> - </div> - <p>Get the current language we're documenting, based on the extension.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">get_language</span><span class="p">(</span><span class="n">source</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-36'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-36">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">try</span><span class="p">:</span> - <span class="k">return</span> <span class="n">languages</span><span class="p">[</span> <span class="n">source</span><span class="p">[</span><span class="n">source</span><span class="o">.</span><span class="n">rindex</span><span class="p">(</span><span class="s">"."</span><span class="p">):]</span> <span class="p">]</span> - <span class="k">except</span> <span class="ne">ValueError</span><span class="p">:</span> - <span class="n">source</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">"r"</span><span class="p">)</span> - <span class="n">code</span> <span class="o">=</span> <span class="n">source</span><span class="o">.</span><span class="n">read</span><span class="p">()</span> - <span class="n">source</span><span class="o">.</span><span class="n">close</span><span class="p">()</span> - <span class="n">lang</span> <span class="o">=</span> <span class="n">lexers</span><span class="o">.</span><span class="n">guess_lexer</span><span class="p">(</span><span class="n">code</span><span class="p">)</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s">"divider_html"</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'\n*<span class="c[1]?">'</span> <span class="o">+</span> <span class="n">l</span><span class="p">[</span><span class="s">"symbol"</span><span class="p">]</span> <span class="o">+</span> <span class="s">'DIVIDER</span></span><span class="se">\n</span><span class="s">*'</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-36'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-36'>#</a> + </div> + <p>Get the Pygments Lexer for this language.</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s">"lexer"</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">"name"</span><span class="p">])</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-37'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-37'>#</a> + </div> + <p>Get the current language we're documenting, based on the extension.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">get_language</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">code</span><span class="p">,</span> <span class="n">language</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-38'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-38'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="n">language</span> <span class="ow">is</span> <span class="ow">not</span> <span class="bp">None</span><span class="p">:</span> <span class="k">for</span> <span class="n">l</span> <span class="ow">in</span> <span class="n">languages</span><span class="o">.</span><span class="n">values</span><span class="p">():</span> - <span class="k">if</span> <span class="n">l</span><span class="p">[</span><span class="s">"name"</span><span class="p">]</span> <span class="o">==</span> <span class="n">lang</span><span class="p">:</span> + <span class="k">if</span> <span class="n">l</span><span class="p">[</span><span class="s">"name"</span><span class="p">]</span> <span class="o">==</span> <span class="n">language</span><span class="p">:</span> <span class="k">return</span> <span class="n">l</span> <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">"Can't figure out the language!"</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-37'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-37">#</a> - </div> - <p>Compute the destination HTML path for an input source file path. If the + <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s">"Unknown forced language: "</span> <span class="o">+</span> <span class="n">language</span><span class="p">)</span> + + <span class="n">m</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">match</span><span class="p">(</span><span class="s">r'.*(\..+)'</span><span class="p">,</span> <span class="n">os</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="k">if</span> <span class="n">source</span> <span class="k">else</span> <span class="bp">None</span> + <span class="k">if</span> <span class="n">m</span> <span class="ow">and</span> <span class="n">m</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="ow">in</span> <span class="n">languages</span><span class="p">:</span> + <span class="k">return</span> <span class="n">languages</span><span class="p">[</span><span class="n">m</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">else</span><span class="p">:</span> + <span class="k">try</span><span class="p">:</span> + <span class="n">lang</span> <span class="o">=</span> <span class="n">lexers</span><span class="o">.</span><span class="n">guess_lexer</span><span class="p">(</span><span class="n">code</span><span class="p">)</span><span class="o">.</span><span class="n">name</span><span class="o">.</span><span class="n">lower</span><span class="p">()</span> + <span class="k">for</span> <span class="n">l</span> <span class="ow">in</span> <span class="n">languages</span><span class="o">.</span><span class="n">values</span><span class="p">():</span> + <span class="k">if</span> <span class="n">l</span><span class="p">[</span><span class="s">"name"</span><span class="p">]</span> <span class="o">==</span> <span class="n">lang</span><span class="p">:</span> + <span class="k">return</span> <span class="n">l</span> + <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="k">except</span> <span class="ne">ValueError</span><span class="p">:</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-39'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-39'>#</a> + </div> + <p>If pygments can't find any lexers, it will raise its own +subclass of ValueError. We will catch it and raise ours +for consistency.</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s">"Can't figure out the language!"</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-40'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-40'>#</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> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-38'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-38">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> + </div> + <div class='code'> + <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">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-41'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-41'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">dirname</span><span class="p">,</span> <span class="n">filename</span> <span class="o">=</span> <span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">filepath</span><span class="p">)</span> + <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">"Missing the required 'outdir' keyword argument."</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">"."</span><span class="p">):</span> <span class="p">],</span> <span class="s">""</span><span class="p">)</span> + <span class="n">name</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">r"\.[^.]*$"</span><span class="p">,</span> <span class="s">""</span><span class="p">,</span> <span class="n">filename</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">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="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outdir</span><span class="p">,</span> <span class="s">"</span><span class="si">%s</span><span class="s">.html"</span> <span class="o">%</span> <span class="n">name</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-39'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-39">#</a> - </div> - <p>Shift items off the front of the <code>list</code> until it is empty, then return + <span class="n">name</span> <span class="o">=</span> <span class="n">filename</span> + <span class="k">if</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">join</span><span class="p">(</span><span class="n">dirname</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span> + <span class="n">dest</span> <span class="o">=</span> <span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outdir</span><span class="p">,</span> <span class="s">u"{}.html"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">name</span><span class="p">))</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-42'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-42'>#</a> + </div> + <p>If <code>join</code> is passed an absolute path, it will ignore any earlier path +elements. We will force outdir to the beginning of the path to avoid +writing outside our destination.</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">dest</span><span class="o">.</span><span class="n">startswith</span><span class="p">(</span><span class="n">outdir</span><span class="p">):</span> + <span class="n">dest</span> <span class="o">=</span> <span class="n">outdir</span> <span class="o">+</span> <span class="n">os</span><span class="o">.</span><span class="n">sep</span> <span class="o">+</span> <span class="n">dest</span> + <span class="k">return</span> <span class="n">dest</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-43'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-43'>#</a> + </div> + <p>Shift items off the front of the <code>list</code> until it is empty, then return <code>default</code>.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">shift</span><span class="p">(</span><span class="nb">list</span><span class="p">,</span> <span class="n">default</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-40'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-40">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">try</span><span class="p">:</span> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">shift</span><span class="p">(</span><span class="nb">list</span><span class="p">,</span> <span class="n">default</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-44'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-44'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">try</span><span class="p">:</span> <span class="k">return</span> <span class="nb">list</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">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-41'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-41">#</a> - </div> - <p>Ensure that the destination directory exists.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">ensure_directory</span><span class="p">(</span><span class="n">directory</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-42'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-42">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isdir</span><span class="p">(</span><span class="n">directory</span><span class="p">):</span> - <span class="n">os</span><span class="o">.</span><span class="n">mkdir</span><span class="p">(</span><span class="n">directory</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-43'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-43">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><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-44'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-44">#</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-45'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-45">#</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-46'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-46">#</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">"<div class=</span><span class="se">\"</span><span class="s">highlight</span><span class="se">\"</span><span class="s">><pre>"</span></pre></div></pre></div> - </td> - </tr><tr id='section-47'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-47">#</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">"</pre></div>"</span></pre></div></pre></div> - </td> - </tr><tr id='section-48'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-48">#</a> - </div> - <p>For each source file passed as argument, generate the documentation.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">process</span><span class="p">(</span><span class="n">sources</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-49'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-49">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> - <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">"Missing the required 'outdir' keyword argument."</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-50'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-50">#</a> - </div> - <p>Make a copy of sources given on the command line. <code>main()</code> needs the + <span class="k">return</span> <span class="n">default</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-45'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-45'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">remove_control_chars</span><span class="p">(</span><span class="n">s</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-46'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-46'>#</a> + </div> + <p>Sanitization regexp copied from +http://stackoverflow.com/questions/92438/stripping-non-printable-characters-from-a-string-in-python</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="kn">from</span> <span class="nn">pycco.compat</span> <span class="kn">import</span> <span class="n">pycco_unichr</span> + <span class="n">control_chars</span> <span class="o">=</span> <span class="s">''</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="nb">map</span><span class="p">(</span><span class="n">pycco_unichr</span><span class="p">,</span> <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">0</span><span class="p">,</span> <span class="mi">32</span><span class="p">))</span> <span class="o">+</span> <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">127</span><span class="p">,</span> <span class="mi">160</span><span class="p">))))</span> + <span class="n">control_char_re</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">u'[{}]'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">re</span><span class="o">.</span><span class="n">escape</span><span class="p">(</span><span class="n">control_chars</span><span class="p">)))</span> + <span class="k">return</span> <span class="n">control_char_re</span><span class="o">.</span><span class="n">sub</span><span class="p">(</span><span class="s">''</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-47'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-47'>#</a> + </div> + <p>Sanitize directory string and ensure that the destination directory exists.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">ensure_directory</span><span class="p">(</span><span class="n">directory</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-48'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-48'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">directory</span> <span class="o">=</span> <span class="n">remove_control_chars</span><span class="p">(</span><span class="n">directory</span><span class="p">)</span> + <span class="k">if</span> <span class="ow">not</span> <span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">isdir</span><span class="p">(</span><span class="n">directory</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">directory</span><span class="p">)</span> + + <span class="k">return</span> <span class="n">directory</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-49'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-49'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre><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> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-50'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-50'>#</a> + </div> + <p>Create the template that we will use to generate the Pycco HTML page.</p> + </div> + <div class='code'> + <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> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-51'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-51'>#</a> + </div> + <p>The CSS styles we'd like to apply to the documentation.</p> + </div> + <div class='code'> + <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> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-52'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-52'>#</a> + </div> + <p>The start of each Pygments highlight block.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="n">highlight_start</span> <span class="o">=</span> <span class="s">"<div class=</span><span class="se">\"</span><span class="s">highlight</span><span class="se">\"</span><span class="s">><pre>"</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-53'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-53'>#</a> + </div> + <p>The end of each Pygments highlight block.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="n">highlight_end</span> <span class="o">=</span> <span class="s">"</pre></div>"</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-54'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-54'>#</a> + </div> + <p>For each source file passed as argument, generate the documentation.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">process</span><span class="p">(</span><span class="n">sources</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">True</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">language</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">encoding</span><span class="o">=</span><span class="s">"utf8"</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-55'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-55'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="ow">not</span> <span class="n">outdir</span><span class="p">:</span> + <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s">"Missing the required 'outdir' keyword argument."</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-56'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-56'>#</a> + </div> + <p>Make a copy of sources given on the command line. <code>main()</code> needs the original list when monitoring for changed files.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">sources</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">sources</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-51'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-51">#</a> - </div> - <p>Proceed to generating the documentation.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="n">sources</span><span class="p">:</span> - <span class="n">ensure_directory</span><span class="p">(</span><span class="n">outdir</span><span class="p">)</span> - <span class="n">css</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outdir</span><span class="p">,</span> <span class="s">"pycco.css"</span><span class="p">),</span> <span class="s">"w"</span><span class="p">)</span> - <span class="n">css</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">pycco_styles</span><span class="p">)</span> - <span class="n">css</span><span class="o">.</span><span class="n">close</span><span class="p">()</span></pre></div></pre></div> - </td> - </tr><tr id='section-52'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-52">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">def</span> <span class="nf">next_file</span><span class="p">():</span> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">sources</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">sources</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-57'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-57'>#</a> + </div> + <p>Proceed to generating the documentation.</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="n">sources</span><span class="p">:</span> + <span class="n">outdir</span> <span class="o">=</span> <span class="n">ensure_directory</span><span class="p">(</span><span class="n">outdir</span><span class="p">)</span> + <span class="n">css</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">join</span><span class="p">(</span><span class="n">outdir</span><span class="p">,</span> <span class="s">"pycco.css"</span><span class="p">),</span> <span class="s">"wb"</span><span class="p">)</span> + <span class="n">css</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">pycco_styles</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">encoding</span><span class="p">))</span> + <span class="n">css</span><span class="o">.</span><span class="n">close</span><span class="p">()</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-58'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-58'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">def</span> <span class="nf">next_file</span><span class="p">():</span> <span class="n">s</span> <span class="o">=</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">dest</span> <span class="o">=</span> <span class="n">destination</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">)</span> @@ -813,146 +1025,183 @@ original list when monitoring for changed files.</p> <span class="k">except</span> <span class="ne">OSError</span><span class="p">:</span> <span class="k">pass</span> - <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">destination</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">),</span> <span class="s">"w"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span> - <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">generate_documentation</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">))</span> + <span class="k">with</span> <span class="nb">open</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="s">"wb"</span><span class="p">)</span> <span class="k">as</span> <span class="n">f</span><span class="p">:</span> + <span class="n">f</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">generate_documentation</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">preserve_paths</span><span class="p">,</span> + <span class="n">outdir</span><span class="o">=</span><span class="n">outdir</span><span class="p">,</span> + <span class="n">language</span><span class="o">=</span><span class="n">language</span><span class="p">,</span> + <span class="n">encoding</span><span class="o">=</span><span class="n">encoding</span><span class="p">))</span> - <span class="k">print</span> <span class="s">"pycco = </span><span class="si">%s</span><span class="s"> -> </span><span class="si">%s</span><span class="s">"</span> <span class="o">%</span> <span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">dest</span><span class="p">)</span> + <span class="k">print</span><span class="p">(</span><span class="s">"pycco = {} -> {}"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">s</span><span class="p">,</span> <span class="n">dest</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> -<span class="n">__all__</span> <span class="o">=</span> <span class="p">(</span><span class="s">"process"</span><span class="p">,</span> <span class="s">"generate_documentation"</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-53'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-53">#</a> - </div> - <p>Monitor each source file and re-generate documentation on change.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">monitor</span><span class="p">(</span><span class="n">sources</span><span class="p">,</span> <span class="n">opts</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-54'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-54">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> - </td> - </tr><tr id='section-55'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-55">#</a> - </div> - <p>The watchdog modules are imported in <code>main()</code> but we need to re-import +<span class="n">__all__</span> <span class="o">=</span> <span class="p">(</span><span class="s">"process"</span><span class="p">,</span> <span class="s">"generate_documentation"</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-59'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-59'>#</a> + </div> + <p>Monitor each source file and re-generate documentation on change.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">monitor</span><span class="p">(</span><span class="n">sources</span><span class="p">,</span> <span class="n">opts</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-60'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-60'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-61'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-61'>#</a> + </div> + <p>The watchdog modules are imported in <code>main()</code> but we need to re-import here to bring them into the local namespace.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="kn">import</span> <span class="nn">watchdog.events</span> - <span class="kn">import</span> <span class="nn">watchdog.observers</span></pre></div></pre></div> - </td> - </tr><tr id='section-56'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-56">#</a> - </div> - <p>Watchdog operates on absolute paths, so map those to original paths + </div> + <div class='code'> + <div class="highlight"><pre> <span class="kn">import</span> <span class="nn">watchdog.events</span> + <span class="kn">import</span> <span class="nn">watchdog.observers</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-62'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-62'>#</a> + </div> + <p>Watchdog operates on absolute paths, so map those to original paths as specified on the command line.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">absolute_sources</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">((</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">source</span><span class="p">),</span> <span class="n">source</span><span class="p">)</span> - <span class="k">for</span> <span class="n">source</span> <span class="ow">in</span> <span class="n">sources</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-57'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-57">#</a> - </div> - <p>A handler for recompiling files which triggered watchdog events</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">class</span> <span class="nc">RegenerateHandler</span><span class="p">(</span><span class="n">watchdog</span><span class="o">.</span><span class="n">events</span><span class="o">.</span><span class="n">FileSystemEventHandler</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-58'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-58">#</a> - </div> - <p>Regenerate documentation for a file which triggered an event</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">def</span> <span class="nf">on_modified</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">event</span><span class="p">):</span></pre></div></pre></div> - </td> - </tr><tr id='section-59'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-59">#</a> - </div> - <p>Re-generate documentation from a source file if it was listed on + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">absolute_sources</span> <span class="o">=</span> <span class="nb">dict</span><span class="p">((</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">abspath</span><span class="p">(</span><span class="n">source</span><span class="p">),</span> <span class="n">source</span><span class="p">)</span> + <span class="k">for</span> <span class="n">source</span> <span class="ow">in</span> <span class="n">sources</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-63'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-63'>#</a> + </div> + <p>A handler for recompiling files which triggered watchdog events</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">class</span> <span class="nc">RegenerateHandler</span><span class="p">(</span><span class="n">watchdog</span><span class="o">.</span><span class="n">events</span><span class="o">.</span><span class="n">FileSystemEventHandler</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-64'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-64'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-65'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-65'>#</a> + </div> + <p>Regenerate documentation for a file which triggered an event</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">def</span> <span class="nf">on_modified</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">event</span><span class="p">):</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-66'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-66'>#</a> + </div> + <p>Re-generate documentation from a source file if it was listed on the command line. Watchdog monitors whole directories, so other files may cause notifications as well.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">src_path</span> <span class="ow">in</span> <span class="n">absolute_sources</span><span class="p">:</span> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="n">event</span><span class="o">.</span><span class="n">src_path</span> <span class="ow">in</span> <span class="n">absolute_sources</span><span class="p">:</span> <span class="n">process</span><span class="p">([</span><span class="n">absolute_sources</span><span class="p">[</span><span class="n">event</span><span class="o">.</span><span class="n">src_path</span><span class="p">]],</span> <span class="n">outdir</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">outdir</span><span class="p">,</span> - <span class="n">preserve_paths</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">paths</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-60'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-60">#</a> - </div> - <p>Set up an observer which monitors all directories for files given on + <span class="n">preserve_paths</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">paths</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-67'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-67'>#</a> + </div> + <p>Set up an observer which monitors all directories for files given on the command line and notifies the handler defined above.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">event_handler</span> <span class="o">=</span> <span class="n">RegenerateHandler</span><span class="p">()</span> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">event_handler</span> <span class="o">=</span> <span class="n">RegenerateHandler</span><span class="p">()</span> <span class="n">observer</span> <span class="o">=</span> <span class="n">watchdog</span><span class="o">.</span><span class="n">observers</span><span class="o">.</span><span class="n">Observer</span><span class="p">()</span> <span class="n">directories</span> <span class="o">=</span> <span class="nb">set</span><span class="p">(</span><span class="n">os</span><span class="o">.</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">source</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span> <span class="k">for</span> <span class="n">source</span> <span class="ow">in</span> <span class="n">sources</span><span class="p">)</span> <span class="k">for</span> <span class="n">directory</span> <span class="ow">in</span> <span class="n">directories</span><span class="p">:</span> - <span class="n">observer</span><span class="o">.</span><span class="n">schedule</span><span class="p">(</span><span class="n">event_handler</span><span class="p">,</span> <span class="n">path</span><span class="o">=</span><span class="n">directory</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-61'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-61">#</a> - </div> - <p>Run the file change monitoring loop until the user hits Ctrl-C.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="n">observer</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> + <span class="n">observer</span><span class="o">.</span><span class="n">schedule</span><span class="p">(</span><span class="n">event_handler</span><span class="p">,</span> <span class="n">path</span><span class="o">=</span><span class="n">directory</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-68'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-68'>#</a> + </div> + <p>Run the file change monitoring loop until the user hits Ctrl-C.</p> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="n">observer</span><span class="o">.</span><span class="n">start</span><span class="p">()</span> <span class="k">try</span><span class="p">:</span> <span class="k">while</span> <span class="bp">True</span><span class="p">:</span> <span class="n">time</span><span class="o">.</span><span class="n">sleep</span><span class="p">(</span><span class="mi">1</span><span class="p">)</span> <span class="k">except</span> <span class="ne">KeyboardInterrupt</span><span class="p">:</span> <span class="n">observer</span><span class="o">.</span><span class="n">stop</span><span class="p">()</span> - <span class="n">observer</span><span class="o">.</span><span class="n">join</span><span class="p">()</span></pre></div></pre></div> - </td> - </tr><tr id='section-62'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-62">#</a> - </div> - <p>Hook spot for the console script.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">main</span><span class="p">():</span></pre></div></pre></div> - </td> - </tr><tr id='section-63'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-63">#</a> - </div> - - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <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">observer</span><span class="o">.</span><span class="n">join</span><span class="p">()</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-69'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-69'>#</a> + </div> + <p>Hook spot for the console script.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">def</span> <span class="nf">main</span><span class="p">():</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-70'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-70'>#</a> + </div> + + </div> + <div class='code'> + <div class="highlight"><pre> <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">'-p'</span><span class="p">,</span> <span class="s">'--paths'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'Preserve path structure of original files'</span><span class="p">)</span> @@ -962,43 +1211,52 @@ the command line and notifies the handler defined above.</p> <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-w'</span><span class="p">,</span> <span class="s">'--watch'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store_true'</span><span class="p">,</span> <span class="n">help</span><span class="o">=</span><span class="s">'Watch original files and re-generate documentation on changes'</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">'-l'</span><span class="p">,</span> <span class="s">'--force-language'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s">'store'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="s">'string'</span><span class="p">,</span> + <span class="n">dest</span><span class="o">=</span><span class="s">'language'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> + <span class="n">help</span><span class="o">=</span><span class="s">'Force the language for the given files'</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">process</span><span class="p">(</span><span class="n">sources</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">outdir</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">paths</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-64'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-64">#</a> - </div> - <p>If the -w / --watch option was present, monitor the source directories + <span class="n">process</span><span class="p">(</span><span class="n">sources</span><span class="p">,</span> <span class="n">outdir</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">outdir</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">paths</span><span class="p">,</span> + <span class="n">language</span><span class="o">=</span><span class="n">opts</span><span class="o">.</span><span class="n">language</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-71'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-71'>#</a> + </div> + <p>If the -w / --watch option was present, monitor the source directories for changes and re-generate documentation for source files whenever they are modified.</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="k">if</span> <span class="n">opts</span><span class="o">.</span><span class="n">watch</span><span class="p">:</span> + </div> + <div class='code'> + <div class="highlight"><pre> <span class="k">if</span> <span class="n">opts</span><span class="o">.</span><span class="n">watch</span><span class="p">:</span> <span class="k">try</span><span class="p">:</span> <span class="kn">import</span> <span class="nn">watchdog.events</span> <span class="kn">import</span> <span class="nn">watchdog.observers</span> <span class="k">except</span> <span class="ne">ImportError</span><span class="p">:</span> <span class="n">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="s">'The -w/--watch option requires the watchdog package.'</span><span class="p">)</span> - <span class="n">monitor</span><span class="p">(</span><span class="n">sources</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span></pre></div></pre></div> - </td> - </tr><tr id='section-65'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-65">#</a> - </div> - <p>Run the script.</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">"__main__"</span><span class="p">:</span> + <span class="n">monitor</span><span class="p">(</span><span class="n">sources</span><span class="p">,</span> <span class="n">opts</span><span class="p">)</span></pre></div> + </div> + </div> + <div class='clearall'></div> + <div class='section' id='section-72'> + <div class='docs'> + <div class='octowrap'> + <a class='octothorpe' href='#section-72'>#</a> + </div> + <p>Run the script.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">"__main__"</span><span class="p">:</span> <span class="n">main</span><span class="p">()</span> -</pre></div></pre></div> - </td> - </tr> - </table> +</pre></div> + </div> + </div> + <div class='clearall'></div> </div> </body> @@ -5,6 +5,7 @@ body { line-height: 24px; color: #252519; margin: 0; padding: 0; + background: #f5f5ff; } a { color: #261a3b; @@ -22,14 +23,17 @@ h2, h3, h4, h5, h6 { margin-top: 0; } #container { + background: white; + } +#container, div.section { position: relative; } #background { - position: fixed; + position: absolute; top: 0; left: 580px; right: 0; bottom: 0; background: #f5f5ff; border-left: 1px solid #e5e5ee; - z-index: -1; + z-index: 0; } #jump_to, #jump_page { background: white; @@ -67,59 +71,57 @@ h2, h3, h4, h5, h6 { } #jump_page .source:first-child { } -table td { - border: 0; - outline: 0; +div.docs { + float: left; + max-width: 500px; + min-width: 500px; + min-height: 5px; + padding: 10px 25px 1px 50px; + vertical-align: top; + text-align: left; } - td.docs, th.docs { - max-width: 500px; - min-width: 500px; - min-height: 5px; - padding: 10px 25px 1px 50px; - vertical-align: top; - text-align: left; + .docs pre { + margin: 15px 0 15px; + padding-left: 15px; } - .docs pre { - margin: 15px 0 15px; - padding-left: 15px; - } - .docs p tt, .docs p code { - background: #f8f8ff; - border: 1px solid #dedede; - font-size: 12px; - padding: 0 0.2em; - } - .octowrap { - position: relative; + .docs p tt, .docs p code { + background: #f8f8ff; + border: 1px solid #dedede; + font-size: 12px; + padding: 0 0.2em; + } + .octowrap { + position: relative; + } + .octothorpe { + font: 12px Arial; + text-decoration: none; + color: #454545; + position: absolute; + top: 3px; left: -20px; + padding: 1px 2px; + opacity: 0; + -webkit-transition: opacity 0.2s linear; } - .octothorpe { - font: 12px Arial; - text-decoration: none; - color: #454545; - position: absolute; - top: 3px; left: -20px; - padding: 1px 2px; - opacity: 0; - -webkit-transition: opacity 0.2s linear; + div.docs:hover .octothorpe { + opacity: 1; } - td.docs:hover .octothorpe { - opacity: 1; - } - td.code, th.code { - padding: 14px 15px 16px 50px; - width: 100%; - vertical-align: top; - background: #f5f5ff; - border-left: 1px solid #e5e5ee; - } -.code pre, .docs p code { - font-size: 12px; +div.code { + margin-left: 580px; + padding: 14px 15px 16px 50px; + vertical-align: top; } + .code pre, .docs p code { + font-size: 12px; + } pre, tt, code { line-height: 18px; font-family: Monaco, Consolas, "Lucida Console", monospace; margin: 0; padding: 0; } +div.clearall { + clear: both; +} /*---------------------- Syntax Highlighting -----------------------------*/ |