Re: [Epydoc-devel] chm files

[Daniele V. <pi...@de...>]

Jürgen Urner ha scritto:
 > Daniele Varrazzo schrieb:
 >> Jürgen Urner ha scritto:
 >>
 >>> Hello,
 >>>
 >>> ...didn't know epydoc is under active developement again.
 >>>
 >>> I just would like to ask if someone is already working on on some
 >>>
 >> mechanism to generate microsoft *.chm files from epydoc output.
 >>
 >>> If not, maybe someone here is interested in joining forces to add this
 >>>
 >> feature
 >>
 >>> to epydoc?
 >>>
 >>> Jürgen
 >>>
 >>>
 >> Hello,
 >>
 >> i think .chm output would be a nice feature, and i think easy enough to
put together.
 >>
 >> My experience is very limited, but it seems chm are just a bunch of html
files together with an index, a ToC and a project file: Epydoc should
produce only a few files more than what the html writer already does.
The
 >> HTML generator already builds identifiers and terms indexes, so it's
probably just a matter of reformatting them to get them right for the
.chm: the informations required are already there.
 >>
 >> There is a open feature request for chm files (SF #938921) where Robin
Dunn posted a script to generate support files to compile a CHM version
of
 >> Python docs: if i had to start with a .chm writer i would start from there.
 >>
 >> I'd work for it after the 3.0 has been completed; any help you may give
would be appreciated and would help us to quickly have chm support in
the
 >> 3.1 alpha development line.
 >>
 >> Thank you very much,
 >>
 >>
 >
 > Yes, I thought of something like simply parsing over the html output from
epydoc, bringing the htmls into adequate form (removing frames
....).

The .chm writer would omit to write frames-related stuff, as the html writer

does with the --no-frames option (as should have done, actually... fixed in 
r1550). I wouldn't perform a post-processing of epydoc pages: instead i'd 
subclass the current HTMLWriter to directly let it create the required
files.
What other difference should be taken into account to create html files to be
chm-compiled? Remember that much customization can be performed using an 
appropriate css stylesheet.

 > I already have a some modules at hand. One to generate all the required
files for micros html workshop compiler (needs rework, ugly code!) and
one for
 > parsing and bringing into shape html files. All not heavily tested,
though working.

Can i have a sample of how the hhc, hhk, hhp file should appear? You may use
the tracker item above to post the files, to keep all the chm stuff together
(i marked the item as to be done for 3.1 release; now i'm mostly focused on 
functional testing for the 3.0 release).

A question: can the index and table of content contain actually different 
indexes? We can generate the class index and the modules indexes, and we can
generate an identifiers and a term definitions tables of contents: it would be
nice if all could fit into the compiled help without having to mix classes 
with modules and terms with identifiers. It's not a great issue anyway,
mostly   curious...

 > Think I could throw this together in a few weeks to a working alpha. But
the thing I can not do is test it on linux. AFAIK, Wine supports micros
compiler
 > and it would be nice to support this.

I've never run it on Wine (actually, i've never run it at all :) but it 
doesn't seem an issue to run the compiler once you have the project [1]. We 
should add a --chm-compiler option to tell epydoc the command line to run;
the
files generation could be performed even if the compiler were not available or
couldn't run on the current platform anyway.

[1]
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/htmlhelp/html/vsconprjcmp7.asp

 > And ....of course, I'd welcome any help or advice on implementation
details.

Just for a pointer, the indexes are created in the epydoc.docwriters.html.py

module, in the HTMLWriter.write() method. I think the informations required to
create chm indexes are the same gathered here: i guess it's a matter of 
creating pages with different format and names for the indexes to be passed
to
the compiler. The class should be refactored so that a ChmWriter could be 
easily subclassed from it, but apart from changing the implementation of the
indexes pages writing, i think there not much stuff to be done.

Probably the list of files to be included in the project should be created 
reading back from the disk every file which has been written in the output 
directory: this way also images (which may be more difficult to track: think
about images generated by docutils directives such as the math formulas we are
everybody expecting...) may be included in the chm project.

Finally, adding a --chm action to the command line and the hook for the chm 
compiler should be done in the cli.py module.

Regards,

-- 
Daniele Varrazzo - Develer S.r.l.
http://www.develer.com