apigen / apigen

PHP 7.1 ready Smart and Simple Documentation for your PHP project

Smart and Readable Documentation for PHP projects

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
  • local type aliases
• 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
• PHP 7.2
  • object type
• PHP 7.1
  • nullable types
  • iterable type
  • void type
  • class constant visibility
• PHP 7.0
  • scalar types
  • return types
• PHP 5.6
  • constant scalar expressions
  • variadic functions
• PHP 5.4
  • traits
  • callable type
  • binary integer notation

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/latest/download/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'

apigen's Issues

Get rid of Console\Progressbar.php

Considering we actually use about 20 % of the library functionality, we can easily move the used code to the Generator, where we have two progressbar related methods anyway.

Generate documentation for global constants and functions

Surprisingly, ApiGen ignores anything but classes. It does not generate documentation for global constants and functions. While such functions are usually hacks or shortcuts, they are still parts of the API.

Option for indication of main project or libraries

Option for Google Analytics

--google-anal for Google Analytics key

NS in extends

example:

<?php
namespace NS1;
use NS2\Foo;
class Bar extends Foo {}

generate result:

class Bar as descendant of NS1\Foo

it does not use declared fully qualified class from use declaration, but use local namespace (and NS1\Foo not exist)

visible in tree of classes and tree part of head in class detail

Fix link resolving

The resolving mechanism is quite capable. So capable that it resolves things that it shouldn't :) It has to take --access-levels, --php, --deprecated and --skip-doc-* configuration into consideration and it must not resolve basic data type names (string, integer, ...).

Add %apigenDir%

For paths config options

$context->prams['apigenDir'] = __DIR__;
$context->expand("%apigenDir%/templates"); // __DIR__ . "/templates"

Strip leading tabs from code snippets while maintaining relative tab spacing

For example, currently the following code block will render with the leading tabs:

<code>
    echo 'some code';
</code>

It would be nice if APIGen could strip the leading tabs off of the code so that it renders correctly. The indentation would allow the code to be more readable in the source. If the code has more tabs within it (like if or foreach blocks), the tabbing on those things should be maintained. Only the leading single tab should be stripped off.

Passing any parameter from the command line

Currently there is no way a custom parameter would get into the Config instance, because it does not pass through the getopt() function in apigen.php. The only way for custom parameters is through a config file.
#9 kind of needs this to allow creating flexible plugins.

Google CSE id

I just now created my own Google CSE and apigen reports "Invalid Google Custom Search ID"

problem is in regexp for check id validity
my new cseid is "007245170196418660962:j-sfigaiwda"
so I think, that the regexp should be modified to somethink like '^\d{21}:[a-z0-9-]{11}$' -> add '-' to second part

Context awareness

Some helpers require the information on which class they operate.

