Source

sphinx / README

Diff from to
-doctools README
-===============
+=================
+README for Sphinx
+=================
 
-FIXME: This is already outdated since the conversion has happened and the
-reST sources are in the Python tree now.
+Installing
+==========
 
-TODO: update this.
+Use ``setup.py``::
 
+   python setup.py build
+   sudo python setup.py install
 
-What you need to know
----------------------
 
-This project uses Python 2.5 features, so you'll need a working Python
-2.5 setup.  Docutils 0.4 is required, the Docutils SVN trunk does not
-work at the moment, but I don't expect it to be difficult to fix that.
+Reading the docs
+================
 
-Docutils can be installed from the PyPI (Cheese Shop) via ``easy_install``
-or from http://docutils.sourceforge.net/.
+After installing::
 
-If you want code highlighting, you need Pygments >= 0.8, easily
-installable from PyPI.  Jinja, the template engine, is included as a
-SVN external.
+   cd doc
+   sphinx-build.py . .build
+   browser .build/index.html
 
+Or read them online at <http://sphinx.pocoo.org/>.
 
-Converting the LaTeX sources
-----------------------------
 
-**This paragraph is obsolete.**  The conversion has been done, and reST docs
-trees are now maintained for 2.6 and 3.0 branches.
+Contributing
+============
 
-For the rest of this document, let's assume that you have a Python
-checkout (you need the 2.6 line, i.e. the trunk -- the SVN URL for readonly
-access is http://svn.python.org/projects/python/trunk) in ~/devel/python
-and this checkout in the current directory.
-
-To convert the LaTeX doc to reST, you first have to apply the patch in
-``etc/inst.diff`` to the ``inst/inst.tex`` LaTeX file in the Python
-checkout::
-
-   patch -d ~/devel/python/Doc -p0 < etc/inst.diff
-
-Then, create a target directory for the reST sources and run the
-converter script::
-
-   mkdir sources
-   python convert.py ~/devel/python/Doc sources
-
-This will convert all LaTeX sources to reST files in the ``sources``
-directory.
-
-The ``sources`` directory contains a ``conf.py`` file which contains
-general configuration for the build process, such as the Python
-version that should be shown, or the date format for "last updated on"
-notes.
-
-
-Building the HTML version
--------------------------
-
-Then, create a target directory and run ::
-
-   mkdir build-html
-   python sphinx-build.py -b html Doc-26 build-html
-
-This will create HTML files in the ``build-html`` directory.
-
-The ``build-html`` directory will also contain a ``.doctrees``
-directory, which caches pickles containing the docutils doctrees for
-all source files, as well as an ``environment.pickle`` file that
-collects all meta-information and data that's needed to
-cross-reference the sources and generate indices.
-
-
-Running the online (web) version
---------------------------------
-
-First, you need to build the source with the "web" builder::
-
-   mkdir build-web
-   python sphinx-build.py -b web Doc-26 build-web
-
-This will create files with pickled contents for the web application
-in the target directory.
-
-Then, you can run ::
-
-   python sphinx-web.py build-web
-
-which will start a webserver using wsgiref on ``localhost:3000``.  The
-web application has a configuration file ``build-web/webconf.py``,
-where you can configure the server and port for the application as
-well as different other settings specific to the web app.
-
-
-Writing new documentation
--------------------------
-
-The new "Documenting Python" document, contained in a converted documentation
-tree, already lists most of the markup and features, both standard reST and
-additional, that can be used in the source docs.
-
-More reST docs are at http://docutils.sf.net/rst.html, tutorials can be found on
-the web.
+Send wishes, comments, patches, etc. to georg@python.org.