Legyen saját Drupal API oldalad!

nevergone képe

Az új Drupal stabil kiadásához közeledve hasznos lehet, ha az ember újragondolja, átnézi a fejlesztéseit, hiszen a legtöbb esetben mindenképpen módosítani kell az általa kifejlesztett, egyedi funkcionalítást adó modulon, hogy használható legyen a Drupal 6 alatt is. Ilyenkor nagy segítséget jelent az api.drupal.org, ahol könnyen lehet keresni a használható függvények között, megnézni a paraméterezését, vagy a működését.
Viszont nem mindenkinek áll a rendelkezésére az Internet, mint ahogy jómagam is ebben a helyzetben voltam évekig, így szeretném bemutatni az ilyenkor használható hűséges segítőtársamat: az API modult, amelyet teljesen offline működésre fogunk bírni.

A megoldást Linux operációs rendszer alatt teszteltem, és ott is használom, így azokról az esetleges eltérésekről, amelyek a Microsoft Windows alatt jelentkezhetnek (pl. a fájlrendszer elérése), nem tudok nyilatkozni.
Amire szükségünk lesz:

  • Egy feltelepített Drupal rendszerre, mivel erről a kézikönyv is hosszasan ír, ezért inkább itt nem taglalnám
  • Az API modulra, ugyan a modul nem rendelkezik még magyar fordítással, de enélkül is könnyen érthető a felülete
  • Kell még a PHP függvények rövid leírása, amelyet itt fogunk megtalálni, mentsük le funcsummary.txt néven (a download linkre kell kattintani)
  • A minél teljesebb dokumentációhoz szükséges még néhány dokumentáció (pl. Form API), és egyéb példakódok, ezeket a következő paranccsal tudjuk kinyerni a Drupal tárolóból:
    cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-5 contributions/docs/developer
  • Végül pedig szükséges még a PHP dokumentáció, itt fontos, hogy a több fájlból álló változatot válasszuk, amely innen tölthető le magyar nyelven.

Ha ezek megvannak, akkor minden szükséges dolgot letöltöttünk, vigyük haza, és lássunk munkához!

Először is, a webszerver által használt gyökérkönyvtárban hozzunk létre egy alkönyvtárat phpdoc néven, és oda tömörítsük ki a PHP dokumentációt, majd ebben a könyvtárban hozzunk létre egy fájlt .htaccess névvel, amelynek a tartalma legyen a következő:

<IfModule mod_rewrite.c>
    RewriteEngine on
 
    RewriteBase /phpdoc/html
 
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteCond %{REQUEST_FILENAME} ^(.*)_(.*)$
    RewriteRule ^(.*)_(.*)$ $1-$2
 
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    RewriteRule ^([0-9A-Za-z\-]*)$ function.$1.html [L]
</IfModule>

Ezzel elértük azt, hogy a http://localhost/phpdoc/html/is_array címen megjelenik az is_array PHP függvény leírása, ez amúgy többféle módon is megoldható, érdemes elolvasni a Weblabor kapcsolódó cikkét. Szintén ebbe a phpdoc könyvtárba másoljuk be a korábban lementett funcsummary.txt állományt.

Az api modul bekapcsolása után az adminisztrációs oldal "webhely beállítása" részében megjelent egy új menüpont "API reference" néven, itt tudjuk a modul működését szabályozni.
Az első megadandó dolog a "Short name", ezt majd a címek generálásakor használja a Drupal, így nem tartalmazhat szóközt, vagy olyan karaktert, amely nem megengedett az internet-címekben.
A következő a "Long name", ez lesz a blokk látható neve, fontos szerepe van akkor, ha egyszerre több Drupal dokumentációját, mondjuk a stabil és a fejlesztői változatét kívánjuk elkészíteni.
A "Directory name" helyen kell megadnunk az indexelni kívánt Drupal abszolút elérési útvonalát, akár egyszerre többet is, kettősponttal elválasztva.
A "Maximun files to scan per cron run" helyen állíthatjuk be, hogy az időzített feladatok futása közben egy-egy alkalommal hány fájlt dolgozzon fel. Ezt érdemes az alapértelmezett 10 értéken hagyni, így nem futnak ki folyamatok az engedélyezett időből.
A "Save changes" gombra kattintva elmenthetjük az itt megadott adatokat, így lehetőség nyílik másik telepítés leindexelésére is, majd ha többet is beállítottunk, a "Default branch" rádiógomb alatt lehetséges az alapértelmezettet kiválasztani. Fontos, hogy miután megjelent a "Changes saved." felirat, akkor mégegyszer nyomjuk meg ezt a gombot, mert ekkor menti el a "Default branch" tartalmát, ennek hiánya esetlegesen galibát okozhat.

A "PHP Manual" résznél az első helyre írjuk be a funcsummary.txt elérési helyét: http://localhost/phpdoc/html/funcsummary.txt
A második résznél pedig megadhatjuk PHP dokumentáció helyét a gépünkön, a "!function" karaktersorozattal kiegészítve (ide kerül majd a függvény neve), tehát:
http://localhost/phpdoc/html/!function

