Finally, after a few days of difficult work, it’s here: the prototype for kdev-python’s new GHNS support for documentation data!
|kdev-python now has its own settings module providing GHNS support|
I don’t want to go into detail here (I’m a bit sick of this stuff currently *grin*), but the OCS backend is written by me and running on my own server currently, for testing purposes. It’s python2 / django using MySQL as database backend, and nginx for a web server. You can register a new user acoount here (admire the awesomeness of stylesheet-free default template files!). The backend is extremely incomplete and doesn’t support most operations. Basically, you can upload an item with a title and a description, and download it again. No screenshots, no license types, no ratings, no download counter. Oh, but the search works. 😉
The upload dialog requires current kdelibs 4.10 (stable doesn’t work) because of a bug I fixed there which prevented changing the provider to something other than the default opendesktop.org one.
There’s also a patch of mine pending review for libattica to fix a bug causing annoying spoof-checker warnings to be displayed when connecting.
The feature is currently residing in the “ghns” branch of kdev-python, so if you want to try it, you’ll have to compile that branch.
Use cases and tools provided
In addition to GHNS integration, I also implemented a set of tools for “develpoing” documentation data. In the following, I will describe them and their purpose. This, once more, is the KCM (you can access it via KDevelop » Configure KDevelop » Python Documentation Files):
|The new KCM, once again|
The “Download new” tool
This one is pretty obvious: you can download documentation files created by other users. You are presented with a list of content and you can install and uninstall the individual packages with one click each.
The “Share selected” tool
The widget allows you to select any amount of files or directories to put into an entity you consider useful to share in the widget on the left, and upload them. A tar.gz archive will automatically be created from the selected files, all you have to do is enter your user name and a title for your package and click upload.
If you select no files, you can chose a tar archive you created yourself.
Packages should be for one Python module specifically. Please don’t make packages which are like “CoolNick47™’s perfect collection of kdev-python docfiles”, but keep them very specific, e.g. “Documentation for numpy.fft” or “django 1.5 fixes”.
The “Generate” tool
This tool starts a little wizard which helps in bootstrapping docfiles for totally undocumented modules, such as those written in C.
|The docfile generator wizard, for creating docfiles from python C modules|
It allows you to enter the name of any python module and let a script generate documentation for it based on introspection and docstring parsing. You can inspect the result and decide whether it’s worth saving or not.
The script being run is introspect.py from kdev_python’s DATA_INSTALL_DIR, so if you like, you can run it manually. The dialog is mainly there for discoverability of this feature.
The dialog also takes care of putting the result files in the correct location.
The “Import from Editor” tool
This tool copies the contents of the file currently open in the editor to a new file in the documentation directory and opens the new file in the editor. This might seem a bit weird at first, but it has a very clear use case: you discovered an error in an existing source file which was bundled with kdev-python, or, equally likely, a file from some Python library which contains a section kdev-python’s analyzer does not understand. If you find out about this, you will most likely have that file opened at the moment (that’s how you found out, right?), so here’s an easy method to modify it — in a way which only kdev-python, but not your real application will notice.
Open File Manager
Opens a file manager in the docfile directory. Whatever you might want to do with it, I can imagine a few things.
Opens all selected files in KDevelop’s editor in the background so you can adjust them.
List of missing things and other issues
This feature is not completely done yet, it’s missing a few things, notably
- The server must corretcly save all fields which you can fill out in the upload dialog, currently License, and the preview images don’t work.
- The server does not handle editing content correctly (it’s implemented but I was too lazy to test it so I assume it doesn’t work)
- A better way to host the server must be found. I’ll talk to the KDE sysadmins about this. At least, the file with the server URL should be somewhere on kdevelop.org, not on my (totally unrelated) domain.
- The dialogs need more visual feedback about which actions work (disable buttons etc.)
- The dialogs do not handle subdirectories correctly, e.g. they are not being created automatically and some can’t even write into them yet. This is rather urgent to fix, I’ll do it asap.
- Users which actually use the tool are very much needed! 😉
That’s all, I hope it’ll be useful! If you think something else would be good to have in this area, please let me know.