{% extends "layout.html" %}
{% set title = 'Overview' %}
{% block body %}
  <h1>Welcome</h1>

  <div class="quotebar">
    <p>What users say:</p>
    <p>&ldquo;Cheers for a great tool that actually makes programmers <b>want</b>
      to write documentation!&rdquo;</p>
  </div>

  <p>
    Sphinx is a tool that makes it easy to create intelligent and beautiful
    documentation, written by Georg Brandl and licensed under the BSD license.</p>
  <p>It was originally created to translate <a href="http://docs.python.org/dev/">the
    new Python documentation</a>, and it has excellent support for the documentation
    of Python projects, but other documents can be written with it too.  Of course,
    this site is also created from reStructuredText sources using Sphinx!
  </p>
  <p>
    It is still under constant development, and the following features are
    already present, work fine and can be seen &#8220;in action&#8221; in the
    Python docs:
  </p>
  <ul>
    <li><b>Output formats:</b> HTML (including Windows HTML Help) and LaTeX, for
    printable PDF versions</li>
    <li><b>Extensive cross-references:</b> semantic markup and automatic links
    for functions, classes, glossary terms and similar pieces of information</li>
    <li><b>Hierarchical structure:</b> easy definition of a document tree, with
    automatic links to siblings, parents and children</li>
    <li><b>Automatic indices:</b> general index as well as a module index</li>
    <li><b>Code handling:</b> automatic highlighting using the <a
    href="http://pygments.org">Pygments</a> highlighter</li>
    <li><b>Extensions:</b> automatic testing of code snippets, inclusion of
    docstrings from Python modules, and more</li>
  </ul>
  <p>
    Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
    as its markup language, and many of its strengths come from the power and
    straightforwardness of reStructuredText and its parsing and translating
    suite, the <a href="http://docutils.sf.net/">Docutils</a>.
  </p>

  <h2>Examples</h2>
  <p>
    The <a href="http://docs.python.org/dev/">Python documentation</a> and
    this page are different examples of Sphinx in use.
    You can also download PDF versions of the Sphinx documentation:
    a <a href="http://sphinx.pocoo.org/sphinx.pdf">version</a> generated from
    the LaTeX Sphinx produces, and a
    <a href="http://sphinx.pocoo.org/sphinx-rst2pdf.pdf">version</a> generated by rst2pdf.
  </p>
  <p>
    For examples of how Sphinx source files look, use the &#8220;Show source&#8221;
    links on all pages of the documentation apart from this welcome page.
  </p>
  <p>Links to more documentation generated with Sphinx can be found on the
    <a href="{{ pathto("examples") }}">Projects using Sphinx</a> page.
  </p>

  <h2>Documentation</h2>

  <table class="contentstable" align="center" style="margin-left: 30px"><tr>
    <td width="50%">
      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/>
         <span class="linkdescr">for a complete overview</span></p>
      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/>
         <span class="linkdescr">search the documentation</span></p>
    </td><td width="50%">
      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/>
         <span class="linkdescr">all functions, classes, terms</span></p>
      <p class="biglink"><a class="biglink" href="{{ pathto("modindex") }}">Module Index</a><br/>
         <span class="linkdescr">quick access to all documented modules</span></p>
    </td></tr>
  </table>

  <p>You may also be interested in the very nice
    <a href="http://matplotlib.sourceforge.net/sampledoc/">tutorial</a> on how to
    create a customized documentation using Sphinx written by the matplotlib
    developers.</p>

  <p>There is a <a href="http://sphinx.shibu.jp/">Japanese translation</a>
    of this documentation, thanks to Yoshiki Shibukawa.</p>

  <h2>Get Sphinx</h2>
  <p>
    Sphinx is available as an <a
    href="http://peak.telecommunity.com/DevCenter/EasyInstall">easy-install</a>able
    package on the <a href="http://pypi.python.org/pypi/Sphinx">Python Package
    Index</a>.
  </p>
  <p>The code can be found in a Mercurial repository, at
    <tt>http://bitbucket.org/birkenfeld/sphinx/</tt>.</p>

{% endblock %}