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

phpdocapiapidocdocumentation

993323

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.

Latest Stable Version Total Downloads Build Status

Installation

The preferred way to install this extension is through composer.

Either run

composer require --prefer-dist yiisoft/yii2-apidoc

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": "~2.1.0"

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 offers two commands:

  • api to generate class API documentation. phpDocumentor is used as a base framework so refer to its guide for the syntax.
  • guide to render nice HTML pages from markdown files such as the yii guide.

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

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 of your applications 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

You need pdflatex and GNU make for this.

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 classes 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

2.1.5 under development

  • no changes in this release.

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



2.1.4 is the latest of 14 releases



BSD-3-Clause license
Stats
232 github stars & 109 github forks
436 downloads in the last day
8018 downloads in the last 30 days
328696 total downloads