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

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

  <p>{%trans%}
    Sphinx is a tool that makes it easy to create intelligent and beautiful
    documentation, written by Georg Brandl and licensed under the BSD license.{%endtrans%}</p>
  <p>{%trans%}It was originally created for <a href="https://docs.python.org/">the
    new Python documentation</a>, and it has excellent facilities for the
    documentation of Python projects, but C/C++ is already supported as well,
    and it is planned to add special support for other languages as well.  Of
    course, this site is also created from reStructuredText sources using
    Sphinx!  The following features should be highlighted:{%endtrans%}
  </p>
  <ul>
    <li>{%trans%}<b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for
      printable PDF versions), ePub, Texinfo, manual pages, plain text{%endtrans%}</li>
    <li>{%trans%}<b>Extensive cross-references:</b> semantic markup and automatic links
      for functions, classes, citations, glossary terms and similar pieces of
      information{%endtrans%}</li>
    <li>{%trans%}<b>Hierarchical structure:</b> easy definition of a document tree, with
      automatic links to siblings, parents and children{%endtrans%}</li>
    <li>{%trans%}<b>Automatic indices:</b> general index as well as a language-specific
      module indices{%endtrans%}</li>
    <li>{%trans%}<b>Code handling:</b> automatic highlighting using the <a
      href="http://pygments.org">Pygments</a> highlighter{%endtrans%}</li>
    <li>{%trans path=pathto('extensions')%}<b>Extensions:</b> automatic testing of code snippets, inclusion of
      docstrings from Python modules (API docs), and
      <a href="{{ path }}#builtin-sphinx-extensions">more</a>{%endtrans%}</li>
    <li>{%trans path=pathto('develop')%}<b>Contributed extensions:</b> more than
      50 extensions <a href="{{ path }}#extensions">contributed by users</a>
      in a second repository; most of them installable from PyPI{%endtrans%}</li>
  </ul>
  <p>{%trans%}
    Sphinx uses <a href="http://docutils.sourceforge.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.sourceforge.net/">Docutils</a>.{%endtrans%}
  </p>

  <h2 style="margin-bottom: 0">{%trans%}Documentation{%endtrans%}</h2>

  <table class="contentstable" align="center" style="margin-left: 30px"><tr>
    <td width="50%">
      <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">{%trans%}First steps with Sphinx{%endtrans%}</a><br/>
         <span class="linkdescr">{%trans%}overview of basic tasks{%endtrans%}</span></p>
      <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">{%trans%}Contents{%endtrans%}</a><br/>
         <span class="linkdescr">{%trans%}for a complete overview{%endtrans%}</span></p>
    </td><td width="50%">
      <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">{%trans%}Search page{%endtrans%}</a><br/>
         <span class="linkdescr">{%trans%}search the documentation{%endtrans%}</span></p>
      <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">{%trans%}General Index{%endtrans%}</a><br/>
         <span class="linkdescr">{%trans%}all functions, classes, terms{%endtrans%}</span></p>
    </td></tr>
  </table>

  <p>{%trans%}
    You can also download PDF/EPUB versions of the Sphinx documentation:
    a <a href="http://readthedocs.org/projects/sphinx/downloads/pdf/stable/">PDF version</a> generated from
    the LaTeX Sphinx produces, and
    a <a href="http://readthedocs.org/projects/sphinx/downloads/epub/stable/">EPUB version</a>.
   {%endtrans%}
  </p>

  <h2>{%trans%}Examples{%endtrans%}</h2>
  <p>{%trans path=pathto("examples")%}Links to documentation generated with Sphinx can be found on the
    <a href="{{ path }}">Projects using Sphinx</a> page.{%endtrans%}
  </p>
  <p>{%trans%}
    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.{%endtrans%}
  </p>

  <p>{%trans%}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.{%endtrans%}</p>

  <p>{%trans%}There is a <a href="http://docs.sphinx-users.jp/">Japanese translation</a>
    of this documentation, thanks to the Japanese Sphinx user group.{%endtrans%}</p>
  <p>{%trans%}A Japanese book about Sphinx has been published by O'Reilly:
    <a href="http://www.oreilly.co.jp/books/9784873116488/">Sphinxをはじめよう /
      Learning Sphinx</a>.{%endtrans%}</p>
  <!-- <p><img src="{{ pathto("_static/bookcover.png", 1) }}"/></p> -->


  <h2>{%trans%}Hosting{%endtrans%}</h2>

  <p>{%trans%}Need a place to host your Sphinx docs?
    <a href="http://readthedocs.org">readthedocs.org</a> hosts a lot of Sphinx docs
    already, and integrates well with projects' source control.  It also features a
    powerful built-in search that exceeds the possibilities of Sphinx' JavaScript-based
    offline search.{%endtrans%}</p>

  <h2>{%trans%}Contributor Guide{%endtrans%}</h2>

  <p>{%trans%}If you want to contribute to the project,
    this part of the documentation is for you.{%endtrans%}</p>

    <ul>
      <li>{%trans path=pathto("devguide")%}<a href="{{ path }}">Sphinx Developer’s Guide</a></li>{%endtrans%}
      <li>{%trans path=pathto("authors")%}<a href="{{ path }}">Sphinx Authors</a></li>{%endtrans%}
    </ul>

{% endblock %}