Majd ha ezek megvannak, kattintás az "Index PHP manual pages" gombra, és egy kis várakozás. Ha végzett, és mindent helyesen állítottunk be, akkor a "Reindex" gombra kattintva megkezdődik a megadott Drupal rendszerek forrásának feldolgozása.
Most nincs más dolgunk, mint szorgosan futtatni az időzített feladatokat, akár böngészőből:
http://localhost/ahol_van_az_oldalunk/cron.php,

akár konzolból a
wget -O - -q http://localhost/ahol_van_az_oldalunk/cron.php

parancsot futtatva.
Annyiszor kell ezt végrehajtani, amíg a hozzáférési naplóban az api modulhoz tartozóan a "Parsing" kezdetű üzenetek el nem fogynak.
Ezek után már csak egy lépés választ el minket a sikertől:
Az adminisztrációs oldal "Blokkok" részében kapcsoljuk be az "API navigation" és az "API search" blokkokat, majd a főoldalra lépve legyünk boldogok, és válljék egészségünkre a gépünkön üzemelő Drupal API dokumentációs rendszer.

Frissítve (2010.06.08):
Drupal 6 hoz a következő CVS paranccsal lehet kinyerni a dokumentációt:
cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 contributions/docs/developer

Hozzászólások

szikar képe

Nagyon jó írás! Mindig tanul valami újat az ember.

nevergone képe

Szóval ez az a bizonyos "harmadik oldal", amelyet itt említettem.

Sweetchuck képe

Létezik egy idevágó php.ini beállítás.
Nevezetesen a

docref_root = "http://localhost/phpdoc/html/"
docref_ext = .html

A PHP hibaüzenetekben linkeké alakulnak a függvénynevek.

A cikkben leírtak kipróbálása közben, támadt egy nagyszerű ötletem. :-D
Mely így hangzik: ...

nevergone képe

És mi az a nagyszerű ötlet?
Amúgy köszönöm, hogy leírtad, ezt az opciót nem ismertem. :)

Sweetchuck képe

...
A jobb fajta, programozásra tervezett szövegszerkesztők tudják kezelni a külső *.chm, vagy *.html formátumban elérhető referenciákat. De a függvény leírást csak egy helyről próbálja meg elérni a szövegszerkesztő.
Tehát nincsen az, hogy ha nem sikerült elérni a leírást a http://localhost/phpdoc/html/function.hook_menu.html oldalon, akkor megpróbálja a http://localhost/ahol_van_az_oldalunk/api/function/hook_menu oldalon.

A megoldást abban láttam, hogy az API modult futtató Drupal példányba bele kell integrálni a PHP kézikönyvet, az API Merger modul segítségével.
Ehhez szintén szükség lesz a PHP kézikönyv egy helyi másolatára. (Bár próbáltam úgy megírni a modult, hogy működjön online is, de nem jött össze.)

A modul bekapcsolása után ellátogatni az admin/settings/apimerger oldalra.
A "PHP manual location" mezőbe ez kerüljön: http://localhost/phpdoc/html/ (a cikk alapján)
beállítások mentése
Továbbá az igazi API modul beállítsain is változtatni kell.
admin/settings/api
A "PHP Manual" részhez tartozik 2 db szövegmező. Az első marad változatlan. De a második
http://localhost/ahol_van_az_oldalunk/api/function/!function

Elvileg a
http://localhost/ahol_van_az_oldalunk/api/function/is_array
http://localhost/ahol_van_az_oldalunk/api/function/is-array
http://localhost/ahol_van_az_oldalunk/api/function/function.is-array.html
http://localhost/ahol_van_az_oldalunk/api/function/hook_menu
linkek is működni fognak.

nevergone képe

Még nem próbáltam ki az általad vázolt megoldást (ígéretesnek tűnik, bár jó lenne ismerni pár ilyen szövegszerkesztőt is), viszont érdemes lenne kipróbálni több Drupal branch dokumentálása esetén.
Ugyanis a node_load () függvény leírása a api/function/node_load/5 címen lesz elérhető, az utolsó perjel utáni érték (itt "5") az API modulban beállított "Short name" értéke. Ennek a szerepe az, hogy több különböző verziójú Drupal feldolgozása esetén meg tudja különböztetni az egyes verziókban szereplő azonos nevű függvényeket egymástól.
Na ezt szép barokkosan írtam le. :)

Sweetchuck képe

Ha az admin/settings/api oldalon megadsz több Drupal verziót, akkor be lehet állítani, hogy melyik legyen a Default Branch:
Figyelni kell, mert alaphelyzetben egyik rádió gomb sincsen benyomva. Csak a választás után lehet elhagyni az URL végéről a "Short name" -et.

Amúgy az apimerger modul mellőz mindenféle hibakezelést, és az eredményt sem kell mutogatni a HTML validátoroknak. :)

bár jó lenne ismerni pár ilyen szövegszerkesztőt is

(Windows felasználó vagyok)
Én jEdite-et használok. Az tud ilyet
Dev-PHP IDE is kezeli a *.chm fájlokat

