Skip to content

Y
yii2
Commit c239afbf by Carsten Brandt
Options

added guide to apidoc bootstrap template

parent 49c62e68
Showing with 268 additions and 107 deletions
extensions/apidoc/commands/RenderController.php
......@@ -25,7 +25,9 @@ use Yii;
*/
class RenderController extends Controller
{
public $template = 'offline';
public $template = 'bootstrap';
public $guide;
/**
* Renders API documentation files
......@@ -48,6 +50,9 @@ class RenderController extends Controller
return 1;
}
$renderer->targetDir = $targetDir;
if ($this->guide !== null && $renderer->hasProperty('guideUrl')) {
$renderer->guideUrl = './';
}
$this->stdout('Searching files to process... ');
$files = [];
......@@ -98,7 +103,12 @@ class RenderController extends Controller
$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
// render models
$renderer->render($context, $this);
$renderer->renderApi($context, $this);
// render guide if specified
if ($this->guide !== null) {
$renderer->renderMarkdownFiles($this->findMarkdownFiles($this->guide, ['README.md']), $this);
}
}
/**
......@@ -133,11 +143,21 @@ class RenderController extends Controller
return FileHelper::findFiles($path, $options);
}
protected function findMarkdownFiles($path, $except = [])
{
$path = FileHelper::normalizePath($path);
$options = [
'only' => ['.md'],
'except' => $except,
];
return FileHelper::findFiles($path, $options);
}
/**
* @inheritdoc
*/
public function globalOptions()
{
return array_merge(parent::globalOptions(), ['template']);
return array_merge(parent::globalOptions(), ['template', 'guide']);
}
}
\ No newline at end of file
extensions/apidoc/helpers/Markdown.php
......@@ -46,8 +46,10 @@ class Markdown extends \yii\helpers\Markdown
if (($pos = strpos($object, '::')) !== false) {
$typeName = substr($object, 0, $pos);
$subjectName = substr($object, $pos + 2);
// Collection resolves relative types
$typeName = (new Collection([$typeName], $context->phpDocContext))->__toString();
if ($context !== null) {
// Collection resolves relative types
$typeName = (new Collection([$typeName], $context->phpDocContext))->__toString();
}
$type = static::$renderer->context->getType($typeName);
if ($type === null) {
return '<span style="background: #f00;">' . $typeName . '::' . $subjectName . '</span>';
......@@ -64,11 +66,13 @@ class Markdown extends \yii\helpers\Markdown
return '<span style="background: #ff0;">' . $type->name . '</span><span style="background: #f00;">::' . $subjectName . '</span>';
}
}
} elseif (($subject = $context->findSubject($object)) !== null) {
} elseif ($context !== null && ($subject = $context->findSubject($object)) !== null) {
return static::$renderer->subjectLink($subject, $title);
}
// Collection resolves relative types
$object = (new Collection([$object], $context->phpDocContext))->__toString();
if ($context !== null) {
// Collection resolves relative types
$object = (new Collection([$object], $context->phpDocContext))->__toString();
}
if (($type = static::$renderer->context->getType($object)) !== null) {
return static::$renderer->typeLink($type, $title);
}
......
extensions/apidoc/templates/BaseRenderer.php
......@@ -39,7 +39,17 @@ abstract class BaseRenderer extends Component
* @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);
public abstract function renderApi($context, $controller);
/**
* Renders a given [[Context]].
*
* @param array $files list of markdown files to render
* @param Context $context the api documentation context to render.
* @param Controller $controller the apidoc controller instance. Can be used to control output.
* @return
*/
public abstract function renderMarkdownFiles($files, $controller);
/**
* creates a link to a type (class, interface or trait)
......
extensions/apidoc/templates/bootstrap/Renderer.php
......@@ -6,6 +6,7 @@
*/
namespace yii\apidoc\templates\bootstrap;
use yii\apidoc\helpers\Markdown;
use yii\apidoc\models\Context;
use yii\console\Controller;
use Yii;
......@@ -19,8 +20,69 @@ use yii\helpers\FileHelper;
*/
class Renderer extends \yii\apidoc\templates\html\Renderer
{
public $layout = '@yii/apidoc/templates/bootstrap/views/bootstrap.php';
public $apiLayout = '@yii/apidoc/templates/bootstrap/layouts/api.php';
public $guideLayout = '@yii/apidoc/templates/bootstrap/layouts/guide.php';
public $indexView = '@yii/apidoc/templates/bootstrap/views/index.php';
public $pageTitle = 'Yii Framework 2.0 API Documentation';
public $pageTitle = 'Yii Framework 2.0 Documentation';
public $guideUrl;
/**
* 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 renderMarkdownFiles($files, $controller)
{
$dir = Yii::getAlias($this->targetDir);
if (!is_dir($dir)) {
mkdir($dir, 0777, true);
}
Markdown::$renderer = $this;
$fileCount = count($files) + 1;
Console::startProgress(0, $fileCount, 'Rendering markdown files: ', false);
$done = 0;
$fileData = [];
$headlines = [];
foreach($files as $file) {
$fileData[$file] = file_get_contents($file);
if (basename($file) == 'index.md') {
continue; // to not add index file to nav
}
if (preg_match("/^(.*)\n=+/", $fileData[$file], $matches)) {
$headlines[$file] = $matches[1];
} else {
$headlines[$file] = basename($file);
}
}
foreach($fileData as $file => $content) {
$output = Markdown::process($content); // TODO generate links to yiiframework.com by default
$output = $this->fixMarkdownLinks($output);
if ($this->guideLayout !== false) {
$params = [
'headlines' => $headlines,
'currentFile' => $file,
'content' => $output,
];
$output = $this->getView()->renderFile($this->guideLayout, $params, $this);
}
$fileName = 'guide_' . str_replace('.md', '.html', basename($file));
file_put_contents($dir . '/' . $fileName, $output);
Console::updateProgress(++$done, $fileCount);
}
Console::updateProgress(++$done, $fileCount);
Console::endProgress(true);
$controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
}
protected function fixMarkdownLinks($content)
{
$content = preg_replace('/href\s*=\s*"([^"]+)\.md"/i', 'href="guide_\1.html"', $content);
return $content;
}
}
\ No newline at end of file
extensions/apidoc/templates/bootstrap/views/bootstrap.php → extensions/apidoc/templates/bootstrap/layouts/api.php
<?php
use yii\apidoc\templates\bootstrap\SideNavWidget;
use yii\bootstrap\Nav;
use yii\bootstrap\NavBar;
use yii\helpers\Html;
use yii\helpers\StringHelper;
use yii\widgets\Menu;
/**
* @var yii\web\View $this
*/
\yii\apidoc\templates\bootstrap\assets\AssetBundle::register($this);
$this->beginPage();
?>
<!DOCTYPE html>
<html lang="<?= Yii::$app->language ?>">
<head>
<meta charset="<?= Yii::$app->charset ?>"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="language" content="en" />
<?php $this->head() ?>
<title><?= Html::encode($this->context->pageTitle) ?></title>
</head>
<body>
<?php $this->beginBody() ?>
<div class="wrap">
<?php
NavBar::begin([
'brandLabel' => $this->context->pageTitle,
'brandUrl' => './index.html',
'options' => [
'class' => 'navbar-inverse navbar-fixed-top',
],
'padded' => false,
'view' => $this,
]);
echo Nav::widget([
'options' => ['class' => 'navbar-nav'],
'items' => [
['label' => 'Class reference', 'url' => './index.html'],
// ['label' => 'Application API', 'url' => '/site/about'],
// ['label' => 'Guide', 'url' => './guide_index.html'],
],
'view' => $this,
]);
NavBar::end();
?>
<!-- <div class="container">-->
<div class="row">
<div class="col-md-2">
<?php
ksort($types);
$nav = [];
foreach($types as $i=>$class) {
$namespace = $class->namespace;
if (empty($namespace)) {
$namespace = 'Not namespaced classes';
}
if (!isset($nav[$namespace])) {
$nav[$namespace] = [
'label' => $namespace,
'url' => '#',
'items' => [],
];
}
$nav[$namespace]['items'][] = [
'label' => StringHelper::basename($class->name),
'url' => './' . $this->context->generateUrl($class->name),
'active' => isset($type) && ($class->name == $type->name),
];
} ?>
<?= SideNavWidget::widget([
'id' => 'navigation',
'items' => $nav,
// 'route' => 'wtf',
'view' => $this,
])?>
</div>
<div class="col-md-9" role="main">
<?= $content ?>
</div>
</div>
<!-- </div>-->
$this->beginContent('@yii/apidoc/templates/bootstrap/layouts/main.php'); ?>
<div class="row">
<div class="col-md-2">
<?php
ksort($types);
$nav = [];
foreach($types as $i=>$class) {
$namespace = $class->namespace;
if (empty($namespace)) {
$namespace = 'Not namespaced classes';
}
if (!isset($nav[$namespace])) {
$nav[$namespace] = [
'label' => $namespace,
'url' => '#',
'items' => [],
];
}
$nav[$namespace]['items'][] = [
'label' => StringHelper::basename($class->name),
'url' => './' . $this->context->generateUrl($class->name),
'active' => isset($type) && ($class->name == $type->name),
];
} ?>
<?= SideNavWidget::widget([
'id' => 'navigation',
'items' => $nav,
'view' => $this,
])?>
</div>
<div class="col-md-9" role="main">
<?= $content ?>
</div>
</div>
<footer class="footer">
<?php /* <p class="pull-left">&copy; My Company <?= date('Y') ?></p> */ ?>
<p class="pull-right"><?= Yii::powered() ?></p>
</footer>
<script type="text/javascript">
/*<![CDATA[*/
$("a.toggle").on('click', function() {
......@@ -122,7 +72,4 @@ $this->beginPage();
/*]]>*/
</script>
<?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>
\ No newline at end of file
<?php $this->endContent(); ?>
\ No newline at end of file
extensions/apidoc/templates/bootstrap/layouts/guide.php 0 → 100644
<?php
use yii\apidoc\templates\bootstrap\SideNavWidget;
use yii\helpers\StringHelper;
/**
* @var yii\web\View $this
*/
$this->beginContent('@yii/apidoc/templates/bootstrap/layouts/main.php'); ?>
<div class="row">
<div class="col-md-2">
<?php
asort($headlines);
$nav = [];
$nav[] = [
'label' => 'Index',
'url' => './guide_index.html',
'active' => isset($currentFile) && (basename($currentFile) == 'index.md'),
];
foreach($headlines as $file => $headline) {
// if (!isset($nav[$namespace])) {
// $nav[$namespace] = [
// 'label' => $namespace,
// 'url' => '#',
// 'items' => [],
// ];
// }
$nav/*[$namespace]['items']*/[] = [
'label' => $headline,
'url' => './guide_' . str_replace('.md', '.html', basename($file)),
'active' => isset($currentFile) && ($file == $currentFile),
];
} ?>
<?= SideNavWidget::widget([
'id' => 'navigation',
'items' => $nav,
'view' => $this,
]) ?>
</div>
<div class="col-md-9" role="main">
<?= $content ?>
</div>
</div>
<?php $this->endContent(); ?>
\ No newline at end of file
extensions/apidoc/templates/bootstrap/layouts/main.php 0 → 100644
<?php
use yii\apidoc\templates\bootstrap\SideNavWidget;
use yii\bootstrap\Nav;
use yii\bootstrap\NavBar;
use yii\helpers\Html;
use yii\helpers\StringHelper;
use yii\widgets\Menu;
/**
* @var yii\web\View $this
*/
\yii\apidoc\templates\bootstrap\assets\AssetBundle::register($this);
$this->beginPage();
?>
<!DOCTYPE html>
<html lang="<?= Yii::$app->language ?>">
<head>
<meta charset="<?= Yii::$app->charset ?>"/>
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="language" content="en" />
<?php $this->head() ?>
<title><?= Html::encode($this->context->pageTitle) ?></title>
</head>
<body>
<?php $this->beginBody() ?>
<div class="wrap">
<?php
NavBar::begin([
'brandLabel' => $this->context->pageTitle,
'brandUrl' => './index.html',
'options' => [
'class' => 'navbar-inverse navbar-fixed-top',
],
'padded' => false,
'view' => $this,
]);
$nav = [
['label' => 'Class reference', 'url' => './index.html'],
// ['label' => 'Application API', 'url' => '/site/about'],
];
if ($this->context->guideUrl !== null) {
$nav[] = ['label' => 'Guide', 'url' => $this->context->guideUrl . 'guide_index.html'];
}
echo Nav::widget([
'options' => ['class' => 'navbar-nav'],
'items' => $nav,
'view' => $this,
]);
NavBar::end();
?>
<?= $content ?>
</div>
<footer class="footer">
<?php /* <p class="pull-left">&copy; My Company <?= date('Y') ?></p> */ ?>
<p class="pull-right"><?= Yii::powered() ?></p>
</footer>
<?php $this->endBody() ?>
</body>
</html>
<?php $this->endPage() ?>
\ No newline at end of file
extensions/apidoc/templates/html/Renderer.php
......@@ -46,7 +46,7 @@ abstract class Renderer extends BaseRenderer implements ViewContextInterface
/**
* @var string path or alias of the layout file to use.
*/
public $layout;
public $apiLayout;
/**
* @var string path or alias of the view file to use for rendering types (classes, interfaces, traits).
*/
......@@ -91,7 +91,7 @@ abstract class Renderer extends BaseRenderer implements ViewContextInterface
* @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)
public function renderApi($context, $controller)
{
$this->context = $context;
$dir = Yii::getAlias($this->targetDir);
......@@ -125,9 +125,9 @@ abstract class Renderer extends BaseRenderer implements ViewContextInterface
protected function renderWithLayout($viewFile, $params)
{
$output = $this->getView()->render($viewFile, $params, $this);
if ($this->layout !== false) {
if ($this->apiLayout !== false) {
$params['content'] = $output;
return $this->getView()->renderFile($this->layout, $params, $this);
return $this->getView()->renderFile($this->apiLayout, $params, $this);
} else {
return $output;
}
......
extensions/apidoc/templates/offline/Renderer.php
......@@ -19,7 +19,7 @@ use yii\helpers\FileHelper;
*/
class Renderer extends \yii\apidoc\templates\html\Renderer
{
public $layout = '@yii/apidoc/templates/offline/views/offline.php';
public $apiLayout = '@yii/apidoc/templates/offline/views/offline.php';
public $indexView = '@yii/apidoc/templates/offline/views/index.php';
public $pageTitle = 'Yii Framework 2.0 API Documentation';
......
extensions/apidoc/templates/online/Renderer.php
......@@ -21,7 +21,7 @@ use yii\helpers\StringHelper;
*/
class Renderer extends \yii\apidoc\templates\html\Renderer
{
public $layout = false;
public $apiLayout = false;
public $indexView = '@yii/apidoc/templates/online/views/index.php';
public $pageTitle = 'Yii Framework 2.0 API Documentation';
......@@ -32,9 +32,9 @@ class Renderer extends \yii\apidoc\templates\html\Renderer
* @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)
public function renderApi($context, $controller)
{
parent::render($context, $controller);
parent::renderApi($context, $controller);
$dir = Yii::getAlias($this->targetDir);
$controller->stdout("writing packages file...");
$packages = [];
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment