In addition to this HTML documentation, PyKDE includes class reference documentation completely revised with release PyKDE-3.8. There are two ways to use the class reference documentation: using the supplied documentation viewer ("wabbit") or by generating a complete set of HTML files.
The documentation viewer "wabbit" uses a specially formatted text file generated from the KDE h files and PyKDE sip files to generate HTML "on the fly". wabbit works like a (crude) HTML browser - it has "forward" and "back" buttons, allows bookmarking, and has user configurable fonts. It also allows the user to annotate the documentation. The PyKDE documentation is fairly lightweight, giving Python formatted versions of methods and indicating which methods have modified argument lists or return types. If you have the KDE Class Reference documentation installed, the PyKDE documentation can be displayed in wabbit's top pane and will link and sychronized with the KDE documentation in the lower pane. The KDE documentation in the lower pane can also be browsed independently.
wabbit can also be used as an HTML generator.- it will produce a complete set of HTML docs (about 2-3MB) which can be viewed with any HTML browser. The generated HTML can also provide links from the PyKDE docs to the more complete KDE docs. If the KDE docs are on the local machine (for either the self-contained browser or generated HTML), linking is at the method level. Additionally, the generated HTML can link to the online KDE docs, but only resolves to the class level.
wabbit is written in Python (of course) using PyQt (of course).
This section gives an overview of using the wabbit doc browser. A later section details configuration and installation.
wabbit currently installs to /usr/bin, so wabbit is invoked by running "wabbit" from any location.
Here's the opening window of the wabbit viewer. Of course the entire viewer can be resized, as can the panes. The upper pane is displaying the main page of the PyKDE class ref docs; the lower pane is displaying the main page of the KDE class ref docs.
wabbit does not have menus - all functions are initiated from the upper and lower toolbars. The upper toolbar controls the upper pane, the lower toolbar controls the lower pane.The back and forward buttons for each pane should be obvious. Here's a look at the rest of the top toolbar with the buttons labeled:
The buttons are:
Here's another wabbit screenshot showing wabbit displaying a method. The lower pane was synchronized to the upper pane by left-clicking on the method name.
Bookmaring and annotating in wabbit's upper pane are to the method level only - classes or other pages can't be bookmarked. If you right click on a method name (as in the above image), the context menu will pop up with the Add Bookmark and Annotate choices enabled:
If you right click outside the method name area, the menu will still pop up, but with the Add Bookmark and Annotate choices disabled:
The upper and lower panes maintain separate bookmark lists and back/forward queues. The lower pane cannot be annotated. Synchronization is only from the upper pane to the lower pane, not it the other direction. You can delete a bookmark from the bookmark list by right clicking a bookmark in a list and clicking "delete" from the popup menu. You can delete an annotation by right clicking the method to which the note is tied and deleting all text in the edit dialog that pops up. You can similarly edit/modify annotations.
When annotate is selected from the context menu, an edit dialog pops up:
If you choose to save the annotation, it will be placed like this:
Annotations can be as long as you want, and can contain HTML formatting tags. Annotations are saved separately from the PyKDE class ref data, so in theory they should survive from version to version, even if new PyKDE class ref data is used.
wabbit should be installed correctly when you install PyKDE, but the path to the KDE Library Class Reference Docs is not set up at that time. To set up these docs, you first need to obtain them if you haven't already. The set that wabbit was designed to work with is at ftp://ftp.kde.com/pub/devel/kdeapidocs/kdeapidoc-cvs.tar.bz2 They need to be untarred to a local directory, as wabbit currently doesn't read compressed files.
Other versions may work with wabbit but have not been tested. The Online KDE Class Reference docs will NOT work with wabbit, as they use a different hierarchy for file naming. The anchors for the online version are also not usable to the method level - only to the class level.
Once you have the KDE docs downloaded and installed, start wabbit and click the Configure button. You should see the following dialog:
Enter the path to the "classref" directory (the top level directory for the docs) in the "Path to KDE Class Ref" edit box, or pop up a directory selection dialog using the button to the right of the edit box. Click "save" and the cofiguration is done.
If you have moved the PyKDE class ref data or PyKDE docs, you can specify the new locations in the configuration as well. The "Path to PyKDE Classref" field should contain the path to the subdirectory that contains PyKDE's "classref.txt" file. The docs field should point to the location of the directory that holds the PyKDE docs' "index.html" file.
If you move "classref.txt", you must move all of the files that were in the original directory (initially docs/wabbit/data/) to the new location as well.
Configuration data is stored in the file ~/.wabbit/wabbitrc, and covers the three paths mentioned above, the window location and size, splitter position, and font selection for each pane. All data is automatically saved at exit. wabbit's icon files, notes file and bookmarks file are stored in the same location.
If you prefer to use a standard browser instead of wabbit, or just want a set of HTML files for the PyKDE Class Reference docs, wabbit can also generate a complete set of HTML files with either the same linkages to locally stored KDE docs or to the online KDE docs.
Clicking the Generate HTML button will bring up the following dialog:
If you choose to link to local KDE docs, put the path to the docs in the "Path to KDE Classref" edit box as for configuration above (if not already done). If you check the "Use internet links to KDE" checkbox, you can leave the upper edit box blank. The path for online KDE docs is hardcoded in wabbit.py in the HTMLDlg.slotSaveClicked method and is currently set to "http://developer.kde.org/documentation/library/cvs-api/" The HTML files generated will be written to the path specified as "Path to PyKDE Docs" (the lower edit box), starting at "classref/" with one subdirectory for each module.
Click the "Save" button to actually generate the HTML files. It should take something like 2 to 10 seconds (depending on CPU speed) to generate the full set of HTML docs with links.
The online docs use a different file hierarchy for the HTML files and the anchor naming scheme only allows linking to the class level. Clicking on a method link in the PyKDE docs will only take you to the KDE class, not all the way to method clicked.
The HTML files/KDE doc links work well with tabbed browsers like Mozilla or Konqueror.
wabbit may have a few minor formatting glitches remaining, but shouldn't have any showstoppers. This is, however, the first public release of wabbit and other bugs may pop up.
wabbit currently uses QTextBrowser (so technically it could be used without PyKDE being installed). Some of the KDE docs' HTML isn't compatible with QTextBrowser - mainly the module pages. An empty table (I think) in the KDE pages generates a huge amount of white space between the header and body of these pages. Future releases may include a script to "fixup" the KDE HTML. The whitespace problem occurs randomly in my tests.
Also, the black square in the first screenshot on this page is caused by being unable to locate an image from the path given in the KDE HTML.
For multiple methods with the same name, wabbit will only synch the KDE pane to the first method in the group. Annotating a method which is one of multiple methods with the same name will casue the annotation to appear with all same-named methods.
As always, bugs should be reported to the PyKDE mailing list at PyKDE@mats.imk.fraunhofer.de . Subscribe to the list here
wabbit is an experiment in providing more complete docs. I'd like to hear comments or criticisms on the PyKDE list. (Subscribe to the list here)
Major changes in the way KDE docs are produced might lead to difficulties with the linking feature of wabbit. In addition, if wabbit isn't used with anything other than PyKDE, it might be more useful to change wabbit from using QTextBrowser to using KHTML widgets, or work being done currently on KParts might make it possible to deliver wabbit as a konqueror plugin without having to generate HTML (I would prefer to eat my own dogfood) The main reasons HTML files aren't provided are to allow linking to the KDE docs, and to keep the size of the PyKDE tarballs smaller.
If wabbit diminishes in usefulnees, proves too hard to install or use, or hardly anybody likes it, it will probably be dropped in favor of something else. Suggestions/alternatives are always welcomed. One of the big advantages of wabbit-style data files is that they can be generated automatically (with minimal markup necessary) using mostly the same code that already generates the PyKDE sip files.
I have looked into (and already answered a question on the PyKDE list about) using something like wabbit with PyQt. There are a number of problems with doing PyQt docs this way because of the differences between Qt and PyKDE (more Qt h files declare methods without argument names), the number of versions PyQt supports (obsolete methods also won't get argument names - this is very hard to fix), differences in how PyQt and PyKDE are generated and other factors.
The present plan, however, is to generalize wabbit or wabbit's HTML generation to be usable for any bindings whose sip files are automatically generated using presip (since that's the same method used to generate wabbit's doc data).