add guidePrefix option for apidoc

extensions/apidoc/CHANGELOG.md

@@ -5,7 +5,9 @@ Yii Framework 2 apidoc extension Change Log
 -----------------------
 
 - Bug #5623: Fixed crash when a class contains a setter that has no arguments e.g. `setXyz()` (cebe)
+- Bug: Guide and API renderer now work with relative paths/URLs (cebe)
 - Enh: Guide generator now skips `images` directory if it does not exist instead of throwing an error (cebe)
+- Enh: Made `--guidePrefix` option available as a command line option (cebe)
 
 
 2.0.0 October 12, 2014

extensions/apidoc/README.md

@@ -59,10 +59,29 @@ 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.
 
-Creating a PDF from the guide
------------------------------
+### Advanced usage
 
-You need `pdflatex` and `make` for this.
+The following script can be used to generate API documentation and guide in different directories and also multiple guides
+in different languages (like it is done on yiiframework.com):
+
+```sh
+#!/bin/sh
+
+# set these paths to match your environment
+YII_PATH=~/dev/yiisoft/yii2
+APIDOC_PATH=~/dev/yiisoft/yii2/extensions/apidoc
+OUTPUT=yii2docs
+
+cd $APIDOC_PATH
+./apidoc api $YII_PATH/framework/,$YII_PATH/extensions $OUTPUT/api --guide=../guide-en --guidePrefix= --interactive=0
+./apidoc guide $YII_PATH/docs/guide    $OUTPUT/guide-en --apiDocs=../api --guidePrefix= --interactive=0
+./apidoc guide $YII_PATH/docs/guide-ru $OUTPUT/guide-ru --apiDocs=../api --guidePrefix= --interactive=0
+# repeat the last line for more languages
+```
+
+### Creating a PDF of the guide
+
+You need `pdflatex` and GNU `make` for this.
 
 ```
 vendor/bin/apidoc guide source/docs ./output --template=pdf

extensions/apidoc/commands/ApiController.php

@@ -26,6 +26,10 @@ class ApiController extends BaseController
      * @var string url to where the guide files are located
      */
     public $guide;
+    /**
+     * @var string prefix to prepend to all guide file names.
+     */
+    public $guidePrefix = 'guide-';
 
 
     // TODO add force update option
@@ -44,6 +48,7 @@ class ApiController extends BaseController
         }
 
         $renderer->apiUrl = './';
+        $renderer->guidePrefix = $this->guidePrefix;
 
         // setup reference to guide
         if ($this->guide !== null) {
@@ -157,6 +162,6 @@ class ApiController extends BaseController
      */
     public function options($actionID)
     {
-        return array_merge(parent::options($actionID), ['template', 'guide']);
+        return array_merge(parent::options($actionID), ['guide', 'guidePrefix']);
     }
 }

extensions/apidoc/commands/GuideController.php

@@ -27,6 +27,10 @@ class GuideController extends BaseController
      * @var string path or URL to the api docs to allow links to classes and properties/methods.
      */
     public $apiDocs;
+    /**
+     * @var string prefix to prepend to all output file names generated for the guide.
+     */
+    public $guidePrefix = 'guide-';
 
 
     /**
@@ -44,6 +48,7 @@ class GuideController extends BaseController
         }
 
         $renderer->guideUrl = './';
+        $renderer->guidePrefix = $this->guidePrefix;
 
         // setup reference to apidoc
         if ($this->apiDocs !== null) {
@@ -117,6 +122,6 @@ class GuideController extends BaseController
      */
     public function options($actionID)
     {
-        return array_merge(parent::options($actionID), ['apiDocs']);
+        return array_merge(parent::options($actionID), ['apiDocs', 'guidePrefix']);
     }
 }

extensions/apidoc/renderers/BaseRenderer.php

@@ -31,8 +31,12 @@ use yii\console\Controller;
  */
 abstract class BaseRenderer extends Component
 {
+    /**
+     * @deprecated since 2.0.1 use [[$guidePrefix]] instead which allows configuring this options
+     */
     const GUIDE_PREFIX = 'guide-';
 
+    public $guidePrefix = 'guide-';
     public $apiUrl;
     /**
      * @var Context the [[Context]] currently being rendered.
@@ -203,6 +207,6 @@ abstract class BaseRenderer extends Component
             $file = substr($file, 0, $pos);
         }
 
-        return rtrim($this->guideUrl, '/') . '/' . static::GUIDE_PREFIX . basename($file, '.md') . '.html' . $hash;
+        return rtrim($this->guideUrl, '/') . '/' . $this->guidePrefix . basename($file, '.md') . '.html' . $hash;
     }
 }

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

@@ -63,7 +63,7 @@ $this->beginPage();
     }
 
     if ($this->context->guideUrl !== null) {
-        $nav[] = ['label' => 'Guide', 'url' => rtrim($this->context->guideUrl, '/') . '/' . BaseRenderer::GUIDE_PREFIX . 'README.html'];
+        $nav[] = ['label' => 'Guide', 'url' => rtrim($this->context->guideUrl, '/') . '/' . $this->context->guidePrefix . 'README.html'];
     }
 
     echo Nav::widget([

extensions/apidoc/templates/html/GuideRenderer.php

@@ -114,7 +114,7 @@ abstract class GuideRenderer extends BaseGuideRenderer
 
     protected function generateGuideFileName($file)
     {
-        return static::GUIDE_PREFIX . basename($file, '.md') . '.html';
+        return $this->guidePrefix . basename($file, '.md') . '.html';
     }
 
     public function getGuideReferences()
@@ -130,7 +130,7 @@ abstract class GuideRenderer extends BaseGuideRenderer
 
     protected function fixMarkdownLinks($content)
     {
-        $content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="' . static::GUIDE_PREFIX . '\1.html\2"', $content);
+        $content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="' . $this->guidePrefix . '\1.html\2"', $content);
 
         return $content;
     }