finished guide command refactoring

docs/guide/events.md

@@ -115,14 +115,14 @@ Removing Event Handlers
 The correspondoing `off` method removes an event handler:
 
 ```php
-// $component->off($eventName);
+$component->off($eventName);
 ```
 
 Yii supports the ability to associate multiple handlers with the same event. When using `off` as in the above,
 every handler is removed. To remove only a specific handler, provide that as the second argument to `off`:
 
 ```php
-// $component->off($eventName, $handler);
+$component->off($eventName, $handler);
 ```
 
 The `$handler` should be presented in the `off` method in the same way as was presented in `on` in order to remove it.

extensions/apidoc/README.md

@@ -25,14 +25,36 @@ to the require section of your composer.json.
 Usage
 -----
 
-To generate API documentation, run the `apidoc` command.
+This extension offers two commands:
+
+- `api` to generate class API documentation.
+- `guide` to render nice HTML pages from markdown files such as the yii guide.
+
+Simple usage for stand alone class documentation:
 
 ```
-vendor/bin/apidoc source/directory ./output
+vendor/bin/apidoc api source/directory ./output
 ```
 
-By default the `offline` template will be used. You can choose a different templates with the `--template=name` parameter.
-Currently there is only the `offline` template available.
+Simple usage for stand alone guide documentation:
+
+```
+vendor/bin/apidoc guide source/docs ./output
+```
+
+You can combine them to generate class API and guide doc in one place:
+
+```
+# first generate guide docs to allow links from code to guide you may skip this if you do not need these.
+vendor/bin/apidoc guide source/docs ./output
+# second generate API docs
+vendor/bin/apidoc api source/directory ./output
+# third run guide docs again to have class links enabled
+vendor/bin/apidoc guide source/docs ./output
+```
+
+By default the `bootstrap` template will be used. You can choose a different templates with the `--template=name` parameter.
+Currently there is only the `bootstrap` template available.
 
 You may also add the `yii\apidoc\commands\RenderController` to your console application class map and
 run it inside of your applications console app.

extensions/apidoc/commands/ApiController.php

@@ -1,16 +1,24 @@
 <?php
 /**
- * @author Carsten Brandt <mail@cebe.cc>
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
  */
 
 namespace yii\apidoc\commands;
 
 
+use yii\apidoc\components\BaseController;
 use yii\apidoc\renderers\ApiRenderer;
+use yii\apidoc\renderers\BaseRenderer;
 use yii\helpers\ArrayHelper;
 use yii\helpers\Console;
 use yii\helpers\FileHelper;
 
+/**
+ * Generate class API documentation
+ *
+ */
 class ApiController extends BaseController
 {
 	/**
@@ -36,8 +44,18 @@ class ApiController extends BaseController
 
 		// setup reference to guide
 		if ($this->guide !== null) {
-			$renderer->guideUrl = $this->guide;
-			$renderer->guideReferences = []; // TODO set references
+			$guideUrl = $this->guide;
+			$referenceFile = $guideUrl . '/' . BaseRenderer::GUIDE_PREFIX . 'references.txt';
+		} else {
+			$guideUrl = './';
+			$referenceFile = $targetDir . '/' . BaseRenderer::GUIDE_PREFIX . 'references.txt';
+		}
+		if (file_exists($referenceFile)) {
+			$renderer->guideUrl = $guideUrl;
+			$renderer->guideReferences = [];
+			foreach(explode("\n", file_get_contents($referenceFile)) as $reference) {
+				$renderer->guideReferences[BaseRenderer::GUIDE_PREFIX . $reference] = $renderer->generateGuideUrl($reference);
+			}
 		}
 
 		// search for files to process

extensions/apidoc/commands/GuideController.php

@@ -1,10 +1,13 @@
 <?php
 /**
- * @author Carsten Brandt <mail@cebe.cc>
+ * @link http://www.yiiframework.com/
+ * @copyright Copyright (c) 2008 Yii Software LLC
+ * @license http://www.yiiframework.com/license/
  */
 
 namespace yii\apidoc\commands;
 
+use yii\apidoc\components\BaseController;
 use yii\apidoc\models\Context;
 use yii\apidoc\renderers\BaseRenderer;
 use yii\apidoc\renderers\GuideRenderer;
@@ -38,6 +41,8 @@ class GuideController extends BaseController
 			return 1;
 		}
 
+		$renderer->guideUrl = './';
+
 		// setup reference to apidoc
 		if ($this->apiDocs !== null) {
 			$renderer->apiUrl = $this->apiDocs;
@@ -59,8 +64,12 @@ class GuideController extends BaseController
 		}
 		$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
 
-
-		// TODO generate api references.txt
+		// generate api references.txt
+		$references = [];
+		foreach($files as $file) {
+			$references[] = basename($file, '.md');
+		}
+		file_put_contents($targetDir . '/guide-references.txt', implode("\n", $references));
 	}
 
 	protected function findFiles($path, $except = ['README.md'])

extensions/apidoc/components/BaseController.php

@@ -5,7 +5,7 @@
  * @license http://www.yiiframework.com/license/
  */
 
