{% extends "layout.html" %} {% set title = 'Overview' %} {% block body %} <h1>Welcome</h1> <div class="quotebar"> <p><em>What users say:</em></p> <p>“Cheers for a great tool that actually makes programmers <b>want</b> to write documentation!”</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 for <a href="http://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! </p> <p> Sphinx is under constant development. The following features are present, work fine and can be seen “in action” in the Python docs: </p> <ul> <li><b>Output formats:</b> HTML (including Windows HTML Help), LaTeX (for printable PDF versions), manual pages, plain text</li> <li><b>Extensive cross-references:</b> semantic markup and automatic links for functions, classes, citations, 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 (API docs), 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>Documentation</h2> <table class="contentstable" align="center" style="margin-left: 30px"><tr> <td width="50%"> <p class="biglink"><a class="biglink" href="{{ pathto("tutorial") }}">First steps with Sphinx</a><br/> <span class="linkdescr">overview of basic tasks</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("contents") }}">Contents</a><br/> <span class="linkdescr">for a complete overview</span></p> </td><td width="50%"> <p class="biglink"><a class="biglink" href="{{ pathto("search") }}">Search page</a><br/> <span class="linkdescr">search the documentation</span></p> <p class="biglink"><a class="biglink" href="{{ pathto("genindex") }}">General Index</a><br/> <span class="linkdescr">all functions, classes, terms</span></p> </td></tr> </table> <p> 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> <h2>Examples</h2> <p>Links to documentation generated with Sphinx can be found on the <a href="{{ pathto("examples") }}">Projects using Sphinx</a> page. </p> <p> For examples of how Sphinx source files look, use the “Show source” links on all pages of the documentation apart from this welcome page. </p> <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-users.jp/doc10/">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 %}