<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Showing code examples — Sphinx v1.0.7 documentation</title>
<link rel="stylesheet" href="../_static/sphinxdoc.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '1.0.7',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<link rel="search" type="application/opensearchdescription+xml"
title="Search within Sphinx v1.0.7 documentation"
href="../_static/opensearch.xml"/>
<link rel="top" title="Sphinx v1.0.7 documentation" href="../index.html" />
<link rel="up" title="Sphinx Markup Constructs" href="index.html" />
<link rel="next" title="Inline markup" href="inline.html" />
<link rel="prev" title="Paragraph-level markup" href="para.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head>
<body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<img src="../_static/sphinx.png" alt="Sphinx logo" />
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="inline.html" title="Inline markup"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="para.html" title="Paragraph-level markup"
accesskey="P">previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="index.html" accesskey="U">Sphinx Markup Constructs</a> »</li>
</ul>
</div>
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Showing code examples</a><ul>
<li><a class="reference internal" href="#line-numbers">Line numbers</a></li>
<li><a class="reference internal" href="#includes">Includes</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="para.html"
title="previous chapter">Paragraph-level markup</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="inline.html"
title="next chapter">Inline markup</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../_sources/markup/code.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../search.html" method="get">
<input type="text" name="q" size="18" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body">
<div class="section" id="showing-code-examples">
<span id="code-examples"></span><h1>Showing code examples<a class="headerlink" href="#showing-code-examples" title="Permalink to this headline">¶</a></h1>
<p id="index-0">Examples of Python source code or interactive sessions are represented using
standard reST literal blocks. They are started by a <tt class="docutils literal"><span class="pre">::</span></tt> at the end of the
preceding paragraph and delimited by indentation.</p>
<p>Representing an interactive session requires including the prompts and output
along with the Python code. No special markup is required for interactive
sessions. After the last line of input or output presented, there should not be
an “unused” primary prompt; this is an example of what <em>not</em> to do:</p>
<div class="highlight-rest"><pre>>>> 1 + 1
2
>>></pre>
</div>
<p>Syntax highlighting is done with <a class="reference external" href="http://pygments.org">Pygments</a> (if it’s
installed) and handled in a smart way:</p>
<ul>
<li><p class="first">There is a “highlighting language” for each source file. Per default, this is
<tt class="docutils literal"><span class="pre">'python'</span></tt> as the majority of files will have to highlight Python snippets,
but the doc-wide default can be set with the <a class="reference internal" href="../config.html#confval-highlight_language"><tt class="xref std std-confval docutils literal"><span class="pre">highlight_language</span></tt></a>
config value.</p>
</li>
<li><p class="first">Within Python highlighting mode, interactive sessions are recognized
automatically and highlighted appropriately. Normal Python code is only
highlighted if it is parseable (so you can use Python as the default, but
interspersed snippets of shell commands or other code blocks will not be
highlighted as Python).</p>
</li>
<li><p class="first">The highlighting language can be changed using the <tt class="docutils literal"><span class="pre">highlight</span></tt> directive,
used as follows:</p>
<div class="highlight-rest"><pre>.. highlight:: c</pre>
</div>
<p>This language is used until the next <tt class="docutils literal"><span class="pre">highlight</span></tt> directive is encountered.</p>
</li>
<li><p class="first">For documents that have to show snippets in different languages, there’s also
a <tt class="xref rst rst-dir docutils literal"><span class="pre">code-block</span></tt> directive that is given the highlighting language
directly:</p>
<div class="highlight-rest"><pre>.. code-block:: ruby
Some Ruby code.</pre>
</div>
<p>The directive’s alias name <tt class="xref rst rst-dir docutils literal"><span class="pre">sourcecode</span></tt> works as well.</p>
</li>
<li><p class="first">The valid values for the highlighting language are:</p>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">none</span></tt> (no highlighting)</li>
<li><tt class="docutils literal"><span class="pre">python</span></tt> (the default when <a class="reference internal" href="../config.html#confval-highlight_language"><tt class="xref std std-confval docutils literal"><span class="pre">highlight_language</span></tt></a> isn’t set)</li>
<li><tt class="docutils literal"><span class="pre">guess</span></tt> (let Pygments guess the lexer based on contents, only works with
certain well-recognizable languages)</li>
<li><tt class="docutils literal"><span class="pre">rest</span></tt></li>
<li><tt class="docutils literal"><span class="pre">c</span></tt></li>
<li>... and any other lexer name that Pygments supports.</li>
</ul>
</li>
<li><p class="first">If highlighting with the selected language fails, the block is not highlighted
in any way.</p>
</li>
</ul>
<div class="section" id="line-numbers">
<h2>Line numbers<a class="headerlink" href="#line-numbers" title="Permalink to this headline">¶</a></h2>
<p>If installed, Pygments can generate line numbers for code blocks. For
automatically-highlighted blocks (those started by <tt class="docutils literal"><span class="pre">::</span></tt>), line numbers must be
switched on in a <tt class="xref rst rst-dir docutils literal"><span class="pre">highlight</span></tt> directive, with the <tt class="docutils literal"><span class="pre">linenothreshold</span></tt>
option:</p>
<div class="highlight-rest"><pre>.. highlight:: python
:linenothreshold: 5</pre>
</div>
<p>This will produce line numbers for all code blocks longer than five lines.</p>
<p>For <tt class="xref rst rst-dir docutils literal"><span class="pre">code-block</span></tt> blocks, a <tt class="docutils literal"><span class="pre">linenos</span></tt> flag option can be given to switch
on line numbers for the individual block:</p>
<div class="highlight-rest"><pre>.. code-block:: ruby
:linenos:
Some more Ruby code.</pre>
</div>
</div>
<div class="section" id="includes">
<h2>Includes<a class="headerlink" href="#includes" title="Permalink to this headline">¶</a></h2>
<dl class="directive">
<dt id="directive-literalinclude">
<tt class="descname">.. literalinclude::</tt><tt class="descclassname"> filename</tt><a class="headerlink" href="#directive-literalinclude" title="Permalink to this definition">¶</a></dt>
<dd><p>Longer displays of verbatim text may be included by storing the example text in
an external file containing only plain text. The file may be included using the
<tt class="docutils literal"><span class="pre">literalinclude</span></tt> directive. <a class="footnote-reference" href="#id2" id="id1">[1]</a> For example, to include the Python source file
<tt class="file docutils literal"><span class="pre">example.py</span></tt>, use:</p>
<div class="highlight-rest"><pre>.. literalinclude:: example.py</pre>
</div>
<p>The file name is usually relative to the current file’s path. However, if it
is absolute (starting with <tt class="docutils literal"><span class="pre">/</span></tt>), it is relative to the top source
directory.</p>
<p>Tabs in the input are expanded if you give a <tt class="docutils literal"><span class="pre">tab-width</span></tt> option with the
desired tab width.</p>
<p>The directive also supports the <tt class="docutils literal"><span class="pre">linenos</span></tt> flag option to switch on line
numbers, and a <tt class="docutils literal"><span class="pre">language</span></tt> option to select a language different from the
current file’s standard language. Example with options:</p>
<div class="highlight-rest"><pre>.. literalinclude:: example.rb
:language: ruby
:linenos:</pre>
</div>
<p>Include files are assumed to be encoded in the <a class="reference internal" href="../config.html#confval-source_encoding"><tt class="xref std std-confval docutils literal"><span class="pre">source_encoding</span></tt></a>.
If the file has a different encoding, you can specify it with the
<tt class="docutils literal"><span class="pre">encoding</span></tt> option:</p>
<div class="highlight-rest"><pre>.. literalinclude:: example.py
:encoding: latin-1</pre>
</div>
<p>The directive also supports including only parts of the file. If it is a
Python module, you can select a class, function or method to include using
the <tt class="docutils literal"><span class="pre">pyobject</span></tt> option:</p>
<div class="highlight-rest"><pre>.. literalinclude:: example.py
:pyobject: Timer.start</pre>
</div>
<p>This would only include the code lines belonging to the <tt class="docutils literal"><span class="pre">start()</span></tt> method in
the <tt class="docutils literal"><span class="pre">Timer</span></tt> class within the file.</p>
<p>Alternately, you can specify exactly which lines to include by giving a
<tt class="docutils literal"><span class="pre">lines</span></tt> option:</p>
<div class="highlight-rest"><pre>.. literalinclude:: example.py
:lines: 1,3,5-10,20-</pre>
</div>
<p>This includes the lines 1, 3, 5 to 10 and lines 20 to the last line.</p>
<p>Another way to control which part of the file is included is to use the
<tt class="docutils literal"><span class="pre">start-after</span></tt> and <tt class="docutils literal"><span class="pre">end-before</span></tt> options (or only one of them). If
<tt class="docutils literal"><span class="pre">start-after</span></tt> is given as a string option, only lines that follow the first
line containing that string are included. If <tt class="docutils literal"><span class="pre">end-before</span></tt> is given as a
string option, only lines that precede the first lines containing that string
are included.</p>
<p>You can prepend and/or append a line to the included code, using the
<tt class="docutils literal"><span class="pre">prepend</span></tt> and <tt class="docutils literal"><span class="pre">append</span></tt> option, respectively. This is useful e.g. for
highlighting PHP code that doesn’t include the <tt class="docutils literal"><span class="pre"><?php</span></tt>/<tt class="docutils literal"><span class="pre">?></span></tt> markers.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.4.3: </span>The <tt class="docutils literal"><span class="pre">encoding</span></tt> option.</p>
<p class="versionadded">
<span class="versionmodified">New in version 0.6: </span>The <tt class="docutils literal"><span class="pre">pyobject</span></tt>, <tt class="docutils literal"><span class="pre">lines</span></tt>, <tt class="docutils literal"><span class="pre">start-after</span></tt> and <tt class="docutils literal"><span class="pre">end-before</span></tt> options,
as well as support for absolute filenames.</p>
<p class="versionadded">
<span class="versionmodified">New in version 1.0: </span>The <tt class="docutils literal"><span class="pre">prepend</span></tt> and <tt class="docutils literal"><span class="pre">append</span></tt> options, as well as <tt class="docutils literal"><span class="pre">tab-width</span></tt>.</p>
</dd></dl>
<p class="rubric">Footnotes</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>There is a standard <tt class="docutils literal"><span class="pre">..</span> <span class="pre">include</span></tt> directive, but it raises errors if the
file is not found. This one only emits a warning.</td></tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="../genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="../py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="inline.html" title="Inline markup"
>next</a> |</li>
<li class="right" >
<a href="para.html" title="Paragraph-level markup"
>previous</a> |</li>
<li><a href="../index.html">Sphinx home</a> | </li>
<li><a href="../contents.html">Documentation</a>
»</li>
<li><a href="index.html" >Sphinx Markup Constructs</a> »</li>
</ul>
</div>
<div class="footer">
© Copyright 2007-2011, Georg Brandl.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a> 1.0.7.
</div>
</body>
</html>
distrib
>
Fedora
>
14
>
x86_64
>
media
>
updates
>
by-pkgid
>
2b39e69e45f9a0b2b3aece7339c56216
>
files
>
107
