wulfheart/apigen-demo

PHP source code API generator.

dev-master 2022-11-30 22:39 UTC

Requires

• php: ^8.1
• ext-ctype: *
• ext-json: *
• ext-mbstring: *
• ext-tokenizer: *
• jetbrains/phpstorm-stubs: ^2022.1
• latte/latte: ^3.0
• league/commonmark: ^2.3
• nette/di: ^3.0
• nette/finder: ^2.5
• nette/schema: ^1.2
• nette/utils: ^3.2
• nikic/php-parser: ^4.15
• phpstan/php-8-stubs: ^0.3.9
• phpstan/phpdoc-parser: ^1.5
• symfony/console: ^6.0

Requires (Dev)

• phpstan/phpstan: ^1.7
• tracy/tracy: ^2.9

Suggests

• ext-pcntl: for multiprocess rendering

MIT

• ApiGen Contributors
• Jaroslav Hanslík
• Ondřej Nešpor
• David Grudl

README

ApiGen is easy to use and modern API doc generator supporting all PHP 8.2 features.

Features

• phpDoc
  • all types supported by PHPStan
  • generic class declarations
• PHP 8.2
  • constants in traits
  • fetch enum properties in const expressions
  • disjunctive normal form types
  • readonly classes
  • true, false and null types
• PHP 8.1
  • enums
  • pure intersection types
  • never type
  • final class constants
  • new in initializers
  • readonly properties
• PHP 8.0
  • constructor property promotion
  • union types
  • mixed type
  • static return type
• PHP 7.4
  • typed properties

Built on Shoulders of Giants

• nikic/php-parser
• phpstan/phpdoc-parser
• latte/latte
• league/commonmark

Install

With Docker

ApiGen is available as apigen/apigen Docker image which you can directly use.

docker run --rm --interactive --tty --volume "$PWD:$PWD" --workdir "$PWD" \
  apigen/apigen:edge \
  src --output docs

With Phar

This will install ApiGen phar binary to tools/apigen.

mkdir -p tools
curl -L https://github.com/ApiGen/ApiGen/releases/download/v7.0.0-alpha.3/apigen.phar -o tools/apigen
chmod +x tools/apigen
tools/apigen src --output docs

With Composer

This will install ApiGen to tools/apigen directory with executable entry point available in tools/apigen/bin/apigen.

composer create-project --no-dev apigen/apigen:^7.0@alpha tools/apigen
tools/apigen/bin/apigen src --output docs

Usage

Generate API docs by passing source directories and destination option:

apigen src --output docs

Configuration

ApiGen can be configured with apigen.neon configuration file.

parameters:
  # string[], passed as arguments in CLI, e.g. ['src']
  paths: []

  # string[], --include in CLI, included files mask, e.g. ['*.php']
  include: ['*.php']

  # string[], --exclude in CLI, excluded files mask, e.g. ['tests/**']
  exclude: []

  # bool, should protected members be excluded?
  excludeProtected: false

  # bool, should private members be excluded?
  excludePrivate: true

  # string[], list of tags used for excluding class-likes and members
  excludeTagged: ['internal']

  # string, --output in CLI
  outputDir: '%workingDir%/api'

  # string | null, --theme in CLI
  themeDir: null

  # string, --title in CLI
  title: 'API Documentation'

  # string, --base-url in CLI
  baseUrl: ''

  # int, --workers in CLI, number of processes that will be forked for parallel rendering
  workerCount: 8

  # string, --memory-limit in CLI
  memoryLimit: '512M'

Performance

To achieve the best performance you need

• pcntl extension (required for parallel rendering) and
• opcache extension with enabled JIT