yiisoft/yii2-apidoc API Documentation generator for the Yii framework 2.0

phpdoc api apidoc documentation

API documentation generator for Yii 2

This extension provides an API documentation generator for the Yii framework 2.0.

For license information check the LICENSE-file.

Installation

The preferred way to install this extension is through composer.

Either run

composer require --prefer-dist yiisoft/yii2-apidoc:"~3.0.6"

The above command may not work on an existing project due to version conflicts that need to be resolved, so it is preferred to add the package manually to the require section of your composer.json:

"yiisoft/yii2-apidoc": "~3.0.6"

afterwards run composer update. You may also run composer update yiisoft/yii2-apidoc cebe/markdown if you want to avoid updating unrelated packages.

Usage

This extension creates executable at /vendor/bin. Please do change directory to that directory if you do not want to use full path i.e /vendor/bin/apidoc and use just the executable name as with below examples.

This extension offers two commands:

1)api to generate class API documentation. phpDocumentor is used as a base framework so refer to its guide for the syntax.

The output of help api command (i.e apidoc help api):

DESCRIPTION

Renders API documentation files

USAGE

apidoc api <sourceDirs> <targetDir> [...options...]

- sourceDirs (required): array

- targetDir (required): string

OPTIONS

--appconfig: string
  custom application configuration file path.
  If not set, default application configuration is used.

--color: boolean, 0 or 1
  whether to enable ANSI color in the output.
  If not set, ANSI color will only be enabled for terminals that support it.

--exclude: string|array
  files to exclude.

--guide: string
  url to where the guide files are located

--guide-prefix: string (defaults to 'guide-')
  prefix to prepend to all guide file names.

--help, -h: boolean, 0 or 1 (defaults to 0)
  whether to display help information about current command.

--interactive: boolean, 0 or 1 (defaults to 1)
  whether to run the command interactively.

--page-title: string

--repo-url: string
  Repository url (e.g. "https://github.com/yiisoft/yii2"). Optional, used for resolving relative links
  within a repository (e.g. "[https://github.com/yiisoft/yii2-apidoc/blob/master/docs/guide/README.md](https://github.com/yiisoft/yii2-apidoc/blob/master/docs/guide/README.md)"). If you don't have such links you can
  skip this. Otherwise, skipping this will cause generation of broken links because they will be not resolved and
  left as is.

--silent-exit-on-exception: boolean, 0 or 1
  if true - script finish with `ExitCode::OK` in case of exception.
  false - `ExitCode::UNSPECIFIED_ERROR`.
  Default: `YII_ENV_TEST`

--template: string (defaults to 'bootstrap')
  template to use for rendering

2)guide to render nice HTML pages from markdown files such as the yii guide.

The output of help guide command (i.e apidoc help guide):

DESCRIPTION

Renders API documentation files

USAGE

apidoc guide <sourceDirs> <targetDir> [...options...]

- sourceDirs (required): array

- targetDir (required): string

OPTIONS

--api-docs: string
  path or URL to the api docs to allow links to classes and properties/methods.

--appconfig: string
  custom application configuration file path.
  If not set, default application configuration is used.

--color: boolean, 0 or 1
  whether to enable ANSI color in the output.
  If not set, ANSI color will only be enabled for terminals that support it.

--exclude: string|array
  files to exclude.

--guide-prefix: string (defaults to 'guide-')
  prefix to prepend to all output file names generated for the guide.

--help, -h: boolean, 0 or 1 (defaults to 0)
  whether to display help information about current command.

--interactive: boolean, 0 or 1 (defaults to 1)
  whether to run the command interactively.

--page-title: string

--silent-exit-on-exception: boolean, 0 or 1
  if true - script finish with `ExitCode::OK` in case of exception.
  false - `ExitCode::UNSPECIFIED_ERROR`.
  Default: `YII_ENV_TEST`

--template: string (defaults to 'bootstrap')
  template to use for rendering

Simple usage for stand-alone class documentation:

vendor/bin/apidoc api source/directory ./output

Simple usage for stand-alone guide documentation:

vendor/bin/apidoc guide source/docs ./output

Note that in order to generate a proper index file, the README.md file containing links to guide sections must be present. An example of such file can be found in the yii2 repository.

You can combine them to generate class API and guide documentation in one place:

# generate API docs
vendor/bin/apidoc api source/directory ./output
# generate the guide (order is important to allow the guide to link to the apidoc)
vendor/bin/apidoc guide source/docs ./output

By default, the bootstrap template will be used. You can choose a different template with the --template=name parameter. Currently, there is only the bootstrap template available.

You may also add the yii\apidoc\commands\ApiController and GuideController to your console application command map and run them inside your application's console app.

Generating docs from multiple sources

The apidoc generator can use multiple directories, so you can generate docs for your application and include the yii framework docs to enable links between your classes and framework classes. This also allows @inheritdoc to work for your classes that extend from the framework. Use the following command to generate combined api docs:

./vendor/bin/apidoc api ./vendor/yiisoft/yii2,. docs/json --exclude="docs,vendor"

