ChEeTaH's - Drupal

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:

Announcing DoxyAssist!

ChEeTaH — Sat, 22 Jan 2011 22:13:36 +0000

For my series of blogs regarding Drupal documentation and the Qt Assistant, I wanted get modular API documentation. Having everything thrown into a big bucket - Drupal Core and all contributed modules - became quite messy. On the other hand, having everything separated is just as cumbersome. I needed a tool which automatically discovers modules and builds the documentation for me. Then bundle everything in one Qt Help Collection with appropriate filters, so I can view everything together or each module's documentation separately, switching quickly in one interface. DoxyAssist to the rescue!

With DoxyAssist you can split up any large project's documentation into submodules. The documentation for each module will be built separately. If you use the Qt Assistant and let DoxyAssist create the help collection for you, it will also bundle the various pieces of documentation again. In the assistant appropriate filters are added so you can easily select which documentation you want to see.

Furthermore it is able to load a single Doxygen configuration file (Doxyfile) and use it as a template. If submodules need slight variations in these settings, you can change these settings, without having to create seperate Doxyfiles for each module. You can set required settings in the DoxyAssist configuration file, and let team members use their own base templates so they can customize the documentation to their liking.

Special support for Drupal is available, with which you can have DoxyAssist automatically discover all contributed modules and themes you have installed and build the documentation in the groups you like.

I hereby present you version 0.1, licensed under GPLv3. It requires Python and optionally PyQt4. It comes with example configuration samples to help you get started.

Download here

Source code @ Gitorious

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

MacDesperate now Online!

ChEeTaH — Tue, 08 Dec 2009 18:56:41 +0000

After quite a long time (well over a year), we finally launched MacDesperate last Sunday. We are me, Rosana, Alex and Wouter. Of course, MacDesperate is powered by Drupal. Rosana and Wouter are saving up for macs - they're the real MacDesperates - and my Donation Goals module helps them keep track of their progress. The first donations are already in. Now it's time for you to support them! Don't hesitate and go to MacDesperate.com! We've got goodies!

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!

Where have you been?

ChEeTaH — Sun, 14 Jun 2009 11:57:35 +0000

It's been a long time again, very long. A lot has changed too, so here goes...

First of all: I got a job in February. It's not the greatest thing, but getting something really nice is hard right now. At least it relieves us a bit from the huge financial burden we'd otherwise have. Another small job at my university, where I worked for only 4 hours each week, is ending this month. I'll have my last paycheck from there soon, unfortunately.

I've also prepared the tContact Drupal module for release. The code has been slightly improved, which is always good. There's also another mini-module for Drupal which allows you to add CSS classes to menu links. This makes it easier for a theme to turn a menu into a series of buttons, similar to the menu at the top of this site (Home/About/Contact). Right now this site uses the menu item's ID number, which is somewhat random. With this module such menus are just a little harder to break :) I hope both modules will land on Drupal.org soon.

What else? KidDraw of course. A few months ago already, I've cleaned up a lot of code, made it a little bit themeable (which resulted in removing a whole lot of code). I've also changed the file loading/saving structures around so that the files KidDraw produces are nice straightforward XML files. They're compressed to save some disk space, but it means that compatibility with future and past versions is much easier. Still, a release is not in sight right now, and I'll stop predicting/hoping anything right now. First I've got some other stuff to finish and wrap up, before I can focus on KidDraw a little more again.

I'm also working on some supersecret projects with Rosana, which has taken some time off of other projects. It has inspired me to write the menu CSS classes module mentioned above though.

Another technical bit I worked on this past weekend is merging all the (5) Drupal installations on this webserver to a single centralized installation. Before, a new version of Drupal would mean updating each site separately: putting the site in maintenance mode, uploading files, updating the database and turning the site back online. Times 5. Right now: Put all sites in maintenance mode, upload files, update all databases, put them all back online. I've set up bookmark folders in Firefox so I can put all sites into maintenance mode with just a few clicks. Same goes for updating and bringing them back online. A similar amount of effort is saved for updates of common modules among various sites. All in all: maintaining the sites is less painful - especially as the amount of Drupal sites we're running will soon grow.

That does mean that if you spot any errors (missing/broken images, links, etc): please contact me! I think I've most of them covered though.

And then there's University of course. It's taking a lot of my time right now, with this year's last set of exams just around the corner. Together with some more deadlines, it's a busy time right now.

The Sims 3 is also out, I've been playing it for a bit. Not much yet - too little time. The (Collector's Edition) box is shiny though.

Spore Galactic Adventures, the first real expansion for Spore, is due next week, and Thursday (18th) me and Rosana will be checking it out at EA Netherlands. A bit late for a preview, but it may just be early enough to get me excited about the game once again. I don't know all too much about it right now, so Wednesday evening I'll have to do some reading to catch up on it.

Finally: I'll be getting a new laptop this summer. After saving up for a long time, the €1000 offer from university (for a HP Elitebook 8530w) is in. I've filled in the form saying I want it, I'll have to pay up soon. I should be getting it around August. My current laptop (6 years old) just doesn't cut it anymore...

That's it for this rough summary of the past couple of months (project/work wise anyway). Until next time!