diff options
| author | Nick Fitzgerald <fitzgen@gmail.com> | 2010-11-22 00:31:04 -0800 |
|---|---|---|
| committer | Nick Fitzgerald <fitzgen@gmail.com> | 2010-11-22 00:31:04 -0800 |
| commit | 2e14d0a70a398fcf91b7c79b6bf9d166cc42ddac (patch) | |
| tree | 57f2ef25cee0a922f1ad5b8fd6db018d59ecb8b5 | |
| parent | 18646cc355d84b6cb77e7996b17875e6c8284ffc (diff) | |
| download | pycco-2e14d0a70a398fcf91b7c79b6bf9d166cc42ddac.tar.gz | |
Updating gh-pages with latest meta-circular pycco render
| -rw-r--r-- | index.html | 541 | ||||
| -rw-r--r-- | pycco.css | 11 |
2 files changed, 404 insertions, 148 deletions
@@ -2,7 +2,7 @@ <html> <head> <meta http-equiv="content-type" content="text/html;charset=utf-8"> - <title>pycco</title> + <title>main.py</title> <link rel="stylesheet" href="pycco.css"> </head> <body> @@ -12,7 +12,7 @@ <table cellspacing=0 cellpadding=0> <thead> <tr> - <th class=docs><h1>pycco</h1></th> + <th class=docs><h1>main.py</h1></th> <th class=code></th> </tr> </thead> @@ -42,10 +42,15 @@ 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> <pre><code>pycco src/*.py </code></pre> -<p>...will generate linked HTML documentation for the named source files, saving -it into a <code>docs</code> folder.</p> +<p>This will generate linked HTML documentation for the named source files, +saving it into a <code>docs</code> folder by default.</p> <p>To install Pycco, simply</p> -<pre><code>sudo setup.py install +<pre><code>pip install pycco +</code></pre> +<p>Or, to install the latest source</p> +<pre><code>git clone git://github.com/fitzgen/pycco.git +cd pycco +python setup.py install </code></pre> </td> <td class=code> @@ -56,7 +61,7 @@ it into a <code>docs</code> folder.</p> <div class="octowrap"> <a class="octothorpe" href="#section-2">#</a> </div> - <h3>Main Documentation Generation Functions</h3> + <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> @@ -66,17 +71,18 @@ it into a <code>docs</code> folder.</p> <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, + <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">options</span><span class="p">):</span> + <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">generate_documentation</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">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="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">generate_html</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">sections</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="n">options</span><span class="p">)</span></pre></div></pre></div> + <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-4'> <td class=docs> @@ -108,81 +114,238 @@ 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> - - <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></pre></div> + </td> + </tr><tr id='section-5'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-5">#</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="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> + <span class="p">})</span></pre></div></pre></div> + </td> + </tr><tr id='section-6'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-6">#</a> + </div> + <p>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_delimeters</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-7'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-7">#</a> + </div> + <p>Only go into multiline comments section when one of the delimeters 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_delimeters</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_delimeters</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> - <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="k">if</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="k">else</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-8'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-8">#</a> + </div> + <p>Get rid of the delimeters 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">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">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-9'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-9">#</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">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-10'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-10">#</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="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="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="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> + <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-5'> + </tr><tr id='section-11'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-5">#</a> + <a class="octothorpe" href="#section-11">#</a> </div> - <p><a name="Preprocessing"><em> Preprocessing the comments </em></a> -Add cross-references before having the text processed by markdown. -It's possible to reference another file, like this : <a href="pycco.html">pycco.py</a> or a specific section of -another file, like this: <a href="pycco.html#Highlighting">pycco.py</a>. Of course, sections have to be manually declared before, -A section name is written on a single line, and surrounded by equals signs, <a name="like"><em> like this </em></a></p> + <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><span class="k">def</span> <span class="nf">preprocess</span><span class="p">(</span><span class="n">comment</span><span class="p">,</span> <span class="n">section_nr</span><span class="p">):</span> - <span class="k">def</span> <span class="nf">sanitize_section_name</span><span class="p">(</span><span class="n">name</span><span class="p">):</span> - <span class="k">return</span> <span class="n">name</span><span class="o">.</span><span class="n">strip</span><span class="p">()</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s">" "</span><span class="p">)[</span><span class="mi">0</span><span class="p">]</span> - - <span class="k">def</span> <span class="nf">replace_crossref</span><span class="p">(</span><span class="n">match</span><span class="p">):</span></pre></div></pre></div> + <div class='highlight'><pre><div class="highlight"><pre></pre></div></pre></div> </td> - </tr><tr id='section-6'> + </tr><tr id='section-12'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-6">#</a> + <a class="octothorpe" href="#section-12">#</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> + <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-13'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-13">#</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-14'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-14">#</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-15'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-15">#</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> - <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">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> + <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> + <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">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">'<a name="</span><span class="si">%s</span><span class="s">">*</span><span class="si">%s</span><span class="s">*</a>'</span> <span class="o">%</span> <span class="p">(</span><span class="n">sanitize_section_name</span><span class="p">(</span><span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">)),</span> <span class="n">match</span><span class="o">.</span><span class="n">group</span><span class="p">(</span><span class="mi">1</span><span class="p">))</span> + <span class="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-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">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 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">"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">1</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">1</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">'===(.+)===</span><span class="se">\\</span><span class="s">n'</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="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="se">\\</span><span class="s">n'</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> + <span class="k">return</span> <span class="n">comment</span></pre></div></pre></div> </td> - </tr><tr id='section-7'> + </tr><tr id='section-17'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-7">#</a> + <a class="octothorpe" href="#section-17">#</a> </div> - <p><a name="Highlighting"><em> Highlighting the source code </em></a> -Highlights a single chunk of code using the <strong>Pygments</strong> module, and runs the + <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-18'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-18">#</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> + <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> + <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="k">for</span> <span class="n">section</span> <span class="ow">in</span> <span class="n">sections</span><span class="p">),</span> @@ -197,63 +360,81 @@ 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="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">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-8'> + </tr><tr id='section-19'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-8">#</a> + <a class="octothorpe" href="#section-19">#</a> </div> - <p><a name="HTML"><em> HTML Code generation </em></a>Once all of the code is finished highlighting, we can generate the HTML file + <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-20'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-20">#</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> +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">options</span><span class="p">):</span> + <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">generate_html</span><span class="p">(</span><span class="n">source</span><span class="p">,</span> <span class="n">sections</span><span class="p">,</span> <span class="n">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="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">options</span><span class="o">.</span><span class="n">paths</span><span class="p">)</span> - <span class="n">html</span> <span class="o">=</span> <span class="n">pycco_template</span><span class="p">({</span> - <span class="s">"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">path</span><span class="o">.</span><span class="n">relpath</span><span class="p">(</span><span class="s">'docs/pycco.css'</span><span class="p">,</span> <span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">dest</span><span class="p">)[</span><span class="mi">0</span><span class="p">]),</span> - <span class="s">"sections"</span><span class="p">:</span> <span class="n">sections</span><span class="p">,</span> - <span class="s">"sources"</span><span class="p">:</span> <span class="n">sources</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="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> + + <span class="k">for</span> <span class="n">sect</span> <span class="ow">in</span> <span class="n">sections</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="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">path</span><span class="o">.</span><span class="n">relpath</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">path</span><span class="o">.</span><span class="n">dirname</span><span class="p">(</span><span class="n">dest</span><span class="p">),</span> <span class="s">"pycco.css"</span><span class="p">),</span> + <span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">dest</span><span class="p">)[</span><span class="mi">0</span><span class="p">]),</span> + <span class="s">"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">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">source</span><span class="p">,</span> <span class="n">dest</span><span class="p">)</span> - <span class="k">try</span><span class="p">:</span> - <span class="n">os</span><span class="o">.</span><span class="n">makedirs</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">dest</span><span class="p">)[</span><span class="mi">0</span><span class="p">])</span> - <span class="k">except</span> <span class="ne">OSError</span><span class="p">:</span> - <span class="k">pass</span> - <span class="n">fh</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="n">dest</span><span class="p">,</span> <span class="s">"w"</span><span class="p">)</span> - <span class="n">fh</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">html</span><span class="o">.</span><span class="n">encode</span><span class="p">(</span><span class="n">getpreferredencoding</span><span class="p">()))</span> - <span class="n">fh</span><span class="o">.</span><span class="n">close</span><span class="p">()</span></pre></div></pre></div> + + <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-9'> + </tr><tr id='section-21'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-9">#</a> + <a class="octothorpe" href="#section-21">#</a> </div> - <h3>Helpers & Setup</h3> + <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-10'> + </tr><tr id='section-22'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-10">#</a> + <a class="octothorpe" href="#section-22">#</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-11'> + </tr><tr id='section-23'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-11">#</a> + <a class="octothorpe" href="#section-23">#</a> </div> <p>Import our external dependencies.</p> </td> @@ -266,61 +447,71 @@ found in <code>resources/pycco.html</code></p> <span class="kn">import</span> <span class="nn">sys</span> <span class="kn">from</span> <span class="nn">markdown</span> <span class="kn">import</span> <span class="n">markdown</span> <span class="kn">from</span> <span class="nn">os</span> <span class="kn">import</span> <span class="n">path</span> -<span class="kn">from</span> <span class="nn">pygments</span> <span class="kn">import</span> <span class="n">lexers</span><span class="p">,</span> <span class="n">formatters</span> -<span class="kn">from</span> <span class="nn">subprocess</span> <span class="kn">import</span> <span class="n">Popen</span><span class="p">,</span> <span class="n">PIPE</span> -<span class="kn">from</span> <span class="nn">locale</span> <span class="kn">import</span> <span class="n">getpreferredencoding</span></pre></div></pre></div> +<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-12'> + </tr><tr id='section-24'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-12">#</a> + <a class="octothorpe" href="#section-24">#</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></pre></div></pre></div> - </td> - </tr><tr id='section-13'> - <td class=docs> - <div class="octowrap"> - <a class="octothorpe" href="#section-13">#</a> - </div> - <p>".coffee": { "name": "coffee-script", "symbol": "#" },</p> - </td> - <td class=code> - <div class='highlight'><pre><div class="highlight"><pre> <span class="s">".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">".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">".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">".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">".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> + <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">"mutliend"</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-14'> + </tr><tr id='section-25'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-14">#</a> + <a class="octothorpe" href="#section-25">#</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-15'> + </tr><tr id='section-26'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-15">#</a> + <a class="octothorpe" href="#section-26">#</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-16'> + </tr><tr id='section-27'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-16">#</a> + <a class="octothorpe" href="#section-27">#</a> </div> <p>The dividing token we feed into Pygments, to delimit the boundaries between sections.</p> @@ -328,10 +519,10 @@ sections.</p> <td class=code> <div class='highlight'><pre><div class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s">"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-17'> + </tr><tr id='section-28'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-17">#</a> + <a class="octothorpe" href="#section-28">#</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> @@ -339,20 +530,20 @@ on this to recover the original sections.</p> <td class=code> <div class='highlight'><pre><div class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s">"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-18'> + </tr><tr id='section-29'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-18">#</a> + <a class="octothorpe" href="#section-29">#</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-19'> + </tr><tr id='section-30'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-19">#</a> + <a class="octothorpe" href="#section-30">#</a> </div> <p>Get the current language we're documenting, based on the extension.</p> </td> @@ -371,28 +562,30 @@ on this to recover the original sections.</p> <span class="k">else</span><span class="p">:</span> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s">"Can't figure out the language!"</span><span class="p">)</span></pre></div></pre></div> </td> - </tr><tr id='section-20'> + </tr><tr id='section-31'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-20">#</a> + <a class="octothorpe" href="#section-31">#</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">False</span><span class="p">):</span> + <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">destination</span><span class="p">(</span><span class="n">filepath</span><span class="p">,</span> <span class="n">preserve_paths</span><span class="o">=</span><span class="bp">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="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="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="s">"docs/</span><span class="si">%s</span><span class="s">.html"</span> <span class="o">%</span> <span class="n">name</span></pre></div></pre></div> + <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-21'> + </tr><tr id='section-32'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-21">#</a> + <a class="octothorpe" href="#section-32">#</a> </div> <p>Shift items off the front of the <code>list</code> until it is empty, then return <code>default</code>.</p> @@ -404,87 +597,147 @@ is <code>lib/example.py</code>, the HTML will be at <code>docs/example.html</cod <span class="k">except</span> <span class="ne">IndexError</span><span class="p">:</span> <span class="k">return</span> <span class="n">default</span></pre></div></pre></div> </td> - </tr><tr id='section-22'> + </tr><tr id='section-33'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-22">#</a> + <a class="octothorpe" href="#section-33">#</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">Popen</span><span class="p">([</span><span class="s">"mkdir"</span><span class="p">,</span> <span class="s">"-p"</span><span class="p">,</span> <span class="s">"docs"</span><span class="p">])</span><span class="o">.</span><span class="n">wait</span><span class="p">()</span> - -<span class="k">def</span> <span class="nf">template</span><span class="p">(</span><span class="n">source</span><span class="p">):</span> + <div class='highlight'><pre><div class="highlight"><pre><span class="k">def</span> <span class="nf">ensure_directory</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">mkdir</span><span class="p">(</span><span class="n">directory</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> + + </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-23'> + </tr><tr id='section-35'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-23">#</a> + <a class="octothorpe" href="#section-35">#</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-24'> + </tr><tr id='section-36'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-24">#</a> + <a class="octothorpe" href="#section-36">#</a> </div> - <p>The CSS styles we"d like to apply to the documentation.</p> + <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-25'> + </tr><tr id='section-37'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-25">#</a> + <a class="octothorpe" href="#section-37">#</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-26'> + </tr><tr id='section-38'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-26">#</a> + <a class="octothorpe" href="#section-38">#</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-27'> + </tr><tr id='section-39'> <td class=docs> <div class="octowrap"> - <a class="octothorpe" href="#section-27">#</a> + <a class="octothorpe" href="#section-39">#</a> </div> - <p>Run the script. -For each source file passed in as an argument, generate the documentation.</p> + <p>For each source file passed in as an argument, generate the documentation.</p> </td> <td class=code> - <div class='highlight'><pre><div class="highlight"><pre><span class="k">if</span> <span class="n">__name__</span> <span class="o">==</span> <span class="s">"__main__"</span><span class="p">:</span> - <span class="n">parser</span> <span class="o">=</span> <span class="n">optparse</span><span class="o">.</span><span class="n">OptionParser</span><span class="p">()</span> - <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-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> - <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> + <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> + <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">sources</span><span class="o">.</span><span class="n">sort</span><span class="p">()</span> <span class="k">if</span> <span class="n">sources</span><span class="p">:</span> - <span class="n">ensure_directory</span><span class="p">()</span> - <span class="n">css</span> <span class="o">=</span> <span class="nb">open</span><span class="p">(</span><span class="s">"docs/pycco.css"</span><span class="p">,</span> <span class="s">"w"</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> + <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-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">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> + + <span class="k">try</span><span class="p">:</span> + <span class="n">os</span><span class="o">.</span><span class="n">makedirs</span><span class="p">(</span><span class="n">path</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">dest</span><span class="p">)[</span><span class="mi">0</span><span class="p">])</span> + <span class="k">except</span> <span class="ne">OSError</span><span class="p">:</span> + <span class="k">pass</span> + + <span class="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">outdir</span><span class="o">=</span><span class="n">outdir</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">def</span> <span class="nf">next_file</span><span class="p">():</span> - <span class="n">generate_documentation</span><span class="p">(</span><span class="n">sources</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="mi">0</span><span class="p">),</span> <span class="n">options</span><span class="o">=</span><span class="n">opts</span><span class="p">)</span> <span class="k">if</span> <span class="n">sources</span><span class="p">:</span> <span class="n">next_file</span><span class="p">()</span> <span class="n">next_file</span><span class="p">()</span> +<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-41'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-41">#</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> + <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> + + <span class="n">parser</span><span class="o">.</span><span class="n">add_option</span><span class="p">(</span><span class="s">'-d'</span><span class="p">,</span> <span class="s">'--directory'</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">'outdir'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s">'docs'</span><span class="p">,</span> + <span class="n">help</span><span class="o">=</span><span class="s">'The output directory that the rendered files should go to.'</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-42'> + <td class=docs> + <div class="octowrap"> + <a class="octothorpe" href="#section-42">#</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">main</span><span class="p">()</span> + </pre></div></pre></div> </td> </tr> @@ -18,8 +18,8 @@ p { h1, h2, h3, h4, h5, h6 { margin: 40px 0 15px 0; } - h3, h4, h5, h6 { - margin-top: 20px; +h2, h3, h4, h5, h6 { + margin-top: 0; } #container { position: relative; @@ -112,8 +112,11 @@ table td { background: #f5f5ff; border-left: 1px solid #e5e5ee; } +.code pre, .docs p code { + font-size: 12px; +} pre, tt, code { - font-size: 12px; line-height: 18px; + line-height: 18px; font-family: Monaco, Consolas, "Lucida Console", monospace; margin: 0; padding: 0; } @@ -182,4 +185,4 @@ body .bp { color: #954121 } /* Name.Builtin.Pseudo */ body .vc { color: #19469D } /* Name.Variable.Class */ body .vg { color: #19469D } /* Name.Variable.Global */ body .vi { color: #19469D } /* Name.Variable.Instance */ -body .il { color: #666666 } /* Literal.Number.Integer.Long */
\ No newline at end of file +body .il { color: #666666 } /* Literal.Number.Integer.Long */ |