This will read the source files from ./vendor/yiisoft/yii2 directory and . which is the current directory (you may replace this with the location of your code if it is not in the current working directory).

Advanced usage

The following script can be used to generate API documentation and guide in different directories and also multiple guides in different languages (like it is done on yiiframework.com):

#!/bin/sh

# set these paths to match your environment
YII_PATH=~/dev/yiisoft/yii2
APIDOC_PATH=~/dev/yiisoft/yii2/extensions/apidoc
OUTPUT=yii2docs

cd $APIDOC_PATH
./apidoc api $YII_PATH/framework/,$YII_PATH/extensions $OUTPUT/api --guide=../guide-en --guidePrefix= --interactive=0
./apidoc guide $YII_PATH/docs/guide    $OUTPUT/guide-en --apiDocs=../api --guidePrefix= --interactive=0
./apidoc guide $YII_PATH/docs/guide-ru $OUTPUT/guide-ru --apiDocs=../api --guidePrefix= --interactive=0
# repeat the last line for more languages

Creating a PDF of the guide

Prerequisites:

pdflatex.
Pygments.
GNU make.

Generation:

vendor/bin/apidoc guide source/docs ./output --template=pdf
cd ./output
make pdf

If all runs without errors the PDF will be guide.pdf in the output dir.

Special Markdown Syntax

We have a special Syntax for linking to a class in the API documentation. See the code style guide for details.

Creating your own templates

TBD

Using the model layer

TBD

Changelog

Yii Framework 2 apidoc extension Change Log

3.0.7 under development

Bug #293: Logged errors and warnings were duplicated in some cases (rhertogh)

3.0.6 November 18, 2022

Bug #288: Improve handling of trait inheritance - precedence, prevent methods' and properties' duplication (arogachev)

3.0.5 April 21, 2022

Bug #284: Fix empty visibility in methods and properties (arogachev)

3.0.4 March 29, 2022

Bug #282: Convert newlines to spaces and consider the first sentence ended only if the dot is followed by a space in BaseDoc::extractFirstSentence() (WinterSilence)

3.0.3 February 19, 2022

Bug #281: Fix encoding in non English guides (arogachev)

3.0.2 February 16, 2022

Bug #280: Do not cache Context::getReflectionProject() at instance level because it can cause apidoc cache to contain stale data (arogachev)

3.0.1 February 08, 2022

Bug #278: Fix error: Call to a member function getNamespaceAliases() on null (arogachev)

3.0.0 January 14, 2022

Bug #34: Improved highlighting of PHP templates (arogachev)
Bug #128: Fixed extracting of first sentence from the text containing backticks (arogachev)
Bug #133: Fixed PHP Parser error with anonymous class (arogachev)
Bug #148: Fixed processing of code containing uniform variable syntax (arogachev)
Bug #155: Fixed processing of classes containing constants with visibility (arogachev)
Bug #162: Fixed skipping some of PHP files / classes (arogachev)
Bug #168: Fixed handling of inheritance (arogachev)
Bug #179: Fixed incorrect output when string type hint is used in method parameters (arogachev)
Bug #180: Fixed "All Classes" broken link (arogachev)
Bug #197: Adapted fixing of Markdown links for multiple links (arogachev)
Bug #199: Fixed processing of nullable return types (arogachev)
Bug #203: Add PHP 8 compatibility, raise minimum PHP version to 7.2 (bizley, arogachev)
Bug #210: Fixed invalid attempt to scan parent class of interface with @inheritdoc tag on a method (bizley)
Bug #213: Fixed error: "Call to undefined method phpDocumentor\Reflection\Php\Argument::getNode()" (arogachev)
Bug #218: Extended detection of @inheritdoc tag in BaseDoc (WinterSilence)
Bug #239: Do not show a "virtual" / "magic" method's full description if it matches short description (arogachev)
Bug #240: Fixed a bug when a "virtual" / "magic" property's full description was displayed instead of preview in properties list (arogachev)
Bug #241: Do not show a method's source code when it's empty (arogachev)
Enh #18: Added pretty print for arrays (arogachev)
Enh #36: Allow customizing "All classes url" and "Available since version" label for type in HTML API (arogachev)
Enh #126: Resolve static return type (arogachev)
Enh #134: Swapped listings package with minted for better code highlighting in PDF guide (arogachev)
Enh #140: Added support for multiple "since" tags (arogachev)
Enh #143: Do not include methods and properties marked as internal (arogachev)
Enh #146: Updated nikic/php-parser version (bizley, arogachev)
Enh #147: Added feature of viewing method source code without external links (arogachev)
Enh #159: Added support to relative links within a repository in HTML API (arogachev)
Enh #161: Render API link text in web guide (arogachev)
Enh #196: Added support for PHPDoc inline links (arogachev)
Enh #209: Added support for todos in properties and methods (arogachev)

2.1.6 May 05, 2021

Bug #206: Fixed invalid path to solarized-light.css in HighlightBundle (bu4ak)

2.1.5 July 19, 2020

Bug #163: Do not stop on fatal errors during parsing source files (samdark)
Bug #198: Add missing initialization of $contexts in ApiMarkdownTrait::parseApiLinks() (samdark)

