Author: ArcRiley Date: 2008-09-28 21:19:49 -0400 (Sun, 28 Sep 2008) New Revision: 1372
Added: trunk/pysoy/docs/src/index.rst trunk/pysoy/docs/src/intro.rst Log: Ticket #964 : * very early draft of actual ReST docs Added: trunk/pysoy/docs/src/index.rst =================================================================== --- trunk/pysoy/docs/src/index.rst (rev 0) +++ trunk/pysoy/docs/src/index.rst 2008-09-29 01:19:49 UTC (rev 1372) @@ -0,0 +1,21 @@ +.. PySoy documentation master file, created by sphinx-quickstart on Fri Sep 26 06:42:36 2008. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +Welcome to PySoy's documentation! +================================= + +Contents: + +.. toctree:: + :maxdepth: 2 + + intro + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` Added: trunk/pysoy/docs/src/intro.rst =================================================================== --- trunk/pysoy/docs/src/intro.rst (rev 0) +++ trunk/pysoy/docs/src/intro.rst 2008-09-29 01:19:49 UTC (rev 1372) @@ -0,0 +1,113 @@ +Introduction +============ + +This is the documentation for the Sphinx documentation builder. Sphinx is a +tool that translates a set of reStructuredText_ source files into various output +formats, automatically producing cross-references, indices etc. That is, if +you have a directory containing a bunch of reST-formatted documents (and +possibly subdirectories of docs in there as well), Sphinx can generate a +nicely-organized arrangement of HTML files (in some other directory) for easy +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. + +Prerequisites +------------- + +Sphinx needs at least **Python 2.4** to run. If you like to have source code +highlighting support, you must also install the Pygments_ library, which you +can +do via setuptools' easy_install. Sphinx should work with docutils version 0.4 +or some (not broken) SVN trunk snapshot. + +.. _reStructuredText: http://docutils.sf.net/rst.html +.. _Pygments: http://pygments.org + + +Setting up the documentation sources +------------------------------------ + +The root directory of a documentation collection is called the :dfn:`source +directory`. Normally, this directory also contains the Sphinx configuration +file :file:`conf.py`, but that file can also live in another directory, the +:dfn:`configuration directory`. + +.. versionadded:: 0.3 + Support for a different configuration directory. + +Sphinx comes with a script called :program:`sphinx-quickstart` that sets up a +source directory and creates a default :file:`conf.py` from a few questions it +asks you. Just run :: + + $ sphinx-quickstart + +and answer the questions. + + +Running a build +--------------- + +A build is started with the :program:`sphinx-build` script. It is called +like this:: + + $ sphinx-build -b latex sourcedir builddir + +where *sourcedir* is the :term:`source directory`, and *builddir* is the +directory in which you want to place the built documentation (it must be an +existing directory). The :option:`-b` option selects a builder; in this +example +Sphinx will build LaTeX files. + +The :program:`sphinx-build` script has several more options: + +**-a** + If given, always write all output files. The default is to only write output + files for new and changed source files. (This may not apply to all + builders.) + +**-E** + Don't use a saved :term:`environment` (the structure caching all + cross-references), but rebuild it completely. The default is to only read + and parse source files that are new or have changed since the last run. + +**-d** *path* + Since Sphinx has to read and parse all source files before it can write an + output file, the parsed source files are cached as "doctree pickles". + Normally, these files are put in a directory called :file:`.doctrees` under + the build directory; with this option you can select a different cache + directory (the doctrees can be shared between all builders). + +**-c** *path* + Don't look for the :file:`conf.py` in the source directory, but use the given + configuration directory instead. Note that various other files and paths + given by configuration values are expected to be relative to the + configuration directory, so they will have to be present at this location + too. + + .. versionadded:: 0.3 + +**-D** *setting=value* + Override a configuration value set in the :file:`conf.py` file. (The value + must be a string value.) + +**-N** + Do not do colored output. (On Windows, colored output is disabled in any + case.) + +**-q** + Do not output anything on standard output, only write warnings to standard + error. + +**-P** + (Useful for debugging only.) Run the Python debugger, :mod:`pdb`, if an + unhandled exception occurs while building. + + +You can also give one or more filenames on the command line after the source and +build directories. Sphinx will then try to build only these output files (and +their dependencies). + _______________________________________________ PySoy-SVN mailing list PySoy-SVN@pysoy.org http://www.pysoy.org/mailman/listinfo/pysoy-svn
