Update blurb in setup.py and on the index page, link directly to tutorial.rst from index.

This commit is contained in:
Georg Brandl 2010-02-28 23:12:00 +01:00
parent 700c831ae7
commit 0ee675b7cf
3 changed files with 49 additions and 45 deletions

View File

@ -4,7 +4,7 @@
<h1>Welcome</h1>
<div class="quotebar">
<p>What users say:</p>
<p><em>What users say:</em></p>
<p>&ldquo;Cheers for a great tool that actually makes programmers <b>want</b>
to write documentation!&rdquo;</p>
</div>
@ -12,28 +12,30 @@
<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>It was originally created for <a href="http://docs.python.org/dev/">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>
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:
Sphinx is under constant development. The following features are 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>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, glossary terms and similar pieces of information</li>
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>
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>
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>
docstrings from Python modules (API docs), and more</li>
</ul>
<p>
Sphinx uses <a href="http://docutils.sf.net/rst.html">reStructuredText</a>
@ -42,39 +44,40 @@
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("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>
</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 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 &#8220;Show
source&#8221; 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

View File

@ -11,9 +11,9 @@ browsing and navigation. But from the same source, it can also generate a
LaTeX file that you can compile into a PDF version of the documents.
The focus is on hand-written documentation, rather than auto-generated API docs.
Though there is limited support for that kind of docs as well (which is intended
to be freely mixed with hand-written content), if you need pure API docs have a
look at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST.
Though there is support for that kind of docs as well (which is intended to be
freely mixed with hand-written content), if you need pure API docs have a look
at `Epydoc <http://epydoc.sf.net/>`_, which also understands reST.
Conversion from other systems

View File

@ -11,20 +11,21 @@ import sphinx
long_desc = '''
Sphinx is a tool that makes it easy to create intelligent and beautiful
documentation for Python projects (or other documents consisting of
multiple reStructuredText sources), written by Georg Brandl.
It was originally created to translate the new Python documentation,
but has now been cleaned up in the hope that it will be useful to many
other projects.
documentation for Python projects (or other documents consisting of multiple
reStructuredText sources), written by Georg Brandl. It was originally created
for the new Python documentation, and has excellent facilities for Python
project documentation, but C/C++ is supported as well, and more languages are
planned.
Sphinx uses reStructuredText as its markup language, and many of its strengths
come from the power and straightforwardness of reStructuredText and its
parsing and translating suite, the Docutils.
come from the power and straightforwardness of reStructuredText and its parsing
and translating suite, the Docutils.
Among its features are the following:
* Output formats: HTML (including derivative formats such as HTML Help, Epub
and Qt Help), plain text and LaTeX or direct PDF output using rst2pdf
and Qt Help), plain text, manual pages and LaTeX or direct PDF output
using rst2pdf
* Extensive cross-references: semantic markup and automatic links
for functions, classes, glossary terms and similar pieces of information
* Hierarchical structure: easy definition of a document tree, with automatic