Welkom bij het vierde en laatste deel van deze serie blogs. Eerder hebben we een PHP preprocessor gemaakt, waarmee enkele kleine problemen in de Drupal documentatie opgelost werden. Daarvoor in deel 1 hebben we ons systeem voorbereid en in deel 2 zijn de belangrijkste items van Doxygen geconfigureerd. Lees deel 3a en deel 3b voor het werk aan de PHP Preprocessor. Deze keer gebruiken we mijn eigen DoxyAssist programma om veel van het werk te automatiseren. Tijd om de documentatie nuttig te maken!

Goede basis

Dankzij het configureren en repareren van Doxygen de vorige keer, voor Drupal in het geheel, hebben een goede basis opgebouwd om mee te beginnen. De volgende stap is om de DoxyAssist scripts te installeren naar een handige locatie. DoxyAssist helpt jou - met name Drupal projecten - om modulair documentatie te bouwen. In plaats van één grote bundel, splitst DoxyAssist de core en extra modules van elkaar. Doxygen wordt voor elke module apart uitgevoerd, waarmee aparte sets van helppagina's gemaakt worden.

Daarna combineert DoxyAssist alle aparte bestanden weer in één Qt Help Collectie. Deze kan gebruikt worden in de Qt Assistant. Met behulp van filters in de UI van de Assistant wordt het mogelijk om alle documentatie samen te bekijken, of de documentatie van specifieke modules.

Projectbestand

