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 |
Technology
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.
Edit selected
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.
- GetHotNewStuff (GHNS) support with a custom server and OCS rant
- Various news in kdevelop, kdev-python, kdev-qmljs
Categories: Everything
Tags: ghns, kdev-python, planetkde
I'm sorry but I am not clear what this is for. What sort of documentation are you referring to? Is this supposed to be just docstrings, or the same sort of data used by something like, say, Sphinx, or some subset/superset of this, or something entirely different? Is this something that has to be distributed by GHNS or can it also be parsed out of the files themselves?
This is about all sorts of data used by kdev-python, such as docstrings, but also "which attributes does this class have", or "how many arguments does this function take".
Usually, this information is extracted from your python code automatically by kdev-python. However there's two reasons why you might still want this:
1) You're using a python module which is written in C, and only exists as a .so file on your hard disks. Well-known examples for this include numpy, or the built-in sys. In this case, the static language analyzer of kdev-python can't do anything, since it can only analyze python code. Here what you can do is run my introspect script on the module, to generate "pseudo"-python files from the binary module (using the run-time information python gives you when you import the module). Those files will not contain the actual code for the module, but only declarations such as def fft(in: cvec): return cvec(). You can then place those files into a special directory, and kdev-python will read them when you use the module in your code.
2) The second case occurs when you have something difficult in your (or a library's code) which kdev-python's analyzer can't figure out. An example for this is modifying the __builtin__ dict in a loop, adding functions. In such a case, you don't want to modify the real python file (since it's what's going to be used by your program), but you could copy that file to said special directoy, and modify it there (and for example list all the functions added in the loop explicitly). That way you'll get good support for the module in kdevelop, but you'll not have to touch your program at all.
You could do all this before manually, but this change proivdes you with an easy-to-use UI to automate most things, and also with the GHNS widget to e.g. share an adjusted version of one of django's modules which has been modified slightly to be better understood by kdev-python's analyzer.
Greetings,
Sven