ChEeTaH's blog

RTL XL Direct Links

ChEeTaH — Sat, 12 Mar 2011 13:13:52 +0000

Dutch (well, officially it's based in Luxembourgish) TV station RTL has a platform called RTL XL. On this platform they publish their videos. With all the current events in the world, it's nice to sometimes be able to watch their videos. Unfortunately, RTL XL insists on using Silverlight, even though not all videos are crippled with DRM. Especially the news videos are - thankfully - DRM-free. Still: Silverlight - or Moonlight - on Linux is somewhat troublesome...

Dutch (well, officially it's based in Luxembourg) TV station RTL has a platform called RTL XL. On this platform they publish their videos. With all the current events in the world, it's nice to sometimes be able to watch their videos. Unfortunately, RTL XL insists on using Silverlight, even though not all videos are crippled with DRM. Especially the news videos are - thankfully - DRM-free. Still: Silverlight - or Moonlight - on Linux is somewhat troublesome.

So I wanted to be able to view those videos without having to install Moonlight on my Linux systems. After a bit of coding, I am now able to get the direct links to videos on RTL.nl and RTL XL. The videos can then be streamed using e.g. VLC or MPlayer. All thanks to GreaseMonkey and mad coding skillz ;-)

If you use Firefox, install GreaseMonkey and install the user script. For other browsers, check this page about possibilities of using the script. The script adds a link to the video when a page on RTL contains a video.

The code is GPLv3 (I will soon update the license information in the script ;-) ). You can view the Git repository right here, or clone it from git://git.simply-life.net/simply-life.net/userscripts/rtlnl_media_url.

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

Sinterklaas Song, Denglish Style #2

ChEeTaH — Sun, 05 Dec 2010 13:34:25 +0000

By popular demand (read: 2 people asked for it), another Sinterklaas song in Denglish* style. The last one of this year, too.

* Note that Wikipedia refers to "Denglisch" as a mixture of German and English. Perhaps Dunglish is the better term in this case... Either way, I'm talking about mixing Dutch and English. My Denglisch (the German variant) is probably far worse than my Denglish/Dunglish.

The Sack of Santa Clause
The sack of Santa Clause
Santa Clause, Santa Clause
The sack of Santa Clause
Oh boys, boys, it's such a boss
There stops he, there stops he
There stops he happy of sin,
The whole, the whole
The whole world in
The sack of Santa Clause
Santa Clause, Santa Clause
The sack of Santa Clause
Oh boys, boys, it's such a boss

He is for big and small
Big and small, big and small
He is for big and small
Foreseen of tay and marsepain
And mountains, and mountains
And mountains sugar goods
So lecker, so lecker
So lecker and so sweet
He is for big and small
Big and small, big and small
He is for big and small
Foreseen of tay and marsepein

But under in that sack
In that sack, in that sack
But under in that sack
There lies the very big pack
For the lovely, for the sweet
For the lovely sweet child
Say was you, say was you
This year gehoresame friend?
But under in that sack
In that sack, in that sack
But under in that sack
There lies the very big pack

Thanks to Liedjesland for the original Dutch lyrics.

Sinterklaas Song, Denglish Style

ChEeTaH — Sat, 04 Dec 2010 13:46:21 +0000

Since tomorrow is Sinterklaas and I've been convinced to do some blogging, here's a nice Sinterklaas song. In the spirit of globalization, I've personally translated it in Denglish, such that the average* Dutch person can still understand the words.

See Ginder Comes The Steam boat
See ginder comes the steam boat
From Spain already on
He brings us Saint Nicholas
I see him already standing
How huppels his horse
The deck up and near
How wave the wimples
All heen and all weather

His knight stands to laughing
He screams us yet too
Who sweet is gets candy
Who bad is the roo
Oh dear Saint Nicholas
Come also to me
And don't drive really silent
Past my home

* No, I've done no research whatsoever, regarding the knowledge of English of the average Dutch person.

Sims Tools Sources: Now Open!

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

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

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

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

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

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

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

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

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

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

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

Drupal Development made easier with Qt Assistant - Part 3b

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

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

The problem

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

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

More preprocessing

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

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

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

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

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

Grabbing the title

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

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

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

And the body?

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

$processor = new HtmlPreprocessor($filename);

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

But Doxygen still doesn't read HTML files!

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

Summary

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

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

Other posts in this series:

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

Drupal Development made easier with Qt Assistant - Part 3a

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

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

Plan for today

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

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

Changes since last time

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

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

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

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

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

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

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

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

Noticed some problems?

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

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

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

A basic preprocessor

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

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

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

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

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

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

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

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

Escaping unknown commands

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

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

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

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

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

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

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

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

Try it out

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

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

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

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

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

Broken links

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

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

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

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

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

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

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

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

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

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

And the call:

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

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

Summary

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

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

Other posts in this series:

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

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