Здравейте! Днес ми се наложи да използвам ApiGen. Лично на мен много ми хареса и за това реших да направя този урок.

Що е 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 са задължителни параметри.

 Примерни документации, създадени с ApiGen

Share on Facebook0Tweet about this on TwitterShare on Google+0Share on LinkedIn0Share on Reddit0Email this to someone