Vannak olyan szövegszerkesztők amik saját maguk értelmezik a forrás fájlokban lévő dokumentációt, és gépelés közben egy kis ablakban feldobják a kurzor alatti függvénynévhez tartozó leírást. Ezek többnyire fizetős programok.

nevergone képe

Valóban, amikor már lefeküdtem aludni, akkor jöttem rá, hogy a default branch lesz a megoldás, ahogy a leírásban is írtam. Csak ezért már nem akartam vissza felkelni. :)

nevergone képe

Nem rossz az általad vázolt megoldás, most nyílt módom kipróbálni. Én egy branch -et indexeltettem le az api modullal, így ezért is lehetséges némelyik hiba.

Szóval a http://localhost/oldal_cime/api/function/is_array oldalra ellátogatva valóban bejön az is_array() függvény dokumentációja, viszont minden link, ami egyéb PHP függvényekre mutat (ilyen az előző/következő link is) már a "hagyományos" http://localhost/oldal_cime/api/function/function.fuggveny.html módot használja, ami kissé zavaró lehet (nem konvertálja át a címet).

A PHP függvények oldalán szereplő "fel" link sehova sem vezet, hibát dob:

  • warning: fopen(http://localhost/phpdoc/html/ref.var.html) [function.fopen]: failed to open stream: HTTP request failed! HTTP/1.1 500 Internal Server Error in /var/www/api/sites/all/modules/apimerger/apimerger.module on line 146.
  • warning: stream_get_contents() expects parameter 1 to be resource, boolean given in /var/www/api/sites/all/modules/apimerger/apimerger.module on line 147.
  • warning: fclose(): supplied argument is not a valid stream resource in /var/www/api/sites/all/modules/apimerger/apimerger.module on line 148.
  • warning: strpos() [function.strpos]: Offset not contained in string. in /var/www/api/sites/all/modules/apimerger/apimerger.module on line 155.

Egy adott függvénynél pedig a "List references" gombra kattintva "Az oldal nem található" hibaüzenetet ad.

További probléma, hogy ha a http://localhost/oldal_cime/api/function/is_array jó helyre mutat, akkor pl. a http://localhost/oldal_cime/api/function/node_load már nem, hibaüzenet ad:

  • warning: fopen(http://localhost/phpdoc/html/function.node-load.html) [function.fopen]: failed to open stream: HTTP request failed! HTTP/1.1 404 Not Found in /var/www/api/sites/all/modules/apimerger/apimerger.module on line 146.
  • warning: stream_get_contents() expects parameter 1 to be resource, boolean given in /var/www/api/sites/all/modules/apimerger/apimerger.module on line 147.
  • warning: fclose(): supplied argument is not a valid stream resource in /var/www/api/sites/all/modules/apimerger/apimerger.module on line 148.
  • warning: strpos() [function.strpos]: Offset not contained in string. in /var/www/api/sites/all/modules/apimerger/apimerger.module on line 155.

csak akkor mőködik jól, ha http://localhost/oldal_cime/api/function/node_load/5 címen használom, vagyis a link végén ott van a "Short name" értéke. Ez a modul használata előtt teljesen jól működött, vagyis a "Short name" nélkül írt cím valóban a "default branch" adott függvényére vezetett.
Végül pedig a modulnak bár van adminisztrációs oldala, de nem helyezi el magát a menüben semmilyen módon, így csak a pontos link ismeretében lehet eljutni oda.

Mindenezek ellenére egy roppant hasznos és segítőkész modul, szeretném kérni a továbbfejlesztését. :)

nevergone képe

Végigolvasva a leírást, nem biztos, hogy mindenkinek érthető az, hogy milyen módon készül el a dokumentáció, hiszen a Drupal maga nem tartalmaz olyan különálló szöveges állományokat, melyek ezeket a leírásokat tartalmaznák.
Nos a Drupal forráskódja "öndokumentálóan" készül, a Doxygen rendszer segítségével. Ez a segédprogram képes arra, hogy a forráskódban elhelyezett speciális megjegyzéseket értelmezze, és abból elkészítse az adott programrész leírását.
Ez a nagy varázslat! :)

Webappz képe

A jó fejlesztői dokumentációnak az alapja a megfelelően kommentezett kód.
Én a phpDocumentort szeretem használni, pláne akkor ha egy ismeretlen kóddal ismerkedem. A forrásokat egy könyvtárba rakom, majd rászabadítom a "kicsikét", aminek az eredménye, hogy kapok egy sorszámozott keresztbe-kasul összelinkelt webes dokumentációt, így nem kell megnyitni az összes forrást, hogy követni tudjam az egyes függvények vagy osztályok implementációját.

Webappz - http://webappz.hu

Páldi Zoltán

nevergone képe

Ez most mitől kapott "új" jelzést, és került a tracker elejére?

Hojtsy Gábor képe

Frissítünk pár dolgot :)

nevergone képe

Drupal 6 hoz a következő CVS paranccsal lehet kinyerni a dokumentációt:
cvs -z6 -d:pserver:anonymous:anonymous@cvs.drupal.org:/cvs/drupal-contrib checkout -r DRUPAL-6--1 contributions/docs/developer