README.md 2.79 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13
API documentation generator for Yii 2
=====================================

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

Installation
------------

The preferred way to install this extension is through [composer](http://getcomposer.org/download/).

Either run

```
14
php composer.phar require --prefer-dist yiisoft/yii2-apidoc "*"
15 16 17 18 19
```

or add

```json
20
"yiisoft/yii2-apidoc": "*"
21 22 23 24 25 26 27
```

to the require section of your composer.json.

Usage
-----

28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44
This extension offers two commands:

- `api` to generate class API documentation.
- `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
```

Carsten Brandt committed
45
You can combine them to generate class API and guide documentation in one place:
Carsten Brandt committed
46 47

```
Carsten Brandt committed
48
# generate API docs
49
vendor/bin/apidoc api source/directory ./output
Carsten Brandt committed
50
# generate the guide (order is important to allow the guide to link to the apidoc)
51
vendor/bin/apidoc guide source/docs ./output
Carsten Brandt committed
52 53
```

Carsten Brandt committed
54
By default the `bootstrap` template will be used. You can choose a different template with the `--template=name` parameter.
55
Currently there is only the `bootstrap` template available.
Carsten Brandt committed
56

Carsten Brandt committed
57 58
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.
59

60
### Advanced usage
61

62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82
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):

```sh
#!/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.
83 84 85 86 87 88 89 90 91

```
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.

Carsten Brandt committed
92 93 94 95 96 97
Special Markdown Syntax
-----------------------

We have a special Syntax for linking to classes in the API documentation.
See the [code style guide](https://github.com/yiisoft/yii2/blob/master/docs/internals/core-code-style.md#markdown) for details.

98 99 100 101 102 103 104 105
Creating your own templates
---------------------------

TDB

Using the model layer
---------------------

Carsten Brandt committed
106
TDB