mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
Update blurb in setup.py and on the index page, link directly to tutorial.rst from index.
This commit is contained in:
parent
700c831ae7
commit
0ee675b7cf
71
doc/_templates/index.html
vendored
71
doc/_templates/index.html
vendored
@ -4,7 +4,7 @@
|
||||
<h1>Welcome</h1>
|
||||
|
||||
<div class="quotebar">
|
||||
<p>What users say:</p>
|
||||
<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>
|
||||
@ -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 “in action” in the
|
||||
Python docs:
|
||||
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) 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 “Show source”
|
||||
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 “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
|
||||
|
@ -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
|
||||
|
17
setup.py
17
setup.py
@ -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
|
||||
|
Loading…
Reference in New Issue
Block a user