<!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>Sphinx FAQ — 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="next" title="Glossary" href="glossary.html" />
<link rel="prev" title="sphinx.ext.oldcmarkup – Compatibility extension for old C markup" href="ext/oldcmarkup.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="glossary.html" title="Glossary"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="ext/oldcmarkup.html" title="sphinx.ext.oldcmarkup – Compatibility extension for old C markup"
accesskey="P">previous</a> |</li>
<li><a href="index.html">Sphinx home</a> | </li>
<li><a href="contents.html">Documentation</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="#">Sphinx FAQ</a><ul>
<li><a class="reference internal" href="#how-do-i">How do I...</a></li>
<li><a class="reference internal" href="#using-sphinx-with">Using Sphinx with...</a></li>
<li><a class="reference internal" href="#epub-info">Epub info</a></li>
</ul>
</li>
</ul>
<h4>Previous topic</h4>
<p class="topless"><a href="ext/oldcmarkup.html"
title="previous chapter"><tt class="docutils literal docutils literal docutils literal"><span class="pre">sphinx.ext.oldcmarkup</span></tt> – Compatibility extension for old C markup</a></p>
<h4>Next topic</h4>
<p class="topless"><a href="glossary.html"
title="next chapter">Glossary</a></p>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/faq.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="sphinx-faq">
<span id="faq"></span><h1>Sphinx FAQ<a class="headerlink" href="#sphinx-faq" title="Permalink to this headline">¶</a></h1>
<p>This is a list of Frequently Asked Questions about Sphinx. Feel free to
suggest new entries!</p>
<div class="section" id="how-do-i">
<h2>How do I...<a class="headerlink" href="#how-do-i" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>... create PDF files without LaTeX?</dt>
<dd>You can use <a class="reference external" href="http://rst2pdf.googlecode.com">rst2pdf</a> version 0.12 or greater
which comes with built-in Sphinx integration. See the <a class="reference internal" href="builders.html#builders"><em>Available builders</em></a>
section for details.</dd>
<dt>... get section numbers?</dt>
<dd>They are automatic in LaTeX output; for HTML, give a <tt class="docutils literal"><span class="pre">:numbered:</span></tt> option to
the <a class="reference internal" href="markup/toctree.html#directive-toctree" title="toctree directive"><tt class="xref rst rst-dir docutils literal"><span class="pre">toctree</span></tt></a> directive where you want to start numbering.</dd>
<dt>... customize the look of the built HTML files?</dt>
<dd>Use themes, see <a class="reference internal" href="theming.html"><em>HTML theming support</em></a>.</dd>
<dt>... add global substitutions or includes?</dt>
<dd>Add them in the <a class="reference internal" href="config.html#confval-rst_epilog"><tt class="xref std std-confval docutils literal"><span class="pre">rst_epilog</span></tt></a> config value.</dd>
<dt>... display the whole TOC tree in the sidebar?</dt>
<dd>Use the <a class="reference internal" href="templating.html#toctree" title="toctree"><tt class="xref py py-data docutils literal"><span class="pre">toctree</span></tt></a> callable in a custom layout template, probably in the
<tt class="docutils literal"><span class="pre">sidebartoc</span></tt> block.</dd>
<dt>... write my own extension?</dt>
<dd>See the <a class="reference internal" href="ext/tutorial.html#exttut"><em>extension tutorial</em></a>.</dd>
<dt>... convert from my existing docs using MoinMoin markup?</dt>
<dd>The easiest way is to convert to xhtml, then convert <a class="reference external" href="http://docutils.sourceforge.net/sandbox/xhtml2rest/xhtml2rest.py">xhtml to reST</a>. You’ll
still need to mark up classes and such, but the headings and code examples
come through cleanly.</dd>
</dl>
</div>
<div class="section" id="using-sphinx-with">
<span id="usingwith"></span><h2>Using Sphinx with...<a class="headerlink" href="#using-sphinx-with" title="Permalink to this headline">¶</a></h2>
<dl class="docutils">
<dt>Epydoc</dt>
<dd>There’s a third-party extension providing an <a class="reference external" href="http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py">api role</a> which refers to
Epydoc’s API docs for a given identifier.</dd>
<dt>Doxygen</dt>
<dd>Michael Jones is developing a reST/Sphinx bridge to doxygen called <a class="reference external" href="http://github.com/michaeljones/breathe/tree/master">breathe</a>.</dd>
<dt>SCons</dt>
<dd>Glenn Hutchings has written a SCons build script to build Sphinx
documentation; it is hosted here: <a class="reference external" href="http://bitbucket.org/zondo/sphinx-scons">http://bitbucket.org/zondo/sphinx-scons</a></dd>
<dt>PyPI</dt>
<dd>Jannis Leidel wrote a <a class="reference external" href="http://pypi.python.org/pypi/Sphinx-PyPI-upload">setuptools command</a> that automatically uploads
Sphinx documentation to the PyPI package documentation area at
<a class="reference external" href="http://packages.python.org/">http://packages.python.org/</a>.</dd>
<dt>MediaWiki</dt>
<dd>See <a class="reference external" href="http://bitbucket.org/kevindunn/sphinx-wiki">http://bitbucket.org/kevindunn/sphinx-wiki</a>, a project by Kevin Dunn.</dd>
<dt>github pages</dt>
<dd>You’ll have to opt out of processing your pages with the “Jekyll” preprocessor
as described in <a class="reference external" href="http://pages.github.com/#using_jekyll_for_complex_layouts">http://pages.github.com/#using_jekyll_for_complex_layouts</a>.</dd>
<dt>Google Analytics</dt>
<dd><p class="first">You can use a custom <tt class="docutils literal"><span class="pre">layout.html</span></tt> template, like this:</p>
<div class="last highlight-html+django"><pre>{% extends "!layout.html" %}
{%- block extrahead %}
{{ super() }}
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'XXX account number XXX']);
_gaq.push(['_trackPageview']);
</script>
{% endblock %}
{% block footer %}
{{ super() }}
<div class="footer">This page uses <a href="http://analytics.google.com/">
Google Analytics</a> to collect statistics. You can disable it by blocking
the JavaScript coming from www.google-analytics.com.
<script type="text/javascript">
(function() {
var ga = document.createElement('script');
ga.src = ('https:' == document.location.protocol ?
'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
ga.setAttribute('async', 'true');
document.documentElement.firstChild.appendChild(ga);
})();
</script>
</div>
{% endblock %}</pre>
</div>
</dd>
</dl>
</div>
<div class="section" id="epub-info">
<span id="epub-faq"></span><h2>Epub info<a class="headerlink" href="#epub-info" title="Permalink to this headline">¶</a></h2>
<p>The epub builder is currently in an experimental stage. It has only been tested
with the Sphinx documentation itself. If you want to create epubs, here are
some notes:</p>
<ul>
<li><p class="first">Split the text into several files. The longer the individual HTML files are,
the longer it takes the ebook reader to render them. In extreme cases, the
rendering can take up to one minute.</p>
</li>
<li><p class="first">Try to minimize the markup. This also pays in rendering time.</p>
</li>
<li><p class="first">For some readers you can use embedded or external fonts using the CSS
<tt class="docutils literal"><span class="pre">@font-face</span></tt> directive. This is <em>extremely</em> useful for code listings which
are often cut at the right margin. The default Courier font (or variant) is
quite wide and you can only display up to 60 characters on a line. If you
replace it with a narrower font, you can get more characters on a line. You
may even use <a class="reference external" href="http://fontforge.sourceforge.net/">FontForge</a> and create
narrow variants of some free font. In my case I get up to 70 characters on a
line.</p>
<p>You may have to experiment a little until you get reasonable results.</p>
</li>
<li><p class="first">Test the created epubs. You can use several alternatives. The ones I am aware
of are <a class="reference external" href="http://code.google.com/p/epubcheck/">Epubcheck</a>, <a class="reference external" href="http://calibre-ebook.com/">Calibre</a>, <a class="reference external" href="http://www.fbreader.org/">FBreader</a> (although it does not render the CSS),
and <a class="reference external" href="http://bookworm.oreilly.com/">Bookworm</a>. For bookworm you can download the source from
<a class="reference external" href="http://code.google.com/p/threepress/">http://code.google.com/p/threepress/</a> and run your own local server.</p>
</li>
<li><p class="first">Large floating divs are not displayed properly.
If they cover more than one page, the div is only shown on the first page.
In that case you can copy the <tt class="file docutils literal"><span class="pre">epub.css</span></tt> from the
<tt class="docutils literal"><span class="pre">sphinx/themes/epub/static/</span></tt> directory to your local <tt class="docutils literal"><span class="pre">_static/</span></tt>
directory and remove the float settings.</p>
</li>
<li><p class="first">Files that are inserted outside of the <tt class="docutils literal"><span class="pre">toctree</span></tt> directive must be manually
included. This sometimes applies to appendixes, e.g. the glossary or
the indices. You can add them with the <a class="reference internal" href="config.html#confval-epub_post_files"><tt class="xref std std-confval docutils literal"><span class="pre">epub_post_files</span></tt></a> option.</p>
</li>
</ul>
</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="glossary.html" title="Glossary"
>next</a> |</li>
<li class="right" >
<a href="ext/oldcmarkup.html" title="sphinx.ext.oldcmarkup – Compatibility extension for old C markup"
>previous</a> |</li>
<li><a href="index.html">Sphinx home</a> | </li>
<li><a href="contents.html">Documentation</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
>
97
