You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
283 lines
7.1 KiB
283 lines
7.1 KiB
11 years ago
|
<?php
|
||
|
/**
|
||
11 years ago
|
* @link http://www.yiiframework.com/
|
||
|
* @copyright Copyright (c) 2008 Yii Software LLC
|
||
|
* @license http://www.yiiframework.com/license/
|
||
11 years ago
|
*/
|
||
|
|
||
11 years ago
|
namespace yii\apidoc\templates\html;
|
||
11 years ago
|
|
||
11 years ago
|
use yii\apidoc\models\MethodDoc;
|
||
|
use yii\apidoc\models\PropertyDoc;
|
||
11 years ago
|
use yii\apidoc\models\ClassDoc;
|
||
|
use yii\apidoc\models\Context;
|
||
11 years ago
|
use yii\apidoc\renderers\ApiRenderer as BaseApiRenderer;
|
||
11 years ago
|
use yii\base\ViewContextInterface;
|
||
|
use yii\helpers\Console;
|
||
|
use yii\helpers\Html;
|
||
11 years ago
|
use yii\web\AssetManager;
|
||
|
use yii\web\View;
|
||
11 years ago
|
use Yii;
|
||
11 years ago
|
|
||
11 years ago
|
/**
|
||
|
* The base class for HTML API documentation renderers.
|
||
|
*
|
||
11 years ago
|
* @property View $view The view instance. This property is read-only.
|
||
|
*
|
||
11 years ago
|
* @author Carsten Brandt <mail@cebe.cc>
|
||
|
* @since 2.0
|
||
|
*/
|
||
11 years ago
|
class ApiRenderer extends BaseApiRenderer implements ViewContextInterface
|
||
11 years ago
|
{
|
||
11 years ago
|
/**
|
||
|
* @var string string to use as the title of the generated page.
|
||
|
*/
|
||
11 years ago
|
public $pageTitle;
|
||
11 years ago
|
/**
|
||
11 years ago
|
* @var string path or alias of the layout file to use.
|
||
|
*/
|
||
11 years ago
|
public $layout;
|
||
11 years ago
|
/**
|
||
|
* @var string path or alias of the view file to use for rendering types (classes, interfaces, traits).
|
||
|
*/
|
||
|
public $typeView = '@yii/apidoc/templates/html/views/type.php';
|
||
|
/**
|
||
|
* @var string path or alias of the view file to use for rendering the index page.
|
||
|
*/
|
||
|
public $indexView = '@yii/apidoc/templates/html/views/index.php';
|
||
|
/**
|
||
|
* @var View
|
||
|
*/
|
||
|
private $_view;
|
||
11 years ago
|
private $_targetDir;
|
||
11 years ago
|
|
||
11 years ago
|
|
||
|
public function init()
|
||
|
{
|
||
11 years ago
|
parent::init();
|
||
|
|
||
|
if ($this->pageTitle === null) {
|
||
|
$this->pageTitle = 'Yii Framework 2.0 API Documentation'; // TODO guess page title
|
||
|
}
|
||
11 years ago
|
}
|
||
|
|
||
11 years ago
|
/**
|
||
|
* @return View the view instance
|
||
|
*/
|
||
|
public function getView()
|
||
|
{
|
||
|
if ($this->_view === null) {
|
||
|
$this->_view = new View();
|
||
11 years ago
|
$assetPath = Yii::getAlias($this->_targetDir) . '/assets';
|
||
11 years ago
|
if (!is_dir($assetPath)) {
|
||
|
mkdir($assetPath);
|
||
|
}
|
||
|
$this->_view->assetManager = new AssetManager([
|
||
|
'basePath' => $assetPath,
|
||
11 years ago
|
'baseUrl' => './assets',
|
||
11 years ago
|
]);
|
||
|
}
|
||
|
return $this->_view;
|
||
|
}
|
||
11 years ago
|
|
||
|
/**
|
||
11 years ago
|
* Renders a given [[Context]].
|
||
|
*
|
||
|
* @param Context $context the api documentation context to render.
|
||
11 years ago
|
* @param $targetDir
|
||
11 years ago
|
*/
|
||
11 years ago
|
public function render($context, $targetDir)
|
||
11 years ago
|
{
|
||
11 years ago
|
$this->apiContext = $context;
|
||
|
$this->_targetDir = $targetDir;
|
||
11 years ago
|
|
||
11 years ago
|
$types = array_merge($context->classes, $context->interfaces, $context->traits);
|
||
|
$typeCount = count($types) + 1;
|
||
11 years ago
|
|
||
|
if ($this->controller !== null) {
|
||
|
Console::startProgress(0, $typeCount, 'Rendering files: ', false);
|
||
|
}
|
||
11 years ago
|
$done = 0;
|
||
11 years ago
|
foreach($types as $type) {
|
||
|
$fileContent = $this->renderWithLayout($this->typeView, [
|
||
|
'type' => $type,
|
||
11 years ago
|
'apiContext' => $context,
|
||
11 years ago
|
'types' => $types,
|
||
11 years ago
|
]);
|
||
11 years ago
|
file_put_contents($targetDir . '/' . $this->generateFileName($type->name), $fileContent);
|
||
|
|
||
|
if ($this->controller !== null) {
|
||
|
Console::updateProgress(++$done, $typeCount);
|
||
|
}
|
||
11 years ago
|
}
|
||
11 years ago
|
|
||
11 years ago
|
$indexFileContent = $this->renderWithLayout($this->indexView, [
|
||
11 years ago
|
'apiContext' => $context,
|
||
11 years ago
|
'types' => $types,
|
||
11 years ago
|
]);
|
||
11 years ago
|
file_put_contents($targetDir . '/index.html', $indexFileContent);
|
||
|
|
||
|
if ($this->controller !== null) {
|
||
|
Console::updateProgress(++$done, $typeCount);
|
||
|
Console::endProgress(true);
|
||
|
$this->controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
|
||
|
}
|
||
11 years ago
|
}
|
||
|
|
||
|
protected function renderWithLayout($viewFile, $params)
|
||
|
{
|
||
|
$output = $this->getView()->render($viewFile, $params, $this);
|
||
11 years ago
|
if ($this->layout !== false) {
|
||
11 years ago
|
$params['content'] = $output;
|
||
11 years ago
|
return $this->getView()->renderFile($this->layout, $params, $this);
|
||
11 years ago
|
} else {
|
||
|
return $output;
|
||
|
}
|
||
|
}
|
||
|
|
||
|
/**
|
||
|
* @param ClassDoc $class
|
||
|
* @return string
|
||
|
*/
|
||
|
public function renderInheritance($class)
|
||
|
{
|
||
11 years ago
|
$parents = [];
|
||
11 years ago
|
$parents[] = $this->createTypeLink($class);
|
||
11 years ago
|
while ($class->parentClass !== null) {
|
||
11 years ago
|
if(isset($this->apiContext->classes[$class->parentClass])) {
|
||
|
$class = $this->apiContext->classes[$class->parentClass];
|
||
|
$parents[] = $this->createTypeLink($class);
|
||
11 years ago
|
} else {
|
||
|
$parents[] = $class->parentClass; // TODO link to php.net
|
||
|
break;
|
||
|
}
|
||
|
}
|
||
11 years ago
|
return implode(" »\n", $parents);
|
||
11 years ago
|
}
|
||
|
|
||
|
/**
|
||
11 years ago
|
* @param array $names
|
||
11 years ago
|
* @return string
|
||
|
*/
|
||
11 years ago
|
public function renderInterfaces($names)
|
||
11 years ago
|
{
|
||
|
$interfaces = [];
|
||
11 years ago
|
sort($names, SORT_STRING);
|
||
|
foreach($names as $interface) {
|
||
11 years ago
|
if(isset($this->apiContext->interfaces[$interface])) {
|
||
|
$interfaces[] = $this->createTypeLink($this->apiContext->interfaces[$interface]);
|
||
11 years ago
|
} else {
|
||
|
$interfaces[] = $interface; // TODO link to php.net
|
||
|
}
|
||
|
}
|
||
11 years ago
|
return implode(', ', $interfaces);
|
||
11 years ago
|
}
|
||
|
|
||
|
/**
|
||
11 years ago
|
* @param array $names
|
||
11 years ago
|
* @return string
|
||
|
*/
|
||
11 years ago
|
public function renderTraits($names)
|
||
11 years ago
|
{
|
||
|
$traits = [];
|
||
11 years ago
|
sort($names, SORT_STRING);
|
||
|
foreach($names as $trait) {
|
||
11 years ago
|
if(isset($this->apiContext->traits[$trait])) {
|
||
|
$traits[] = $this->createTypeLink($this->apiContext->traits[$trait]);
|
||
11 years ago
|
} else {
|
||
|
$traits[] = $trait; // TODO link to php.net
|
||
|
}
|
||
|
}
|
||
11 years ago
|
return implode(', ', $traits);
|
||
11 years ago
|
}
|
||
|
|
||
11 years ago
|
/**
|
||
|
* @param array $names
|
||
|
* @return string
|
||
|
*/
|
||
|
public function renderClasses($names)
|
||
11 years ago
|
{
|
||
11 years ago
|
$classes = [];
|
||
|
sort($names, SORT_STRING);
|
||
|
foreach($names as $class) {
|
||
11 years ago
|
if(isset($this->apiContext->classes[$class])) {
|
||
|
$classes[] = $this->createTypeLink($this->apiContext->classes[$class]);
|
||
11 years ago
|
} else {
|
||
11 years ago
|
$classes[] = $class; // TODO link to php.net
|
||
11 years ago
|
}
|
||
|
}
|
||
11 years ago
|
return implode(', ', $classes);
|
||
11 years ago
|
}
|
||
|
|
||
11 years ago
|
/**
|
||
|
* @param PropertyDoc $property
|
||
|
* @return string
|
||
|
*/
|
||
|
public function renderPropertySignature($property)
|
||
|
{
|
||
11 years ago
|
if ($property->getter !== null || $property->setter !== null) {
|
||
|
$sig = [];
|
||
|
if ($property->getter !== null) {
|
||
|
$sig[] = $this->renderMethodSignature($property->getter);
|
||
|
}
|
||
|
if ($property->setter !== null) {
|
||
|
$sig[] = $this->renderMethodSignature($property->setter);
|
||
|
}
|
||
|
return implode('<br />', $sig);
|
||
11 years ago
|
}
|
||
11 years ago
|
return $this->createTypeLink($property->types) . ' ' . $property->name . ' = ' . ($property->defaultValue === null ? 'null' : $property->defaultValue);
|
||
11 years ago
|
}
|
||
|
|
||
|
/**
|
||
|
* @param MethodDoc $method
|
||
|
* @return string
|
||
|
*/
|
||
|
public function renderMethodSignature($method)
|
||
|
{
|
||
|
$params = [];
|
||
|
foreach($method->params as $param) {
|
||
|
$params[] = (empty($param->typeHint) ? '' : $param->typeHint . ' ')
|
||
|
. ($param->isPassedByReference ? '<b>&</b>' : '')
|
||
|
. $param->name
|
||
|
. ($param->isOptional ? ' = ' . $param->defaultValue : '');
|
||
|
}
|
||
|
|
||
|
return ($method->isReturnByReference ? '<b>&</b>' : '')
|
||
11 years ago
|
. ($method->returnType === null ? 'void' : $this->createTypeLink($method->returnTypes))
|
||
|
. ' ' . $this->createSubjectLink($method, $method->name) . '( '
|
||
11 years ago
|
. implode(', ', $params)
|
||
|
. ' )';
|
||
|
}
|
||
11 years ago
|
|
||
11 years ago
|
public function generateApiUrl($typeName)
|
||
11 years ago
|
{
|
||
|
return $this->generateFileName($typeName);
|
||
|
}
|
||
|
|
||
11 years ago
|
protected function generateFileName($typeName)
|
||
11 years ago
|
{
|
||
11 years ago
|
return strtolower(str_replace('\\', '-', $typeName)) . '.html';
|
||
11 years ago
|
}
|
||
|
|
||
|
/**
|
||
|
* Finds the view file corresponding to the specified relative view name.
|
||
|
* @param string $view a relative view name. The name does NOT start with a slash.
|
||
|
* @return string the view file path. Note that the file may not exist.
|
||
|
*/
|
||
|
public function findViewFile($view)
|
||
|
{
|
||
11 years ago
|
return Yii::getAlias('@yii/apidoc/templates/html/views/' . $view);
|
||
11 years ago
|
}
|
||
11 years ago
|
|
||
|
/**
|
||
|
* generate link markup
|
||
|
* @param $text
|
||
|
* @param $href
|
||
|
* @return mixed
|
||
|
*/
|
||
|
protected function generateLink($text, $href)
|
||
|
{
|
||
|
return Html::a($text, null, ['href' => $href]);
|
||
|
}
|
||
11 years ago
|
}
|