This is not a problem when the class is inserted into the template as a variable. However there is no way a helper would know the class when traversing over an array of classes without the class being explicitly passed to the helper. And this approach cannot be used in plugins (#9).

That is why we need a way to determine the current "context", especially using the {foreach} macro.

Option for disable package

Option for disable package because PHP 5.3 libraries uses namespace.

Documentation should be inherited for missing pieces

if i have a class implementing an interface method and put no documentation in the implementation, the docblock from the interface is taken.
however, if i have a docblock i.e. to add something and use {@inheritdoc}, the @return, @throws and @param fields are no longer inherited.
the javadoc way would be to fetch each of those fields from the parent class / interface if its not defined, allowing you to overwrite just what you need. http://download.oracle.com/javase/1.4.2/docs/tooldocs/windows/javadoc.html#inheritingcomments

Use libraries as git submodules instead of minified versions

Plugin system

There will be a plugin system allowing developers to easily modify default ApiGen behavior.

At the moment we plan to provide two types of plugins:

• Custom links to the highlighted source code (to Github for example).
• Custom annotation processing (Doctrine tags for example).

Complete set of ApiGen custom reflections

For flexible plugins use we need to have envelope classes for all reflection types. That means that we need to add \Apigen\ReflectionMethod and \ApiGen\ReflectionProperty and alter \ApiGen\ReflectionClass accordingly.

Provide a link from Todo list directly to source code.

Excluding functions

Is there a way to exclude only some functions from some files?

Could not process file

this error is reporting on local copy of https://github.com/Lopo/Lohini/blob/master/Lohini/Localization/Filters/LatteMacros.php

no idea why

Remove the tmp dir during wipeout

If the generating process crashes, the tmp directory with compiled templates stays in the destination directory. The rest of generated files gets deleted (--wipeout). The tmp directory should as well.

Support for @example

Is there a way to include highlighted code on the function details page? I would use this to include an example for instance.

PHP 5.4 support

As PHP 5.4 is knocking on the doors, it'd be nice to have a support for traits.

Traits support

https://wiki.php.net/rfc/horizontalreuse

Looking for a sample config file

Is there a sample config file anywhere?

Missing log directory.

When exception is thrown during doc processing, a debug report can not be saved because apigen/log directory is missing.

Option to make all documentation expanded instead of using mouseovers

Would it be difficult to add an option to make all of the method and variable documentation expanded by default, instead of using mouseover to expand the sections? Does an option like this already exist?

Annotation class list

List classes with annotation. (example: list all doctrine entity class - classes with @entity annotation)

Make the default template usable even without the splitter JS functionality

Allow remote URL with the highlighted source code

When using the generated documentation on GitHub for example, there is no need to generate the highlighted source code. There should be a link to the appropriate GitHub URL instead.

--source-code will be changed to accept both Yes, No as well as some form of an URL mask.

@var description is ignored

While docs defined like:

    /**
    * Description
    * @var type
    */

are parsed as they should, in case description is specified after @var:

    /**
    * @var type Description
    */

nothing is shown in resulting doc.
As I understand, according to phpDoc specification, such case should be appropriate.

Google CSE more option

Koukal jsem že jste odstranili more:api z Google CSE nevím jesti to bylo šťastné... Přidal bych tedy option do configu.

Support for // @todo

Example:

public function foo($bar)
{
    return $bar; // @todo
}

Or detect all @todo in sources.

Update jQuery

Test if php libraries (mbstring...) are loaded

E.g. when mbstring library is not loaded, apigen "throws" error. This can be confusing.
Fatal Error: Call to undefined function Nette\Utils\mb_substr()

Doctrine plugin

This depends on #9.

We will provide a custom plugin for processing doctrine docblock tags. Currently we are analysing what exactly should be visualized and how to make it useful.

If you have any suggestions, feel free to leave a comment.

New template using frames

Better expanding of nested namespaces

Small website tweaks

I would suggest some tweaks to your current website.

1. Position the logo to the left (with the square icon, it looks weird if centered) and leave more space in the top area.
2. Define the h1 and h2 font-weight as normal (It looks awfully bold at least in Opera and Firefox 6)
3. Promote he Git repository a bit more, maybe by using the "Fork me" ribbon.

Support for @internal

The @internal tag has two versions:

• The inline version lets the developer mark a certain part of the documentation as internal and (using a configuration option) decide if such parts should belong to the generated documentation or be silently ignored.
• The standard version marks a whole element (class, function, constant) as internal. Using the configuration option one can decide if the documentation of such elements should be generated.

This implementation slightly differs from the phpDocumentor http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.internal.pkg.html.

Disable coloring output messages

Is there any way to disable coloring output messages that produce ApiGen while create php documentation because I put that messages in separated log file? It will be nice to have option for this.

New splitter

Clean mess in helpers

New option --colors to enable/disable colors in console

Debugger initialization should follow the --debug option

The Nette debugger ignores the --debug option. That makes debugging e.g. exceptions from templates pretty hard unless you alter ApiGen sources for development.

When turning --debug on Nette Debugger should be initialized in development mode.

"onSomething" event support

This is just a suggestion. It would be great to have some kind of support for Nette-like events.

Consider following example:

/**
 * @event
 * @param Form $form
 */
public $onSuccess;

It would generate a section in a class documentation, similar to the Method Summary section, with all available events in the class, and possibly also inherited ones.

I think it would make a great plugin ;-)

New option --tree to disable generating tree view of classes

Templates inheritance

We need some kind of templates inheritance. Currently if someone wants to have a custom template, they have to copy the whole original one even if changing only a single file.

Inheritance will be implemented using template config files (already present).

Add colorize config option

Add colorize config / arg option

Move navigation to layout instead of having it in all templates

Support for custom docblock tags processing

While some libraries use docblock tags for specific purposes (Doctrine being an example), we plan to include support for custom tags processing.

There has been no discussion about the particular implementation yet and this feature will definitely not make it to the 2.0 final.