{% 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%}&#8220;Cheers for a great tool that actually makes programmers <b>want</b>
      to write documentation!&#8220;{%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
    Python documentation</a>, and it has excellent facilities for the
    documentation of software projects in a range of languages.  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('ext/builtins')%}<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">
    <tr>
      <td>
        <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>
      </td><td>
        {%- if hasdoc('search') %}<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>{%- endif %}
      </td>
    </tr><tr>
      <td>
        <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>
        {%- if hasdoc('genindex') %}<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>{%- endif %}
      </td>
    </tr><tr>
      <td>
        <p class="biglink"><a class="biglink" href="{{ pathto("changes") }}">{%trans%}Changes{%endtrans%}</a><br/>
           <span class="linkdescr">{%trans%}release history{%endtrans%}</span></p>
      </td><td>
      </td>
    </tr>
  </table>

  <p>{%trans%}
    You can also download PDF/EPUB versions of the Sphinx documentation:
    a <a href="https://media.readthedocs.org/pdf/sphinx/stable/sphinx.pdf">PDF version</a> generated from
    the LaTeX Sphinx produces, and
    a <a href="https://media.readthedocs.org/epub/sphinx/stable/sphinx.epub">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="https://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 %}