Today, I decided to make an offline version of the Panda API and an API of Airblade. You can get them at http://home.earthlink.net/~lvraab. Feel free to make suggestions, critiques, etc. Just don’t go all out flaming me.
Kudos also to the HappyDoc team.
As it turns out, the API reference on the panda website was generated using epydoc. Also as it turns out, recent changes to panda have made it very hard to use epydoc any more. Epydoc wants to import everything, but this has the effect of actually deleting files when it imports the genpycode source. Not nice.
I like the organization of the documentation produced by epydoc much better than the organization of happydoc. Happydoc seems to want to organize everything by directory and file. Most people don’t know what directory a class is in, they only know what class or subroutine they want reference on. So having the classes and global subroutines at the top level is ideal.
So I seem to have two choices: modify epydoc to make it more robust, or modify happydoc to change the data organization. I don’t know which is easier or the better idea.
Any insights?
I’m glad somebody else is thinking about this. My plate is really full.
Remarkably, I was just looking into getting the epydoc stuff to work earlier today.
There were a couple of issues I had to work around, and there are still some errors that cause a few modules to be omitted, but I was able to create a fairly complete set of documentation.
Interestingly, genPyCode threw an error regarding FFIInterrogateDatabase, so I didn’t run into the same problem you did with the code being regenerated. The issue, of course, is that epydoc imports all of the modules and generates some of its information based on inspection, so if you have any modules that have side effect on import, you can run into problems.
The best way to fix situations like this is to put if name == “main”: around any code that is expected to be executed as a standalone script. That way it won’t cause problems when it’s imported as a module. I had to do this for ParticleFloorTest as there was some code in angularEulerIntegrator spewing output onto stderr. Running epydoc turns out to be a good way to find misbehaved code.
You can find the stuff I just built here:
http://www.schellgames.com/temp/PandaEpydocs.zip
I plan to work through the remaining errors and get it to run cleanly on the entire source tree. At that point it should probably be handed off to the ETC.
Awesome! Thank you very much. I was wondering if I’d ever have time to take care of that.
- Josh
There’s now a PDF version of the Panda manual that I made that’s in a ZIP file at the same site.