Python LaTeX Setup

---

 
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 Introduction
  • 2 Where to Get the Source (for This Support)
  • 3 Instructions -- Step by Step
    • 3.1 Step 1 -- Install the Python Source
    • 3.2 Step 2 -- Install Needed Related Software
    • 3.3 Step 3 -- Install the icons
    • 3.4 Step 4 -- Create an Input Document
    • 3.5 Step 5 -- Create a Makefile to process your documents
    • 3.6 Step 6 -- Run the makefile to process your document
  • 4 Hints and Suggestions
  • 5 Summary
  • 6 Acknowledgements

 
1 Introduction

The Python LaTeX system is excellent for producing documentation on Python code, extensions, programs, etc. "Documenting Python" explains how to write LaTeX documents for input to the Python LaTeX system. The document you are currently reading provides instructions on how to do the setup needed in order to process documents through the Python LaTeX system.

Additional very helpful information on using the Python LaTeX system is in Doc/README in the Python source distribution. This is a must read.

 
2 Where to Get the Source (for This Support)

A distribution file containing a Makefile, the reStructuredText source for this document, a template for reSturcturedText source documents, etc is in http://www.rexx.com/~dkuhlman/pythonlatexsetup.zip.

 
3 Instructions -- Step by Step

Briefly, you will have to perform the following steps:

1. Install the Python Source

2. Install Needed Related Software

3. Install the icons

4. Create an Input Document

5. Create a Makefile to process your documents

6. Run the makefile to process your document

Read on for more details.

 
3.1 Step 1 -- Install the Python Source

You will the source distribution for Python. You can obtain it from Python.org.

I'm not sure that you have to install Python from source in order to use the documentation system. But, it's easy, so why not build and install it. Doing so will also help you appreciate the incredible work done by the Python project to make Python build-able and usable.

 
3.2 Step 2 -- Install Needed Related Software

In my case, since I wanted to generate HTML, I had to install LaTeX2HTML (99.2b8 or newer).

Other software requirements are described in Doc/README in the Python source distribution.

If you want to use reStructuredText (reST) as your source documents and to translate reST source files into Python LaTeX files before processing with the Python LaTeX system, as I often do, then you will also need the following:

1. Docutils

2. The Python LaTeX writer for Docutils

 
3.3 Step 3 -- Install the icons

Needed for HTML output.

If you look in the generated HTML files, you will see links to icons. You should make these icons available in a directory that is a sibling of the directory in which the HTML file will be installed. In my case I do the following while in the directory containing my source document:

$ ln -s ${PYDIR}/Python-2.3b2/Doc/html/icons/

Alternately, copy the icons directory and its contents.

And, when you install the generated files in another location, you will need to make the icons available there, also.

 
3.4 Step 4 -- Create an Input Document

There are (at least) two methods for doing this.

 
3.4.1 Copy a template

There are templates or skeletons for LaTeX documents in Doc/templates/ in the Python source distribution. This directory contains the following templates:

• howto.tex -- Use this skeleton as a starter for moderate length documents. Unless you anticipate a very long document or have special needs, this is probably the template to use.

• manual.tex -- Start with this skeleton if your document will be exceptionally long. Since the manual document type is the only one which uses the chapter LaTeX mark-up, I'm suggesting that you consider using this template only when you anticipate producing a large document the size of a book.

• module.tex -- This is a not a document type, but is intended a section to be included in a longer document. In particular, it is intended to form the basis for documentation on a module to be included in another Python LaTeX document. For examples, of the use of this template see the documents in the Doc/lib directory of the Python source code distribution.

 
3.4.2 Create a reStructuredText document

There is now support for translating reST documents into Python LaTeX documents. This support has not been released yet, but is (in my not-so-humble opinion) usable. In fact, I'm using it to process the document that you are currently reading.

In order to use reST you will have to install the following:

1. Docutils

2. The Python LaTeX writer for Docutils

You can use the source document for this document (pythonlatexsetup.txt) as a sample for your reST source document.

Using reST as your source format has the advantages of making writing documents exceptionally easy and eliminates the need to learn LaTeX. It has the disadvantage of not providing much of the power of the mark-up described in "Documenting Python".

 
3.5 Step 5 -- Create a Makefile to process your documents

Here is a skeleton for a Makefile that produces HTML. Read the comments to learn how to modify this source file for your specific needs:

# 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=pythonlatexsetup
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

To learn the options for the Python LaTeX system, run "Doc/tools/mkhowto -help" in your Python source code directory .

 
3.6 Step 6 -- Run the makefile to process your document

Given the above Makefile, execute these commands:

$ make SRC_NAME=mysrcname clean
$ make SRC_NAME=mysrcname

This will produce a subdirectory under the current directory that contains the resulting files.

 
4 Hints and Suggestions

The trailer information at the bottom of generated files comes from Doc/html/about.dat in the Python source code distribution. You can edit this file to add your own custom output. Or, you can create a new file, then use the "-about" option to the mkhowto script (see the Makefile above) to specify your own file.

 
5 Summary

It seems like a lot. But, after you've done it once, you will find that copying a Makefile and making a few edits etc is very quick.

 
6 Acknowledgements

Thanks to Fred Drake and others working on the Python documentation project.

Thanks to David Goodger and others working on the Docutils project.

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

---

Python LaTeX Setup

---

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