In het vorige deel van deze walk-through hebben we de nodige software geïnstalleerd om de Drupal API documentatie in de Qt Assistant te krijgen. De volgende stap is om de Drupal documentatie te genereren zodat we er doorheen kunnen bladeren, zoeken en meer. Als je dat nog niet gedaan hebt, lees dan eerst deel 1 zodat je zeker weet dat je de goede software geïnstalleerd hebt.

Een Doxyfile Maken

Allereerst moeten we een configuratiebestand voor Doxygen maken. Dit bestand bevat instructies voor Doxygen over het formaat waarin de documentatie moet zijn, waar de code staat, enzovoorts. Ik zal laten zien hoe het werkt met het grafische programmaatje, doxywizard. Natuurlijk is het ook mogelijk om het doxygen commando een bestand aan te laten maken, dat je handmatig aanpast (met een tekstverwerker). Het maakt niet uit hoe je het doet. Als je het Doxyfile bestand direct wilt downloaden: dit staat onderaan deze post.

Laten we beginnen met de Doxygen wizard. Deze staat in je applicatiemenu, waarschijnlijk onder Ontwikkeling (Development). Je kunt ook gewoon doxywizard starten van een terminal. Het venster dat je te zien krijgt vraagt je, als eerst, om de werkdirectory te selecteren. Kies een Drupal directory hier. In mijn geval is dat /home/cheetah/public_html/drupal.api. Aangezien we wat geavanceerde instellingen willen aanpassen, gaan we gelijk naar het Expert tabblad om alles te configureren.

De eerste instellingen waar je op moet letten zijn de PROJECT_NAME ("drupal"), PROJECT_NUMBER ("6" of welke versie van Drupal je ook mee werkt), en de OUTPUT_DIRECTORY instellingen. Voor die laatste is het het makkelijkst om een nieuwe locatie op te geven waar Doxygen zijn bestanden wegschrijft. Hiermee voorkom je dat Doxygen bestanden je Drupal installatie volgooit met allerlei bestanden. Ik heb een doxygen subdirectory gebruikt ("/home/cheetah/public_html/drupal.api/doxygen"). Je kunt het best ook de REPEAT_BRIEF en ALWAYS_DETAILED_SEC opties inschakelen. De STRIP_FROM_PATH zou nu leeg moeten zijn, maar het is wel zo handig om de hoofddirectory van je Drupal installatie hier in te vullen (op deze manier, als je Doxygen niet vanuit de Drupal directory start, haalt hij nog steeds het juiste pad van de bestandsnamen af). Ik heb ook de QT_AUTOBRIEF en OPTIMIZE_OUTPUT_FOR_C opties ingeschakeld.

Als laatste is er nog één belangrijke instelling op het Project topic, en dat is EXTENSION_MAPPING. Normaal gesproken gebruikt Drupal *.php, *.module en *.inc bestanden voor de code. We moeten Doxygen wel vertellen dat dit PHP bestanden zijn. Voeg "module=PHP" en "install=PHP" toe aan deze instelling (volgens de documentatie moet je de punt vooraan in de extensie weglaten).

Het volgende tabblad is het Build topic. We willen alle documentatie krijgen, dus zetten wede EXTRACT opties aan voor ALL, PRIVATE, STATIC, LOCAL_CLASSES en LOCAL_METHODS. De SHOW_DIRECTORIES instelling is handig als je de directorystructuur zichtbaar in de documentatie wilt hebben. We gaan gelijk verder naar Input, waar we onze Drupal directory aan de INPUT instelling toevoegen. Belangrijk is ook de FILE_PATTERNS instelling: deze geeft aan Doxygen aan in welke bestanden documentatie staat. De bestanden *.php en *.inc staan er waarschijnlijk al, maar voor Drupal moet je hier ook de *.module en *.install patronene aan toevoegen. Hiermee zal Doxygen de meeste, zo niet alle, documentatie van Drupal code indexeren (helaas werkt Doxygen niet zo goed met Javascript).

