Здравейте! Днес ми се наложи да използвам ApiGen. Лично на мен много ми хареса и за това реших да направя този урок.
Що е ApiGen?
ApiGen е инструмент за създаване на професионална API документация за PHP проекти. Подобен е на phpDocumentator/phpDoc.
ApiGen използва:
- Темплейтната система на Nette Framework и Texy, за да прави полезна и лесна за четене HTML документация;
- FSH, за да подчертава изходния код (highlighting);
- TokenReflection, за да описва документирания изходен код.
Функции на ApiGen:
- Детайлно документиране на класове, функции и константи.
- Подчертаване на изходния код (highlighting)
- Поддръжка на namespaces и packages със суб-packages
- Експериментална поддръжка на traits.
- Страница с дървовиден списък на класове (classes), интерфейси (interfaces), traits и exceptions
- Страница с depricated елементи
- Страница с Todo задачи
- Връзка за теглене на документацията като ZIP архиви
- Поддръжка на docblock темплейти
- Поддръжка на
@inheritdoc - Поддръжка на
{@link} - Документация за използвани вградени PHP класове
- Проверка за нова версия
- Поддръжка на Google CSE
- Поддръжка на Google Analytics
- Поддръжка на собствени темплейти
- Поддръжка на Sitemap и Live търсачка
- Поддръжка на различни енкодинги (charsets)
Инсталация на ApiGen
Как се използва ApiGen?
ApiGen се използва чрез конзола – независимо дали сте под Windows или Linux.
apigen --source <path> --destination <path> [options]
Опции на ApiGen
--config|-c
Път до конфигурационния файл
--source|-s <directory|file>
Път към изходния код на приложението ви. Задължително!
--destination|-d <directory>
Път към директорията, където документацията ще се качи. Задължително!
--extensions <list>
Списък с разширения за обхождане. По подразбиране: „php“.
--skip-doc-path <mask> --skip-doc-prefix <value>
Използвайки тези опции, казвате на ApiGen да не обхожда зададените файлове. В новосъздадената документация ще се покажат имената на файловете, но кодът им няма да бъде наличен.
--charset <list>
Енкодингът, с който файловете ще бъдат прочетени. По подразбиране: „auto“.
--main <value>
Файловете, които започват със зададения параметър ще се считат за главни, а останалите – за библиотеки.
--title <value>
Заглавие на новосъздадената документация
--base-url <value>
Base URL на новосъздадената документация. Използва се в Sitemap-a.
--google-cse-id <value>
Ако имате Google CSE ID, търсачка ще използва него при търсене на класове, namespaces, и т.н.
--google-cse-label <value>
Етикет по подразбиране на Google CSE.
--google-analytics <value>
Google Analytics tracking код.
--template-config <file>
Конфигурационен файл (config.neon) на темплейта. По подразбиране: templates/default/config.neon
--allowed-html <list>
Разрешени HTML тагове. Разделят се със запетая. По подразбиране: b,i,a,ul,ol,li,p,br,var,samp,kbd,tt.
--groups <value>
Как елементите ще бъдат групирани в менюто. Наличните стойности са „auto“, „namespaces“, „packages“ и „none“. По подразбиране: „auto“. (Namespace-ите се използват ако са налични в кода. В противен случай – packages).
--autocomplete <list>
Списък с включените елементи при обхождане. Наличните стойности са „classes“, „constants“, „functions“, „methods“, „properties“ и „classconstants“. По поздразбиране: „classes,constants,functions“.
--access-levels <list>
Access level на свойствата и методите. Наличните стойности са „public“, „protected“ и „private“. По подразбиране: „public, protected“.
--internal <yes|no>
Генерира документация за елементите, които за маркиране като вътрешни (@internal). По подразбиране: „No“.
--php <yes|no>
Генерира документация за вградените в PHP елементи. По подразбиране: „Yes“.
--tree <yes|no>
Генерира дървовидно показване на classes, interfaces, traits и exceptions. По подразбиране: „Yes“.
--deprecated <yes|no>
Генерира документация за deprecated-елементите. По подразбиране: „No“.
--todo <yes|no>
Генерира ToDo списък със задачи. По подразбиране: „No“.
--source-code <yes|no>
Генерира подчертаване на изходния код (highlighting). По подразбиране: „Yes“.
--download <yes|no>
Добавя връзка за изтегляне на документацията като ZIP архив. По подразбиране: „No“.
--report <file>
XML Error Handling.
--wipeout <yes|no>
Изтрива файловете, генерирани при предишно изпълнение. По подразбиране: „Yes“.
--quiet <yes|no>
Не показва никакви съобщения в конзолата. По подразбиране: „No“.
--progressbar <yes|no>
Показва Progress барове при генерация. По подразбиране: „Yes“.
--colors <yes|no>
Използва цветове при конзолата. По подразбиране „No“ за Windows и „Yes“ за други операционни системи. Windows не поддържа цветове в конзолата, освен ако не го активирате с Ansicon.
--update-check <yes|no>
Проверява за нови версии в ApiGen. По подразбиране: „Yes“.
--debug <yes|no>
Показва допълнителна информация ако възникне грешка (Exception). По подразбиране: „No“.
--help|-h
Показва списъка с наличните опции.
Само --source и--destination са задължителни параметри.