Merge pull request #1784 from yiisoft/api-doc-generator

api doc generator

extensions/yii/apidoc/.gitignore

@@ -0,0 +1,2 @@
+/vendor
+composer.lock

extensions/yii/apidoc/CHANGELOG.md

@@ -0,0 +1,7 @@
+Yii Framework 2 apidoc extension Change Log
+===========================================
+
+2.0.0 beta under development
+----------------------------
+
+- Initial release.

extensions/yii/apidoc/LICENSE.md

@@ -0,0 +1,32 @@
+The Yii framework is free software. It is released under the terms of
+the following BSD License.
+
+Copyright © 2008 by Yii Software LLC (http://www.yiisoft.com)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+ * Redistributions of source code must retain the above copyright
+   notice, this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
+   notice, this list of conditions and the following disclaimer in
+   the documentation and/or other materials provided with the
+   distribution.
+ * Neither the name of Yii Software LLC nor the names of its
+   contributors may be used to endorse or promote products derived
+   from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
+COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
+ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

extensions/yii/apidoc/README.md

@@ -0,0 +1,48 @@
+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
+
+```
+php composer.phar require yiisoft/yii2-apidoc "*"
+```
+
+or add
+
+```json
+"yiisoft/yii2-apidoc": "*"
+```
+
+to the require section of your composer.json.
+
+Usage
+-----
+
+To generate API documentation, run the `apidoc` command.
+
+```
+vendor/bin/apidoc source/directory ./output
+```
+
+By default the `offline` template will be used. You can choose a different templates with the `--template=name` parameter.
+Currently there is only the `offline` template available.
+
+You may also add the `yii\apidoc\commands\RenderController` to your console application class map and
+run it inside of your applications console app.
+
+Creating your own templates
+---------------------------
+
+TDB
+
+Using the model layer
+---------------------
+
+TDB

extensions/yii/apidoc/apidoc

@@ -0,0 +1,49 @@
+#!/usr/bin/env php
+<?php
+/**
+ * Yii Framework 2.0 API documentation generator
+ *
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+defined('YII_DEBUG') or define('YII_DEBUG', false);
+
+$composerAutoload = [
+	__DIR__ . '/vendor/autoload.php', // standalone with "composer install" run
+	__DIR__ . '/../../../../autoload.php', // script is installed as a composer binary
+];
+foreach($composerAutoload as $autoload) {
+	if (file_exists($autoload)) {
+		require($autoload);
+		break;
+	}
+}
+$yiiDirs = [
+	__DIR__ . '/../../../framework', // in yii2-dev repo
+	__DIR__ . '/vendor/yiisoft/yii2', // standalone with "composer install" run
+	__DIR__ . '/../../../../yiisoft/yii2', // script is installed as a composer binary
+];
+foreach($yiiDirs as $dir) {
+	if (file_exists($dir . '/yii/Yii.php')) {
+		require($dir . '/yii/Yii.php');
+		break;
+	}
+}
+if (!class_exists('Yii')) {
+	echo PHP_EOL . "The Yii Framework 2.0 does not seem to be installed. Try running composer install." . PHP_EOL . PHP_EOL;
+	exit(1);
+}
+
+Yii::setAlias('@yii/apidoc', __DIR__);
+
+$application = new yii\console\Application([
+	'id' => 'yii2-apidoc',
+	'basePath' => __DIR__,
+	'enableCoreCommands' => false,
+	'controllerNamespace' => 'yii\\apidoc\\commands',
+	'controllerPath' => '@yii/apidoc/commands',
+]);
+$exitCode = $application->run();
+exit($exitCode);

extensions/yii/apidoc/apidoc.bat

@@ -0,0 +1,20 @@
+@echo off
+
+rem -------------------------------------------------------------
+rem  Yii command line bootstrap script for Windows.
+rem
+rem  @author Qiang Xue <qiang.xue@gmail.com>
+rem  @link http://www.yiiframework.com/
+rem  @copyright Copyright &copy; 2012 Yii Software LLC
+rem  @license http://www.yiiframework.com/license/
+rem -------------------------------------------------------------
+
+@setlocal
+
+set YII_PATH=%~dp0
+
+if "%PHP_COMMAND%" == "" set PHP_COMMAND=php.exe
+
+"%PHP_COMMAND%" "%YII_PATH%apidoc" %*
+
+@endlocal

extensions/yii/apidoc/commands/RenderController.php

@@ -0,0 +1,144 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\apidoc\commands;
+
+use phpDocumentor\Reflection\FileReflector;
+use TokenReflection\ReflectionFile;
+use yii\apidoc\templates\BaseRenderer;
+use yii\console\Controller;
+use yii\helpers\Console;
+use yii\helpers\FileHelper;
+use yii\apidoc\components\OfflineRenderer;
+use yii\apidoc\models\Context;
+use Yii;
+
+/**
+ * Command to render API Documentation files
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
+class RenderController extends Controller
+{
+	public $template = 'offline';
+
+	/**
+	 * Renders API documentation files
+	 * @param array $sourceDirs
+	 * @param string $targetDir
+	 * @return int
+	 */
+	public function actionIndex(array $sourceDirs, $targetDir)
+	{
+		$targetDir = rtrim(Yii::getAlias($targetDir), '\\/');
+		if (is_dir($targetDir) && !$this->confirm('TargetDirectory already exists. Overwrite?')) {
+			return 2;
+		}
+		if (!is_dir($targetDir)) {
+			mkdir($targetDir);
+		}
+
+		$renderer = $this->findRenderer();
+		$renderer->targetDir = $targetDir;
+
+		$this->stdout('Searching files to process... ');
+		$files = [];
+		foreach($sourceDirs as $source) {
+			foreach($this->findFiles($source) as $fileName) {
+				$files[$fileName] = $fileName;
+			}
+		}
+
+		$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
+
+		$context = new Context();
+
+		$cacheFile = $targetDir . '/cache/' . md5(serialize($files)) . '.tmp';
+		if (file_exists($cacheFile)) {
+			$this->stdout('Loading processed data from cache... ');
+			$context = unserialize(file_get_contents($cacheFile));
+			$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
+
+			$this->stdout('Checking for updated files... ');
+			foreach($context->files as $file => $sha) {
+				if (sha1_file($file) === $sha) {
+					unset($files[$file]);
+				}
+			}
+			$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
+		}
+
+		$fileCount = count($files);
+		$this->stdout($fileCount . ' file' . ($fileCount == 1 ? '' : 's') . ' to update.' . PHP_EOL);
+		Console::startProgress(0, $fileCount, 'Processing files... ', false);
+		$done = 0;
+		foreach($files as $file) {
+			$context->addFile($file);
+			Console::updateProgress(++$done, $fileCount);
+		}
+		Console::endProgress(true);
+		$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
+
+		// save processed data to cache
+		if (!is_dir(dirname($cacheFile))) {
+			mkdir(dirname($cacheFile));
+		}
+		file_put_contents($cacheFile, serialize($context));
+
+		$this->stdout('Updating cross references and backlinks... ');
+		$context->updateReferences();
+		$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
+
+		// render models
+		$renderer->render($context, $this);
+	}
+
+	/**
+	 * @return BaseRenderer
+	 */
+	protected function findRenderer()
+	{
+		$file = Yii::getAlias('@yii/apidoc/templates/' . $this->template . '/Renderer.php');
+		$reflection = new FileReflector($file, true);
+		$reflection->process();
+		$classes = $reflection->getClasses();
+		if (empty($classes)) {
+			$this->stderr('Renderer not found.' . PHP_EOL);
+		}
+		$rendererClass = reset($classes)->getName();
+		require($file);
+		return new $rendererClass();
+	}
+
+	protected function findFiles($path, $except = [])
+	{
+		$path = FileHelper::normalizePath($path);
+		$options = [
+			'filter' => function ($path) {
+				if (is_file($path)) {
+					$file = basename($path);
+					if ($file[0] < 'A' || $file[0] > 'Z') {
+						return false;
+					}
+				}
+				return null;
+			},
+			'only' => ['.php'],
+			'except' => $except,
+		];
+		return FileHelper::findFiles($path, $options);
+	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function globalOptions()
+	{
+		return array_merge(parent::globalOptions(), ['template']);
+	}
+}

extensions/yii/apidoc/composer.json

@@ -0,0 +1,30 @@
+{
+	"name": "yiisoft/yii2-apidoc",
+	"description": "API Documentation generator for the Yii framework 2.0",
+	"keywords": ["yii", "phpdoc", "apidoc", "api", "documentation"],
+	"type": "yii2-extension",
+	"license": "BSD-3-Clause",
+	"support": {
+		"issues": "https://github.com/yiisoft/yii2/issues?labels=ext%3Aapidoc",
+		"forum": "http://www.yiiframework.com/forum/",
+		"wiki": "http://www.yiiframework.com/wiki/",
+		"irc": "irc://irc.freenode.net/yii",
+		"source": "https://github.com/yiisoft/yii2"
+	},
+	"authors": [
+		{
+			"name": "Carsten Brandt",
+			"email": "mail@cebe.cc"
+		}
+	],
+    "minimum-stability": "dev",
+	"require": {
+		"yiisoft/yii2": "*",
+		"phpdocumentor/reflection": "1.0.2"
+	},
+	"autoload": {
+		"psr-0": { "yii\\apidoc\\": "" }
+	},
+	"target-dir": "yii/apidoc",
+	"bin": ["apidoc"]
+}