restructured apidoc templates

extensions/yii/apidoc/README.md

@@ -26,3 +26,13 @@ Usage
 -----
 
 TDB
+
+Creating your own templates
+---------------------------
+
+TDB
+
+Using the model layer
+---------------------
+
+TDB

extensions/yii/apidoc/apidoc

@@ -32,7 +32,7 @@ foreach($yiiDirs as $dir) {
 	}
 }
 if (!class_exists('Yii')) {
-	echo "\nThe Yii Framework 2.0 does not seem to be installed. Try running composer install.\n\n";
+	echo PHP_EOL . "The Yii Framework 2.0 does not seem to be installed. Try running composer install." . PHP_EOL . PHP_EOL;
 	exit(1);
 }
 

extensions/yii/apidoc/commands/RenderController.php

@@ -8,6 +8,8 @@
 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;
@@ -23,6 +25,8 @@ use Yii;
  */
 class RenderController extends Controller
 {
+	public $template = 'offline';
+
 	/**
 	 * Renders API documentation files
 	 * @param array $sourceDirs
@@ -31,7 +35,7 @@ class RenderController extends Controller
 	 */
 	public function actionIndex(array $sourceDirs, $targetDir)
 	{
-		$targetDir = Yii::getAlias($targetDir);
+		$targetDir = rtrim(Yii::getAlias($targetDir), '\\/');
 		if (is_dir($targetDir) && !$this->confirm('TargetDirectory already exists. Overwrite?')) {
 			return 2;
 		}
@@ -39,6 +43,9 @@ class RenderController extends Controller
 			mkdir($targetDir);
 		}
 
+		$renderer = $this->findRenderer();
+		$renderer->targetDir = $targetDir;
+
 		$this->stdout('Searching files to process... ');
 		$files = [];
 		foreach($sourceDirs as $source) {
@@ -88,11 +95,26 @@ class RenderController extends Controller
 		$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
 
 		// render models
-		$renderer = new OfflineRenderer();
-		$renderer->targetDir = $targetDir;
 		$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);
@@ -115,4 +137,12 @@ class RenderController extends Controller
 		];
 		return FileHelper::findFiles($path, $options);
 	}
+
+	/**
+	 * @inheritdoc
+	 */
+	public function globalOptions()
+	{
+		return array_merge(parent::globalOptions(), ['template']);
+	}
 }

extensions/yii/apidoc/models/BaseDoc.php

