diff --git a/CHANGELOG.md b/CHANGELOG.md index daf3c42b..8e76c47d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,10 @@ Yii Framework 2 apidoc extension Change Log 2.0.7 under development ----------------------- -- no changes in this release. +- Enh #38: Fixed display of default values given as octal or hex notation (hiqsol) +- Enh #152: Set `@bower` and `@npm` aliases dependent on the existing directories (ricpelo) +- Enh: Display TOC only if there is more than one headline (cebe) +- Enh: Extracted markdown code highlighting to a trait `MarkdownHighlightTrait` (cebe) 2.0.6 November 22, 2016 diff --git a/apidoc b/apidoc index 0dd7d372..5074e84b 100755 --- a/apidoc +++ b/apidoc @@ -49,6 +49,26 @@ $application = new yii\console\Application([ ]); if ($vendorPath !== null) { $application->setVendorPath($vendorPath); + $bowerDirs = [ + "$vendorPath/bower", + "$vendorPath/bower-asset", + ]; + foreach ($bowerDirs as $dir) { + if (file_exists($dir)) { + Yii::setAlias('@bower', $dir); + break; + } + } + $npmDirs = [ + "$vendorPath/npm", + "$vendorPath/npm-asset", + ]; + foreach ($npmDirs as $dir) { + if (file_exists($dir)) { + Yii::setAlias('@npm', $dir); + break; + } + } } $exitCode = $application->run(); exit($exitCode); diff --git a/helpers/ApiMarkdown.php b/helpers/ApiMarkdown.php index 2f70848b..4bdd2861 100644 --- a/helpers/ApiMarkdown.php +++ b/helpers/ApiMarkdown.php @@ -8,8 +8,6 @@ namespace yii\apidoc\helpers; use cebe\markdown\GithubMarkdown; -use DomainException; -use Highlight\Highlighter; use yii\apidoc\models\TypeDoc; use yii\apidoc\renderers\BaseRenderer; use yii\helpers\Html; @@ -25,6 +23,7 @@ class ApiMarkdown extends GithubMarkdown { use ApiMarkdownTrait; + use MarkdownHighlightTrait; /** * @var BaseRenderer @@ -70,11 +69,12 @@ public function parse($text) */ protected function applyToc($content) { - // generate TOC - if (!empty($this->headings)) { + // generate TOC if there is more than one headline + if (!empty($this->headings) && count($this->headings) > 1) { $toc = []; - foreach ($this->headings as $heading) + foreach ($this->headings as $heading) { $toc[] = '
  • ' . Html::a(strip_tags($heading['title']), '#' . $heading['id']) . '
  • '; + } $toc = '
      ' . implode("\n", $toc) . "
    \n"; if (strpos($content, '') !== false) $content = str_replace('', "\n" . $toc, $content); @@ -84,69 +84,6 @@ protected function applyToc($content) return $content; } - /** - * @var Highlighter - */ - private static $highlighter; - - /** - * @inheritdoc - */ - protected function renderCode($block) - { - if (self::$highlighter === null) { - self::$highlighter = new Highlighter(); - self::$highlighter->setAutodetectLanguages([ - 'apache', 'nginx', - 'bash', 'dockerfile', 'http', - 'css', 'less', 'scss', - 'javascript', 'json', 'markdown', - 'php', 'sql', 'twig', 'xml', - ]); - } - try { - if (isset($block['language'])) { - $result = self::$highlighter->highlight($block['language'], $block['content'] . "\n"); - return "
    language} language-{$block['language']}\">{$result->value}
    \n"; - } else { - $result = self::$highlighter->highlightAuto($block['content'] . "\n"); - return "
    language}\">{$result->value}
    \n"; - } - } catch (DomainException $e) { - echo $e; - return parent::renderCode($block); - } - } - - /** - * Highlights code - * - * @param string $code code to highlight - * @param string $language language of the code to highlight - * @return string HTML of highlighted code - * @deprecated since 2.0.5 this method is not used anymore, highlight.php is used for highlighting - */ - public static function highlight($code, $language) - { - if ($language !== 'php') { - return htmlspecialchars($code, ENT_NOQUOTES | ENT_SUBSTITUTE, 'UTF-8'); - } - - if (strncmp($code, '\n and tags added by php - $text = substr(trim($text), 36, -16); - - return $text; - } - /** * @inheritDoc */ diff --git a/helpers/MarkdownHighlightTrait.php b/helpers/MarkdownHighlightTrait.php new file mode 100644 index 00000000..5a949dbd --- /dev/null +++ b/helpers/MarkdownHighlightTrait.php @@ -0,0 +1,83 @@ + + */ +trait MarkdownHighlightTrait +{ + /** + * @var Highlighter + */ + private static $highlighter; + + /** + * @inheritdoc + */ + protected function renderCode($block) + { + if (self::$highlighter === null) { + self::$highlighter = new Highlighter(); + self::$highlighter->setAutodetectLanguages([ + 'apache', 'nginx', + 'bash', 'dockerfile', 'http', + 'css', 'less', 'scss', + 'javascript', 'json', 'markdown', + 'php', 'sql', 'twig', 'xml', + ]); + } + try { + if (isset($block['language'])) { + $result = self::$highlighter->highlight($block['language'], $block['content'] . "\n"); + return "
    language} language-{$block['language']}\">{$result->value}
    \n"; + } else { + $result = self::$highlighter->highlightAuto($block['content'] . "\n"); + return "
    language}\">{$result->value}
    \n"; + } + } catch (DomainException $e) { + echo $e; + return parent::renderCode($block); + } + } + + /** + * Highlights code + * + * @param string $code code to highlight + * @param string $language language of the code to highlight + * @return string HTML of highlighted code + * @deprecated since 2.0.5 this method is not used anymore, highlight.php is used for highlighting + */ + public static function highlight($code, $language) + { + if ($language !== 'php') { + return htmlspecialchars($code, ENT_NOQUOTES | ENT_SUBSTITUTE, 'UTF-8'); + } + + if (strncmp($code, '\n and tags added by php + $text = substr(trim($text), 36, -16); + + return $text; + } +} diff --git a/templates/bootstrap/RendererTrait.php b/templates/bootstrap/RendererTrait.php index 92b40e9b..6c9310bc 100644 --- a/templates/bootstrap/RendererTrait.php +++ b/templates/bootstrap/RendererTrait.php @@ -27,10 +27,12 @@ trait RendererTrait 'elasticsearch', 'faker', 'gii', + 'httpclient', 'imagine', 'jui', 'mongodb', 'redis', + 'shell', 'smarty', 'sphinx', 'swiftmailer', diff --git a/templates/html/ApiRenderer.php b/templates/html/ApiRenderer.php index 7cc22abd..12b7a465 100644 --- a/templates/html/ApiRenderer.php +++ b/templates/html/ApiRenderer.php @@ -247,7 +247,7 @@ public function renderPropertySignature($property, $context = null) return '' . implode(' ', $definition) . ' ' . '' . $this->createTypeLink($property->types, $context) . '' . ' ' . $this->createSubjectLink($property, $property->name) . ' ' - . ApiMarkdown::highlight('= ' . ($property->defaultValue === null ? 'null' : $property->defaultValue), 'php'); + . ApiMarkdown::highlight('= ' . $this->renderDefaultValue($property->defaultValue), 'php'); } /** @@ -262,7 +262,7 @@ public function renderMethodSignature($method, $context = null) . ($param->isPassedByReference ? '&' : '') . ApiMarkdown::highlight( $param->name - . ($param->isOptional ? ' = ' . $param->defaultValue : ''), + . ($param->isOptional ? ' = ' . $this->renderDefaultValue($param->defaultValue) : ''), 'php' ); } @@ -283,6 +283,38 @@ public function renderMethodSignature($method, $context = null) . str_replace(' ', ' ', ' ( ' . implode(', ', $params) . ' )'); } + /** + * Renders the default value. + * @param mixed $value + * @return string + * @since 2.0.7 + */ + public function renderDefaultValue($value) + { + if ($value === null) { + return 'null'; + } + + // special numbers which are usually used in octal or hex notation + static $specials = [ + // file permissions + '420' => '0644', + '436' => '0664', + '438' => '0666', + '493' => '0755', + '509' => '0775', + '511' => '0777', + // colors used in yii\captcha\CaptchaAction + '2113696' => '0x2040A0', + '16777215' => '0xFFFFFF', + ]; + if (isset($specials[$value])) { + return $specials[$value]; + } + + return $value; + } + /** * @inheritdoc */ diff --git a/templates/pdf/main.tex b/templates/pdf/main.tex index d80e5c10..f89416bf 100644 --- a/templates/pdf/main.tex +++ b/templates/pdf/main.tex @@ -9,6 +9,9 @@ % declare some unicode characters \DeclareUnicodeCharacter{2713}{yes} % ✓ \DeclareUnicodeCharacter{20AC}{EUR} % € +\DeclareUnicodeCharacter{251C}{|} % ├ +\DeclareUnicodeCharacter{2500}{-} % ─ +\DeclareUnicodeCharacter{2514}{|} % └ % % Title and author info