cgidocs.py

This document describes cgidocs.py, a CGI-based Viewer for the Python Documentation. It includes a hierarchic table-of-contents, an alphabetically sorted index, and a fulltext search engine for all of the python documentation.

Requirements

Python 2.0 or higher.
A MySQL database.
The MySQLdb module for python must be installed.
A webserver. I use Apache, but other common mailservers should work fine, too, provided they can run Python cgi-scripts.
A browser that supports frames and javascript navigation in frames. I have successfully tested cgidocs.py with Konqueror, Mozilla and that other browser.

Installation

First, you should unzip the files in the distribution. You will get the following files:

cgi-bin/cgidocs.py
htdocs/single_item.png
htdocs/expanded_item.png
htdocs/expandable_item.png
mysql/pydoc.sql
other/create-cgidoc-database.py
readme.htm

Creating the database

The first step (provided that you have installed all tools required above) is to create the database. You can do this at the shell prompt using

mysqladmin create pydoc

Here, "pydoc" is the name of the database. You can choose a different name if you want. If the database admin account has a password, you can use the "-p" command line option to specify it. You would say:

mysqladmin -p create pydoc

and then be asked for a password.

The next step is to create the structure of the database. For this, you need to connect to mysql.

From a command line, start "mysql".
Connect to the newly created database.
Execute the SQL script "cgidocs.sql" which is part of the download for this package.

NOTE: Before overwriting the database, please do check if a database named "pydoc" already exists and is in possible use by another application.

Here is a sample session on a Win32 machine:

D:\scripts\cgidocs> c:\mysql\bin\mysql.exe -p
Enter password: **************

Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 1 to server version: 3.23.43-nt

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> connect pydoc;
Connection id:    2
Current database: pydoc

mysql> source cgidocs.sql;
Query OK, 0 rows affected (0.05 sec)
Query OK, 0 rows affected (0.01 sec)
Query OK, 0 rows affected (0.00 sec)
Query OK, 0 rows affected (0.02 sec)
Query OK, 0 rows affected (0.01 sec)
Query OK, 0 rows affected (0.00 sec)
.... (and so on) ...

You can omit the -p option if your database doesn't need name and password. If everything went OK, you now have the data structure set up completely.

Editing the configuration

Before you start, you should edit the settings at the top of cgidocs.py. They are:

# path to the grep binary. For linux, the standard grep will do;
# For windows, use the grep from the cygwin distribution.
GREP_PATH = r"d:\cygwin\bin\grep.exe"

# Directory relative to the webserver, where the documentation files are stored.
# Note that some webbrowsers do not display links to local files, so you
# have to publish the python documentation from your webserver root.
DOCS_DIR = "/Doc"

# Default topic to display
DEFAULT_TOPIC = "/Doc/index.html"

# Root directory for greps
GREP_ROOT = "C:\\Apache\\Apache\\htdocs\\Doc"

# Enable this for GREP search.
ENABLE_GREP_SEARCH = 1

# If this switch is enabled, the documentation over at
# http://www.python.org will be used. But, this means no
# grep search will be available...
USE_PYTHON_ORG_WEBSITE = 1

# Your MySQL Server and Database
MYSQL_SERVER = "localhost"
MYSQL_DATABASE = "pydoc"

# If your MySQL Database is protected by name and password,
# please edit these two variables:
MYSQL_USER_NAME = ""
MYSQL_USER_PASSWORD = ""

Installing the CGI

Copy the CGI to your cgi-bin directory. If your path is not cgi-bin, you must edit the function GenerateLink().

Copy the three icons (*.png) to your webserver root directory.

Copy the python documentation to the webserver root.

That's it! You can contact me if you have troubles installing this.