mirror of
https://github.com/sphinx-doc/sphinx.git
synced 2025-02-25 18:55:22 -06:00
98 lines
3.1 KiB
Plaintext
98 lines
3.1 KiB
Plaintext
doctools README
|
|
===============
|
|
|
|
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.
|
|
|
|
Docutils can be installed from the PyPI (Cheese Shop) via ``easy_install``
|
|
or from http://docutils.sourceforge.net/.
|
|
|
|
If you want code highlighting, you need Pygments >= 0.8, easily
|
|
installable from PyPI. Jinja, the template engine, is included as a
|
|
SVN external.
|
|
|
|
|
|
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.
|
|
|
|
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.
|