@@ -11,6 +11,11 @@ use phpDocumentor\Reflection\DocBlock\Tag\DeprecatedTag;
 use phpDocumentor\Reflection\DocBlock\Tag\SinceTag;
 use yii\base\Object;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class BaseDoc extends Object
 {
 	public $name;

extensions/yii/apidoc/models/ClassDoc.php

@@ -8,7 +8,9 @@
 namespace yii\apidoc\models;
 
 /**
- * Class ClassDoc
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
  */
 class ClassDoc extends TypeDoc
 {

extensions/yii/apidoc/models/ConstDoc.php

@@ -7,6 +7,11 @@
 
 namespace yii\apidoc\models;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class ConstDoc extends BaseDoc
 {
 	public $definedBy;

extensions/yii/apidoc/models/Context.php

@@ -7,11 +7,15 @@
 
 namespace yii\apidoc\models;
 
-
 use phpDocumentor\Reflection\FileReflector;
 use yii\base\Component;
 use yii\base\Exception;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class Context extends Component
 {
 	/**

extensions/yii/apidoc/models/EventDoc.php

@@ -10,6 +10,11 @@ namespace yii\apidoc\models;
 use phpDocumentor\Reflection\DocBlock\Tag\ParamTag;
 use phpDocumentor\Reflection\DocBlock\Tag\ReturnTag;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class EventDoc extends ConstDoc
 {
 	public $type;

extensions/yii/apidoc/models/FunctionDoc.php

@@ -13,6 +13,11 @@ use phpDocumentor\Reflection\DocBlock\Tag\ReturnTag;
 use phpDocumentor\Reflection\DocBlock\Tag\ThrowsTag;
 use yii\base\Exception;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class FunctionDoc extends BaseDoc
 {
 	/**

extensions/yii/apidoc/models/InterfaceDoc.php

@@ -7,6 +7,11 @@
 
 namespace yii\apidoc\models;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class InterfaceDoc extends TypeDoc
 {
 	public $parentInterfaces = [];

extensions/yii/apidoc/models/MethodDoc.php

@@ -7,6 +7,11 @@
 
 namespace yii\apidoc\models;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class MethodDoc extends FunctionDoc
 {
 	public $isAbstract;

extensions/yii/apidoc/models/ParamDoc.php

@@ -9,6 +9,11 @@ namespace yii\apidoc\models;
 
 use yii\base\Object;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class ParamDoc extends Object
 {
 	public $name;

extensions/yii/apidoc/models/PropertyDoc.php

@@ -9,6 +9,11 @@ namespace yii\apidoc\models;
 
 use phpDocumentor\Reflection\DocBlock\Tag\VarTag;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class PropertyDoc extends BaseDoc
 {
 	public $visibility;

extensions/yii/apidoc/models/TraitDoc.php

@@ -7,6 +7,11 @@
 
 namespace yii\apidoc\models;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class TraitDoc extends TypeDoc
 {
 	// classes using the trait

extensions/yii/apidoc/models/TypeDoc.php

@@ -11,6 +11,11 @@ use phpDocumentor\Reflection\DocBlock\Tag\AuthorTag;
 use yii\base\Exception;
 use yii\helpers\StringHelper;
 
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 class TypeDoc extends BaseDoc
 {
 	public $authors = [];

extensions/yii/apidoc/templates/BaseRenderer.php

@@ -5,33 +5,28 @@
  * @license http://www.yiiframework.com/license/
  */
 
-namespace yii\apidoc\components;
+namespace yii\apidoc\templates;
 
 use Yii;
 use yii\base\Component;
 use yii\console\Controller;
 use yii\apidoc\models\Context;
+use yii\web\AssetManager;
 use yii\web\View;
 
+/**
+ * Base class for all API documentation renderers
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
 abstract class BaseRenderer extends Component
 {
-
-	private $_view;
-
-
-	public function getView()
-	{
-		if ($this->_view === null) {
-			$this->_view = new View();
-		}
-		return $this->_view;
-	}
-
 	/**
-	 * @param Context $context
-	 * @param Controller $controller
-	 * @return mixed
+	 * Renders a given [[Context]].
+	 *
+	 * @param Context $context the api documentation context to render.
+	 * @param Controller $controller the apidoc controller instance. Can be used to control output.
 	 */
 	public abstract function render($context, $controller);
-
 }

extensions/yii/apidoc/templates/html/README.md

@@ -0,0 +1,4 @@
+The html API doc template
+-------------------------
+
+This templates provides view files and a Renderer class that can be reused in other html templates.

extensions/yii/apidoc/templates/html/Renderer.php

@@ -5,8 +5,7 @@
  * @license http://www.yiiframework.com/license/
  */
 
-namespace yii\apidoc\components;
-
+namespace yii\apidoc\templates\html;
 
 use yii\apidoc\models\BaseDoc;
 use yii\apidoc\models\ConstDoc;
@@ -14,35 +13,80 @@ use yii\apidoc\models\EventDoc;
 use yii\apidoc\models\MethodDoc;
 use yii\apidoc\models\PropertyDoc;
 use yii\apidoc\models\TypeDoc;
+use yii\apidoc\models\ClassDoc;
+use yii\apidoc\models\Context;
+use yii\apidoc\models\InterfaceDoc;
+use yii\apidoc\models\TraitDoc;
+use yii\apidoc\templates\BaseRenderer;
 use yii\base\ViewContextInterface;
 use yii\console\Controller;
 use yii\helpers\Console;
-use yii\helpers\FileHelper;
 use yii\helpers\Html;
-use yii\apidoc\models\ClassDoc;
-use yii\apidoc\models\Context;
 use Yii;
-use yii\apidoc\models\InterfaceDoc;
-use yii\apidoc\models\TraitDoc;
+use yii\web\AssetManager;
+use yii\web\View;
 
-class OfflineRenderer extends BaseRenderer implements ViewContextInterface
+/**
+ * The base class for HTML API documentation renderers.
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
+abstract class Renderer extends BaseRenderer implements ViewContextInterface
 {
+	/**
+	 * @var string directory to use for output of html files. Can be a path alias.
+	 */
 	public $targetDir;
-
-	public $layout = '@yii/apidoc/views/layouts/offline.php';
-	public $typeView = '@yii/apidoc/views/type.php';
-	public $indexView = '@yii/apidoc/views/index.php';
-
+	/**
+	 * @var string string to use as the title of the generated page.
+	 */
 	public $pageTitle = 'Yii Framework 2.0 API Documentation';
-
 	/**
-	 * @var Context
+	 * @var string path or alias of the layout file to use.
+	 */
+	public $layout;
+	/**
+	 * @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 Context the [[Context]] currently being rendered.
 	 */
 	protected $context;
+	/**
+	 * @var View
+	 */
+	private $_view;
+
+	/**
+	 * @return View the view instance
+	 */
+	public function getView()
+	{
+		if ($this->_view === null) {
+			$this->_view = new View();
+			$assetPath = Yii::getAlias($this->targetDir) . '/assets';
+			if (!is_dir($assetPath)) {
+				mkdir($assetPath);
+			}
+			$this->_view->assetManager = new AssetManager([
+				'basePath' => $assetPath,
+				'baseUrl' => '/assets',
+			]);
+		}
+		return $this->_view;
+	}
 
 	/**
-	 * @param Context $context
-	 * @param Controller $controller
+	 * Renders a given [[Context]].
+	 *
+	 * @param Context $context the api documentation context to render.
+	 * @param Controller $controller the apidoc controller instance. Can be used to control output.
 	 */
 	public function render($context, $controller)
 	{
@@ -72,11 +116,6 @@ class OfflineRenderer extends BaseRenderer implements ViewContextInterface
 		Console::updateProgress(++$done, $typeCount);
 		Console::endProgress(true);
 		$controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
-
-		$controller->stdout('Copying asset files... ');
-		FileHelper::copyDirectory(__DIR__ . '/../assets/css', $dir . '/css');
-		$controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
-
 	}
 
 	protected function renderWithLayout($viewFile, $params)
@@ -93,7 +132,7 @@ class OfflineRenderer extends BaseRenderer implements ViewContextInterface
 	/**
 	 * creates a link to a type (class, interface or trait)
 	 * @param ClassDoc|InterfaceDoc|TraitDoc $types
-	 * @param string $title
+	 * @param BaseDoc $context
 	 * @return string
 	 */
 	public function typeLink($types, $context = null)
@@ -161,6 +200,7 @@ class OfflineRenderer extends BaseRenderer implements ViewContextInterface
 	 */
 	private function resolveNamespace($context)
 	{
+		// TODO use phpdoc Context for this
 		if ($context === null) {
 			return '';
 		}
@@ -285,8 +325,6 @@ class OfflineRenderer extends BaseRenderer implements ViewContextInterface
 				. ($param->isOptional ? ' = ' . $param->defaultValue : '');
 		}
 
-		//<?php echo preg_replace('/\{\{([^\{\}]*?)\|([^\{\}]*?)\}\}\(/','$2(',$method->signature);
-
 		return ($method->isReturnByReference ? '<b>&</b>' : '')
 			. ($method->returnType === null ? 'void' : $this->typeLink($method->returnTypes))
 			. ' ' . $method->name . '( '
@@ -294,7 +332,7 @@ class OfflineRenderer extends BaseRenderer implements ViewContextInterface
 			. ' )';
 	}
 
-	public function generateFileName($typeName)
+	protected function generateFileName($typeName)
 	{
 		return strtolower(str_replace('\\', '_', $typeName)) . '.html';
 	}
@@ -306,6 +344,6 @@ class OfflineRenderer extends BaseRenderer implements ViewContextInterface
 	 */
 	public function findViewFile($view)
 	{
-		return Yii::getAlias('@yii/apidoc/views/' . $view);
+		return Yii::getAlias('@yii/apidoc/templates/html/views/' . $view);
 	}
 }

extensions/yii/apidoc/templates/html/views/type.php

@@ -81,21 +81,21 @@ $renderer = $this->context;
 </div>
 
 <a name="properties"></a>
-<?= $this->render('propertySummary', ['type' => $type,'protected' => false]) ?>
-<?= $this->render('propertySummary', ['type' => $type,'protected' => true]) ?>
+<?= $this->render('@yii/apidoc/templates/html/views/propertySummary', ['type' => $type,'protected' => false]) ?>
+<?= $this->render('@yii/apidoc/templates/html/views/propertySummary', ['type' => $type,'protected' => true]) ?>
 
 <a name="methods"></a>
-<?= $this->render('methodSummary', ['type' => $type, 'protected' => false]) ?>
-<?= $this->render('methodSummary', ['type' => $type, 'protected' => true]) ?>
+<?= $this->render('@yii/apidoc/templates/html/views/methodSummary', ['type' => $type, 'protected' => false]) ?>
+<?= $this->render('@yii/apidoc/templates/html/views/methodSummary', ['type' => $type, 'protected' => true]) ?>
 
 <a name="events"></a>
-<?= $this->render('eventSummary', ['type' => $type]) ?>
+<?= $this->render('@yii/apidoc/templates/html/views/eventSummary', ['type' => $type]) ?>
 
 <a name="constants"></a>
-<?= $this->render('constSummary', ['type' => $type]) ?>
+<?= $this->render('@yii/apidoc/templates/html/views/constSummary', ['type' => $type]) ?>
 
-<?= $this->render('propertyDetails', ['type' => $type]) ?>
-<?= $this->render('methodDetails', ['type' => $type]) ?>
+<?= $this->render('@yii/apidoc/templates/html/views/propertyDetails', ['type' => $type]) ?>
+<?= $this->render('@yii/apidoc/templates/html/views/methodDetails', ['type' => $type]) ?>
 <?php if($type instanceof ClassDoc): ?>
-	<?= $this->render('eventDetails', ['type' => $type]) ?>
+	<?= $this->render('@yii/apidoc/templates/html/views/eventDetails', ['type' => $type]) ?>
 <?php endif; ?>

extensions/yii/apidoc/templates/offline/Renderer.php

@@ -0,0 +1,44 @@
+<?php
+/**
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
+ */
+
+namespace yii\apidoc\templates\offline;
+use yii\apidoc\models\Context;
+use yii\console\Controller;
+use Yii;
+use yii\helpers\Console;
+use yii\helpers\FileHelper;
+
+/**
+ *
+ * @author Carsten Brandt <mail@cebe.cc>
+ * @since 2.0
+ */
+class Renderer extends \yii\apidoc\templates\html\Renderer
+{
+	public $layout = '@yii/apidoc/templates/offline/views/offline.php';
+	public $indexView = '@yii/apidoc/templates/offline/views/index.php';
+
+	public $pageTitle = 'Yii Framework 2.0 API Documentation';
+
+	/**
+	 * Renders a given [[Context]].
+	 *
+	 * @param Context $context the api documentation context to render.
+	 * @param Controller $controller the apidoc controller instance. Can be used to control output.
+	 */
+	public function render($context, $controller)
+	{
+		parent::render($context, $controller);
+
+		$dir = Yii::getAlias($this->targetDir);
+
+		$controller->stdout('Copying asset files... ');
+		FileHelper::copyDirectory(__DIR__ . '/assets/css', $dir . '/css');
+		$controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
+	}
+
+}

extensions/yii/apidoc/templates/offline/views/offline.php

@@ -35,6 +35,7 @@ $this->beginPage();
 All Rights Reserved.<br/>
 </div><!-- end of footer -->
 
+<?php \yii\web\JqueryAsset::register($this); ?>
 <script type="text/javascript">
 /*<![CDATA[*/
 $("a.toggle").toggle(function(){