added guide to apidoc bootstrap template

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>
+<?php $this->endContent(); ?>
\ No newline at end of file
-</html>
-<?php $this->endPage() ?>
\ No newline at end of file

extensions/apidoc/templates/bootstrap/layouts/guide.php

+<?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

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