diff options
Diffstat (limited to 'doc/usage/quickstart.rst')
| -rw-r--r-- | doc/usage/quickstart.rst | 40 |
1 files changed, 27 insertions, 13 deletions
diff --git a/doc/usage/quickstart.rst b/doc/usage/quickstart.rst index b5462a388..8d2de021e 100644 --- a/doc/usage/quickstart.rst +++ b/doc/usage/quickstart.rst @@ -2,21 +2,38 @@ Getting Started =============== -Once Sphinx is :doc:`installed </usage/installation>`, you can proceed with -setting up your first Sphinx project. To ease the process of getting started, -Sphinx provides a tool, :program:`sphinx-quickstart`, which will generate a -documentation source directory and populate it with some defaults. We're going -to use the :program:`sphinx-quickstart` tool here, though its use is by no means -necessary. +Sphinx is a *documentation generator* or a tool that translates a set of plain +text source files into various output formats, automatically producing +cross-references, indices, etc. That is, if you have a directory containing a +bunch of :doc:`/usage/restructuredtext/index` or :doc:`/usage/markdown` +documents, Sphinx can generate a series of HTML files, a PDF file (via LaTeX), +man pages and much more. + +Sphinx focuses on documentation, in particular handwritten documentation, +however, Sphinx can also be used to generate blogs, homepages and even books. +Much of Sphinx's power comes from the richness of its default plain-text markup +format, :doc:`reStructuredText </usage/restructuredtext/index>`, along with +it's :doc:`significant extensibility capabilities </development/index>`. + +The goal of this document is to give you a quick taste of what Sphinx it is and +how you might use it. When you're done here, you can check out the +:doc:`installation guide </usage/installation>` followed by the intro to the +default markup format used by Sphinx, :doc:`reStucturedText +</usage/restructuredtext/index>`. + +For a great "introduction" to writing docs in general -- the whys and hows, see +also `Write the docs`__, written by Eric Holscher. + +.. __: http://www.writethedocs.org/guide/writing/beginners-guide-to-docs/ Setting up the documentation sources ------------------------------------ -The root directory of a Sphinx collection of :term:`reStructuredText` document -sources is called the :term:`source directory`. This directory also contains -the Sphinx configuration file :file:`conf.py`, where you can configure all -aspects of how Sphinx reads your sources and builds your documentation. [#]_ +The root directory of a Sphinx collection of plain-text document sources is +called the :term:`source directory`. This directory also contains the Sphinx +configuration file :file:`conf.py`, where you can configure all aspects of how +Sphinx reads your sources and builds your documentation. [#]_ Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a source directory and creates a default :file:`conf.py` with the most useful @@ -26,9 +43,6 @@ configuration values from a few questions it asks you. To use this, run: $ sphinx-quickstart -There is also an automatic "API documentation" generator called -:program:`sphinx-apidoc`; see :doc:`/man/sphinx-apidoc` for details. - Defining document structure --------------------------- |