changed syntax for referencing the guide in apidoc

extensions/apidoc/commands/ApiController.php

@@ -48,18 +48,15 @@ class ApiController extends BaseController
 
         // setup reference to guide
         if ($this->guide !== null) {
-            $guideUrl = $this->guide;
-            $referenceFile = $guideUrl . '/' . BaseRenderer::GUIDE_PREFIX . 'references.txt';
+            $renderer->guideUrl = $guideUrl = $this->guide;
         } else {
             $guideUrl = './';
-            $referenceFile = $targetDir . '/' . BaseRenderer::GUIDE_PREFIX . 'references.txt';
+            $renderer->guideUrl = $targetDir;
         }
-        if (file_exists($referenceFile)) {
+        if (file_exists($renderer->generateGuideUrl('README.md'))) {
             $renderer->guideUrl = $guideUrl;
-            $renderer->guideReferences = [];
-            foreach (explode("\n", file_get_contents($referenceFile)) as $reference) {
-                $renderer->guideReferences[BaseRenderer::GUIDE_PREFIX . $reference]['url'] = $renderer->generateGuideUrl($reference);
-            }
+        } else {
+            $renderer->guideUrl = null;
         }
 
         // search for files to process

extensions/apidoc/commands/GuideController.php

@@ -70,13 +70,6 @@ class GuideController extends BaseController
             FileHelper::copyDirectory(rtrim($source, '/\\') . '/images', $targetDir . '/images');
         }
         $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
-
-        // generate api references.txt
-        $references = [];
-        foreach ($files as $file) {
-            $references[] = basename($file, '.md');
-        }
-        file_put_contents($targetDir . '/guide-references.txt', implode("\n", $references));
     }
 
 

extensions/apidoc/helpers/ApiMarkdown.php

@@ -89,6 +89,21 @@ class ApiMarkdown extends GithubMarkdown
     }
 
     /**
+     * @inheritdoc
+     */
+    protected function parseLink($markdown)
+    {
+        list($result, $skip) = parent::parseLink($markdown);
+
+        // add special syntax for linking to the guide
+        $result = preg_replace_callback('/href="guide:([A-z0-9-.#]+)"/i', function($match) {
+            return 'href="' . static::$renderer->generateGuideUrl($match[1]) . '"';
+        }, $result, 1);
+
+        return [$result, $skip];
+    }
+
+    /**
      * Converts markdown into HTML
      *
      * @param string $content

extensions/apidoc/renderers/BaseRenderer.php

@@ -43,7 +43,6 @@ abstract class BaseRenderer extends Component
      */
     public $controller;
     public $guideUrl;
-    public $guideReferences = [];
 
 
     public function init()
@@ -198,6 +197,12 @@ abstract class BaseRenderer extends Component
      */
     public function generateGuideUrl($file)
     {
-        return rtrim($this->guideUrl, '/') . '/' . static::GUIDE_PREFIX . basename($file, '.md') . '.html';
+        $hash = '';
+        if (($pos = strpos($file, '#')) !== false) {
+            $hash = substr($file, $pos);
+            $file = substr($file, 0, $pos);
+        }
+
+        return rtrim($this->guideUrl, '/') . '/' . static::GUIDE_PREFIX . basename($file, '.md') . '.html' . $hash;
     }
 }

framework/BaseYii.php

@@ -264,7 +264,7 @@ class BaseYii
      * will be loaded using the `@yii/bootstrap` alias which points to the directory where bootstrap extension
      * files are installed and all classes from other `yii` namespaces will be loaded from the yii framework directory.
      *
-     * Also the [guide section on autoloading][guide-concept-autoloading].
+     * Also the [guide section on autoloading](guide:concept-autoloading).
      *
      * @param string $className the fully qualified class name without a leading backslash "\"
      * @throws UnknownClassException if the class does not exist in the class file

framework/base/Application.php

@@ -87,7 +87,7 @@ abstract class Application extends Module
      * This namespace will be used to load controller classes by prepending it to the controller class name.
      * The default namespace is `app\controllers`.
      *
-     * Please refer to the [guide about class autoloading][guide-concept-autoloading] for more details.
+     * Please refer to the [guide about class autoloading](guide:concept-autoloading.md) for more details.
      */
     public $controllerNamespace = 'app\\controllers';
     /**

framework/base/Module.php

@@ -94,7 +94,7 @@ class Module extends ServiceLocator
      * For example, if the namespace of this module is "foo\bar", then the default
      * controller namespace would be "foo\bar\controllers".
      *
-     * See also the [guide section on autoloading][guide-concept-autoloading] to learn more about
+     * See also the [guide section on autoloading](guide:concept-autoloading) to learn more about
      * defining namespaces and how classes are loaded.
      */
     public $controllerNamespace;

framework/db/ActiveRecord.php

@@ -45,7 +45,7 @@ use yii\helpers\StringHelper;
  *
  * The `tableName` method only has to return the name of the database table associated with the class.
  *
- * > Tip: You may also use the [Gii code generator][guide-gii] to generate ActiveRecord classes from your
+ * > Tip: You may also use the [Gii code generator](guide:start-gii) to generate ActiveRecord classes from your
  * > database tables.
  *
  * Class instances are obtained in one of two ways:
@@ -67,7 +67,7 @@ use yii\helpers\StringHelper;
  * $orders = $user->orders;
  * ```
  *
- * For more details and usage information on ActiveRecord, see the [guide article on ActiveRecord][guide-active-record].
+ * For more details and usage information on ActiveRecord, see the [guide article on ActiveRecord](guide:db-active-record).
  *
  * @method ActiveQuery hasMany(string $class, array $link) see BaseActiveRecord::hasMany() for more info
  * @method ActiveQuery hasOne(string $class, array $link) see BaseActiveRecord::hasOne() for more info