diff options
| author | Zach Smith <zd@zdsmith.com> | 2018-05-02 10:00:18 -0400 |
|---|---|---|
| committer | Zach Smith <zd@zdsmith.com> | 2018-05-02 10:00:18 -0400 |
| commit | ef2c72a6d69200b8bb806957cf68cd17e26504b1 (patch) | |
| tree | c36baf58b6db0aca7feb18cb66436139857d27c5 /index.html | |
| parent | 77a012aa8d197d2955ee5d18560e3fb991afc73d (diff) | |
| download | pycco-ef2c72a6d69200b8bb806957cf68cd17e26504b1.tar.gz | |
Update index
Diffstat (limited to 'index.html')
| -rw-r--r-- | index.html | 714 |
1 files changed, 376 insertions, 338 deletions
@@ -17,14 +17,61 @@ <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> + <div class='code'> + <div class="highlight"><pre><span></span><span class="kn">from</span> <span class="nn">__future__</span> <span class="kn">import</span> <span class="n">absolute_import</span><span class="p">,</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> + <p>Import our external dependencies.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="kn">import</span> <span class="nn">argparse</span> +<span class="kn">import</span> <span class="nn">os</span> +<span class="kn">import</span> <span class="nn">re</span> +<span class="kn">import</span> <span class="nn">sys</span> +<span class="kn">import</span> <span class="nn">time</span> +<span class="kn">from</span> <span class="nn">os</span> <span class="kn">import</span> <span class="n">path</span> + +<span class="kn">import</span> <span class="nn">pygments</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">pycco.generate_index</span> <span class="kn">import</span> <span class="n">generate_index</span> +<span class="kn">from</span> <span class="nn">pycco.languages</span> <span class="kn">import</span> <span class="n">supported_languages</span> +<span class="kn">from</span> <span class="nn">pycco_resources</span> <span class="kn">import</span> <span class="n">css</span> <span class="k">as</span> <span class="n">pycco_css</span></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> + <p>This module contains all of our static resources.</p> + </div> + <div class='code'> + <div class="highlight"><pre><span class="kn">from</span> <span class="nn">pycco_resources</span> <span class="kn">import</span> <span class="n">pycco_template</span> +<span class="kn">from</span> <span class="nn">pygments</span> <span class="kn">import</span> <span class="n">formatters</span><span class="p">,</span> <span class="n">lexers</span></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>“<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 -<a href="http://daringfireball.net/projects/markdown/syntax">Markdown</a> and -<a href="http://daringfireball.net/projects/smartypants">SmartyPants</a>, while code is -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> +documentation generator. It produces HTML that displays your comments alongside +your code. Comments are passed through <a href="http://daringfireball.net/projects/markdown/syntax">Markdown</a> and +<a href="https://python-markdown.github.io/extensions/footnotes/">SmartyPants</a><sup id="fnref:extensions"><a class="footnote-ref" href="#fn:extensions" rel="footnote">1</a></sup>, while code is passed through +<a href="http://pygments.org/">Pygments</a> for syntax highlighting.</p> +<p>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> <pre><code>pycco src/*.py </code></pre> @@ -40,28 +87,30 @@ and released under the MIT license.</p> cd pycco 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 class="footnote"> +<hr /> +<ol> +<li id="fn:extensions"> +<p>Three extensions to Markdown are available:</p> +<ol> +<li><a href="https://python-markdown.github.io/extensions/smarty/">SmartyPants</a></li> +<li><a href="https://python-markdown.github.io/extensions/fenced_code_blocks/">Fenced code blocks</a></li> +<li><a href="https://python-markdown.github.io/extensions/footnotes/">Footnotes</a></li> +</ol> +<p><a class="footnote-backref" href="#fnref:extensions" rev="footnote" title="Jump back to footnote 1 in the text">↩</a></p> +</li> +</ol> +</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='section' id='section-4'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-2'>#</a> + <a class='octothorpe' href='#section-4'>#</a> </div> <h3><span id="main-documentation-generation-functions" href="main-documentation-generation-functions"> Main Documentation Generation Functions </span></h3> </div> @@ -70,10 +119,10 @@ python setup.py install </div> </div> <div class='clearall'></div> - <div class='section' id='section-3'> + <div class='section' id='section-5'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-3'>#</a> + <a class='octothorpe' href='#section-5'>#</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 @@ -81,29 +130,29 @@ language, and merging them into an HTML template.</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">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> + <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="s2">"utf8"</span><span class="p">):</span></pre></div> </div> </div> <div class='clearall'></div> - <div class='section' id='section-4'> + <div class='section' id='section-6'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-4'>#</a> + <a class='octothorpe' href='#section-6'>#</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">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">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"Missing the required 'outdir' keyword argument."</span><span class="p">)</span> + <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="s2">"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='section' id='section-7'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-5'>#</a> + <a class='octothorpe' href='#section-7'>#</a> </div> <p>Helper function to allow documentation generation without file handling.</p> </div> @@ -112,25 +161,25 @@ language, and merging them into an HTML template.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-6'> + <div class='section' id='section-8'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-6'>#</a> + <a class='octothorpe' href='#section-8'>#</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> + <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_name</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='section' id='section-9'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-7'>#</a> + <a class='octothorpe' href='#section-9'>#</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. @@ -148,33 +197,33 @@ Sections take the form:</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-8'> + <div class='section' id='section-10'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-8'>#</a> + <a class='octothorpe' href='#section-10'>#</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> + <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="s2">"</span><span class="se">\n</span><span class="s2">"</span><span class="p">)</span> <span class="n">sections</span> <span class="o">=</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">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="s2">""</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> + <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="s2">"#!"</span><span class="p">):</span> <span class="n">lines</span><span class="o">.</span><span class="n">pop</span><span class="p">(</span><span class="mi">0</span><span class="p">)</span> - <span class="k">if</span> <span class="n">language</span><span class="p">[</span><span class="s">"name"</span><span class="p">]</span> <span class="o">==</span> <span class="s">"python"</span><span class="p">:</span> + <span class="k">if</span> <span class="n">language</span><span class="p">[</span><span class="s2">"name"</span><span class="p">]</span> <span class="o">==</span> <span class="s2">"python"</span><span class="p">:</span> <span class="k">for</span> <span class="n">linenum</span><span class="p">,</span> <span class="n">line</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">lines</span><span class="p">[:</span><span class="mi">2</span><span class="p">]):</span> - <span class="k">if</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="s">r'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="k">if</span> <span class="n">re</span><span class="o">.</span><span class="n">search</span><span class="p">(</span><span class="sa">r</span><span class="s1">'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> </div> </div> <div class='clearall'></div> - <div class='section' id='section-9'> + <div class='section' id='section-11'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-9'>#</a> + <a class='octothorpe' href='#section-11'>#</a> </div> </div> @@ -182,34 +231,34 @@ Sections take the form:</p> <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="s2">"docs_text"</span><span class="p">:</span> <span class="n">docs</span><span class="p">,</span> + <span class="s2">"code_text"</span><span class="p">:</span> <span class="n">code</span> <span class="p">})</span></pre></div> </div> </div> <div class='clearall'></div> - <div class='section' id='section-10'> + <div class='section' id='section-12'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-10'>#</a> + <a class='octothorpe' href='#section-12'>#</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="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="s2">"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="s2">"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="s1">'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='section' id='section-13'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-11'>#</a> + <a class='octothorpe' href='#section-13'>#</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> @@ -240,60 +289,60 @@ found to be at the start of a line</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-12'> + <div class='section' id='section-14'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-12'>#</a> + <a class='octothorpe' href='#section-14'>#</a> </div> - <p>Get rid of the delimiters so that they aren't in the final + <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> + <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="s1">''</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="s1">''</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="s1">'</span><span class="se">\n</span><span class="s1">'</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="sa">r</span><span class="s2">"\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="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="s1">'</span><span class="se">\n</span><span class="s1">'</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="s1">''</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='section' id='section-15'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-13'>#</a> + <a class='octothorpe' href='#section-15'>#</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> + <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="sa">r</span><span class="s1">' {{{: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="s1">'</span><span class="se">\n</span><span class="s1">'</span> <span class="k">else</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="n">docs_text</span> <span class="o">+=</span> <span class="n">line</span> <span class="o">+</span> <span class="s1">'</span><span class="se">\n</span><span class="s1">'</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">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">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="s1">''</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="s2">""</span><span class="p">,</span> <span class="n">line</span><span class="p">)</span> <span class="o">+</span> <span class="s2">"</span><span class="se">\n</span><span class="s2">"</span> <span class="k">else</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="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="p">[</span><span class="s1">'class '</span><span class="p">,</span> <span class="s1">'def '</span><span class="p">,</span> <span class="s1">'@'</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="s2">"@"</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">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="s1">''</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">code_text</span> <span class="o">+=</span> <span class="n">line</span> <span class="o">+</span> <span class="s1">'</span><span class="se">\n</span><span class="s1">'</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> @@ -301,10 +350,10 @@ docs</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-14'> + <div class='section' id='section-16'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-14'>#</a> + <a class='octothorpe' href='#section-16'>#</a> </div> <h3><span id="preprocessing-the-comments" href="preprocessing-the-comments"> Preprocessing the comments </span></h3> </div> @@ -313,17 +362,18 @@ docs</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-15'> + <div class='section' id='section-17'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-15'>#</a> + <a class='octothorpe' href='#section-17'>#</a> </div> - <p>Add cross-references before having the text processed by markdown. It's + <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">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: +declared; they are written on a single line, and surrounded by equals +signs: <code>=== like this ===</code></p> </div> <div class='code'> @@ -331,36 +381,36 @@ declared; they are written on a single line, and surrounded by equals signs: </div> </div> <div class='clearall'></div> - <div class='section' id='section-16'> + <div class='section' id='section-18'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-16'>#</a> + <a class='octothorpe' href='#section-18'>#</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> + <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"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='section' id='section-19'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-17'>#</a> + <a class='octothorpe' href='#section-19'>#</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> + <span class="k">return</span> <span class="s2">"-"</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="s2">" "</span><span class="p">))</span></pre></div> </div> </div> <div class='clearall'></div> - <div class='section' id='section-18'> + <div class='section' id='section-20'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-18'>#</a> + <a class='octothorpe' href='#section-20'>#</a> </div> </div> @@ -369,34 +419,34 @@ declared; they are written on a single line, and surrounded by equals signs: </div> </div> <div class='clearall'></div> - <div class='section' id='section-19'> + <div class='section' id='section-21'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-19'>#</a> + <a class='octothorpe' href='#section-21'>#</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="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">name</span><span class="p">,</span> + <div class="highlight"><pre> <span class="k">if</span> <span class="s1">'#'</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="s1">'#'</span><span class="p">)</span> + <span class="k">return</span> <span class="s2">" [{}]({}#{})"</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="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="k">return</span> <span class="s2">" [{}]({})"</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='section' id='section-22'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-20'>#</a> + <a class='octothorpe' href='#section-22'>#</a> </div> <p>Replace equals-sign-formatted section names with anchor links.</p> </div> @@ -405,31 +455,31 @@ declared; they are written on a single line, and surrounded by equals signs: </div> </div> <div class='clearall'></div> - <div class='section' id='section-21'> + <div class='section' id='section-23'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-21'>#</a> + <a class='octothorpe' href='#section-23'>#</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> + <div class="highlight"><pre> <span class="k">return</span> <span class="s1">'{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="s1">'='</span><span class="p">,</span> <span class="s1">'#'</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="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="sa">r</span><span class="s1">'^([=]+)([^=]+)[=]*\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="sa">r</span><span class="s1">'(?<!`)\[\[(.+?)\]\]'</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='section' id='section-24'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-22'>#</a> + <a class='octothorpe' href='#section-24'>#</a> </div> <h3><span id="highlighting-the-source-code" href="highlighting-the-source-code"> Highlighting the source code </span></h3> </div> @@ -438,10 +488,10 @@ declared; they are written on a single line, and surrounded by equals signs: </div> </div> <div class='clearall'></div> - <div class='section' id='section-23'> + <div class='section' id='section-25'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-23'>#</a> + <a class='octothorpe' href='#section-25'>#</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> @@ -454,44 +504,65 @@ wherever our markers occur.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-24'> + <div class='section' id='section-26'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-24'>#</a> + <a class='octothorpe' href='#section-26'>#</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="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"Missing the required 'outdir' keyword argument."</span><span class="p">)</span> + + <span class="n">divider_text</span> <span class="o">=</span> <span class="n">language</span><span class="p">[</span><span class="s2">"divider_text"</span><span class="p">]</span> + <span class="n">lexer</span> <span class="o">=</span> <span class="n">language</span><span class="p">[</span><span class="s2">"lexer"</span><span class="p">]</span> + <span class="n">divider_html</span> <span class="o">=</span> <span class="n">language</span><span class="p">[</span><span class="s2">"divider_html"</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> - <span class="n">formatters</span><span class="o">.</span><span class="n">get_formatter_by_name</span><span class="p">(</span><span class="s">"html"</span><span class="p">))</span> + <span class="n">joined_text</span> <span class="o">=</span> <span class="n">divider_text</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="s2">"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">html_formatter</span> <span class="o">=</span> <span class="n">formatters</span><span class="o">.</span><span class="n">get_formatter_by_name</span><span class="p">(</span><span class="s2">"html"</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">joined_text</span><span class="p">,</span> <span class="n">lexer</span><span class="p">,</span> <span class="n">html_formatter</span> + <span class="p">)</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span> + <span class="n">highlight_start</span><span class="p">,</span> <span class="s2">""</span> + <span class="p">)</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span> + <span class="n">highlight_end</span><span class="p">,</span> <span class="s2">""</span> + <span class="p">)</span> + <span class="n">fragments</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">divider_html</span><span class="p">,</span> <span class="n">output</span><span class="p">)</span> - <span class="n">output</span> <span class="o">=</span> <span class="n">output</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">highlight_start</span><span class="p">,</span> <span class="s">""</span><span class="p">)</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">highlight_end</span><span class="p">,</span> <span class="s">""</span><span class="p">)</span> - <span class="n">fragments</span> <span class="o">=</span> <span class="n">re</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="n">language</span><span class="p">[</span><span class="s">"divider_html"</span><span class="p">],</span> <span class="n">output</span><span class="p">)</span> <span class="k">for</span> <span class="n">i</span><span class="p">,</span> <span class="n">section</span> <span class="ow">in</span> <span class="nb">enumerate</span><span class="p">(</span><span class="n">sections</span><span class="p">):</span> - <span class="n">section</span><span class="p">[</span><span class="s">"code_html"</span><span class="p">]</span> <span class="o">=</span> <span class="n">highlight_start</span> <span class="o">+</span> <span class="n">shift</span><span class="p">(</span><span class="n">fragments</span><span class="p">,</span> <span class="s">""</span><span class="p">)</span> <span class="o">+</span> <span class="n">highlight_end</span> + <span class="n">section</span><span class="p">[</span><span class="s2">"code_html"</span><span class="p">]</span> <span class="o">=</span> <span class="n">highlight_start</span> <span class="o">+</span> <span class="n">shift</span><span class="p">(</span><span class="n">fragments</span><span class="p">,</span> <span class="s2">""</span><span class="p">)</span> <span class="o">+</span> <span class="n">highlight_end</span> <span class="k">try</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="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="s2">"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">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="s2">"docs_text"</span><span class="p">]</span><span class="o">.</span><span class="n">decode</span><span class="p">(</span><span class="s1">'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">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> + <span class="n">docs_text</span> <span class="o">=</span> <span class="n">section</span><span class="p">[</span><span class="s1">'docs_text'</span><span class="p">]</span> + <span class="n">section</span><span class="p">[</span><span class="s2">"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">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">extensions</span><span class="o">=</span><span class="p">[</span> + <span class="s1">'markdown.extensions.smarty'</span><span class="p">,</span> + <span class="s1">'markdown.extensions.fenced_code'</span><span class="p">,</span> + <span class="s1">'markdown.extensions.footnotes'</span><span class="p">,</span> + <span class="p">]</span> + <span class="p">)</span> + <span class="n">section</span><span class="p">[</span><span class="s2">"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='section' id='section-27'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-25'>#</a> + <a class='octothorpe' href='#section-27'>#</a> </div> <h3><span id="html-code-generation" href="html-code-generation"> HTML Code generation </span></h3> </div> @@ -500,17 +571,17 @@ wherever our markers occur.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-26'> + <div class='section' id='section-28'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-26'>#</a> + <a class='octothorpe' href='#section-28'>#</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 + <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 +“unique enough” identifier before rendering, and then post-process the rendered template and change the identifier back to <code>{{</code>.</p> </div> <div class='code'> @@ -518,57 +589,32 @@ rendered template and change the identifier back to <code>{{</code>.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-27'> + <div class='section' id='section-29'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-27'>#</a> + <a class='octothorpe' href='#section-29'>#</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="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"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> - <span class="n">csspath</span> <span class="o">=</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">outdir</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="n">csspath</span> <span class="o">=</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">outdir</span><span class="p">,</span> <span class="s2">"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="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">sect</span><span class="p">[</span><span class="s2">"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="sa">r</span><span class="s2">"\{\{"</span><span class="p">,</span> <span class="sa">r</span><span class="s2">"{{"</span><span class="p">,</span> <span class="n">sect</span><span class="p">[</span><span class="s2">"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="s2">"title"</span><span class="p">:</span> <span class="n">title</span><span class="p">,</span> + <span class="s2">"stylesheet"</span><span class="p">:</span> <span class="n">csspath</span><span class="p">,</span> + <span class="s2">"sections"</span><span class="p">:</span> <span class="n">sections</span><span class="p">,</span> + <span class="s2">"source"</span><span class="p">:</span> <span class="n">source</span><span class="p">,</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> - </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> + <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="sa">r</span><span class="s2">"{{"</span><span class="p">,</span> <span class="s2">"{{"</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="s2">"utf-8"</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> @@ -577,19 +623,10 @@ rendered template and change the identifier back to <code>{{</code>.</p> <div class='octowrap'> <a class='octothorpe' href='#section-30'>#</a> </div> - <p>Import our external dependencies.</p> + <h3><span id="helpers-&-setup" href="helpers-&-setup"> Helpers & Setup </span></h3> </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> -<span class="kn">import</span> <span class="nn">re</span> -<span class="kn">import</span> <span class="nn">sys</span> -<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> + <div class="highlight"><pre></pre></div> </div> </div> <div class='clearall'></div> @@ -598,46 +635,10 @@ rendered template and change the identifier back to <code>{{</code>.</p> <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> + <p>Build out the appropriate matchers and delimiters for each language.</p> </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 class="highlight"><pre><span class="k">def</span> <span class="nf">compile_language</span><span class="p">(</span><span class="n">l</span><span class="p">):</span></pre></div> </div> </div> <div class='clearall'></div> @@ -646,10 +647,11 @@ add another language to Pycco's repertoire, add it here.</p> <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 class="highlight"><pre> <span class="n">language_name</span> <span class="o">=</span> <span class="n">l</span><span class="p">[</span><span class="s2">"name"</span><span class="p">]</span> + <span class="n">comment_symbol</span> <span class="o">=</span> <span class="n">l</span><span class="p">[</span><span class="s2">"comment_symbol"</span><span class="p">]</span></pre></div> </div> </div> <div class='clearall'></div> @@ -661,7 +663,7 @@ add another language to Pycco's repertoire, add it here.</p> <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 class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s2">"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="sa">r</span><span class="s2">"^\s*{}\s?"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">comment_symbol</span><span class="p">))</span></pre></div> </div> </div> <div class='clearall'></div> @@ -674,7 +676,7 @@ add another language to Pycco's repertoire, add it here.</p> sections.</p> </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 class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s2">"divider_text"</span><span class="p">]</span> <span class="o">=</span> <span class="s2">"</span><span class="se">\n</span><span class="s2">{}DIVIDER</span><span class="se">\n</span><span class="s2">"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">comment_symbol</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> @@ -687,7 +689,9 @@ sections.</p> on this to recover the original sections.</p> </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 class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s2">"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="sa">r</span><span class="s1">'\n*<span class="c[1]?">{}DIVIDER</span>\n*'</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">comment_symbol</span><span class="p">)</span> + <span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> @@ -699,7 +703,11 @@ on this to recover the original sections.</p> <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 class="highlight"><pre> <span class="n">l</span><span class="p">[</span><span class="s2">"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">language_name</span><span class="p">)</span> + + +<span class="k">for</span> <span class="n">entry</span> <span class="ow">in</span> <span class="n">supported_languages</span><span class="o">.</span><span class="n">values</span><span class="p">():</span> + <span class="n">compile_language</span><span class="p">(</span><span class="n">entry</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> @@ -708,10 +716,10 @@ on this to recover the original sections.</p> <div class='octowrap'> <a class='octothorpe' href='#section-37'>#</a> </div> - <p>Get the current language we're documenting, based on the extension.</p> + <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 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_name</span><span class="o">=</span><span class="bp">None</span><span class="p">):</span></pre></div> </div> </div> <div class='clearall'></div> @@ -723,25 +731,26 @@ on this to recover the original sections.</p> </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">language</span><span class="p">:</span> - <span class="k">return</span> <span class="n">l</span> + <div class="highlight"><pre> <span class="k">if</span> <span class="n">language_name</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">entry</span> <span class="ow">in</span> <span class="n">supported_languages</span><span class="o">.</span><span class="n">values</span><span class="p">():</span> + <span class="k">if</span> <span class="n">entry</span><span class="p">[</span><span class="s2">"name"</span><span class="p">]</span> <span class="o">==</span> <span class="n">language_name</span><span class="p">:</span> + <span class="k">return</span> <span class="n">entry</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">"Unknown forced language: "</span> <span class="o">+</span> <span class="n">language</span><span class="p">)</span> + <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"Unknown forced language: {}"</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">language_name</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> + <span class="k">if</span> <span class="n">source</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="sa">r</span><span class="s1">'.*(\..+)'</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">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">supported_languages</span><span class="p">:</span> + <span class="k">return</span> <span class="n">supported_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">try</span><span class="p">:</span> + <span class="n">language_name</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">entry</span> <span class="ow">in</span> <span class="n">supported_languages</span><span class="o">.</span><span class="n">values</span><span class="p">():</span> + <span class="k">if</span> <span class="n">entry</span><span class="p">[</span><span class="s2">"name"</span><span class="p">]</span> <span class="o">==</span> <span class="n">language_name</span><span class="p">:</span> + <span class="k">return</span> <span class="n">entry</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> @@ -750,12 +759,12 @@ on this to recover the original sections.</p> <div class='octowrap'> <a class='octothorpe' href='#section-39'>#</a> </div> - <p>If pygments can't find any lexers, it will raise its own + <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 class="highlight"><pre> <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"Can't figure out the language!"</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> @@ -765,7 +774,7 @@ for consistency.</p> <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> +source is <code>lib/example.py</code>, the HTML will be at <code>docs/example.html</code>.</p> </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> @@ -782,14 +791,14 @@ source is <code>lib/example.py</code>, the HTML will be at <code>docs/example.ht <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">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"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">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="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="sa">r</span><span class="s2">"\.[^.]*$"</span><span class="p">,</span> <span class="s2">""</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">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> + <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="sa">u</span><span class="s2">"{}.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> @@ -859,9 +868,10 @@ http://stackoverflow.com/questions/92438/stripping-non-printable-characters-from </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> + <span class="n">control_chars</span> <span class="o">=</span> <span class="s1">''</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="sa">u</span><span class="s1">'[{}]'</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="s1">''</span><span class="p">,</span> <span class="n">s</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> @@ -898,11 +908,10 @@ http://stackoverflow.com/questions/92438/stripping-non-printable-characters-from <div class='octowrap'> <a class='octothorpe' href='#section-49'>#</a> </div> - + <p>The start of each Pygments highlight block.</p> </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 class="highlight"><pre><span class="n">highlight_start</span> <span class="o">=</span> <span class="s2">"<div class=</span><span class="se">\"</span><span class="s2">highlight</span><span class="se">\"</span><span class="s2">><pre>"</span></pre></div> </div> </div> <div class='clearall'></div> @@ -911,10 +920,10 @@ http://stackoverflow.com/questions/92438/stripping-non-printable-characters-from <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> + <p>The end of each Pygments highlight block.</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 class="highlight"><pre><span class="n">highlight_end</span> <span class="o">=</span> <span class="s2">"</pre></div>"</span></pre></div> </div> </div> <div class='clearall'></div> @@ -923,10 +932,11 @@ http://stackoverflow.com/questions/92438/stripping-non-printable-characters-from <div class='octowrap'> <a class='octothorpe' href='#section-51'>#</a> </div> - <p>The CSS styles we'd like to apply to the documentation.</p> + <p>This function will iterate through the list of sources and if a directory +is encountered it will walk the tree for any files.</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 class="highlight"><pre><span class="k">def</span> <span class="nf">_flatten_sources</span><span class="p">(</span><span class="n">sources</span><span class="p">):</span></pre></div> </div> </div> <div class='clearall'></div> @@ -935,10 +945,19 @@ http://stackoverflow.com/questions/92438/stripping-non-printable-characters-from <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 class="highlight"><pre> <span class="n">_sources</span> <span class="o">=</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">if</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">source</span><span class="p">):</span> + <span class="k">for</span> <span class="n">dirpath</span><span class="p">,</span> <span class="n">_</span><span class="p">,</span> <span class="n">filenames</span> <span class="ow">in</span> <span class="n">os</span><span class="o">.</span><span class="n">walk</span><span class="p">(</span><span class="n">source</span><span class="p">):</span> + <span class="n">_sources</span><span class="o">.</span><span class="n">extend</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">join</span><span class="p">(</span><span class="n">dirpath</span><span class="p">,</span> <span class="n">f</span><span class="p">)</span> <span class="k">for</span> <span class="n">f</span> <span class="ow">in</span> <span class="n">filenames</span><span class="p">])</span> + <span class="k">else</span><span class="p">:</span> + <span class="n">_sources</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">source</span><span class="p">)</span> + + <span class="k">return</span> <span class="n">_sources</span></pre></div> </div> </div> <div class='clearall'></div> @@ -947,10 +966,11 @@ http://stackoverflow.com/questions/92438/stripping-non-printable-characters-from <div class='octowrap'> <a class='octothorpe' href='#section-53'>#</a> </div> - <p>The end of each Pygments highlight block.</p> + <p>For each source file passed as argument, generate the documentation.</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 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="s2">"utf8"</span><span class="p">,</span> <span class="n">index</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span> <span class="n">skip</span><span class="o">=</span><span class="bp">False</span><span class="p">):</span></pre></div> </div> </div> <div class='clearall'></div> @@ -959,59 +979,49 @@ http://stackoverflow.com/questions/92438/stripping-non-printable-characters-from <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> + <span class="k">raise</span> <span class="ne">TypeError</span><span class="p">(</span><span class="s2">"Missing the required 'directory' keyword argument."</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> - <div class='section' id='section-56'> + <div class='section' id='section-55'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-56'>#</a> + <a class='octothorpe' href='#section-55'>#</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> </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 class="highlight"><pre> <span class="n">sources</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">_flatten_sources</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='section' id='section-56'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-57'>#</a> + <a class='octothorpe' href='#section-56'>#</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> + <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="s2">"pycco.css"</span><span class="p">),</span> <span class="s2">"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_css</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> + + <span class="n">generated_files</span> <span class="o">=</span> <span class="p">[]</span></pre></div> </div> </div> <div class='clearall'></div> - <div class='section' id='section-58'> + <div class='section' id='section-57'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-58'>#</a> + <a class='octothorpe' href='#section-57'>#</a> </div> </div> @@ -1025,26 +1035,38 @@ 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">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">try</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="s2">"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="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">print</span><span class="p">(</span><span class="s2">"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="n">generated_files</span><span class="o">.</span><span class="n">append</span><span class="p">(</span><span class="n">dest</span><span class="p">)</span> + <span class="k">except</span> <span class="p">(</span><span class="ne">ValueError</span><span class="p">,</span> <span class="ne">UnicodeDecodeError</span><span class="p">)</span> <span class="k">as</span> <span class="n">e</span><span class="p">:</span> + <span class="k">if</span> <span class="n">skip</span><span class="p">:</span> + <span class="k">print</span><span class="p">(</span><span class="s2">"pycco [FAILURE]: {}, {}"</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">e</span><span class="p">))</span> + <span class="k">else</span><span class="p">:</span> + <span class="k">raise</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> + <span class="k">if</span> <span class="n">index</span><span class="p">:</span> + <span class="k">with</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="s2">"index.html"</span><span class="p">),</span> <span class="s2">"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_index</span><span class="p">(</span><span class="n">generated_files</span><span class="p">,</span> <span class="n">outdir</span><span class="p">))</span> + + +<span class="n">__all__</span> <span class="o">=</span> <span class="p">(</span><span class="s2">"process"</span><span class="p">,</span> <span class="s2">"generate_documentation"</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> - <div class='section' id='section-59'> + <div class='section' id='section-58'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-59'>#</a> + <a class='octothorpe' href='#section-58'>#</a> </div> <p>Monitor each source file and re-generate documentation on change.</p> </div> @@ -1053,10 +1075,10 @@ original list when monitoring for changed files.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-60'> + <div class='section' id='section-59'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-60'>#</a> + <a class='octothorpe' href='#section-59'>#</a> </div> </div> @@ -1065,10 +1087,10 @@ original list when monitoring for changed files.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-61'> + <div class='section' id='section-60'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-61'>#</a> + <a class='octothorpe' href='#section-60'>#</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> @@ -1079,10 +1101,10 @@ here to bring them into the local namespace.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-62'> + <div class='section' id='section-61'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-62'>#</a> + <a class='octothorpe' href='#section-61'>#</a> </div> <p>Watchdog operates on absolute paths, so map those to original paths as specified on the command line.</p> @@ -1093,22 +1115,22 @@ as specified on the command line.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-63'> + <div class='section' id='section-62'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-63'>#</a> + <a class='octothorpe' href='#section-62'>#</a> </div> - <p>A handler for recompiling files which triggered watchdog events</p> + <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='section' id='section-63'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-64'>#</a> + <a class='octothorpe' href='#section-63'>#</a> </div> </div> @@ -1117,22 +1139,22 @@ as specified on the command line.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-65'> + <div class='section' id='section-64'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-65'>#</a> + <a class='octothorpe' href='#section-64'>#</a> </div> - <p>Regenerate documentation for a file which triggered an event</p> + <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='section' id='section-65'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-66'>#</a> + <a class='octothorpe' href='#section-65'>#</a> </div> <p>Re-generate documentation from a source file if it was listed on the command line. Watchdog monitors whole directories, so other @@ -1146,10 +1168,10 @@ files may cause notifications as well.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-67'> + <div class='section' id='section-66'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-67'>#</a> + <a class='octothorpe' href='#section-66'>#</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> @@ -1163,10 +1185,10 @@ the command line and notifies the handler defined above.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-68'> + <div class='section' id='section-67'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-68'>#</a> + <a class='octothorpe' href='#section-67'>#</a> </div> <p>Run the file change monitoring loop until the user hits Ctrl-C.</p> </div> @@ -1181,10 +1203,10 @@ the command line and notifies the handler defined above.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-69'> + <div class='section' id='section-68'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-69'>#</a> + <a class='octothorpe' href='#section-68'>#</a> </div> <p>Hook spot for the console script.</p> </div> @@ -1193,65 +1215,81 @@ the command line and notifies the handler defined above.</p> </div> </div> <div class='clearall'></div> - <div class='section' id='section-70'> + <div class='section' id='section-69'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-70'>#</a> + <a class='octothorpe' href='#section-69'>#</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> + <div class="highlight"><pre> <span class="n">parser</span> <span class="o">=</span> <span class="n">argparse</span><span class="o">.</span><span class="n">ArgumentParser</span><span class="p">()</span> + <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-p'</span><span class="p">,</span> <span class="s1">'--paths'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">,</span> + <span class="n">help</span><span class="o">=</span><span class="s1">'Preserve path structure of original files'</span><span class="p">)</span> + + <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-d'</span><span class="p">,</span> <span class="s1">'--directory'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">str</span><span class="p">,</span> + <span class="n">dest</span><span class="o">=</span><span class="s1">'outdir'</span><span class="p">,</span> <span class="n">default</span><span class="o">=</span><span class="s1">'docs'</span><span class="p">,</span> + <span class="n">help</span><span class="o">=</span><span class="s1">'The output directory that the rendered files should go to.'</span><span class="p">)</span> + + <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-w'</span><span class="p">,</span> <span class="s1">'--watch'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">,</span> + <span class="n">help</span><span class="o">=</span><span class="s1">'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">'-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">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-l'</span><span class="p">,</span> <span class="s1">'--force-language'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store'</span><span class="p">,</span> <span class="nb">type</span><span class="o">=</span><span class="nb">str</span><span class="p">,</span> + <span class="n">dest</span><span class="o">=</span><span class="s1">'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="s1">'Force the language for the given 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">'-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_argument</span><span class="p">(</span><span class="s1">'-i'</span><span class="p">,</span> <span class="s1">'--generate_index'</span><span class="p">,</span> <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">,</span> + <span class="n">help</span><span class="o">=</span><span class="s1">'Generate an index.html document with sitemap content'</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">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'-s'</span><span class="p">,</span> <span class="s1">'--skip-bad-files'</span><span class="p">,</span> <span class="s1">'-e'</span><span class="p">,</span> <span class="s1">'--ignore-errors'</span><span class="p">,</span> + <span class="n">action</span><span class="o">=</span><span class="s1">'store_true'</span><span class="p">,</span> + <span class="n">dest</span><span class="o">=</span><span class="s1">'skip_bad_files'</span><span class="p">,</span> + <span class="n">help</span><span class="o">=</span><span class="s1">'Continue processing after hitting a bad file'</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> - <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> + <span class="n">parser</span><span class="o">.</span><span class="n">add_argument</span><span class="p">(</span><span class="s1">'sources'</span><span class="p">,</span> <span class="n">nargs</span><span class="o">=</span><span class="s1">'*'</span><span class="p">)</span> + + <span class="n">args</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="k">if</span> <span class="n">args</span><span class="o">.</span><span class="n">outdir</span> <span class="o">==</span> <span class="s1">''</span><span class="p">:</span> + <span class="n">outdir</span> <span class="o">=</span> <span class="s1">'.'</span> + <span class="k">else</span><span class="p">:</span> + <span class="n">outdir</span> <span class="o">=</span> <span class="n">args</span><span class="o">.</span><span class="n">outdir</span> + + <span class="n">process</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">sources</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">preserve_paths</span><span class="o">=</span><span class="n">args</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">args</span><span class="o">.</span><span class="n">language</span><span class="p">,</span> <span class="n">index</span><span class="o">=</span><span class="n">args</span><span class="o">.</span><span class="n">generate_index</span><span class="p">,</span> + <span class="n">skip</span><span class="o">=</span><span class="n">args</span><span class="o">.</span><span class="n">skip_bad_files</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> - <div class='section' id='section-71'> + <div class='section' id='section-70'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-71'>#</a> + <a class='octothorpe' href='#section-70'>#</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> </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> + <div class="highlight"><pre> <span class="k">if</span> <span class="n">args</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="kn">import</span> <span class="nn">watchdog.observers</span> <span class="c1"># noqa</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">sys</span><span class="o">.</span><span class="n">exit</span><span class="p">(</span><span class="s1">'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> + <span class="n">monitor</span><span class="p">(</span><span class="n">args</span><span class="o">.</span><span class="n">sources</span><span class="p">,</span> <span class="n">args</span><span class="p">)</span></pre></div> </div> </div> <div class='clearall'></div> - <div class='section' id='section-72'> + <div class='section' id='section-71'> <div class='docs'> <div class='octowrap'> - <a class='octothorpe' href='#section-72'>#</a> + <a class='octothorpe' href='#section-71'>#</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> + <div class="highlight"><pre><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span> <span class="n">main</span><span class="p">()</span> </pre></div> |