ChEeTaH's - Open Source

Drupal Development made easier with Qt Assistant - Part 4

ChEeTaH — Sat, 22 Jan 2011 23:15:13 +0000

Welcome to the fourth and final part of this series of blogs. Last time we created and finished our PHP preprocessor, which helped us overcome some quirks in the Drupal documentation. Before that, in part one we prepared our system and in part two we configured the most important pieces of Doxygen. Read part 3a and part 3b for the work we did on the PHP Preprocessor. This time, we'll use my own DoxyAssist tool to have lots of work done for us automatically. Time to make the documentation useful!

Good base

Having fully configured and fixed most of Doxygen last time, for Drupal in its entirety, there is a nice base to work from. The next step is now to install the DoxyAssist scripts to a location you like. DoxyAssist will help - especially Drupal projects - to build modular documentation. Rather than just ending up with one big bundle, DoxyAssist will split core and contributed modules from each other. The contributed modules will each get their own Doxygen run which creates separate sets of help pages.

Next, DoxyAssist automatically combines all those separate files back into one Qt Help Collection. This collection can be used nicely in the Qt Assistant. Making use of filters in the UI of the Assistant, it becomes possible to view all documentation together, or documentation of just the specific modules.

Project File

DoxyAssist uses projects and subprojects to determine what part of a source code project to include or exclude in each separate run of Doxygen. Special support is available for Drupal, which makes DoxyAssist automatically discover the subprojects (contributed modules, themes, etc) in the "sites" directory.

So we create an XML file which tells DoxyAssist where to find the source code, which base Doxyfile it has to use as a base, and which options to override. Additionally it also specifies some options for Qt Assistant. These last options will determine what features are available in the assistant when opening the collection.

In this example I assume the base Doxyfile is correctly set up for Drupal. See part 3b if you want to download the latest version, but make sure you adapt it to your environment. Next open up your text editor, and paste in the following as a start:

<?xml version="1.0" encoding="utf-8"?>
<DoxyAssist xmlns="http://simply-life.net/doxyassist/doxyassist.xsd"
            xmlns:da="http://simply-life.net/doxyassist/doxyassist.xsd"
            version="1.0" type="drupal" name="Drupal API">
    <doxygen doxyfile="/home/cheetah/public_html/drupal/Doxyfile" />

As you can see in the part above, we first set up some base things like XML Namespaces. We say the project is of a "drupal" type, and we use version 1.0 of the DoxyAssist configuration format. We have a name for the configuration, and finally tell DoxyAssist which base doxyfile we use. Make sure you edit the path there!

The next part we add are the options for Qt Assistant:

    <qtHelp collectionFile="/home/cheetah/.local/doc/drupal-6.qhc"
            projectFile="/home/cheetah/.local/doc/drupal-6.qhcp"
            storage="qch" copyAction="copy">
        <title>Drupal API Documentation (6.x)</title>
        <startPage>qthelp://org.drupal.6-x/org.Drupal.6-x/main.html</startPage>
        <applicationIcon>drupal.png</applicationIcon>
        <enableFilterFunctionality visible="true">true</enableFilterFunctionality>
        <enableDocumentationManager>false</enableDocumentationManager>
        <enableAddressBar>false</enableAddressBar>
        <cacheDirectory>drupal6/api</cacheDirectory>
    </qtHelp>

The paths to the collectionFile and projectFile are somewhere where they won't be in the way during every day tasks. The separate qch files will be kept within a "qch" subdirectory (the "storage" attribute), and they will be copied from the Doxygen output directories. Other options include "move" (which will move the compressed help files away from their original Doxygen directories) and "symlink" (create a symbolic link to the original location).

The options that follow define the interface of the Assistant. More details about those options are available in the Qt documentation. Note the applicationIcon: this has to exist in the same directory as where the collectionFile is placed. It will allow you to use a special icon for your Drupal assistant - you can also just omit it if you don't want to spend any time on it.

Now for the interesting stuff: defining our Drupal (6) project:

    <drupal>
        <name>Drupal</name>
        <version>6.x</version>
        <versionSpecific>true</versionSpecific>
        <input>/home/cheetah/public_html/drupal</input>
        <exclude>/home/cheetah/public_html/drupal/backup</exclude>
        <exclude>/home/cheetah/public_html/drupal/doc</exclude>
        <output>/home/cheetah/public_html/drupal/doc</output>
        <logDirectory>/home/cheetah/public_html/drupal/doc/log</logDirectory>
        <namespace>org</namespace>
 
        <!-- The following are Drupal specific options! -->
        <groupBy>name</groupBy>
        <buildCore>true</buildCore>
        <buildModules>true</buildModules>
        <buildThemes>false</buildThemes>
        <latestContribOnly>true</latestContribOnly>
    </drupal>
</DoxyAssist>

Oh, and we close up the open DoxyAssist tag as well. But before that, we define our project with a name and version tag. We want version specific builds, which means the project version names will be included in the final output. It makes it just a bit easier to find out the versions later on. In the input option, we tell DoxyAssist where to look for the Drupal source code. We also add some directories which we want to skip. That includes our output directory, where Doxygen will write all its files to. There is also a separate directory where the log files of Doxygen will be written to, such that each (failed) documentation build can be investigated separately, if the need arises.

Finally, the namespace is the base namespace used in Qt Assistant. DoxyAssist will automatically append the project name ("Drupal") and version ("6.x") to this. For modules, this will be followed by the module name and version in a similar way. In Qt Assistant, these full names will help the Assistant to distinguish all the pages, since there will be some overlap - especially for common pages.

So far the options have been largely the same as for any (generic) DoxyAssist project. The next set is specific for Drupal. They will determine which items to build (Core, contributed modules and/or themes), and whether to include all versions of a project, or just the latest version. The latter is especially useful if you have a multi-site install, where some sites still run older versions of modules.

The groupBy option is especially important: this identifies how to group documentation of contributed modules. The value is a key in the .info file of modules. Good values are "name" or "package".

DoxyAssist comes with an example configuration for Drupal projects, that contains some more elaborate explanations of each option in XML comments. You can use that as a base. See the doc/examples directory in the DoxyAssist package to get that example.

Save the XML file you just created to somewhere where you can find it again. The file extension doesn't matter much, although I recommend plain .xml or .doxyassist. I'll use /home/cheetah/public_html/drupal/drupal6.xml in this example.

Running DoxyAssist

Whew, everything's set up. Our preprocessor of the previous parts is (hopefully) still in place, so it's time to get this thing working. The project file is done, so we better keep that safe for a bit. If you don't have it already, install Python 2.7 now (Python 3.x is not yet supported, 2.6 will work just fine though).

Fire up a command line and enter the following:

python /home/cheetah/usr/share/doxyassist/doxyassist.py /home/cheetah/public_html/drupal/drupal6.xml

