Browse Source

restructured apidoc templates

tags/2.0.0-beta
Carsten Brandt 11 years ago
parent
commit
f7e00887d6
  1. 10
      extensions/yii/apidoc/README.md
  2. 2
      extensions/yii/apidoc/apidoc
  3. 36
      extensions/yii/apidoc/commands/RenderController.php
  4. 5
      extensions/yii/apidoc/models/BaseDoc.php
  5. 4
      extensions/yii/apidoc/models/ClassDoc.php
  6. 5
      extensions/yii/apidoc/models/ConstDoc.php
  7. 6
      extensions/yii/apidoc/models/Context.php
  8. 5
      extensions/yii/apidoc/models/EventDoc.php
  9. 5
      extensions/yii/apidoc/models/FunctionDoc.php
  10. 5
      extensions/yii/apidoc/models/InterfaceDoc.php
  11. 5
      extensions/yii/apidoc/models/MethodDoc.php
  12. 5
      extensions/yii/apidoc/models/ParamDoc.php
  13. 5
      extensions/yii/apidoc/models/PropertyDoc.php
  14. 5
      extensions/yii/apidoc/models/TraitDoc.php
  15. 5
      extensions/yii/apidoc/models/TypeDoc.php
  16. 31
      extensions/yii/apidoc/templates/BaseRenderer.php
  17. 4
      extensions/yii/apidoc/templates/html/README.md
  18. 92
      extensions/yii/apidoc/templates/html/Renderer.php
  19. 0
      extensions/yii/apidoc/templates/html/views/constSummary.php
  20. 0
      extensions/yii/apidoc/templates/html/views/eventDetails.php
  21. 0
      extensions/yii/apidoc/templates/html/views/eventSummary.php
  22. 0
      extensions/yii/apidoc/templates/html/views/methodDetails.php
  23. 0
      extensions/yii/apidoc/templates/html/views/methodSummary.php
  24. 0
      extensions/yii/apidoc/templates/html/views/propertyDetails.php
  25. 0
      extensions/yii/apidoc/templates/html/views/propertySummary.php
  26. 0
      extensions/yii/apidoc/templates/html/views/seeAlso.php
  27. 18
      extensions/yii/apidoc/templates/html/views/type.php
  28. 44
      extensions/yii/apidoc/templates/offline/Renderer.php
  29. 0
      extensions/yii/apidoc/templates/offline/assets/css/api.css
  30. 0
      extensions/yii/apidoc/templates/offline/assets/css/style.css
  31. 0
      extensions/yii/apidoc/templates/offline/views/index.php
  32. 1
      extensions/yii/apidoc/templates/offline/views/offline.php

10
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

2
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);
}

36
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']);
}
}

5
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;

4
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
{

5
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;

6
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
{
/**

5
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;

5
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
{
/**

5
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 = [];

5
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;

5
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;

5
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;

5
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

5
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 = [];

31
extensions/yii/apidoc/components/BaseRenderer.php → extensions/yii/apidoc/templates/BaseRenderer.php vendored

@ -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);
}
}

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

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

92
extensions/yii/apidoc/components/OfflineRenderer.php → extensions/yii/apidoc/templates/html/Renderer.php vendored

@ -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);
}
}

0
extensions/yii/apidoc/views/constSummary.php → extensions/yii/apidoc/templates/html/views/constSummary.php vendored

0
extensions/yii/apidoc/views/eventDetails.php → extensions/yii/apidoc/templates/html/views/eventDetails.php vendored

0
extensions/yii/apidoc/views/eventSummary.php → extensions/yii/apidoc/templates/html/views/eventSummary.php vendored

0
extensions/yii/apidoc/views/methodDetails.php → extensions/yii/apidoc/templates/html/views/methodDetails.php vendored

0
extensions/yii/apidoc/views/methodSummary.php → extensions/yii/apidoc/templates/html/views/methodSummary.php vendored

0
extensions/yii/apidoc/views/propertyDetails.php → extensions/yii/apidoc/templates/html/views/propertyDetails.php vendored

0
extensions/yii/apidoc/views/propertySummary.php → extensions/yii/apidoc/templates/html/views/propertySummary.php vendored

0
extensions/yii/apidoc/views/seeAlso.php → extensions/yii/apidoc/templates/html/views/seeAlso.php vendored

18
extensions/yii/apidoc/views/type.php → extensions/yii/apidoc/templates/html/views/type.php vendored

@ -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; ?>

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

@ -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);
}
}

0
extensions/yii/apidoc/assets/css/api.css → extensions/yii/apidoc/templates/offline/assets/css/api.css vendored

0
extensions/yii/apidoc/assets/css/style.css → extensions/yii/apidoc/templates/offline/assets/css/style.css vendored

0
extensions/yii/apidoc/views/index.php → extensions/yii/apidoc/templates/offline/views/index.php vendored

1
extensions/yii/apidoc/views/layouts/offline.php → extensions/yii/apidoc/templates/offline/views/offline.php vendored

@ -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(){
Loading…
Cancel
Save