Schakel ook de RECURSIVE optie in, anders moet je Doxygen precies vertellen in welke directories er gezocht moet worden, in de INPUT instelling. Als je een directory met backups van oude modules binnen je Drupal installatie bewaart, stel dan het pad in bij de EXCLUDE instelling (bijvoorbeeld "backup"). Voor EXCLUDE_PATTERNS zijn de volgende patronen wellicht nuttig: */CVS/*, */.svn/*, */.git/* (zodat Doxygen bestanden van versiebeheersystemen negeert), plus */settings.php en */*.settings.php om site-specifieke instellingbestanden te negeren.

De volgende stap is het HTML topic, waarmee we de HTML uitvoer van Doxygen instellen. Ja, we willen HTML genereren (schakel GENERATE_HTML in) in de html subdirectory (HTML_OUTPUT) met de .html extensie voor de bestanden (HTML_FILE_EXTENSION). Nu een heel belangrijke instelling voor het maken van Qt Help bestanden, die de Qt Assistant gebruikt. Schakel GENERATE_QHP in. Voor QCH_FILE, die net beschikbaar is gemaakt, stel je drupal-6.qch in (of simpelweg drupal.qch, of vervang de 6 door het versienummer van Drupal waar je mee werkt). Stel QHP_NAMESPACE in op org.drupal.6 (vervang weer het versienummer) en stel all in als de QHP_VIRTUAL_FOLDER - dit komt later nog van pas. Dan nog de filter instellingen: Zet QHP_CUST_FILTER_NAME op "Drupal 6 (all)" en zowel QHP_CUST_FILTER_ATTRS als QHP_SECT_FILTER_ATTRS op drupal drupal-6. Als laatste stellen we het pad naar het "qhelpgenerator" programma ("qhelpgenerator.exe" op Windows, neem ik aan) in met de QHG_LOCATION instelling. Dit is waarschijnlijk iets als "/usr/bin/qhelpgenerator" of "C:/Qt/bin/qhelpgenerator.exe". Laat de rest van de instellingen op hun standaardwaarde staan (DISABLE_INDEX uit, GENERATE_TREEVIEW op none, enz.).

Controleer uiteindelijk nog even dat de uitvoer van LaTeX, RTF, Man en XML uit staan op de topics daarvoor. We gebruiken deze toch niet. Als je wilt kun je ook nog de klassediagrammen aan of uitschakelen op het Dot topic. Dit zal voor sommige modules (met name Views) verschil maken.

Eerste Keer Starten

Alles is nu ingesteld, tijd om Doxygen te draaien! Ga naar het Run tabblad, klik op de Run doxygen knop en laat het z'n werk doen. Als het eenmaal klaar is, klik je op "Show HTML Output" en je browser start met de Drupal documentatie recht voor je. Tenzij je de "sites" subdirectory hebt weggelaten, krijg je ook de documentatie van contributed modules mee. Sommige links zullen niet werken (bijvoorbeeld de Form API referentie), en het geheel is misschien wat onoverzichtelijk als je veel modules erbij hebt. Dat lossen we in het volgende deel op. Eerst sluiten we de wizard af. Hij vraagt om de configuratie op te slaan. Doe dit met de standaard naam ("/home/cheetah/public_html/drupal.api/doxygen/Doxyfile" in mijn geval). Het voorbeeldbestand dat hier gemaakt is vind je onderaan deze post.

Als laatste voor vandaag gaan we zorgen dat de Qt Assistant onze documentatie gaat laten zien. Dit vereist enig werk op de terminal/command line. Zorg eerst dat je weet waar Qt Assistant staat. Het programma heet simpelweg assistant, dus op de meeste platforms moet je het nu met which assistant kunnen vinden. Op Windows kijk je in je Qt installatiedirectory, in de bin directory. Kies nu een bestandsnaam voor je Qt Help Collectie, en maak een leeg bestand aan met deze naam. Dit kan met het touch commando, of door met je bestandsbeheerder een leeg bestand met de juiste naam aan te maken (Windows gebruikers willen dat waarschijnlijk doen; gebruik de Verkenner of Kladblok en maak dat bestand aan. Zorg wel dat de extensie .qhc en niet .txt of iets anders is!). Start nu je terminal en voer het volgende commando uit (uitgaande van een bestandsnaam van drupal-6.qhc in je home directory, en een username van cheetah):

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

Je kunt ook een snelkoppeling maken die dit uitvoert, natuurlijk. Je krijgt nu een lege Qt Assistant te zien:

Zolang het de eerste keer is dat je de assistent met dit bestand opstart, kun je naar het Edit > Preferences menu gaan. Kies hier het Documentation tabblad, klik Add... en voeg het drupal-6.qch bestand toe dat door Doxygen is gemaakt (dit staat in de doxygen/html directory in je Drupal installatie, als je deze tutorial hebt gevolgd. Qt Assistant werkt nu de index bij, en je kunt je documentatie nu zien en doorzoeken:

Als je de assistant de volgende keer opstart met dezelfde collectionFile parameter, dan zal het Documentation tabblad niet meer beschikbaar zijn onder de voorkeuren, zelfs na het verwijderen en opnieuw aanmaken van het bestand. Als dit gebeurt, kun je het helpbestand nog wel uit de collectie registreren en deregistreren, vanaf de opdrachtregel, als volgt (pas natuurlijk wel de bestandsnamen aan):

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

Om het bestand weer uit de collectie te verwijderen:

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

Deze commando's vertellen je of er iets nuttigs gebeurt is, maar ze starten de assistant niet op. Start hem opnieuw op met alleen het collectionFile argument om de documentatie weer te zien.

Let op dat zolang de Qt Compressed Help bestanden (die aangemaakt zijn door Doxygen) op dezelfde plek blijven staan, je de documentatie kunt bijwerken en de aanpassingen direct kunt zien in de assistant, als je ooit de documentatie bijwerkt. De assistant maakt automatisch zijn index opnieuw aan en regelt de rest voor jou. Met die kennis kun je dus een icoontje maken dat de assistant opstart, met directe toegang tot de Drupal documentatie. Gewoon bovenstaand commando gebruiken (dat van boven de lege assistant screenshot). Let op dat je de juiste bestandsnaam meegeeft!

Updates

Als je ooit je documentatie wilt bijwerken (omdat je bijvoorbeeld extra modules hebt geïnstalleerd, Drupal hebt bijgewerkt naar een nieuwe versie, enz), maak je de documentatie opnieuw aan met Doxygen. Je kunt met de wizard het eerder opgeslagen Doxyfile inladen, Doxygen opnieuw draaien, en de assistant toont de bijgewerkte documentatie als je het de volgende keer opstart. Zo simpel is het. Je kunt ook, met een terminal, naar je Drupal directory gaan (of waar je je Doxyfile dan ook hebt staan) en daar doxygen aanroepen. Zolang je de INPUT instelling hierboven expliciet hebt ingesteld, kun je ook doxygen /pad/naar/Doxyfile gebruiken en zo zelfs een geheel andere bestandsnaam gebruiken voor je Doxygen configuratie. Je kunt natuurlijk ook wat met de instellingen van Doxygen spelen, het opnieuw draaien, en zo de documentatie met de nieuwe instellingen in je Qt Assistant krijgen.

Natuurlijk hoef je ook geen apart collectiebestand (*.qhc) te gebruiken voor elke Drupal versie die je hebt. Je kunt elke versie van Drupal in dezelfde assistant zetten. Zolang je verschillende namespaces hebt gebruikt (vandaar dat de versienummers in de configuratie staan), kun je filteren op versie aan de bovenkant van de interface.

Samenvatting

De vorige keer hebben we alleen wat software geïnstalleerd. Deze keer hebben we die software allemaal gebruikt, al is het wel op de meest eenvoudige manier, maar met succes: de Qt Assistant laat nu de Drupal documentatie zien. Hiermee kun je al een heel eind op weg om alle informatie van de Drupal API die je nodig hebt te vinden. Er zijn nog wat problemen met niet werkende links naar speciale onderwerpen en je kunt nog niet filteren per module, enzovoorts.

Maar: het belangrijkste zit er op. De volgende keer gaan we wat dieper in op die problemen, om deze op te lossen. Het wordt vast niet zo veel werk als dit deel. Tot de volgende keer!

Andere delen in deze serie:

• Deel 1
• Deel 3a
• Deel 3b
• Deel 4