Naturally, change the path to wherever you have DoxyAssist installed. If this throws some odd (syntax) error, replace "python" with "python2" - you're probably running Python 3.x by default.

Once you got the command right, DoxyAssist will process the configuration and do its magic. This may take a little while. If you have PyQt4 installed as well, the Assistant cache will be cleared. This means custom changes you made in the Assistant with the same collection (an earlier build) will be reset. Such changes will be lost, but this step is required to get rid of left-over filters. Without this step, older tags (e.g. old versions of modules) will remain in the filter list, even though they are of no use at all anymore.

Finally, check the collectionFile setting in the qtHelp part of the DoxyAssist configuration file. You're gonna need this to finally open up the Drupal Assistant:

assistant -collectionFile /home/cheetah/.local/doc/drupal-6.qhc

The result is best shown in the following set of screenshots:

Finally, if you ever add new modules, update Drupal, or need to rebuild the documentation again: just re-run DoxyAssist with the same project file as before. Everything will be updated, and next time you run your Drupal Assistant you will see the refreshed documentation with all updates - including newly installed or updated modules. Quick and painless.

The End

This concludes this series of blog posts (finally). From scratch we set up Qt Assistant to become our main assistant in Drupal coding. All of this with the help of Doxygen, a special preprocessor and DoxyAssist. I hope you found it helpful.

Feel free to comment if you run into problems. Of course, also contact me if you'd like to discuss DoxyAssist, report bugs or request features etc!

Other posts in this series:

Sims Tools Sources: Now Open!

ChEeTaH — Tue, 10 Aug 2010 21:04:59 +0000

It's been a very long time since the Sims community was very active with the Sims 1. At the time I developed two applications for the game: The Neighborhood Handler and The Add-on Handler. Almost three years ago I decided to make the source code of these two available under the GPL2 license. Time has passed and although the source was publicly available online, it was never really announced. Time to change that, so here's the announcement (and more)!

The Neighborhood Handler and The Add-on Handler are now Open Source software! I must say I haven't properly cleaned up the code or anything: it's basically nothing but a dump of the code I wrote all those years ago. As I was still learning at the time, I bet it's full of bugs, crappy ("WTF") code and other nightmares. Yet if anyone is willing to pick up and improve (or rewrite) one or two of these projects, you now can. If you just want to take a peek: you can do that too.

As for The Neighborhood Handler: I've made a minor restart for a brand new version (still C++, but using the Qt toolkit for UI). Although I haven't had the time to put any work in it, that source is also available for anyone to work with.

There's one more thing Sims 2 content creators may find useful: I've put quite some work into a Sims 2 Packer, which allows custom packaging of the famous .package files for the Sims 2 (into .Sims2Pack files). In fact, this project may serve as a nice base for custom Sims 3 packages as well, since the file format for The Sims 3 is quite similar. I never got around to actually finishing up and publishing this, but it may still be useful to someone.

For all my open code, which also includes Drupal projects, other tools I wrote way back and more, see my public git repositories. If you're just looking for the projects mentioned above, go to:

TheNeighborhoodHandler repository (see 4.1 branch for the old version, or the master branch for the new almost-nothing-done version)
TheAddonHandler repository
libSims2Pack repository
Sims2PackerUI repository (depends on libSims2Pack)

Note that the old software requires Borland C++ Builder to build. The newer stuff (the new version of The Neighborhood Handler, libSims2Pack and Sims2PackerUI) uses CMake as build system, and depends on Qt (both are freely available). You can use the Qt Creator to build and debug all that code.

Also note that all of this is to little or no use if you're just a user of these tools, and have no interest in the actual source code. I currently have no (recent) binaries/installers available, although you may still find The Neighborhood Handler and The Add-on Handler at The Sims Zone.

Feel free to contact me if you have questions about the code or if you'd like to continue development of one or more of these projects: I can give you write permissions to the repositories if you're serious about taking these projects to a new level. It is unlikely that I'll be touching this code anytime soon.

All in all this is mostly legacy stuff, but nevertheless I hope someone will find it useful!

Drupal Development made easier with Qt Assistant - Part 3b

ChEeTaH — Tue, 10 Aug 2010 19:58:42 +0000

Remember when last time we fixed Doxygen comments of Drupal so they would look right even when using Doxygen? It's time for another part in the series, and we'll continue with some more fixing. Do you still need to get set up, because perhaps you missed the earlier parts? Please (re)read parts 1, 2 and especially 3a before you move on. This time: getting in-depth topics such as the Forms API working as expected. Let's go!

The problem

In the Drupal documentation comments, all links, including the ones to other pages, are set using the @link command. We already fixed external and Drupal specific links earlier. However, our Doxygen documentation still doesn't contain some topics as Doxygen doesn't just process or include HTML files. Because of the Doxygen processing, the defined links also remain without valid target. The links don't work, and we don't have the nice documentation together with the rest.

We could of course just change the links to the external pages at api.drupal.org. But wouldn't it be nicer to have the documentation all in one place? That's what we're going to achieve right now!

More preprocessing

Remember how in our preprocessor we left some extra space for HTML preprocessing? We'll now create a HtmlPreprocessor. Later on we'll let Doxygen scan HTML files as well. And with our special preprocessor, we will trick Doxygen to create and include the HTML pages, which we can link to without even changing the existing links.

First some structure. Open up the preprocess-drupal-doxygen.php file in your text editor or IDE again. Below the CodePreprocessor class, add the following skeleton:

class HtmlPreprocessor extends Preprocessor {
  private $_basename = ''; /**< The basename of the filename */
 
  public function __construct ($filename) {
    Preprocessor::__construct($filename);
    $this->_basename = basename($filename);
  }
 
  protected function doProcess($contents) {
    // We will go and fill this in soon...
  }
}

