:author: Dave Kuhlman
:revision: 1.0a
:date: July 1, 2003

:copyright: This document has been placed in the public domain.
    You may do with it as you wish. You may copy, modify,
    redistribute, reattribute, sell, buy, rent, lease, destroy, or
    improve it, quote it at length, excerpt, incorporate, collate,
    fold, staple, or mutilate it, or do anything else to it that
    your or anyone else's heart desires.

:abstract: This document describes a Docutils writer for
    use with the Python project's documentation tools.


==============================================
Introduction to the Documenting Python Writer
==============================================


-------------
What It Does
-------------

This writer for Docutils generates LaTeX suitable for
input to the documentation system described in `Documenting
Python`_

.. _`Documenting Python`: http://www.python.org/dev/doc/devel/doc/doc.html


--------------
How to Use It
--------------

Conversion has several steps:

1. Run *documenting_python.py* in *docutils/tools*, for example:

2. Run the writer. Here is an example::

    $ docutils/tools/documenting_python.py --documentclass=howto docpy_intro.rst

There is one option:


--documentclass=class 

    Selects the template type from Doc/templates in the Python
    source distribution. Possible values are ``howto``,
    ``manual``, and ``module``. The ``module`` document type is
    not yet implemented. See the Doc/templates subdirectory in the
    Python Source code distribution for samples of these document
    types.  

.. ("module" too, according to the writer's settings_spec.  Or should
   "module" be removed from the writer?)

Here is a make_file that was used to convert the document that you
are currently reading::

    PYTHON_SRC = /w1/Python/Python-2.3b1
    DOCUTILS_DIR = /w1/Python/DocUtils/docutils
    
    DOCUTILSTOOLS_DIR = $(DOCUTILS_DIR)/tools
    TRANSFORMDOCPY = $(DOCUTILSTOOLS_DIR)/documenting_python.py \
        --documentclass=howto
    
    
    HTMLFLAGS= --image-type png --html -s 1 --favicon ../icons/pyfav.gif
    
    MKHOWTO = $(PYTHON_SRC)/Doc/tools/mkhowto
    
    TARGETS = docpy_intro/docpy_intro.html
    
    all:    html
    
    html:   $(TARGETS)
    
    docpy_intro/docpy_intro.html: docpy_intro.tex
        $(MKHOWTO) $(HTMLFLAGS) docpy_intro.tex
    
    docpy_intro.tex: docpy_intro.rst
        $(TRANSFORMDOCPY) docpy_intro.rst > docpy_intro.tex
    
    clean:
        rm -f *~ *.aux *.idx *.ilg *.ind *.log *.toc *.bkm *.syn \
            *.pla *.eps *.pdf *.ps *.lof *.l2h *.tex2 *.dvi
        rm -f docpy_intro.tex
        rm -f docpy_intro/*
        rmdir docpy_intro
        rm -f docpy_intro.tex
    



------------------------------
Special Formatting Constructs
------------------------------

See the companion document 'Quick reStructuredText for
"Documenting Python"' for additional mark-up that can be used
when generating LaTeX for "Documenting Python".

The first section of this document has information specific to the
generation of LaTeX for Documenting Python.

In addition, that document also adds another column to the
specification tables.  This additional column describes the LaTeX
commands generated by this writer.


-----------------
Acknowledgements
-----------------

Thanks to the Docutils project members for Docutils.  In
particular, thanks to project coordinator David Goodger.

Thanks to Engelbert Gruber for the implementation of the LaTeX
writer.  That implementation formed the starting point for this
writer.  He should get much of the credit for this writer also,
however, any bugs were likely introduced by me.

Thanks to Fred Drake (and many more I'm sure) for the Python
documentation tools, the Python documentation project, and the
Python documentation itself.

---------
See Also
---------

`The Docutils Home Page`_

.. _`The Docutils Home Page`: http://docutils.sourceforge.net/


`The Python home page`_

.. _`The Python home page`: http://www.python.org/ 


`The documentation on the Documenting Python system`_

.. _`The documentation on the Documenting Python system`:
    http://www.python.org/dev/doc/devel/doc/doc.html