DoxyAssist gebruikt projecten en subprojecten om te bepalen welk deel van de broncode wel of niet meegenomen moet worden in elke aparte uitvoer van Doxygen. Speciale ondersteuning is er voor Drupal, waarmee Drupal automatisch subprojecten (community modules, thema's, enzovoorts) ontdekt in de "sites" directory.

Dus maken we een XML bestand dat DoxyAssist vertelt waar de broncode gevonden moet worden, welk Doxyfile als basis bebruikt moet worden en welke opties overschreven moeten worden. Het geeft ook enkele specifieke opties voor de Qt Assistant aan. Deze laatste opties bepalen welke mogelijkheden beschikbaar zijn in de assistant, bij het openen van de collectie.

In dit voorbeeld neem ik even aan dat het basis-Doxyfile correct ingesteld is voor Drupal. Zie deel 3b voor de laatste versie, maar pas het wel aan voor jouw omgeving. Open daarna je editor en plak om te beginnen het volgende stuk erin:

Zoals je ziet in het deel hierboven worden eerst enkele basisdingen als XML namespaces uitgewerkt. We geven aan dat het een project van het type "drupal" is en dat we versie 1.0 van het DoxyAssist configurieformaat gebruiken. We geven de confuratie een naam en vertellen DoxyAssist welk basis-Doxyfile gebruikt moet worden. Vergeet niet daar het pad aan te passen!

In het volgende deel voegen we opties voor de Qt Assistant toe:

De paden naar het collectionFile en het projectFile zijn zodanig dat ze bij de dagelijse taken niet in de weg staan. De aparte qch bestanden worden in een "qch" subdirectory gezet (het "storage" attribuut) en ze worden gekopiëerd van de Doxygen uitvoerdirectories. Andere opties daarvoor zijn "move" (waarmee de gecomprimeerde helpbestanden uit de oorspronkelijke Doxygendirectories verplaatst worden) en "symlink" (maak een symbolische link naar de oorspronkelijke locatie).

De opties die volgen defini&eum;lren de interface van de Assistant. Meer details hierover vind je in de Qt documentatie. Let op het applicationIcon: dit moet in dezelfde directory als het collectionFile staan. Hiermee kun je een speciaal icoontje voor je Drupal assistant gebruiken - als je hiet niet wilt gebruiken laat je de optie gewoon weg.

Nu het interessante deel: de definities voor het Drupal (6) project:

Oh, en we sluiten de DoxyAssist ook nog even af. Maar eerder definiëren we ons project met een naam en versie. We willen versiespecifieke builds, wat wil zeggen dat de projectversie wordt meegenomen in de uiteindelijke uitvoer. Dat maakt het net wat makkelijker om later de versies uit te zoeken. In de input optie geven we aan waar de Drupal broncode staat. We voegen ook nog even enkele directories toe die Doxygen niet mee moet nemen. Daar zit ook onze uitvoerdirectory bij, waar Doxygen alle bestanden plaatst. Er is ook nog een aparte directory waar de logbestanden van Doxygen naar weggeschreven worden, zodat ook (mislukte) uitvoeren apart onderzocht kunnen worden, mocht dat nodig zijn.

Als laatste is de namespace optie de basisnamespace die gebruikt wordt in de Qt Assistant. DoxyAssist zet daar automatisch de projectnaam ("Drupal") en versie ("6.x") achter. Voor modules, komt hier op een vergelijkbare manier nog de modulenaam en versie achter. In de Qt Assistant worden deze volledige namen gebruikt om alle pagina's te kunnen onderscheiden. Zo wordt overlap voorkomen, wat zeker bij veel voorkomende pagina's een probleem is.

Tot dusver zijn de opties met name voor elk (generiek) DoxyAssist project geschikt. De volgende set opties is specifiek voor Drupal. Daarmee bepaal je van welke items de documentatie gemaakt moet worden (Core, extra modules en/of thema's) en of alle versies van een project gebruikt moeten worden, of alleen de laatste versie. Dat laatste is met name handig met een multi-site installatie, waar sommige sites nog oudere versies van modules hebben.

De groupBy optie is ook belangrijk: hiermee bepaal je hoe documentatie van modules gegroepeerd moet worden. De waarde is een item in de .info bestanden van modules. Nuttige waarden voor deze optie zijn "name" of "package".

DoxyAssist komt met een voorbeeldconfiguratie voor Drupal projecten met meer uitleg over elke optie in XML commentaar. Die kun je gebruiken om mee te beginnen. Zie de doc/examples directory in het DoxyAssist pakket om dat voorbeeld te krijgen.

Sla het XML bestand dat je hebt gemaakt op waar je het weer terug kunt vinden. De extensie maakt niet veel uit, maar ik raad zelf simpelweg .xml of .doxyassist aan. Ik ga in dit voorbeeld verder uit van /home/cheetah/public_html/drupal/drupal6.xml.

DoxyAssist Uitvoeren

Phew, alles staat klaar. Onze preprocessor uit de eerdere delen staat (hopelijk) ook nog op zijn plek. Tijd om het geheel werkend te krijgen. Het projectbestand staat klaar, dus dat kunnen we ook maar beter veilig bewaren. Als je het nog niet hebt, installeer dan nu Python 2.7 (Python 3.x werkt nog niet goed, 2.6 zou het wel gewoon moeten doen).

Start een terminal en voer het volgende in:

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

Pas uiteraard het pad aan naar waar je DoxyAssist hebt geïnstalleerd. Als je hiermee een vage (syntax) foutmelding krijg, vervang dan "python" door "python2" - Python 3.x is dan waarschijnlijk je standaardversie.

Als je het commando goed hebt, leest DoxyAssist de configuratie en gaat aan de slag. Dit kan even duren. Als je PyQt4 ook nog hebt geïnstalleerd, zal de cache van de Assistant verwijderd worden. Dit betekent dat aanpassingen in de Assistant met dezelfde collectie (een oudere build) gereset worden. Dit is nodig om overgebleven filters te verwijderen. Zonder die stap zouden oude tags (bijvoorbeeld oude versies van modules) in de filterlijst blijven staan, ook al is de documentatie niet meer beschikbaar.

De laatste stap is om even de collectionFile instelling in het qtHelp gedeelte in het DoxyAssist configuratiebestand op te zoeken. Je hebt dit nodig om de Drupal Assistant eindelijk te starten:

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

Het resultaat is te zien in de volgende set screenshots:

Tot slot, als je ooit nieuwe modules installeert, Drupal bijwerkt of de documentatie gewoon opnieuw wilt maken: simpelweg DoxyAssist opnieuw starten met hetzelfde projectbestand is voldoende. Alles wordt bijgewerkt en de volgende keer dat je de Drupal Assistant start zie je de vernieuwde documentatie met alle updates - inclusief nieuwe of bijgewerkte modules. Snel en simpel.

Einde

Dit is het einde van deze serie blogs (eindelijk!). We hebben de Qt Assistant zo gemaakt zodat hij ons ook assisteert bij Drupal ontwikkeling. Dit alles met behulp van Doxygen, een speciale preprocessor en DoxyAssist. Ik hoop dat je het nuttig vond.

Laat gerust een comment achter als je problemen hebt. Natuurlijk kun je ook contact met me opnemen als je het wilt hebben over DoxyAssist, bugs wilt melden of features wilt vragen enzovoorts!

Andere delen in deze serie:

• Deel 1
• Deel 2
• Deel 3a
• Deel 3b