diff --git a/docs/guide/events.md b/docs/guide/events.md
index 0cae195..94c5e9a 100644
--- a/docs/guide/events.md
+++ b/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.
diff --git a/extensions/apidoc/README.md b/extensions/apidoc/README.md
index 55b1e99..1cb7c03 100644
--- a/extensions/apidoc/README.md
+++ b/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 api source/directory ./output
+```
+
+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:
```
-vendor/bin/apidoc source/directory ./output
+# 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 `offline` template will be used. You can choose a different templates with the `--template=name` parameter.
-Currently there is only the `offline` template available.
+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.
diff --git a/extensions/apidoc/commands/ApiController.php b/extensions/apidoc/commands/ApiController.php
index 51dcbee..b3c28f3 100644
--- a/extensions/apidoc/commands/ApiController.php
+++ b/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
diff --git a/extensions/apidoc/commands/GuideController.php b/extensions/apidoc/commands/GuideController.php
index 5b7750f..8dbe648 100644
--- a/extensions/apidoc/commands/GuideController.php
+++ b/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'])
diff --git a/extensions/apidoc/components/BaseController.php b/extensions/apidoc/components/BaseController.php
index 6a5f14c..768280d 100644
--- a/extensions/apidoc/components/BaseController.php
+++ b/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;
diff --git a/extensions/apidoc/renderers/BaseRenderer.php b/extensions/apidoc/renderers/BaseRenderer.php
index 0170213..786ec61 100644
--- a/extensions/apidoc/renderers/BaseRenderer.php
+++ b/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';
+ }
}
\ No newline at end of file
diff --git a/extensions/apidoc/templates/bootstrap/layouts/api.php b/extensions/apidoc/templates/bootstrap/layouts/api.php
index c60956c..1acf68c 100644
--- a/extensions/apidoc/templates/bootstrap/layouts/api.php
+++ b/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;
diff --git a/extensions/apidoc/templates/bootstrap/layouts/guide.php b/extensions/apidoc/templates/bootstrap/layouts/guide.php
index 20778f1..16f846c 100644
--- a/extensions/apidoc/templates/bootstrap/layouts/guide.php
+++ b/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),
];
} ?>
diff --git a/extensions/apidoc/templates/bootstrap/layouts/main.php b/extensions/apidoc/templates/bootstrap/layouts/main.php
index 2ec970f..de40aca 100644
--- a/extensions/apidoc/templates/bootstrap/layouts/main.php
+++ b/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([
diff --git a/extensions/apidoc/templates/html/GuideRenderer.php b/extensions/apidoc/templates/html/GuideRenderer.php
index dded806..49d0456 100644
--- a/extensions/apidoc/templates/html/GuideRenderer.php
+++ b/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;
}