ChEeTaH's - Open Source

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!

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!

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.

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!

Pledge and Download!

ChEeTaH — Thu, 12 Jun 2008 14:14:29 +0000

Mozilla has announced the official release date of Firefox 3: June 17th. In just 5 days you can get the newest release of this great browser. To give the browser some special attention a Guinness World Record attempt will be made on the 17th. Within 24 hours, Mozilla wants to set a new record of the most downloaded piece of software. That means you'll have 24 hours to download Firefox 3 and help Mozilla to a world record. Pledge now, download Tuesday!

Big Buck Bunny

ChEeTaH — Sun, 08 Jun 2008 20:09:37 +0000

Blender is an Open Source tool to create animated movies. It runs on all common platforms and is aimed to bring the Hollywood animation techniques to home users and artists. To show off what the program can do, a small team was financed by sponsors and the Blender Institute in Amsterdam to create a short movie. After the Orange Project resulting in an Elephants Dream about 2 years ago, there is now the Peach Project. Its movie has been released under the name of Big Buck Bunny.

I absolutely recommend you to watch this movie. It's a short one, just about 10 minutes. It was created by a team of 7 people in about six months time. The short film features a big bunny which just loves nature and outdoors. But not bad little critters. As you may expect there are some hilarious twists and turns.

Big Buck Bunny Trailer

The graphics are great, and although perhaps not as good as Pixar can make 'em, they are visually quite stunning. The main task was to create something "funny and furry," putting Blender's fur physics and creation to the test.

During the making of the movie Blender was vastly improved to support techniques required by the Peach project.

I won't spoil the plot for you. All I can say is that the mission has succeeded and that Big Buck Bunny is definitely funny and furry. And free and open. You can check out various sizes of the film, from full HD to PSP or iPod, download or streaming. If your eyes are somewhat slow, you can check out every single frame as PNG file, all 14,315 of them. If you want to support Blender - remember, everything relies on donations and sponsors - you can also buy the (double) DVD with lots of extra goodies.

Check out BigBuckBunny.org for all the downloads, sources and the trailer above. Enjoy!

Desktop Pimpin'

ChEeTaH — Tue, 03 Jun 2008 20:56:24 +0000

Google has introduced its gadgets to Linux. After the Windows and Mac releases of Google Desktop giving you clocks, calendars and more straight to your desktop, the framework is now available for Linux as well. Under the Apache license (2.0), with both Qt and GTK hosts. But they're not the first.

Gadgets are far from new. Even on Linux, KDE 3.x had Superkaramba to pimp your desktop. Now with KDE 4 there's Plasma, with Plasmoids in your panel and on your desktop. I'm sure there are other similar gadget/widget/plasmoid/dashboard systems out there. While some developers like having many analog clocks, I stick to the digital ones. Behold: my desktop, as I currently see it:

That is still without any Google gadgets on there. You can see my beautiful girlfriend and son, as well as a calculator I hardly ever use, two comics, a calendar, a picture frame showing some of my favorite pictures, KDETwitter, a fifteen-puzzle (with a lovely picture, again), and some clocks. The blank space at the right bottom of the panel shows the current moon phase. It's well, blank right now. This is all with the new default KDE 4.1 Plasma theme, by the way. I should blog about that soon, now Beta 1 is long out and Beta 2 is coming up soon.

Now come the Google Gadgets. Following the instructions - there are no Gentoo ebuilds yet, and as it was only announced today I don't think there are any packages just yet - there was one small problem. It couldn't load a library. Running 'ldconfig' as root did the trick, so I started ggl-qt.

It quietly hides in the system tray, where plenty of other icons are dumped. Google could've picked a slightly different icon I guess, this one reminds me of a certain OS logo from Redmond.

After I figured out the program went there, I double clicked it. Nothing. Single click perhaps? Nope. Right click it is. Add gadgets, there we go.

Plenty to choose from, I guess. The choice seems somewhat limited though, no Spore countdown for example, no Twitter or Plurk gadgets either. The Spore countdown does exist for Mac Dashboard, and Plasma should be able to load it, but for some reason it seems unsuccessful (I never see it, though it is installed). I should try to find out what's going on there.

Anyway, time to add some gadgets. More clocks! Four pages of search results for "clock", that should suffice...

Those clocks are just from the first page, a few of them giving errors and not installing. The gadget interface seemed to get a little slow, so I stopped adding more.

The gadgets sure look nice, though there's no coherent theme like my Plasma desktop. That's not much of a problem though, there are a few bigger issues. The first is a visible one: square shadows, if that's what you can call them, show up around each gadget. Also I had some trouble moving the gadgets to the right position, which was quickly solved by holding Alt while dragging the gadget. Unfortunately it's not possible to drag gadgets from the Add Gadgets interface straight to the desktop. You have to click "Add" followed by moving the gadgets around. Still, nothing major, it could just be a little friendlier in that aspect.

What is really bad: every gadget is its own window. Having a couple of gadgets around means Alt+Tab takes so much longer to find the right app now, as you'll also have to go through each single gadget now. The only solution right now is right clicking the gadgets icon again, and then hiding all the gadgets. But well, that really defeats the purpose of having gadgets on your desktop, right?

There are some other issues with the window-for-each-gadget thing. Because they are windows, they are dimmed when inactive, due to my KWin settings (love compositing). They also cover my existing plasmoids, so stacking a plasmoid over a gadget would not be possible. One advantage is that you can put a gadget always on top, so it is always visible. That's something I can't do with the plasmoids, but then again I'm not sure if I'd ever use it.

So after this quick run, that's my major gripe with Google Gadgets. Nevertheless, it's a good thing Google got these for Linux now too. Besides the actual UI there are libraries that come with the package, which can load the gadgets. All released as open source!

As long as license issues do no arise between the Apache and GPL license, I guess that the plasma folks will go ahead and integrate Google gadget support in a future version - possibly 4.2 - of Plasma. Not sure, of course, but it would be a nice addition to the dashboard gadgets that are supported (though not completely, obviously) right now.

I also quickly tested the GTK+ host. It looks pretty much the same, though gadgets get an addition expanded view (which seemed to be no more than loading the gadget in another separate window, which also looks more like a window). I could not find the sidebar Google says it has. perhaps it's only available under Gnome.

All in all: Google Gadgets is definitely nice, but because each gadget is its own window, there are some (major) usability issues. It's still a first version and I'm sure Google - and others - will improve Gadgets in the future. It doesn't integrate well at the moment, but support for these gadgets from within Plasma would solve that problem for me. Releasing the gadgets libraries under an open license is a great thing, so kudos to Google for that!

But, for now, I'll stick to the clocks I already have.

Wanna try for yourself? Check the Google Gadgets for Linux project on Google Code, the build and install instructions are easy enough.