Introduction to the Documenting Python Writer

---

 
Front Matter

Copyright (c) 2003 Dave Kuhlman Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Abstract:

Contents

• • 1 What It Does
  • 2 Where to Get It
  • 3 How to Use It
  • 4 Special Formatting Constructs
  • 5 Acknowledgements

 
1 What It Does

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

 
2 Where to Get It

This writer is not yet part of the Docutils distribution. Until it is, you can find it at http://www.rexx.com/~dkuhlman/rstpythonlatex-1.0b.zip.

 
3 How to Use It

Conversion has several steps:

1. Run the writer - Run documenting_python.py in docutils/tools, for example:

   $ docutils/tools/python_latex.py --documentclass=howto rstpythonlatex_intro.txt
   

   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.

2. Run the "Documenting Python" document processor.

Here is a Makefile that performs these two steps. It was used to convert the document that you are currently reading:

# Makefile to process a file LaTeX with the Python LaTeX system.
#  Optionally processes reStructuredText files.

#
# Change the following to point to your Python source code.
#
PYTHON_SRC = /w1/Python/Python-2.3b2
DOCUTILS_DIR = /w1/Python/DocUtils/docutils

#
# Change the following to point to your Docutils installation.
#
DOCUTILSTOOLS_DIR = $(DOCUTILS_DIR)/tools
TRANSFORMDOCPY = $(DOCUTILSTOOLS_DIR)/python_latex.py \
    --documentclass=howto

#
# Change these flags for your purposes.
#
#HTMLFLAGS= --image-type png --html -s 1 --favicon ../icons/pyfav.gif
HTMLFLAGS= --iconserver ../icons --html -s 1 --favicon ../icons/pyfav.gif

MKHOWTO = $(PYTHON_SRC)/Doc/tools/mkhowto

PAPER = a4

#
# Change this to the name of your source file (without extension).
#
#SRC_NAME=zip-ls
ifndef SRC_NAME
$(error Must define SRC_NAME (no extension), e.g. make SRC_NAME=mysourcefile)
endif

TARGETS = $(SRC_NAME)/$(SRC_NAME).html

FIGURES = 

all:        html

html:       $(TARGETS) $(FIGURES)

$(SRC_NAME)/$(SRC_NAME).html: $(SRC_NAME).tex
    $(MKHOWTO) $(HTMLFLAGS) $(SRC_NAME).tex

#
# Remove or Comment out the following lines if your source file
#   is a LaTeX file not a reST file.
#
$(SRC_NAME).tex: $(SRC_NAME).txt
    $(TRANSFORMDOCPY) $(SRC_NAME).txt > $(SRC_NAME).tex

clean:
    rm -f *~ *.aux *.idx *.ilg *.ind *.log *.toc *.bkm *.syn \
*.pla *.eps *.pdf *.ps *.lof *.l2h *.tex2 *.dvi
    -rm -f $(SRC_NAME).tex
    -rm -f $(SRC_NAME)/*
    -rmdir $(SRC_NAME)
    -rm -f $(SRC_NAME).tex

Run this Makefile with the following commands:

$ make SRC_NAME=rstpythonlatex_intro clean
$ make SRC_NAME=rstpythonlatex_intro

 
4 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". It is included in the distribution file for this writer.

The first section of that 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.

 
5 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.

About this document ...

This document was generated using the LaTeX2HTML translator.

LaTeX2HTML is Copyright © 1993, 1994, 1995, 1996, 1997, Nikos Drakos, Computer Based Learning Unit, University of Leeds, and Copyright © 1997, 1998, Ross Moore, Mathematics Department, Macquarie University, Sydney.

The application of LaTeX2HTML to the Python documentation has been heavily tailored by Fred L. Drake, Jr. Original navigation icons were contributed by Christopher Petrilli.

The reStructuredText to Python LaTeX translator (writer) was developed by Dave Kuhlman with extensive help from the Docutils project and is available from CVS at the Docutils project page at SourceForge.net in project ``sandbox'' under ``dkuhlman''.

---

Introduction to the Documenting Python Writer

---

Release 1.0a, documentation updated on July 1, 2003.