-namespace yii\apidoc\commands;
+namespace yii\apidoc\components;
 
 use yii\apidoc\renderers\BaseRenderer;
 use yii\console\Controller;

extensions/apidoc/renderers/BaseRenderer.php

@@ -31,6 +31,8 @@ use yii\helpers\Html;
  */
 abstract class BaseRenderer extends Component
 {
+	const GUIDE_PREFIX = 'guide-';
+
 	public $apiUrl;
 	/**
 	 * @var Context the [[Context]] currently being rendered.
@@ -160,4 +162,14 @@ abstract class BaseRenderer extends Component
 	 * @return mixed
 	 */
 	public abstract function generateApiUrl($typeName);
+
+	/**
+	 * Generate an url to a guide page
+	 * @param string $file
+	 * @return string
+	 */
+	public function generateGuideUrl($file)
+	{
+		return rtrim($this->guideUrl, '/') . '/' . static::GUIDE_PREFIX . basename($file, '.md') . '.html';
+	}
 }

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

@@ -1,4 +1,5 @@
 <?php
+
 use yii\apidoc\templates\bootstrap\ApiRenderer;
 use yii\apidoc\templates\bootstrap\SideNavWidget;
 use yii\helpers\StringHelper;

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

@@ -1,4 +1,5 @@
 <?php
+
 use yii\apidoc\templates\bootstrap\SideNavWidget;
 
 /**
@@ -15,20 +16,13 @@ $this->beginContent('@yii/apidoc/templates/bootstrap/layouts/main.php'); ?>
 		$nav = [];
 		$nav[] = [
 			'label' => 'Index',
-			'url' => './guide_index.html',
+			'url' => $this->context->generateGuideUrl('index.md'),
 			'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']*/[] = [
+			$nav[] = [
 				'label' => $headline,
-				'url' => './guide_' . str_replace('.md', '.html', basename($file)),
+				'url' => $this->context->generateGuideUrl($file),
 				'active' => isset($currentFile) && ($file == $currentFile),
 			];
 		} ?>

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

@@ -1,4 +1,6 @@
 <?php
+
+use yii\apidoc\renderers\BaseRenderer;
 use yii\bootstrap\Nav;
 use yii\bootstrap\NavBar;
 use yii\helpers\Html;
@@ -17,7 +19,7 @@ $this->registerJs(<<<JS
 	window.addEventListener("hashchange", shiftWindow);
 JS
 ,
-	\yii\web\View::POS_HEAD
+	\yii\web\View::POS_READY
 );
 
 $this->beginPage();
@@ -38,30 +40,32 @@ $this->beginPage();
 	<?php
 	NavBar::begin([
 		'brandLabel' => $this->context->pageTitle,
-		'brandUrl' => './index.html',
+		'brandUrl' => ($this->context->apiUrl === null && $this->context->guideUrl !== null) ? './guide-index.html' : './index.html',
 		'options' => [
 			'class' => 'navbar-inverse navbar-fixed-top',
 		],
 		'renderInnerContainer' => false,
 		'view' => $this,
 	]);
-	$nav = [
-		['label' => 'Class reference', 'url' => './index.html'],
-	];
-	if (!empty($this->context->extensions))
-	{
-		$extItems = [];
-		foreach($this->context->extensions as $ext) {
-			$extItems[] = [
-				'label' => $ext,
-				'url' => "./ext_{$ext}_index.html",
-			];
+	$nav = [];
+
+	if ($this->context->apiUrl !== null) {
+		$nav[] = ['label' => 'Class reference', 'url' => rtrim($this->context->apiUrl, '/') . '/index.html'];
+		if (!empty($this->context->extensions))
+		{
+			$extItems = [];
+			foreach($this->context->extensions as $ext) {
+				$extItems[] = [
+					'label' => $ext,
+					'url' => "./ext_{$ext}_index.html",
+				];
+			}
+			$nav[] = ['label' => 'Extensions', 'items' => $extItems];
 		}
-		$nav[] = ['label' => 'Extensions', 'items' => $extItems];
 	}
 
 	if ($this->context->guideUrl !== null) {
-		$nav[] = ['label' => 'Guide', 'url' => $this->context->guideUrl . 'guide_index.html'];
+		$nav[] = ['label' => 'Guide', 'url' => rtrim($this->context->guideUrl, '/') . '/' . BaseRenderer::GUIDE_PREFIX . 'index.html'];
 	}
 
 	echo Nav::widget([

extensions/apidoc/templates/html/GuideRenderer.php

@@ -115,10 +115,9 @@ abstract class GuideRenderer extends BaseGuideRenderer
 		}
 	}
 
-	// TODO move these to guide renderer
 	protected function generateGuideFileName($file)
 	{
-		return 'guide_' . basename($file, '.md') . '.html';
+		return static::GUIDE_PREFIX . basename($file, '.md') . '.html';
 	}
 
 	public function getGuideReferences()
@@ -134,7 +133,7 @@ abstract class GuideRenderer extends BaseGuideRenderer
 
 	protected function fixMarkdownLinks($content)
 	{
-		$content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="guide_\1.html\2"', $content);
+		$content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="' . static::GUIDE_PREFIX . '\1.html\2"', $content);
 		return $content;
 	}