From 73cb5f8aac21b7d35ea87c18d1c6d8bb93851a1b Mon Sep 17 00:00:00 2001 From: Carsten Brandt <mail@cebe.cc> Date: Fri, 5 Sep 2014 14:59:22 +0200 Subject: [PATCH] changed syntax for referencing the guide in apidoc New syntax: ``` [link to guide](guide:file-name.md) [link to guide](guide:file-name.md#subsection) ``` fixes #4719 --- extensions/apidoc/commands/ApiController.php | 13 +++++-------- extensions/apidoc/commands/GuideController.php | 7 ------- extensions/apidoc/helpers/ApiMarkdown.php | 15 +++++++++++++++ extensions/apidoc/renderers/BaseRenderer.php | 9 +++++++-- framework/BaseYii.php | 2 +- framework/base/Application.php | 2 +- framework/base/Module.php | 2 +- framework/db/ActiveRecord.php | 4 ++-- 8 files changed, 32 insertions(+), 22 deletions(-) diff --git a/extensions/apidoc/commands/ApiController.php b/extensions/apidoc/commands/ApiController.php index 79e8380..ea3cf1f 100644 --- a/extensions/apidoc/commands/ApiController.php +++ b/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 diff --git a/extensions/apidoc/commands/GuideController.php b/extensions/apidoc/commands/GuideController.php index 9d3ca69..86bfee0 100644 --- a/extensions/apidoc/commands/GuideController.php +++ b/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)); } diff --git a/extensions/apidoc/helpers/ApiMarkdown.php b/extensions/apidoc/helpers/ApiMarkdown.php index 6bf319d..dde0b83 100644 --- a/extensions/apidoc/helpers/ApiMarkdown.php +++ b/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 diff --git a/extensions/apidoc/renderers/BaseRenderer.php b/extensions/apidoc/renderers/BaseRenderer.php index c7c1372..c10093f 100644 --- a/extensions/apidoc/renderers/BaseRenderer.php +++ b/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; } } diff --git a/framework/BaseYii.php b/framework/BaseYii.php index 867d4a5..27acded 100644 --- a/framework/BaseYii.php +++ b/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 diff --git a/framework/base/Application.php b/framework/base/Application.php index 39156fa..165a066 100644 --- a/framework/base/Application.php +++ b/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'; /** diff --git a/framework/base/Module.php b/framework/base/Module.php index 873a564..f071198 100644 --- a/framework/base/Module.php +++ b/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; diff --git a/framework/db/ActiveRecord.php b/framework/db/ActiveRecord.php index a59a89c..89bce56 100644 --- a/framework/db/ActiveRecord.php +++ b/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 -- libgit2 0.27.1