I've already created the constructor for you, which stores the basename of the file we're processing (that's the filename without path or directories). We'll need it later. The doProcess() function is also in place, but is in need of some content.

Remember that the $contents variable will store the entire HTML file. This may include headers, closing garbage and much more. But for future convenience, or perhaps for your own projects, perhaps you just want to create a simple HTML page with only content. The file itself will then not be valid HTML, but when put inside Doxygen output, everything will be just fine. Whatever the input is, we'll deal with it as good as we can.

Grabbing the title

The first part of the doProcess will deal with extracting the title from the document. The preferred title will be enclosed in a <title> tag. But if we get no header, we may want to check some other tags like <h1> through <h6>. For each of these, we check the document if the tag exists and has some content. We'll then grab the contents of the tag and make sure it is all on one line. If the document happens to contain a line break in the middle of the contents, we don't want that to break our documentation.

Finally, if none of the tags are found, we fall back to using the file's name. This gives us the following code, of which the regular expression is inspired by the Drupal API module:

    // Find title in the first listed tag that's in the file
    $title = NULL;
    $titleTags = array('title', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6');
    foreach($titleTags as $tag) {
      $titleMatch = array();
      if (preg_match('@<' . $tag . '(\s.*?)?>\s*(\w.*?)\s*</' . $tag . '\s*?>@is', $contents, $titleMatch)) {
        $title = str_replace("\n", " ", $titleMatch[2]); // Make sure it's all on one line
        break;
      }
    }
 
    if (!isset($title)) {
      $title = $this->_basename;
    }

And the body?

Next is the actual contents. We have two cases to deal with, as described before: one if the file contains a full HTML page (including header and whatnot, and the all-important <body> tag), or one which is a bit messy and has only the actual content (without a <body> tag).

So what do we do? Like the method used above, we go and grab the contents of the <body> tag. If our regular expression doesn't match, we'll just use the entire file:

    // Get <body> of HTML, if present (otherwise use whole document)
    $bodyMatch = array();
    if (preg_match('!<body(\s.*?)?>(.*)</body(\s.*?)?>!is', $contents, $bodyMatch)) {
      $contents = $bodyMatch[2];
    }
    $contents = str_replace("\n", "\n * ", $contents);
    $contents = preg_replace('!([@\\\\])endhtmlonly!', '\\1<span>endhtmlonly</span>', $contents);

The last but one line indents every line with " * ". Doxygen will remove this indentation from output again. So why do we do this? Just in case the HTML document starts a line with " * " somewhere, we want to keep that in the output. By adding the indentation in our preprocessor, Doxygen will remove only what we added, and nothing else.

Another issue is that the document may contain the Doxygen @endhtmlonly command in the content. As you'll see later, this may cause breakage, as that will terminate our @htmlonly block, used to insert the HTML code verbatim below. Note that in such a block, @endhtmlonly is also the only Doxygen command that is recognized, with escaping it being of no use at all. So we simply break the command wherever it occurs, by placing the endhtmlonly part in an (otherwise useless) <span> tag. You won't see the difference, but Doxygen will see @<span>endhtmlonly</span> and stick to printing verbatim HTML code. Success!

Finally, we may have some cross references in between documents. For example, the Forms API Quickstart and Forms API Reference refer to each other, using absolute links to api.drupal.org. That works, but as we have all that documentation in Doxygen, again, why not let everything work from the same place?

So let's replace some links. Add a new function to the HtmlPreprocessor:

  private function replaceLinks($contents, $links) {
    foreach($links as $original => $new) {
      $re = '/(<a\s+[^>]*)href=(["\'])' . str_replace('/', '\/', $original) . '(\/\S*)?\\2/si';
      $contents = preg_replace($re, '\\1href=\\2' . $new . '\\2', $contents);
    }
    return $contents;
  }

This function will find links we pass into the $links array (as keys), and replace them with their values. It will also catch longer URLs, if the given URL is continues with a slash and then some more stuff. As such, a link to http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6 will turn into just forms_api_reference.html if we call it as follows (add this to the doProcess() function body):

    $contents = $this->replaceLinks($contents, array(
      'http://api.drupal.org/api/file/developer/topics/forms_api.html' => 'forms_api.html',
      'http://api.drupal.org/api/file/developer/topics/forms_api_reference.html' => 'forms_api_reference.html',
      'http://api.drupal.org/api/file/developer/topics/javascript_startup_guide.html' => 'javascript_startup_guide.html',
    ));

Now for the all important step: create the Doxygen comment and include the HTML code. We'll give Doxygen some documentation of the file itself, and create a Doxygen page with some HTML only content. This is easy by just creating an appropriate Doxygen comment block:

    $contents = "/**\n"
              // Clone page's documentation in File listing
              . " * @file\n"
              . " * @brief @link {$this->_basename} {$title} @endlink\n"
              . " * \n"
              . " * This file contains a special documentation topic: @link {$this->_basename} {$title} @endlink.\n"
              . " */\n"
              // Create custom page
              . "/**\n"
              . " * @page {$this->_basename} {$title}\n"
              . " * \n"
              . " * @htmlonly\n"
              . " * " . $contents . "\n"
              . " * @endhtmlonly\n"
              . " */\n";
    return $contents;

There will be one minor issue now. If we go to the files list in the Doxygen output and look up our HTML file there, that part will not contain the actual documentation. It will instead link to the custom page we created, which has everything we want. If you like, you can copy the three lines from @htmlonly to @endhtmlonly to the file's documentation. Unfortunately if you leave out the custom page, the normal links to the page don't seem to work, so that page will need to stay in.

You can now refer to the documentation file anywhere you like by using the Doxygen command @link (e.g. "@link file.html My Link Text @endlink").

There's just one bit left in our preprocessor to do: actually construct and use this new HtmlPreprocessor. If you used the script of the last time, find the line near the end saying // HTML Processing is for later.... Found it? Replace that line with the following:

$processor = new HtmlPreprocessor($filename);

That's all for the preprocessor. Note that if you got lost somewhere in the process, you can download the complete script below. All the code is GPL v2 by the way, so feel free to change, reuse and redistribute it.

But Doxygen still doesn't read HTML files!

Now the preprocessor is completely in place, we can let Doxygen include our HTML files. This is fairly simple: in the past we let it only handle some .php, .inc, .module and .install files for Drupal. Just add .html (and any other extensions you may use) to the FILE_PATTERNS list (Input topic) in the Doxywizard. Run Doxygen, and the custom documentation will be nicely included. For Drupal documentation, simply check the main page to get to the topics. If all went well, it should all work just fine.

Summary

In part 1 we prepared our system, and in part 2 we got our Drupal documentation in the Qt Assistant. Now we fixed the documentation using some homebrew code from part 3a and this part. Last time we corrected some differences between the commands used by the Drupal API module and Doxygen, making Doxygen output resemble the output of the module. This time we expanded our code to include advanced topics from HTML pages.

There's just one issue left. All the documentation, core and modules, is grouped together. But often it's also nice to view the documentation of just a specific module. Qt Assistant makes this possible by letting it show us a selection of documentation collections (which may be the whole package as we have now). How? I'll be back soon.

Other posts in this series:

Attachment	Size
Doxyfile.	62.98 KB
preprocess-drupal-doxygen.phps	12.45 KB

Drupal Development made easier with Qt Assistant - Part 3a

ChEeTaH — Tue, 27 Jul 2010 09:07:02 +0000

Welcome back! It's been a while since I posted parts one and two of this series (yeah, I should blog more often...). Remember I was making Drupal documentation available in the Qt Assistant, a useful documentation viewer? Nice. I have some good news: I have spent some time again to get the documentation in decent order. So, without furder ado, let's continue!

Plan for today

In part one we prepared our system and got the necessary tools ready to begin our work. In part two we actually got our Drupal documentation working in the Qt Assistant, although there were several problems in the layout, as you may have noticed.

After catching up with the changes in Drupal documentation since last time, today we will take a deeper look at some of the (Drupal specific) problems in the generated documentation. This includes getting back some text that is lost in the Doxygen process, by preprocessing the code that goes into Doxygen. This is subpart A, soon we'll also get the in-depth topics (e.g. the Forms API reference) working as well, in part 3B.

Changes since last time

Since the last time, there have been a few changes in the resources we used. Although I am now using a different Linux distribution, it seems that the Doxygen templates got a bit of a make-over: your documentation will look even better with the latest version. Everything looks a bit more modern now, which is good. You may want to update your software (Doxygen and Qt) to the latest versions if you haven't already done so, just for the sake of it.

A more important change, however, is that the Drupal Developer Documentation on CVS no longer includes examples. Instead, the examples have now moved to their own project. You can grab a snapshot of the appropriate version and extract it to your developer subdirectory, which contains the Drupal Developer Documentation. Another useful option is to also grab this from CVS (see "Checking out from the contributions repository" for detailed instructions):

cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -d developer/examples contributions/modules/examples

Don't forget to update your developer documentation to the latest version as well. Especially if you're using Drupal 6, you may want to switch to the appropriate branch as follows (from the Drupal base directory, replace -r DRUPAL-6--1 with -A for the latest HEAD version):

cvs -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib update -d -P -r DRUPAL-6--1 developer

Just for completeness' sake, if you want to do a clean checkout of all this developer documentation, enter the following two commands:

cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 -d developer contributions/docs/developer
cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 -d developer/examples contributions/modules/examples

All done? Good, we're ready to move on again...

Noticed some problems?

If you used the documentation we created last time, you may have noticed some odd problems. We'll skip the broken links on the main page for now. First we deal with missing text. Look at the documentation of the t() function (in includes/common.inc). You can see what's wrong in the screenshot as well:

Notice how the @variable is missing in the second bullet, and the % character in front of variable in the third bullet? A closer look at the Doxygen error output will tell us that it doesn't know the @variable command. Doxygen commands are prefixed with a '@' or '\' in Doxygen, but the code Drupal API module (which is used to run api.drupal.org) happily ignores any commands it doesn't know. Doxygen doesn't, which causes an issue here. With the '%' character, we tell Doxygen that we do not want the word 'variable' to be auto-linked. But again, the Drupal API module doesn't seem to use that and simply prints it out.

We will take a few steps to solve these problems. Part one: time for some PHP Regular Expressions magic!

A basic preprocessor

Create a new plain text file with a nice name such as perprocess-drupal-doxygen.php. This tells us exactly what it does: preprocess Drupal files for Doxygen; and it's a PHP script. Let's set up a quick base class first by pasting the following code in the file:

#!/usr/bin/php
<?php
abstract class Preprocessor {
  private $_filename = '';
 
  public function __construct ($filename) {
    $this->_filename = $filename;
  }
 
  public function process() {
    $contents = file_get_contents($this->_filename);
    // Convert Mac/Win line breaks to Unix format.
    $contents = str_replace("\r\n", "\n", $contents);
    $contents = str_replace("\r", "\n", $contents);
 
    return $this->doProcess($contents);
  }
 
  protected abstract function doProcess($contents);
}

Note that I have omitted the comments in this (and further) code snippets; you can download the full script at the bottom of this post, with all comments.

Save the file and make sure you have execute permissions. On Windows, you may want to set up a file association such that *.phpx is executed by php (or php_cli), and name the file accordingly. Another option is creating a .cmd file which runs the PHP script (passing all comand line arguments).

The blob sets up a few things. The first line says the script is to be executed by PHP. Furthermore there is a Preprocessor class, which reads a file and changes all types of newlines into Unix format, for convenience (code borrowed from the Drupal API module). It then calls the (abstract) doProcess() function on the content. We'll work on this function in two child classes (the second one in part 3B). These will do the actual work.

Now we'll add the CodePreprocessor class which will handle our code files (.php, .module, .inc etc.). First things first: let's go and detect the comment blocks.

class CodePreprocessor extends Preprocessor {
 
  public function __construct ($filename) {
    Preprocessor::__construct($filename);
  }
 
  protected function doProcess($contents) {
    // Beyond Drupal's API module: we also work on blocks started with "/*!"
    $contents = preg_replace_callback('@/\*[\*!](.*?)\*/@s',
                                      array($this, 'processCommentBlock'),
                                      $contents);
    // And those with at least two lines of /// or //!
    $contents = preg_replace_callback('@(//[/!])[^\\n]*\\n(\\1[^\\n]*\\n)+@s',
                                      array($this, 'processCommentBlock'),
                                      $contents);
    // Return processed file contents
    return $contents;
  }
 
  private function processCommentBlock($matches) {
    $contents = $matches[0];
 
    // ADD FUNCTION CALLS HERE LATER
 
    return $contents;
  }

The doProcess implementation here finds comment structures indicating Doxygen documentation. Unlike Drupal's API module, this includes comment blocks starting with '/*!', as well as blocks of at least two lines starting with '///' or '//!'. These are all blocks Doxygen will process, so we do the same. On each comment block, we call processCommentBlock. This function gets the matches array from the regular expression ($matches[0] being the complete match), and expects a string in return. The match will be replaced with that string. All in all a very useful place to do our processing.

Escaping unknown commands

Now for some actual preprocessing code. To get Doxygen to keep the '@' and '%' characters in the output (to solve our first problem), we have to escape them, i.e. put a backslash in front of them. But we don't want actual Doxygen commands to be ignored. Also, we might as well solve another problem at the same time: drupal_match_path() has documentation containing "\r" and "\n". Drupal's API module doesn't replace the "\n" command, while Doxygen will throw in a newline. Also, Doxygen will complain about now knowing "\r" and discard it. Hence we'll also go and escape unknown backslash commands, and (valid!) backslash commands followed by a single letter (\a, \n etc), as long as they're not escaped already. So: \r will become \\r (and \r again in the HTML output), but something saying \\e scaped will remain the same.

So, it's now time for some more magic with regular expressions. Add a function in the CodePreprocessor class, which starts off listing all the known Doxygen commands:

  private function escapeUnknownCommands($contents) {
    static $commandsArray = array(
      'a', 'addindex', 'addtogroup', 'anchor', 'arg', 'attention', 'author', 'b', 'brief', 'bug',
      'c', 'callgraph', 'callgraph', 'callergraph', 'category', 'class', 'code', 'cond',
      'copybrief', 'copydetails', 'copydoc', 'date', 'def', 'defgroup', 'deprecated', 'details', 'dir',
      'dontinclude', 'dot', 'dotfile', 'e', 'else', 'elseif', 'em', 'endcode', 'endcond', 'enddot',
      'endhtmlonly', 'endif', 'endlatexonly', 'endlink', 'endmanonly', 'endmsc', 'endverbatim', 'endxmlonly',
      'enum', 'example', 'exception', 'extends', 'file', 'fn', 'headerfile', 'hideinitializer', 'htmlinclude',
      'htmlonly', 'if', 'ifnot', 'image', 'implements', 'include', 'includelineno', 'ingroup', 'internal',
      'invariant', 'interface', 'latexonly', 'li', 'line', 'link', 'mainpage', 'manonly', 'memberof', 'msc',
      'n', 'name', 'namespace', 'nosubgrouping', 'note', 'overload', 'p', 'package', 'page', 'paragraph',
      'param', 'post', 'pre', 'private', 'privatesection', 'property', 'protected', 'protectedsection',
      'public', 'publicsection', 'protocol', 'ref', 'relates', 'relatesalso', 'remarks', 'return', 'retval',
      'sa', 'section', 'see', 'showinitializer', 'since', 'skip', 'skipline', 'struct', 'subpage',
      'subsection', 'subsubsection', 'test', 'throw', 'todo', 'tparam', 'typedef', 'union', 'until', 'var',
      'verbatim', 'verbinclude', 'version', 'warning', 'weakgroup', 'xmlonly', 'xrefitem',
      'annotatedclasslist', 'classhierarchy', 'define', 'functionindex', 'header', 'headerfilelist',
      'inherit', 'l', 'postheader',
    );
    static $backslashCommandsArray = array(
      'addindex', 'addtogroup', 'anchor', 'arg', 'attention', 'author', 'brief', 'bug',
      'callgraph', 'callgraph', 'callergraph', 'category', 'class', 'code', 'cond',
      'copybrief', 'copydetails', 'copydoc', 'date', 'def', 'defgroup', 'deprecated', 'details', 'dir',
      'dontinclude', 'dot', 'dotfile', 'else', 'elseif', 'em', 'endcode', 'endcond', 'enddot',
      'endhtmlonly', 'endif', 'endlatexonly', 'endlink', 'endmanonly', 'endmsc', 'endverbatim', 'endxmlonly',
      'enum', 'example', 'exception', 'extends', 'file', 'fn', 'headerfile', 'hideinitializer', 'htmlinclude',
      'htmlonly', 'if', 'ifnot', 'image', 'implements', 'include', 'includelineno', 'ingroup', 'internal',
      'invariant', 'interface', 'latexonly', 'li', 'line', 'link', 'mainpage', 'manonly', 'memberof', 'msc',
      'name', 'namespace', 'nosubgrouping', 'note', 'overload', 'package', 'page', 'paragraph',
      'param', 'post', 'pre', 'private', 'privatesection', 'property', 'protected', 'protectedsection',
      'public', 'publicsection', 'protocol', 'ref', 'relates', 'relatesalso', 'remarks', 'return', 'retval',
      'sa', 'section', 'see', 'showinitializer', 'since', 'skip', 'skipline', 'struct', 'subpage',
      'subsection', 'subsubsection', 'test', 'throw', 'todo', 'tparam', 'typedef', 'union', 'until', 'var',
      'verbatim', 'verbinclude', 'version', 'warning', 'weakgroup', 'xmlonly', 'xrefitem',
      'annotatedclasslist', 'classhierarchy', 'define', 'functionindex', 'header', 'headerfilelist',
      'inherit', 'postheader',
    );
    static $noWordCommands = array(
      'f[\$\[\]\{\}]', '[\$@\\\\&~<>#%"]',
    );
  }

Now we'll use these arrays to construct the major regular expressions we need: two to escape unknown commands. Oh, and we don't forget to escape all those unescaped percentage characters. Expand the function you just made with:

    static $backslashCommandRegex = NULL;
    static $commandsRegex = NULL;
    static $noWordCommandsRegex = NULL;
 
    if (!isset($backslashCommandRegex)) {
      $commandsRegex = '/(^|(?<=\W))(?<!\\\\|@)@(?!' . implode('\W|', $commandsArray) . '\W|'
                     . implode('|', $noWordCommands) . ')/';
      $backslashCommandRegex = '/(^|(?<=\W))(?<!\\\\|@)\\\\(?!'
                             . implode('\W|', $backslashCommandsArray) . '\W|'
                             . implode('|', $noWordCommands) . ')/';
    }
 
    // First replace all unknown backslash commands that occur before commands
    $contents = preg_replace($backslashCommandRegex, '\\\\\\\\', $contents);
    // And unknown '@' prefixed commands
    $contents = preg_replace($commandsRegex, '\@', $contents);
    // Escape all unescaped percentage characters
    $contents = preg_replace('/(?<!\\\\|@)%/', '\\\\%', $contents);
    return $contents;

The regular expressions look complicated (especially because we have to do a lot of escaping of backslashes ourselves), but basically work as described above. The 'noWordCommands' array is separate, as such commands followed by a letter will be kept intact. If a regular command is followed by extra letters, we should still escape it (e.g. @var should remain as such, but @variable should become \@variable).

Now we still need to call the new function: place the following line in the main processCommentBlock() function as described earlier, near the clearly marked comment:

$contents = $this->escapeUnknownCommands($contents);

Try it out

Before we can actually use our code, we'll have to add some code to control the preprocessor, at the bottom of the script (outside any classes):

// Default to processing stdin if no arguments are given
if ($argc == 1) {
  $argc = 2;
  $argv[1] = '-';
}
 
// Process all files in argument list
for ($i = 1; $i < $argc; ++$i) {
  $filename = $argv[$i];
 
  if ($filename == "-") {
    $filename = "php://stdin";
  }
 
  // Find out type of file (based on filename)
  $processor = NULL;
  $info = pathinfo($filename);
  if (!empty($info['extension']) && in_array($info['extension'], array('html', 'htm', 'xhtml'))) {
    // HTML Processing is for later...
  }
  else {
    $processor = new CodePreprocessor($filename);
  }
 
  // Process file
  print $processor->process();
}

This code will create the CodePreprocessor (we'll add a separate one for HTML files later). For each of the files in the script's arguments, we'll process the code and print out the results. It will fallback to standard input, allowing us to reuse this script for something outside Doxygen, if we ever find the need (It was mainly useful for debugging the script above, allowing me to run it on selections or other files straight from my IDE).

So let's try this script out now. Save it (I'll be using /home/cheetah/public_html/drupal.api/preprocess-drupal-doxygen.php here) and open up the Doxygen wizard once again (as in part two). Change the INPUT_FILTER in the Input topic to point to your script. You may also want to add it to the excludes list (add preprocess-drupal-doxygen.php the EXCLUDE setting in the Input topic), if you keep the script in your Drupal directory. This will prevent it from being included in your Drupal documentation.

Now if you run Doxygen and check out the documentation, you'll see if everything went well. If so, the documentation of t() should now look as it does online. Good.

Broken links

Something else you'll notice from the start is that the main page of your documentation will have some broken links. The group links (Module system, Database abstraction layer, etcetera) work just fine, as do those to the example modules, if you have included them in your documentation. However, the links to the constants, global variables and the in-depth discussions are all broken. Let's get those fixed as well, by expanding the preprocessor.

First off, we want to fix the link to all the constants, or enums in Doxygen. We know there's a page, but it's not at /api/constants. We want to use globals_enum.html instead; this page has all the define() elements found in the code. So, we make it a regular anchor link (or <a> tag):

  private function makeAnchorLinks($contents, $links) {
    foreach($links as $original => $new) {
      $re = '/@link ' . str_replace('/', '\/', $original) . '(\/\S*)?\s(.*\S)\s*@endlink/';
      $contents = preg_replace($re, '<a class="el" href="' . $new . '">\\2</a>', $contents);
    }
    return $contents;
  }

The following function will change our /api/globals link to refer to the globals.php documentation. This file, in the extra developer documentation, contains documented versions of all the Drupal (core) globals. Another option is to link to globals_vars.html using the function above, which will include all global variables (and not just Drupal core ones). If you opt for that choice, the following function will not be necessary unless you find more broken links you want to fix.

  private function replaceLinks($contents, $links) {
    foreach($links as $original => $new) {
      $re = '/@link ' . str_replace('/', '\/', $original) . '(\/\S*)?\s(.*\S)\s*@endlink/';
      $contents = preg_replace($re, '@link ' . $new . ' \\2 @endlink', $contents);
    }
    return $contents;
  }

Place these both in your CodePreprocessor class. Now call them as follows, after the call to escapeUnknownCommands:

      $contents = $this->makeAnchorLinks($contents, array(
        '/api/constants' => 'globals_enum.html',
        // '/api/globals' => 'globals_vars.html',
      ));
      $contents = $this->replaceLinks($contents, array(
        '/api/globals' => 'globals.php',
      ));

Note the commented line? That's the alternative for the globals; remove/comment the other line mentioning /api/globals if you prefer the global_vars.html page (you can still access that through the Files, then Globals in the Doxygen navigation). Note that the code is flexible in that you can easily add more links. It will also automatically change longer URLs, if the extra part starts with a forward slash (e.g. /api/constants/7 will also be caught as a whole, but /api/constants_7 is considered to be a different link).

Now to deal with any external links (like the "Drupal Programming from an Object-Oriented Perspective" link on the main page). The following function will remove the used @link command, and replace it with an HTML tag again, which will not be touched by Doxygen.

  private function replaceExternalLinks($contents) {
    return preg_replace('/@link (([a-zA-Z]+:\/\/|mailto\:)\S*)\s+(.*\S)\s*@endlink/',
                 '<a class="el" href="\\1">\\3</a>', $contents);
  }

And the call:

$contents = $this->replaceExternalLinks($contents);

Note that any protocol (http://, ftp:// etc) will be caugt as external. The mailto: protocol is dealt with somewhat separately, as it doesn't have the two slashes after it, but other than that everything's the same. The whole URL, until the first space, is considered to be the actual URL to link to. The rest is the text that is linked. If you want to go a little bit further, you could even add code to show the URL as linked text, if nothing else is present (Doxygen will work that one out if you remove the @link and @endlink commands). I'll leave that as exercise to the reader.

Summary

So... wow. This post has turned out longer than expected. I've attached a renewed Doxyfile (with only the extra INPUT_FILTER and expanded EXCLUDE settings), as well as the code so far to this post. The major pains in the Doxygen code are now solved, making the documentation of Drupal more suitable for Doxygen itself. All of this work is useful whether or not you use the Qt Assistant; as soon as you use Doxygen instead of Drupal's API module, you'll probably want to have issues described here to be fixed.

Next is not part 4, but 3b. We'll continue fixing the documentation by having Doxygen properly include and find the HTML pages containing documentation, such as the Forms API reference. It'll be a quicker now we have a base to work from!

Other posts in this series:

Attachment	Size
Doxyfile.	62.95 KB
preprocess-drupal-doxygen.php_.txt	9.55 KB

Drupal Development made easier with Qt Assistant - Part 2

ChEeTaH — Sun, 22 Nov 2009 22:36:49 +0000

In the previous part of this walk-through, we installed the necessary software to get our Drupal API documentation in Qt Assistant. The next step is to actually generate the documentation so we can browse through it, search it and more. If you haven't done so already, read part 1 so you're sure to have the right software.

Creating a Doxyfile

The first thing we need to do is creating a configuration file for Doxygen. This will contain instructions for Doxygen about the formats you want the documentation to be in, where to get the documentation from, etc. I'll show the settings in the graphical tool, doxywizard. Of course it's also possible to let the doxygen command generate the file for you so you can edit it manually (with a text editor). Either way is fine. If you want to use the Doxyfile generated through this tutorial straight away, scroll to the bottom of this post to download it.

So, let's start the Doxygen wizard. You should find this in your launcher menu, probably under the Development submenu, or you can just run doxywizard from a terminal. The window you get presented asks you, as a first step, to select the working directory. Point this to your Drupal directory. For me this would be /home/cheetah/public_html/drupal.api. Now, as we want to set some advanced settings, we skip straight to the Expert tab to configure everything.

The first things to pay attention for are the PROJECT_NAME ("drupal"), PROJECT_NUMBER ("6" or whichever Drupal version you're working with), and the OUTPUT_DIRECTORY settings. For the last setting, creating a new place for Doxygen to dump its files in is the easiest way to prevent the Doxygen output from cluttering your Drupal installation. I've put it in a doxygen subdirectory ("/home/cheetah/public_html/drupal.api/doxygen"). You'll probably also want to enable the REPEAT_BRIEF and ALWAYS_DETAILED_SEC as well. The STRIP_FROM_PATH setting should be empty, but it also doesn't hurt to enter the base directory of your Drupal installation (this way, if your run Doxygen outside the Drupal directory, it'll still properly strip the path from the filenames). I've also enabled the QT_AUTOBRIEF and OPTIMIZE_OUTPUT_FOR_C options.

There's a final important setting on the Project topic, which is the EXTENSION_MAPPING. Generally, Drupal uses *.php, *.module and *.inc filenames for code. However, we need to tell Doxygen that these are PHP files. Add "module=PHP" and "install=PHP" (according to the documentation, you should omit the "." in front of the extension).

Next tab is the Build topic. We want to get all the documentation, so we extract ALL, PRIVATE, STATIC, LOCAL_CLASSES and LOCAL_METHODS. The SHOW_DIRECTORIES setting may be useful to have the directory structure visible in the documentation. We skip straight to the Input topic, and add our Drupal directory as INPUT setting. Important is the FILE_PATTERNS setting: this tells Doxygen which files contain documentation. The *.php and *.inc should normally already be in there, but for Drupal add the *.module and *.install patterns as well. This way Doxygen should extract documentation from most if not all of the code files in Drupal (unfortunately Doxygen doesn't work well with Javascript).

Also enable the RECURSIVE option, otherwise you'll need to tell Doxygen explicitly which directories it should look in for documentation, in the INPUT setting. If you keep a directory with backups of old modules within the Drupal directory, enter its path in the EXCLUDE setting (e.g. "backup"). As EXCLUDE_PATTERNS some useful entries may be */CVS/*, */.svn/*, */.git/* (so Doxygen skips version-controlled directories), plus */settings.php and */*.settings.php to ignore site-specific settings files.

Next up is the HTML topic, in which we configure the HTML output Doxygen generates. Yes, we want to generate HTML (switch on GENERATE_HTML) in the html subdirectory (HTML_OUTPUT) with the .html extension for the files (HTML_FILE_EXTENSION). Now a very important setting to generate the Qt Help files, which Qt Assistant uses. Switch on GENERATE_QHP. For QCH_FILE, which just became enabled, set drupal-6.qch (or just drupal.qch, or replace the 6 with the version of Drupal you're working with). Set the QHP_NAMESPACE to org.drupal.6 (again, replace the version number). Set all as the QHP_VIRTUAL_FOLDER - this will come in handy later. Also set the filter settings: QHP_CUST_FILTER_NAME to "Drupal 6 (all)", and set both QHP_CUST_FILTER_ATTRS and QHP_SECT_FILTER_ATTRS to drupal drupal-6. Finally, we set the path to the "qhelpgenerator" program ("qhelpgenerator.exe" on Windows, I assume) in the QHG_LOCATION setting. This is probably something like "/usr/bin/qhelpgenerator" or "C:/Qt/bin/qhelpgenerator.exe". Leave the other settings at their defaults (DISABLE_INDEX off, GENERATE_TREEVIEW to none, etc.).

Finally, head to the LaTeX, RTF, Man and XML topics, and turn output for each of these off. We won't be using these. Finally, if you want to, enable or disable class diagrams on the Dot topic. This will make a difference for some contributed modules (mostly Views).

First Run

We're all set now, so let's run Doxygen! Go to the Run tab, click the Run doxygen button and let it do its work. When it's done (don't close the Doxygen Wizard until I tell you to!), click "Show HTML Output" and your browser will start with the Drupal documentation right at your hands. Unless you excluded the "sites" subdirectory, you also get all the documentation of contributed modules as well. You may notice some problems with broken links (e.g. the Form API reference etc), and the documentation is a little bit messy if you have many contributed modules. We'll solve these problems in the next part. First, let's exit the wizard. It will ask us to save the configuration. Save it under its default name (that would be "/home/cheetah/public_html/drupal.api/doxygen/Doxyfile" in my case). You'll find the sample file created in this tutorial at the bottom of this post.

Last step for today is loading up the Qt Assistant with our documentation. This will require using a terminal/command line. First make sure you know where Qt Assistant is located. The program is called just assistant, so for most platforms you should be able to find it using which assistant on the terminal. On Windows, look in your Qt installation path, in the bin directory. Now decide for a location for your Qt Help Collection file. Create an empty file with any name you like (e.g. drupal-6.qhc). You can use the touch command to do so, or by creating an empty file in that directory using your file manager (that would be the way to go for Windows users; use Explorer or Notepad and create the empty file. Make sure the extension is .qhc and not .txt or something else!). Now, assuming you've chosen the filename to be drupal-6.qhc in your home directory (and your username is cheetah) enter in a terminal:

/usr/bin/assistant -collectionFile /home/cheetah/drupal-6.qhc

You can also just set up a shortcut to do this, of course. You should see an empty Qt Assistant:

As long as this is the first time you're starting up the assistant with this file, you can head to the Edit > Preferences menu. Go to the Documentation tab, click Add... and add the drupal-6.qch file created by Doxygen (this will be in the doxygen/html directory within your Drupal installation, if you followed this tutorial). Qt Assistant will start updating its indexes, and you get to see and search your documentation:

You'll find out that once you restart the assistant with the same collectionFile parameter, the Documentation tab will disappear from the preferences, even after removing and recreating the file. If this happened, you can still register and unregister help files from the collection file, from the command line as follows (change the filenames etc. of course):

assistant -collectionFile drupal-6.qhc -register /home/cheetah/public_html/drupal.api/doxygen/html/drupal-6.qch

To remove the help file from the collection again:

assistant -collectionFile drupal-6.qhc -unregister /home/cheetah/public_html/drupal.api/doxygen/html/drupal-6.qch

These commands will tell you if something useful happened, but won't actually start the assistant. Restart the assistant with just the collectionFile parameter again to just see the documentation.

Note that as long as the Qt Compressed Help file (the one generated by Doxygen) stays in the same place, you should be able to update it and see the changes in the assistant if you ever recreate the documentation. The assistant will automatically recreate its index and take care of such updates for you. Knowing that, you can create an icon that fires up the assistant for you, with the Drupal help loaded, so you can get that quick documentation access. Just use the above command above the empty assistant screenshot. Make sure you do give the proper path to the collection file!

Updates

If you ever want to update the documentation (for example because you added more contributed modules, updated Drupal to a newer version, etc), regenerate it with Doxygen. You can use the wizard to open the Doxyfile you saved, rerun Doxygen and the assistant should show the updated documentation after you start it again. It's as simple as that. Alternatively, using a terminal, head to your Drupal directory (or wherever you stored the Doxyfile) and simply call doxygen. As long as you've explicitly set the INPUT setting above, then run doxygen /path/to/Doxyfile and so you can even use a different filename for your Doxygen configuration. Of course you can also play with the various Doxygen settings, rerun doxygen, and you'll also get the documentation with the new settings in Qt Assistant.

Of course you don't have to use a separate collection file (*.qhc) for each version of Drupal you have. You can put each version of Drupal in the same assistant. Now if you made sure you have different namespaces (hence we placed the version numbers in the configuration), you should be able to filter per version at the top of the UI.

Summary

Last time all we did was install the necessary software. This time we actually used it all in the most basic way, with success: the Qt Assistant now displays the Drupal documentation. This should be enough to get you started finding all the information of the Drupal API that you need. There are still some problems with broken links to special topics, there's no way to filter out specific module information, and so on.

With the major steps taken, next time I'll dig a little deeper in fixing the most painful problems. It probably won't be as much work as this part. See you next time!

Other posts in this series:

Attachment	Size
Doxyfile.	62.83 KB

Donation Goals module at Drupal

ChEeTaH — Sat, 14 Nov 2009 20:30:03 +0000

Yesterday I wrapped up some work I've been putting into a Drupal module recently, for a site that's probably launching before the end of the year (not putting any pressure on anyone here!). It's called "Donation Goals" and can be grabbed from the Donation Goals Project page.

With Donation Goals you can make a new type of content in your Drupal site. You guessed it, a "Donation Goal". Enter some details, especially how much money you need, open it up and make sure you get some visitors. They can donate money to you, through PayPal, helping you reach your goal.

The module keeps track of all donations (as long as they're made through the site) and even allows you to build some fancy overviews of all donations (Views FTW!). If you saved some money yourself, you could of course pay it yourself through PayPal. The easier way is to just add the money to the current savings and let the module do the work for you (saving you the PayPal fees that you might have to pay otherwise).

There are some similar modules (Bounty, Donation and ChipIn) available, but they all take a somewhat different approach, or they are completely abandoned.

While a first development version is out, the module probably still has some features to add, things to change and bugs to fix. Try it out from drupal.org/project/donation_goals and let me know what you think!

Drupal Development made easier with Qt Assistant - Part 1

ChEeTaH — Tue, 10 Nov 2009 22:53:23 +0000

If you've followed my blog for even the smallest bit, you'll know I have KDE 4 as my desktop environment. I've also done quite some development (mostly messing around so far, just tContact is published) for Drupal. One of the main tools to help me during development is the Qt Assistant, which comes with Qt 4 and later. It's a fast documentation viewer, with a great index making it easy to look up all those little details about each function that's available in Qt4... or Drupal. Let me show you how I've set things up...

Oh, and if you're not that into all this techy stuff: feel free to stop reading, of course.

Some quick notes

First of all: this guide is focused on getting the Drupal API in the Qt Assistant, but it should work for pretty much any C++/PHP/Java/Python project etc. which Doxygen can handle. See the Doxygen website for details on how to document your code et cetera. Unfortunately I have not been able to get the PHP documentation itself integrated in Qt Assistant yet.

I will also be using some scripts to be run from a terminal or shell. This should not be much of a problem for you Linux or Mac users, for Windows it might be necessary to get CygWin. Unfortunately I haven't tried all of this from Windows, so if someone can jump in and post useful/necessary tips for Windows users in the comments, that would be helpful.

Preparing your system

Well, you're still here. First thing to do is to install Qt4. You get it from QtSoftware.com for pretty much any platform. Get the LGPL/Free version of the Framework or SDK. Note that on Linux it'll very likely come with the repositories of your distribution, you may just need to install the -dev or -devel packages.

Next, get a copy of Drupal from Drupal.org and extract it somewhere on your hard drive. You can of course use your existing Drupal installation full with all the modules you like, or just whichever product you want to use in combination with the Assistant (as long as you have access to the source code). You can do this several times for any version of Drupal, so you can even get separate access to your Drupal 5, 6 and 7 documentation. The choice is yours. No need to actually install it, just make sure the source is available.

For Drupal you'll also want to pull the Developer documentation from CVS. These contain some special help pages like the FAPI Reference and more, as well as documentation about all the hooks (hook_* functions). I won't repeat the exact instructions on how to get the documentation. Just follow the instructions at drupal.org.

Finally, get Doxygen (www.stack.nl/~dimitri/doxygen/). For Linux users: this is probably also in your distribution's repositories. This is the tool that will extract the documentation from your source code, and place it in useful HTML files - and finally in Qt Assistant too.

Qt Assistant - A Quick Look

Now that we have the necessary software installed, you could just take a quick peek at what Qt Assistant does for Qt. You should find it in your launcher/start menu/wherever (Mac: /Developer/Applications/Qt), or just by running "assistant" from the terminal. Go ahead and try it, you should see something similar to this:

Now let's look up the documentation of a function we know (part of) the name of: aboutQt(). Hit the Index tab on the left, enter about and you'll see a list of matching declarations (as well as some more generic topics). Double click aboutQt and Qt Assistant will prompt you to choose in which topic you want to look, QApplication or QMessageBox. I've opted for QApplication in the screenshot below, some actual documentation!

Finally one feature I don't use as often, but which is lightning fast: the Search. You'll find this tab on the right, just above the documentation. Searching for "about" will give you something like below, very useful if you only know the general topic of something you need:

Play around a bit and if you're daring: see if you can already get your Drupal documentation in there. That's what's coming up in the next part - the entire Drupal (and contributed) API, without even mixing it up with the Qt documentation.

Other posts in this series:

tContact at Drupal.org!

ChEeTaH — Thu, 02 Jul 2009 21:18:45 +0000

I've talked about it before... but today it's finally happened! I got a CVS account for Drupal.org a week or two ago. I postponed actually using it for a bit due to exams, but I just put it to some good use. Got a Drupal site and need your contact forms in multiple languages? Meet tContact! Version 6.x-1.0 is now officially out in the wild!

KidDraw Progress

ChEeTaH — Tue, 15 Jul 2008 18:20:45 +0000

For the past couple of days I've spent a bit of time getting KidDraw into shape. It's not there yet, not at all, but with the foundations in place I should be able to get a nice version in KDE 4.2 (January). Screens inside!

First let's take a look at the old Windows version, made in Delphi:

Now what you see is a fully working version. You can pick a color and line width (no need to click for those), load up to 5 images you made before, clear the current canvas and stop the program. Oh, and you can draw, of course.

Enter the new KDE/Qt version: It's largely the same. Except that it's cross platform. And that it supports multiple color palettes. And that it isn't finished yet. But: progress is there!

Painting was already possible somewhere around last year, well before I got it into KDE. This week or so I've done some housecleaning, made saving and reloading of drawings possible - in a straightforward self-made binary format, to keep the files of reasonable size. I might still change to XML though, probably compressed, so extending the format is more flexible.

Another thing I'm happy with is the palette support. I'm planning options to download and install new palettes, but I'm not that far yet. The most important stuff already exists though. The next screenshots all show the same image, but with different palettes. You can cycle through them and you'll see the image change colors.

The amount of colors in the palette doesn't matter. KidDraw keeps the original information so when you go back to the original palette, all colors will still be there.

As for the big gray area on top: that's where you'll be able to open/save images to in the future... but that's for another update.

All this currently lives on the SVN server of KDE, in Playground/edu. If you want to try it out, you'll most likely need to build it yourself.

Big Release Week [Update]

ChEeTaH — Mon, 16 Jun 2008 21:30:45 +0000

This morning, while waking up and surfing the web a bit, it came to me. There are many software releases this week.

First of all, tomorrow is download day for Firefox 3. Get it tomorrow! I already blogged about this one, and I once again urge you to help Mozilla to that world record. Download Firefox 3 tomorrow!

Then, also tomorrow, Spore's Creature Creator is officially released. Now EA already gave fansites (including me) a copy, so you can already get a bunch of my creatures, including a full alphabet, from Sporepedia. Look at my shiny badge:

Visitk Spore.com

Finally there's another release this Thursday. Although I'm quite a big fan of Gentoo, I've also used openSUSE (previously SuSE) a lot in the past. I'm thinking of putting that on my laptop again, saving myself the hassle of continuous compilations, and what better opportunity than the release of openSUSE 11.0 to do so?

Update (17 June): Just found out that Wine also just released version 1.0 today. That's three major software releases on one day! Congratulations!

Also, Firefox 3 Download Day is on! You have until tomorrow (18 June) 17:00 UTC to help Mozilla set that world record! Go and download!