2.1.4 May 02, 2020

Enh #7, #132: Add support for @property and @method (samdark)

2.1.3 February 12, 2020

Bug #145: Fixed broken API links on property/method docs that were pulled in with @inheritdoc (brandonkelly)
Bug #187: Prevent getter/setter methods from affecting class-defined property docs (brandonkelly)
Enh #137: @since tags are now propagated to inherited methods/properties in the same package (brandonkelly)
Enh #185: Use HTTPS for www.php.net links (kamarton)

2.1.2 August 20, 2019

Bug #172: Upgraded highlight.js dependency to 9.13.1 (samdark)
Bug #176: Prevent multiple TOC rendering in ApiMarkdown (machour)

2.1.1 November 14, 2018

Bug #149: Fixed crash on wrongly formatted API links (cebe, santosh-1265)
Bug #160: Fixed parsing of '{@inheritdoc}' tag (klimov-paul)
Bug: Usage of deprecated yii\base\Object changed to yii\base\BaseObject allowing compatibility with PHP 7.2 (klimov-paul)
Enh #38: Fixed display of default values given as octal or hex notation (hiqsol)
Enh #152: Set @bower and @npm aliases dependent on the existing directories (ricpelo)
Enh: Display TOC only if there is more than one headline (cebe)
Enh: Extracted markdown code highlighting to a trait MarkdownHighlightTrait (cebe)
Enh: Added "type" attribute to JSON renderer to keep information about whether an entry is a class, interface or trait (cebe)

2.1.0 November 22, 2016

Enh #8: Updated PHP Parser dependency to from version 0.9 to 1.0 to resolve dependency conflicts with other libraries. This breaks the implementation of the yii\apidoc\helpers\PrettyPrinter class (cebe)

2.0.6 November 22, 2016

Bug #5: Enable display of deprecated information for methods, properties, constants and events (cebe)
Bug #12: Do not publish PHP files for jssearch.js asset (cebe)
Bug #42: Fixed stopword filter in JS search index, which resulted in empty results for some words like sort (cebe)
Bug #61: Fixed duplicate description when @inheritdoc is used for properties (cebe)
Bug #62: Make @inheritdoc tag more robust (cebe, sasha-ch)
Bug #65: Fixed handling of YiiRequirementChecker namespace and navigation (cebe)
Bug #67: Use multibyte compatible function for ucfirst() in descriptions (cebe, samdark)
Bug #68: Fixed crash on empty type in PHPdoc (cebe, itnelo)
Bug #76: Fixed broken links with external urls (CedricYii)
Bug #79: Fixed crash due to missing encoding specified in mb_* functions (cebe, dingzhihao)
Enh #29: Added styling for bootstrap tables (cebe)
Enh #117: Add support for int and bool types (rob006)
Enh #118: Separate warnings and errors occurred on processing files (rob006)
Enh: Moved the title page of the PDF template into a separate file for better customization (cebe)

2.0.5 March 17, 2016

Bug #25: Fixed encoding of HTML tags in method definition for params passed by reference (cebe)
Bug #37: Fixed error when extending Interfaces that are not in the current code base (cebe)
Bug #10470: Fixed TOC links for headlines which include links (cebe)
Enh #13: Allow templates to be specified by class name (tom--)
Enh #13: Added a JSON template to output the class structure as a JSON file (tom--)
Enh: Added callback afterMarkdownProcess() to HTML Guide renderer (cebe)
Enh: Added getHeadings() method to ApiMarkdown class (cebe)
Enh: Added css class to Info, Warning, Note and Tip blocks (cebe)
Chg #31: Hightlight.php library is now used for code highlighing, the builtin ApiMarkdown::hightligh() function is not used anymore (cebe)

2.0.4 May 10, 2015

Bug #3: Interface documentation did not show inheritance (cebe)
Enh: Added ability to set pageTitle from command line (unclead)

2.0.3 March 01, 2015

no changes in this release.

2.0.2 January 11, 2015

no changes in this release.

2.0.1 December 07, 2014

Bug #5623: Fixed crash when a class contains a setter that has no arguments e.g. setXyz() (cebe)
Bug #5899: Incorrect class listed as definedBy reference for properties (cebe)
Bug: Guide and API renderer now work with relative paths/URLs (cebe)
Enh: Guide generator now skips images directory if it does not exist instead of throwing an error (cebe)
Enh: Made --guidePrefix option available as a command line option (cebe)

2.0.0 October 12, 2014

Chg: Updated cebe/markdown to 1.0.0 which includes breaking changes in its internal API (cebe)

2.0.0-rc September 27, 2014

no changes in this release.

2.0.0-beta April 13, 2014

Initial release.

Statistics

Downloads

GitHub Stars

GitHub Forks

Releases

Comments

3.0.6 is the latest of 23 releases

yiisoft

github.com/yiisoft/yii2-apidoc

BSD-3-Clause license

Stats

258 github stars & 121 github forks

121 downloads in the last day

4782 downloads in the last 30 days

642660 total downloads