README for gendoc
=================

Contents:

* Short intro
* Release notes


Introduction
============

'gendoc' is a tool to generate manual pages from Python source code.
Read the docstrings in gendoc.py for instructions how to use the
tool.

'gendoc' has the notion of formatters, which emit manual pages in
different formats (currently HTML, FrameMaker and ASCII). The
most widely used formatter is probably the "HTMLg" formatter, which
uses Robin Friedrich's HTMLgen module. You need to grab HTMLgen
separately (you can find it at http://starship.skyport.net somewhere).

If you use HTMLg, you will notice some weird names (M. Python) on the
generated pages. There is a file called "HTML.rc" in the "formatters"
directory, which controls a number of things when generating the
HTML code. Have a look in the file!


Release notes
=============

gendoc release 0.73 (1998-05-25)
===============================
Removed use of obsolete codehack module (thanks to
Lars Marius Garshol).

gendoc release 0.72 (1998-05-20)
===============================
Small fixes, and fixed (hopefully) the distribution.
Sorry for the delay, but I've been extremely busy at
work lately...

gendoc release 0.71 (1998-04-01)
==================
Minor fixes from Python community.
Added function calling interface.

gendoc release 0.7 (1998-01-19)
==================
This release just contains minor fixes to make it work with
python 1.5.

gendoc release 0.6
==================
Again, this release is done the day before my 4 week vacation
in Spain. This is a somewhat hasty release, so I guess I might
expect the Spanish inquisition when I come back. Anyways, most
setext markups are now gone in favor of Jim Fulton's structured
text approach. This means some new goodies, such as nested and
numbered lists, definition lists and nested headings.

Take a look in gendoc_test.py to see how to write your markups.
By my mistake, the previous releases missed the important file
'gendoc', which is the main program (just imports gendoc.py).
This is now corrected. The Makefile now uses BSD style install,
instead of the HP/UX convoluted version (thanks to David Morley,
morley@aaii.oz.au).


gendoc release 0.5
==================
Not wanting to break a long python tradition, I release this
on the last day before my vacation. I'll be back august 5.
Hope you like the tool, and if not, please tell me what you
would like differently. Anyways have a good summer!

New features:

- HTMLg formatter can generate index page as frame
  (Thanks to Robin Friedrich).

- Special actions for module variable '__author__'.

- Bug fixes for the import mode.

- setext bug fixes: hyperlinks now work.

Did some simple measurements on gendoc generating HTMLg
documentation for all python modules in the standard
ditribution (almost) (HP 712/80Mhz):

gendoc -i (import mode)    gendoc -p (parser mode)
-----------------------    -----------------------
real    6m19.93s           real    1h26m31.63s
user    1m56.36s           user    22m29.63s
sys     0m10.41s           sys     0m47.38s


gendoc release 0.4
==================
New features:

- HTMLg formatter inserts navigation button links.

- Supports Python 1.4 (thanks to Fred Drake's updated docco tool).

- Bug fixes:
  * Bullet lists.
  * Double underscores made the setext regexps confused.
  * Problems with character escaping fixed.


gendoc release 0.3
==================
This release features a number of changes since the last release:

- Started using packages.

  - Most code is in the Gendoc package

  - The formatters are in the Gendoc.formatters package

  Formatters are searched for and found automatically once they are put
  in the formatters subdirectory.

  Hopefully this will make it easier to add new formatters. Comments
  on this approach is welcome.

- The MML formatter is now working.

- Added HTMLg formatter, based on Robin Friedrich's HTMLgen module.

- Options to gendoc are changed. To choose a formatter, use the -f option.

  -f HTML   - old HTML formatter
  -f HTMLg  - new HTML formatter, based on HTMLgen
  -f MIF    - FrameMaker MIF formatter
  -f MML    - FrameMaker MML formatter (replacement for MIF)
  -f ASCII  - ASCII formatter

- Added support for setext hyperlinks. See example use in Gendoc/setext.py
  (last three lines in the module docstring).


gendoc release 0.2
==================
This is an upgraded release of the gendoc tool (I should probably come
up with a more pythonish name then this...).

I've integrated the front end of Martin Chilvers' docco tool, which
means gendoc can also generate docs by parsing files. The "old" way
of importing modules is still supported, and I haven't touched much
of it. Eventually I want to do a complete rewrite of that since the
code is a terrible mess (I know, I wrote it...).

I would be very grateful if people would try this out and send me
suggestions, bugfixes and formatters for LaTeX, RTF, and ... :-)

Anyways, It supports the following formats:

- Plain old ASCII

- HTML (no indexing though)

- MIF (FrameMaker Interchange Format), with automating indexing

- very crude MML (also a FrameMaker format, but much simpler).
  Since I hacked this after lunch today, I probably needs some
  adjustments before it is usable. For instance I can't make
  code fragments look good. It all gets flowed, which is less
  than appealing.

I've added support for some setext markups:

 **this is shown in bold**

 ~italic~
 ~the~ ~setext~ ~specification~ ~states~ ~that~
 ~you~ ~must~ ~do~ ~this~ ~to~ ~mark~ ~up~
 ~multiple~ ~words~!

 _underlined_text_

Understanding numbered lists and definitions are things I would
like, but haven't done yet.

Jim Fulton told me he had some code for doing things with docstrings,
but I haven't looked at it yet. I'll do that.

Anyway, please help out if you can. This is supposed to be a
collaborative effort to come up with one really useful documentation
tool for the Python community.

--
Daniel Larsson
dlarsson@sw.seisy.abb.se