I’ve been playing around with Panda3D for a few weeks now, and I noticed that the reference guide is the only offline downloadable material. I’ve since taken that and made a CHM file out of it, althought this is just my first pass through testing I thought I would try it out.
Would anyone be interested in having the Manual and the Reference in a searchable offline CHM format? I’d like to think that I’m not the only one that might want this. If so, I’ll assemble a better CHM of the Reference for starters and then go from there.
That’s where I got the HTML files to compile the CHM. I’ve got an (almost) fully automated toolchain performing the compilation on one of my systems here thanks to some Python scripting, so it wouldn’t be much of a stretch to go one step further and automate downloading on new release. I say it’s almost fully automated because the indexing isn’t quite there yet, but I could easily add that in.
IMHO, it would be even easier if the individual files were in a neutral XML format and then processed/converted into whatever format was needed (PDF/CHM, etc.), but I think that might be asking too much. Are you using PyDoc to generate your current documentation set?
I forgot to mention that the CHM compiler comes with the free HTML Help Workshop and is command-line friendly. The main file it takes in is an HHP project file, which follows INI conventions. The index and table of contents I’m still looking at in terms of building automatically, but they’re not too difficult.
As for the manual, I know it’s in Wiki format, but it wouldn’t be too difficult to assemble either.
This is just an idea I had since the Panda site was inaccessible to me yesterday and I wanted to look up something in the manual.
Absolutely! I travel a bit and at times don’t have a 'net connection to access the online docs. While there is the .pdf manual available, a searchable .chm version would be very handy too.
Perhaps too, it might spur some interest in completing the online docs as well?
I’ll see about beefing up the toolchain for automated production of the Reference and the Manual. A single source format for both would be the most beneficial, but I think I can work with what is here already in terms of output HTML. Good doc is key to a good system.
All that would be required at that point is notification that a new version is up and I could gen up the CHM files.
Note: the current Reference in CHM format is around 10MB, without any index or TOC. Once those are in compiled in, it will be bigger. So I’m not sure if there is a size issue here.
Okay, after a bit of fiddling, I was able to get a decent CHM compile with an index and TOC generated automatically. With some internal compression applied, it comes out to about 4.2MB.
If anybody is interested in looking it over, let me know and I’ll put it up for review somewhere.
Please note that this is just the Reference, not the Wiki-based online Manual.
The API Reference docs are generated automatically each release. The fact that most functions are marked “undocumented” is a bug in the gendocs.py script, which generates html versions of the reference. It will be fixed in 1.5.4.
Ideally, if we had a python script to automate the process of making a .chm version of the reference, we could implement that in gendocs. Are you volunteering to write such a script?
to have an offline chm manual would be great for me and having a seamless system that implements the mechanics dklon suggested (neutral XML produced by gendocs.py -> chm or whatever else) would be a dream pushing P3D project 1 level up, I think. I’d happy to give a hand if needed.
I’m not sure, but I may have already written such a script. The only caveat to it is that it requires the HHC compiler on a Windows machine to produce the actual CHM file.
I could put the CHM file up for people to look over and see if it is really what they want.
I was looking at the docs for PyCHM, and it looks like it is for accessing the CHM file after compilation. Seems like, in order to compile it, you’d still need a system with HHC installed.
Why not .pdf?Im sorry,i dont know much about the .chm format.Pythons doc is in .chm.But when i use it,i think .pdf could do almost the same thing.
And .chm doesnt open by my default ubuntu apps.
I can do PDF also as a target output, converting the HTML along the way. It’s a little more involved because you have to crawl the DOM tree, but it’s possible to add this into the chain.
In ubuntu, you can install “gnochm” which does a good job opening CHM files. There are also CHMsee, FBreader, kchmviewer, Kchm, xCHM, Archimage, DisplayCHM, CHM Firefox addon, etc and varioius other tools for linux.
dklon, thanks for the script. I’ll try it out as soon as I’m in windows.
Thank you for creating the .chm and making available. From what I can see of it so far, the formatting and content appear to be very good. The search and index functions work as they should and the whole document appears very useful.
