epydoc-devel

[Epydoc-devel] chm files

[<jU...@ar...>]

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



 

Re: [Epydoc-devel] chm files

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

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,

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

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

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

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.

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.

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

Thanks for feedback, Jurgen

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

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>  
>  >
>  > 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.
>   

That's a clean option, if if not too difficult to implement. Difference 
sould be only to get
rid of the browse frames 'cos all browsing is handled by the chm window.


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

I'll prepair some samle files and post them as soon as I find the time.

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

No, I don't think this possible. HelpWorkshop supports plugging together
multiple chms but the index is generated as one from all chms.
But one can freely name keywords as they appear in the index or if it
comes to that, provide some meta keywords.


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

No problem to generate the required files without actually compiling.
Commandline ....you actually feed the compiler  an *.ini file like 
project file with
all required data. Things like:

- where is the index file
- where is the contents file
- title of the window
- buttons to show
- a dozen more.....

so a single chm option might be a bit uncomfortable. But I have to take 
a closer look at it.



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

Images (and css and javascripts) are handled by micros compiler. As long as
they are linked correctly they are automatically included in the 
project. So that's
easier aswell to handle on an already dumped tree ++ you have to know 
wheter
a folder contains subitems or not. So there is a some lookahead necessary.


It all boils down to two methods

def has_intersting_subitems(item):
    # yes, give it a folder icon
    # no, give it a file icon

def get_index_page(items):
    # locate the item to be displayed when clicking on a folder in the tree


to get a contents tree like this:

<chm>
    <item name="root" local='root.html' icon="folder">
        <item name="page1" local="root/page1.html"/>
        <item name="page2" local="root/page2.html"/>
    </item>
</chm>

other names in the contents file ...Html not Xml, but it should give the 
idea.

But I don't know what epydoc offers to handle this. Or if it there is need
to process intime rather than processing an already dumped tree.



> 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,
>
>   

Jürgen

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>> 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).
>>
>>     

There seems no way to attatch files in tracker comments, so I dumped some
samples and links for further reading into the comment box of the tracker.

Jürgen

Re: [Epydoc-devel] chm files

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

> Daniele Varrazzo schrieb:
>>> 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).
>>>
>>>
>
> There seems no way to attatch files in tracker comments, so I dumped some
> samples and links for further reading into the comment box of the tracker.

Thank you for the exaustive description: it will be very useful to put
together the chm support.

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

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>> Daniele Varrazzo schrieb:
>>     
>>>> 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).
>>>>
>>>>
>>>>         
>> There seems no way to attatch files in tracker comments, so I dumped some
>> samples and links for further reading into the comment box of the tracker.
>>     
>
> Thank you for the exaustive description: it will be very useful to put
> together the chm support.
>
>   

I am currently fiddeling along on a Chm generator. If you like you may
take a look...

http://frogpie.svn.sourceforge.net/svnroot/frogpie/trunk/sandbox/chm


Jürgen

Re: [Epydoc-devel] chm files

[<jU...@ar...>]

Daniele Varrazzo schrieb:
>> Daniele Varrazzo schrieb:
>>     
>>>> 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).
>>>>
>>>>
>>>>         
>> There seems no way to attatch files in tracker comments, so I dumped some
>> samples and links for further reading into the comment box of the tracker.
>>     
>
> Thank you for the exaustive description: it will be very useful to put
> together the chm support.
>
>   

...took a bit closer look at epydoc now and ran a test compile.

Everything works fine, micros compiler is complaining
about the xml decls in the html files, but does the job.

Generating a Chm from epydoc seems to be no more
than running a parser over the generated html output
to bring the (dotted) names epydoc throws out into
hirarchical form ++ a bit of this and a bit of that.
Should be no problem to get some reasonable output in a few
days without even toutching the internals of epydoc.

In case you are interested, see: chm_doc.py

http://frogpie.svn.sourceforge.net/svnroot/frogpie/trunk/sandbox/chm


BTW: epydoc looks great as Chm. Congrats....


Jürgen