diff --git a/extensions/yii/apidoc/README.md b/extensions/yii/apidoc/README.md index b733d7d..7d20c71 100644 --- a/extensions/yii/apidoc/README.md +++ b/extensions/yii/apidoc/README.md @@ -25,4 +25,14 @@ to the require section of your composer.json. Usage ----- +TDB + +Creating your own templates +--------------------------- + +TDB + +Using the model layer +--------------------- + TDB \ No newline at end of file diff --git a/extensions/yii/apidoc/apidoc b/extensions/yii/apidoc/apidoc index 91f7981..c19d642 100755 --- a/extensions/yii/apidoc/apidoc +++ b/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); } diff --git a/extensions/yii/apidoc/commands/RenderController.php b/extensions/yii/apidoc/commands/RenderController.php index 33aee50..8a46de3 100644 --- a/extensions/yii/apidoc/commands/RenderController.php +++ b/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']); + } } \ No newline at end of file diff --git a/extensions/yii/apidoc/models/BaseDoc.php b/extensions/yii/apidoc/models/BaseDoc.php index d52011c..b595dcc 100644 --- a/extensions/yii/apidoc/models/BaseDoc.php +++ b/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 + * @since 2.0 + */ class BaseDoc extends Object { public $name; diff --git a/extensions/yii/apidoc/models/ClassDoc.php b/extensions/yii/apidoc/models/ClassDoc.php index 82da1d5..a70ae85 100644 --- a/extensions/yii/apidoc/models/ClassDoc.php +++ b/extensions/yii/apidoc/models/ClassDoc.php @@ -8,7 +8,9 @@ namespace yii\apidoc\models; /** - * Class ClassDoc + * + * @author Carsten Brandt + * @since 2.0 */ class ClassDoc extends TypeDoc { diff --git a/extensions/yii/apidoc/models/ConstDoc.php b/extensions/yii/apidoc/models/ConstDoc.php index b1d3a93..a0fbf08 100644 --- a/extensions/yii/apidoc/models/ConstDoc.php +++ b/extensions/yii/apidoc/models/ConstDoc.php @@ -7,6 +7,11 @@ namespace yii\apidoc\models; +/** + * + * @author Carsten Brandt + * @since 2.0 + */ class ConstDoc extends BaseDoc { public $definedBy; diff --git a/extensions/yii/apidoc/models/Context.php b/extensions/yii/apidoc/models/Context.php index 549c318..5378195 100644 --- a/extensions/yii/apidoc/models/Context.php +++ b/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 + * @since 2.0 + */ class Context extends Component { /** diff --git a/extensions/yii/apidoc/models/EventDoc.php b/extensions/yii/apidoc/models/EventDoc.php index 78aee19..41771c5 100644 --- a/extensions/yii/apidoc/models/EventDoc.php +++ b/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 + * @since 2.0 + */ class EventDoc extends ConstDoc { public $type; diff --git a/extensions/yii/apidoc/models/FunctionDoc.php b/extensions/yii/apidoc/models/FunctionDoc.php index 30338a6..1120f77 100644 --- a/extensions/yii/apidoc/models/FunctionDoc.php +++ b/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 + * @since 2.0 + */ class FunctionDoc extends BaseDoc { /** diff --git a/extensions/yii/apidoc/models/InterfaceDoc.php b/extensions/yii/apidoc/models/InterfaceDoc.php index 8aea744..57cd9ce 100644 --- a/extensions/yii/apidoc/models/InterfaceDoc.php +++ b/extensions/yii/apidoc/models/InterfaceDoc.php @@ -7,6 +7,11 @@ namespace yii\apidoc\models; +/** + * + * @author Carsten Brandt + * @since 2.0 + */ class InterfaceDoc extends TypeDoc { public $parentInterfaces = []; diff --git a/extensions/yii/apidoc/models/MethodDoc.php b/extensions/yii/apidoc/models/MethodDoc.php index 96ca5c3..0f7288f 100644 --- a/extensions/yii/apidoc/models/MethodDoc.php +++ b/extensions/yii/apidoc/models/MethodDoc.php @@ -7,6 +7,11 @@ namespace yii\apidoc\models; +/** + * + * @author Carsten Brandt + * @since 2.0 + */ class MethodDoc extends FunctionDoc { public $isAbstract; diff --git a/extensions/yii/apidoc/models/ParamDoc.php b/extensions/yii/apidoc/models/ParamDoc.php index da5127b..0d4c162 100644 --- a/extensions/yii/apidoc/models/ParamDoc.php +++ b/extensions/yii/apidoc/models/ParamDoc.php @@ -9,6 +9,11 @@ namespace yii\apidoc\models; use yii\base\Object; +/** + * + * @author Carsten Brandt + * @since 2.0 + */ class ParamDoc extends Object { public $name; diff --git a/extensions/yii/apidoc/models/PropertyDoc.php b/extensions/yii/apidoc/models/PropertyDoc.php index 68fc414..cf17b0d 100644 --- a/extensions/yii/apidoc/models/PropertyDoc.php +++ b/extensions/yii/apidoc/models/PropertyDoc.php @@ -9,6 +9,11 @@ namespace yii\apidoc\models; use phpDocumentor\Reflection\DocBlock\Tag\VarTag; +/** + * + * @author Carsten Brandt + * @since 2.0 + */ class PropertyDoc extends BaseDoc { public $visibility; diff --git a/extensions/yii/apidoc/models/TraitDoc.php b/extensions/yii/apidoc/models/TraitDoc.php index 347640a..37f1799 100644 --- a/extensions/yii/apidoc/models/TraitDoc.php +++ b/extensions/yii/apidoc/models/TraitDoc.php @@ -7,6 +7,11 @@ namespace yii\apidoc\models; +/** + * + * @author Carsten Brandt + * @since 2.0 + */ class TraitDoc extends TypeDoc { // classes using the trait diff --git a/extensions/yii/apidoc/models/TypeDoc.php b/extensions/yii/apidoc/models/TypeDoc.php index d892a3d..9ceaf26 100644 --- a/extensions/yii/apidoc/models/TypeDoc.php +++ b/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 + * @since 2.0 + */ class TypeDoc extends BaseDoc { public $authors = []; diff --git a/extensions/yii/apidoc/components/BaseRenderer.php b/extensions/yii/apidoc/templates/BaseRenderer.php similarity index 50% rename from extensions/yii/apidoc/components/BaseRenderer.php rename to extensions/yii/apidoc/templates/BaseRenderer.php index 5b8fb69..4f29e43 100644 --- a/extensions/yii/apidoc/components/BaseRenderer.php +++ b/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 + * @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); - -} \ No newline at end of file +} \ No newline at end of file diff --git a/extensions/yii/apidoc/templates/html/README.md b/extensions/yii/apidoc/templates/html/README.md new file mode 100644 index 0000000..90e3b35 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/extensions/yii/apidoc/components/OfflineRenderer.php b/extensions/yii/apidoc/templates/html/Renderer.php similarity index 79% rename from extensions/yii/apidoc/components/OfflineRenderer.php rename to extensions/yii/apidoc/templates/html/Renderer.php index bb06141..bf730c7 100644 --- a/extensions/yii/apidoc/components/OfflineRenderer.php +++ b/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 + * @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 : ''); } - //signature); - return ($method->isReturnByReference ? '&' : '') . ($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); } } \ No newline at end of file diff --git a/extensions/yii/apidoc/views/constSummary.php b/extensions/yii/apidoc/templates/html/views/constSummary.php similarity index 100% rename from extensions/yii/apidoc/views/constSummary.php rename to extensions/yii/apidoc/templates/html/views/constSummary.php diff --git a/extensions/yii/apidoc/views/eventDetails.php b/extensions/yii/apidoc/templates/html/views/eventDetails.php similarity index 100% rename from extensions/yii/apidoc/views/eventDetails.php rename to extensions/yii/apidoc/templates/html/views/eventDetails.php diff --git a/extensions/yii/apidoc/views/eventSummary.php b/extensions/yii/apidoc/templates/html/views/eventSummary.php similarity index 100% rename from extensions/yii/apidoc/views/eventSummary.php rename to extensions/yii/apidoc/templates/html/views/eventSummary.php diff --git a/extensions/yii/apidoc/views/methodDetails.php b/extensions/yii/apidoc/templates/html/views/methodDetails.php similarity index 100% rename from extensions/yii/apidoc/views/methodDetails.php rename to extensions/yii/apidoc/templates/html/views/methodDetails.php diff --git a/extensions/yii/apidoc/views/methodSummary.php b/extensions/yii/apidoc/templates/html/views/methodSummary.php similarity index 100% rename from extensions/yii/apidoc/views/methodSummary.php rename to extensions/yii/apidoc/templates/html/views/methodSummary.php diff --git a/extensions/yii/apidoc/views/propertyDetails.php b/extensions/yii/apidoc/templates/html/views/propertyDetails.php similarity index 100% rename from extensions/yii/apidoc/views/propertyDetails.php rename to extensions/yii/apidoc/templates/html/views/propertyDetails.php diff --git a/extensions/yii/apidoc/views/propertySummary.php b/extensions/yii/apidoc/templates/html/views/propertySummary.php similarity index 100% rename from extensions/yii/apidoc/views/propertySummary.php rename to extensions/yii/apidoc/templates/html/views/propertySummary.php diff --git a/extensions/yii/apidoc/views/seeAlso.php b/extensions/yii/apidoc/templates/html/views/seeAlso.php similarity index 100% rename from extensions/yii/apidoc/views/seeAlso.php rename to extensions/yii/apidoc/templates/html/views/seeAlso.php diff --git a/extensions/yii/apidoc/views/type.php b/extensions/yii/apidoc/templates/html/views/type.php similarity index 75% rename from extensions/yii/apidoc/views/type.php rename to extensions/yii/apidoc/templates/html/views/type.php index a911b63..50959dc 100644 --- a/extensions/yii/apidoc/views/type.php +++ b/extensions/yii/apidoc/templates/html/views/type.php @@ -81,21 +81,21 @@ $renderer = $this->context; -render('propertySummary', ['type' => $type,'protected' => false]) ?> -render('propertySummary', ['type' => $type,'protected' => true]) ?> +render('@yii/apidoc/templates/html/views/propertySummary', ['type' => $type,'protected' => false]) ?> +render('@yii/apidoc/templates/html/views/propertySummary', ['type' => $type,'protected' => true]) ?> -render('methodSummary', ['type' => $type, 'protected' => false]) ?> -render('methodSummary', ['type' => $type, 'protected' => true]) ?> +render('@yii/apidoc/templates/html/views/methodSummary', ['type' => $type, 'protected' => false]) ?> +render('@yii/apidoc/templates/html/views/methodSummary', ['type' => $type, 'protected' => true]) ?> -render('eventSummary', ['type' => $type]) ?> +render('@yii/apidoc/templates/html/views/eventSummary', ['type' => $type]) ?> -render('constSummary', ['type' => $type]) ?> +render('@yii/apidoc/templates/html/views/constSummary', ['type' => $type]) ?> -render('propertyDetails', ['type' => $type]) ?> -render('methodDetails', ['type' => $type]) ?> +render('@yii/apidoc/templates/html/views/propertyDetails', ['type' => $type]) ?> +render('@yii/apidoc/templates/html/views/methodDetails', ['type' => $type]) ?> - render('eventDetails', ['type' => $type]) ?> + render('@yii/apidoc/templates/html/views/eventDetails', ['type' => $type]) ?> diff --git a/extensions/yii/apidoc/templates/offline/Renderer.php b/extensions/yii/apidoc/templates/offline/Renderer.php new file mode 100644 index 0000000..1e544b7 --- /dev/null +++ b/extensions/yii/apidoc/templates/offline/Renderer.php @@ -0,0 +1,44 @@ + + * @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); + } + +} \ No newline at end of file diff --git a/extensions/yii/apidoc/assets/css/api.css b/extensions/yii/apidoc/templates/offline/assets/css/api.css similarity index 100% rename from extensions/yii/apidoc/assets/css/api.css rename to extensions/yii/apidoc/templates/offline/assets/css/api.css diff --git a/extensions/yii/apidoc/assets/css/style.css b/extensions/yii/apidoc/templates/offline/assets/css/style.css similarity index 100% rename from extensions/yii/apidoc/assets/css/style.css rename to extensions/yii/apidoc/templates/offline/assets/css/style.css diff --git a/extensions/yii/apidoc/views/index.php b/extensions/yii/apidoc/templates/offline/views/index.php similarity index 100% rename from extensions/yii/apidoc/views/index.php rename to extensions/yii/apidoc/templates/offline/views/index.php diff --git a/extensions/yii/apidoc/views/layouts/offline.php b/extensions/yii/apidoc/templates/offline/views/offline.php similarity index 96% rename from extensions/yii/apidoc/views/layouts/offline.php rename to extensions/yii/apidoc/templates/offline/views/offline.php index 809de75..36b2487 100644 --- a/extensions/yii/apidoc/views/layouts/offline.php +++ b/extensions/yii/apidoc/templates/offline/views/offline.php @@ -35,6 +35,7 @@ $this->beginPage(); All Rights Reserved.
+