# 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. "[docs/guide/README.md](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

# Class Reference

Class | Description
--- | ---
yii\apidoc\commands\ApiController | Generate class API documentation.
yii\apidoc\commands\GuideController | This command can render documentation stored as markdown files such as the yii guide or your own applications documentation setup.
yii\apidoc\components\BaseController | Command to render API Documentation files
yii\apidoc\helpers\ApiIndexer | ApiIndexer indexes framework API
yii\apidoc\helpers\ApiMarkdown | A Markdown helper with support for class reference links.
yii\apidoc\helpers\ApiMarkdownLaTeX | A Markdown helper with support for class reference links.
yii\apidoc\helpers\ApiMarkdownTrait | Class ApiMarkdownTrait
yii\apidoc\helpers\BrokenLinkException | BrokenLinkException represents a broken API link.
yii\apidoc\helpers\IndexFileAnalyzer | IndexFileAnalyzer analyzes index file with TOC. Typically README.md.
yii\apidoc\helpers\MarkdownHighlightTrait | MarkdownHighlightTrait provides code highlighting functionality for Markdown Parsers.
yii\apidoc\helpers\PrettyPrinter | Enhances the phpDocumentor PrettyPrinter:
yii\apidoc\models\BaseDoc | Base class for API documentation information.
yii\apidoc\models\ClassDoc | Represents API documentation information for a `class`.
yii\apidoc\models\ConstDoc | Represents API documentation information for a `constant`.
yii\apidoc\models\Context |
yii\apidoc\models\EventDoc | Represents API documentation information for an `event`.
yii\apidoc\models\FunctionDoc | Represents API documentation information for a `function`.
yii\apidoc\models\InterfaceDoc | Represents API documentation information for an `interface`.
yii\apidoc\models\MethodDoc | Represents API documentation information for a `method`.
yii\apidoc\models\ParamDoc | Represents API documentation information for a function or method `param`.
yii\apidoc\models\PropertyDoc | Represents API documentation information for a `property`.
yii\apidoc\models\TraitDoc | Represents API documentation information for a `trait`.
yii\apidoc\models\TypeDoc | Base class for API documentation information for classes, interfaces and traits.
yii\apidoc\renderers\ApiRenderer | Base class for all API documentation renderers
yii\apidoc\renderers\BaseRenderer | Base class for all documentation renderers
yii\apidoc\renderers\GuideRenderer | Base class for all Guide documentation renderers
yii\apidoc\templates\bootstrap\ApiRenderer |
yii\apidoc\templates\bootstrap\GuideRenderer |
yii\apidoc\templates\bootstrap\RendererTrait | Common methods for renderers
yii\apidoc\templates\bootstrap\SideNavWidget | Nav renders a nav HTML component.
yii\apidoc\templates\bootstrap\assets\AssetBundle | The asset bundle for the offline template.
yii\apidoc\templates\bootstrap\assets\HighlightBundle | The asset bundle for the highlight.js styles.
yii\apidoc\templates\bootstrap\assets\JsSearchAsset | The asset bundle for the offline template.
yii\apidoc\templates\html\ApiRenderer | The base class for HTML API documentation renderers.
yii\apidoc\templates\html\GuideRenderer |
yii\apidoc\templates\json\ApiRenderer | The class for outputting documentation data structures as a JSON text.
yii\apidoc\templates\online\ApiRenderer |
yii\apidoc\templates\pdf\GuideRenderer |