Skip to content

Y
yii2
Commit 29753b3e by Carsten Brandt
Options

apidocs: use erusev/parsedown for markdown parsing

added quick and dirty code highlighing and got much faster
parent 62290c13
Showing with 62 additions and 101 deletions
extensions/apidoc/composer.json
......@@ -21,7 +21,8 @@
"require": {
"yiisoft/yii2": "*",
"yiisoft/yii2-bootstrap": "*",
"phpdocumentor/reflection": "dev-master | >1.0.2"
"phpdocumentor/reflection": "dev-master | >1.0.2",
"erusev/parsedown": "0.9.*"
},
"autoload": {
"psr-4": { "yii\\apidoc\\": "" }
......
extensions/apidoc/helpers/Markdown.php
......@@ -7,10 +7,8 @@
namespace yii\apidoc\helpers;
use phpDocumentor\Reflection\DocBlock\Type\Collection;
use yii\apidoc\models\MethodDoc;
use yii\apidoc\models\TypeDoc;
use yii\apidoc\templates\BaseRenderer;
use Parsedown;
use yii\base\Component;
/**
* A Markdown helper with support for class reference links.
......@@ -18,83 +16,45 @@ use yii\apidoc\templates\BaseRenderer;
* @author Carsten Brandt <mail@cebe.cc>
* @since 2.0
*/
class Markdown extends \yii\helpers\Markdown
class Markdown extends Component
{
/**
* @var BaseRenderer
*/
public static $renderer;
private $_parseDown;
/**
* Converts markdown into HTML
*
* @param string $content
* @param TypeDoc $context
* @return string
*/
public static function process($content, $context = null)
protected function getParseDown()
{
if (is_string($context)) {
$context = static::$renderer->context->getType($context);
if ($this->_parseDown === null) {
$this->_parseDown = new ParseDown();
}
$content = trim(parent::process($content, []));
if (!strncmp($content, '<p>', 3) && substr($content, -4, 4) == '</p>') {
$content = substr($content, 3, -4);
return $this->_parseDown;
}
$content = preg_replace_callback('/\[\[([\w\d\\\\\(\):$]+)(\|[^\]]*)?\]\]/xm', function($matches) use ($context) {
$object = $matches[1];
$title = (empty($matches[2]) || $matches[2] == '|') ? null : substr($matches[2], 1);
if (($pos = strpos($object, '::')) !== false) {
$typeName = substr($object, 0, $pos);
$subjectName = substr($object, $pos + 2);
if ($context !== null) {
// Collection resolves relative types
$typeName = (new Collection([$typeName], $context->phpDocContext))->__toString();
}
$type = static::$renderer->context->getType($typeName);
if ($type === null) {
static::$renderer->context->errors[] = [
'file' => ($context !== null) ? $context->sourceFile : null,
'message' => 'broken link to ' . $typeName . '::' . $subjectName . (($context !== null) ? ' in ' . $context->name : ''),
];
return '<span style="background: #f00;">' . $typeName . '::' . $subjectName . '</span>';
} else {
if (($subject = $type->findSubject($subjectName)) !== null) {
if ($title === null) {
$title = $type->name . '::' . $subject->name;
if ($subject instanceof MethodDoc) {
$title .= '()';
}
}
return static::$renderer->subjectLink($subject, $title);
} else {
static::$renderer->context->errors[] = [
'file' => ($context !== null) ? $context->sourceFile : null,
'message' => 'broken link to ' . $type->name . '::' . $subjectName . (($context !== null) ? ' in ' . $context->name : ''),
];
return '<span style="background: #ff0;">' . $type->name . '</span><span style="background: #f00;">::' . $subjectName . '</span>';
public function parse($markdown)
{
return $this->getParseDown()->parse($markdown);
}
public function parseLine($markdown)
{
return $this->getParseDown()->parseLine($markdown);
}
} elseif ($context !== null && ($subject = $context->findSubject($object)) !== null) {
return static::$renderer->subjectLink($subject, $title);
public function registerBlockHander($blockName, $callback)
{
$this->getParseDown()->register_block_handler($blockName, $callback);
}
if ($context !== null) {
// Collection resolves relative types
$object = (new Collection([$object], $context->phpDocContext))->__toString();
public function unregisterBlockHander($blockName)
{
$this->getParseDown()->remove_block_handler($blockName);
}
if (($type = static::$renderer->context->getType($object)) !== null) {
return static::$renderer->typeLink($type, $title);
public function registerInlineMarkerHandler($marker, $callback)
{
$this->getParseDown()->add_span_marker($marker, $callback);
}
static::$renderer->context->errors[] = [
'file' => ($context !== null) ? $context->sourceFile : null,
'message' => 'broken link to ' . $object . (($context !== null) ? ' in ' . $context->name : ''),
];
return '<span style="background: #f00;">' . $object . '</span>';
}, $content);
return $content;
public function unregisterInlineMarkerHandler($marker)
{
$this->getParseDown()->remove_span_marker($marker);
}
}
extensions/apidoc/templates/bootstrap/Renderer.php
......@@ -6,7 +6,7 @@
*/
namespace yii\apidoc\templates\bootstrap;
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\Context;
use yii\console\Controller;
use Yii;
......@@ -145,7 +145,7 @@ class Renderer extends \yii\apidoc\templates\html\Renderer
mkdir($dir, 0777, true);
}
Markdown::$renderer = $this;
ApiMarkdown::$renderer = $this;
$fileCount = count($files) + 1;
Console::startProgress(0, $fileCount, 'Rendering markdown files: ', false);
......@@ -165,7 +165,7 @@ class Renderer extends \yii\apidoc\templates\html\Renderer
}
foreach($fileData as $file => $content) {
$output = Markdown::process($content); // TODO generate links to yiiframework.com by default
$output = ApiMarkdown::process($content); // TODO generate links to yiiframework.com by default
$output = $this->fixMarkdownLinks($output);
if ($this->guideLayout !== false) {
$params = [
......
extensions/apidoc/templates/bootstrap/views/index.php
......@@ -9,7 +9,7 @@ use yii\apidoc\models\TraitDoc;
*/
if (isset($readme)) {
echo \yii\apidoc\helpers\Markdown::process($readme);
echo \yii\apidoc\helpers\ApiMarkdown::process($readme);
}
?><h1>Class Reference</h1>
......@@ -30,7 +30,7 @@ foreach($types as $i=>$class):
?>
<tr>
<td><?= $this->context->typeLink($class, $class->name) ?></td>
<td><?= \yii\apidoc\helpers\Markdown::process($class->shortDescription, $class) ?></td>
<td><?= \yii\apidoc\helpers\ApiMarkdown::process($class->shortDescription, $class, true) ?></td>
</tr>
<?php endforeach; ?>
</table>
extensions/apidoc/templates/html/Renderer.php
......@@ -7,7 +7,7 @@
namespace yii\apidoc\templates\html;
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\BaseDoc;
use yii\apidoc\models\ConstDoc;
use yii\apidoc\models\EventDoc;
......@@ -65,7 +65,7 @@ abstract class Renderer extends BaseRenderer implements ViewContextInterface
public function init()
{
Markdown::$renderer = $this;
ApiMarkdown::$renderer = $this;
}
/**
......
extensions/apidoc/templates/html/views/constSummary.php
<?php
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\ClassDoc;
use yii\helpers\ArrayHelper;
......@@ -33,7 +33,7 @@ ArrayHelper::multisort($constants, 'name');
<tr<?= $constant->definedBy != $type->name ? ' class="inherited"' : '' ?> id="<?= $constant->name ?>">
<td><?= $constant->name ?><a name="<?= $constant->name ?>-detail"></a></td>
<td><?= $constant->value ?></td>
<td><?= Markdown::process($constant->shortDescription . "\n" . $constant->description, $constant->definedBy) ?></td>
<td><?= APiMarkdown::process($constant->shortDescription . "\n" . $constant->description, $constant->definedBy, true) ?></td>
<td><?= $this->context->typeLink($constant->definedBy) ?></td>
</tr>
<?php endforeach; ?>
......
extensions/apidoc/templates/html/views/eventDetails.php
<?php
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\ClassDoc;
use yii\helpers\ArrayHelper;
......@@ -32,7 +32,7 @@ ArrayHelper::multisort($events, 'name');
<?php echo $event->trigger->signature; ?>
</div>*/ ?>
<p><?= Markdown::process($event->description, $type); ?></p>
<p><?= ApiMarkdown::process($event->description, $type); ?></p>
<?= $this->render('seeAlso', ['object' => $event]); ?>
......
extensions/apidoc/templates/html/views/eventSummary.php
<?php
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\ClassDoc;
use yii\helpers\ArrayHelper;
......@@ -34,7 +34,7 @@ ArrayHelper::multisort($events, 'name');
<td><?= $this->context->subjectLink($event) ?></td>
<td><?= $this->context->typeLink($event->types) ?></td>
<td>
<?= Markdown::process($event->shortDescription, $event->definedBy) ?>
<?= ApiMarkdown::process($event->shortDescription, $event->definedBy, true) ?>
<?php if(!empty($event->since)): ?>
(available since version <?php echo $event->since; ?>)
<?php endif; ?>
......
extensions/apidoc/templates/html/views/methodDetails.php
<?php
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\ClassDoc;
use yii\apidoc\models\TraitDoc;
use yii\helpers\ArrayHelper;
......@@ -39,21 +39,21 @@ ArrayHelper::multisort($methods, 'name');
<tr>
<td class="paramNameCol"><?= $param->name ?></td>
<td class="paramTypeCol"><?= $this->context->typeLink($param->types) ?></td>
<td class="paramDescCol"><?= Markdown::process($param->description, $type) ?></td>
<td class="paramDescCol"><?= ApiMarkdown::process($param->description, $type) ?></td>
</tr>
<?php endforeach; ?>
<?php if(!empty($method->return)): ?>
<tr>
<td class="paramNameCol"><?= 'return'; ?></td>
<td class="paramTypeCol"><?= $this->context->typeLink($method->returnTypes); ?></td>
<td class="paramDescCol"><?= Markdown::process($method->return, $type); ?></td>
<td class="paramDescCol"><?= ApiMarkdown::process($method->return, $type); ?></td>
</tr>
<?php endif; ?>
<?php foreach($method->exceptions as $exception => $description): ?>
<tr>
<td class="paramNameCol"><?= 'throws' ?></td>
<td class="paramTypeCol"><?= $this->context->typeLink($exception) ?></td>
<td class="paramDescCol"><?= Markdown::process($description, $type) ?></td>
<td class="paramDescCol"><?= ApiMarkdown::process($description, $type) ?></td>
</tr>
<?php endforeach; ?>
<?php endif; ?>
......@@ -61,8 +61,8 @@ ArrayHelper::multisort($methods, 'name');
<!-- --><?php //$this->renderPartial('sourceCode',array('object'=>$method)); ?>
<p><?= Markdown::process($method->shortDescription, $type) ?></strong></p>
<p><?= Markdown::process($method->description, $type) ?></p>
<p><?= ApiMarkdown::process($method->shortDescription, $type, true) ?></strong></p>
<p><?= ApiMarkdown::process($method->description, $type) ?></p>
<?= $this->render('seeAlso', ['object' => $method]); ?>
......
extensions/apidoc/templates/html/views/methodSummary.php
<?php
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\ClassDoc;
use yii\apidoc\models\InterfaceDoc;
use yii\apidoc\models\TraitDoc;
......@@ -37,7 +37,7 @@ foreach($methods as $method): ?>
<?php if($protected && $method->visibility == 'protected' || !$protected && $method->visibility != 'protected'): ?>
<tr<?= $method->definedBy != $type->name ? ' class="inherited"' : '' ?> id="<?= $method->name ?>()">
<td><?= $this->context->subjectLink($method, $method->name.'()') ?></td>
<td><?= Markdown::process($method->shortDescription, $method->definedBy) ?></td>
<td><?= ApiMarkdown::process($method->shortDescription, $method->definedBy, true) ?></td>
<td><?= $this->context->typeLink($method->definedBy, $type) ?></td>
</tr>
<?php endif; ?>
......
extensions/apidoc/templates/html/views/propertyDetails.php
<?php
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\ClassDoc;
use yii\apidoc\models\TraitDoc;
use yii\helpers\ArrayHelper;
......@@ -34,7 +34,7 @@ ArrayHelper::multisort($properties, 'name');
<div class="signature"><?php echo $this->context->renderPropertySignature($property); ?></div>
<p><?= Markdown::process($property->description, $type) ?></p>
<p><?= ApiMarkdown::process($property->description, $type) ?></p>
<?= $this->render('seeAlso', ['object' => $property]); ?>
......
extensions/apidoc/templates/html/views/propertySummary.php
<?php
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\ClassDoc;
use yii\apidoc\models\TraitDoc;
use yii\helpers\ArrayHelper;
......@@ -38,7 +38,7 @@ foreach($properties as $property): ?>
<tr<?= $property->definedBy != $type->name ? ' class="inherited"' : '' ?> id="<?= $property->name ?>">
<td><?= $this->context->subjectLink($property) ?></td>
<td><?= $this->context->typeLink($property->types) ?></td>
<td><?= Markdown::process($property->shortDescription, $property->definedBy) ?></td>
<td><?= ApiMarkdown::process($property->shortDescription, $property->definedBy, true) ?></td>
<td><?= $this->context->typeLink($property->definedBy) ?></td>
</tr>
<?php endif; ?>
......
extensions/apidoc/templates/html/views/seeAlso.php
......@@ -25,7 +25,7 @@ if (empty($see)) {
<h4>See Also</h4>
<ul>
<?php foreach($see as $ref): ?>
<li><?= \yii\apidoc\helpers\Markdown::process($ref, $object->definedBy) ?></li>
<li><?= \yii\apidoc\helpers\ApiMarkdown::process($ref, $object->definedBy, true) ?></li>
<?php endforeach; ?>
</ul>
</div>
extensions/apidoc/templates/html/views/type.php
<?php
use yii\apidoc\helpers\Markdown;
use yii\apidoc\helpers\ApiMarkdown;
use yii\apidoc\models\ClassDoc;
use yii\apidoc\models\InterfaceDoc;
use yii\apidoc\models\TraitDoc;
......@@ -77,8 +77,8 @@ $renderer = $this->context;
</table>
<div id="classDescription">
<strong><?= Markdown::process($type->shortDescription, $type) ?></strong>
<p><?= Markdown::process($type->description, $type) ?></p>
<strong><?= ApiMarkdown::process($type->shortDescription, $type, true) ?></strong>
<p><?= ApiMarkdown::process($type->description, $type) ?></p>
</div>
<a name="properties"></a>
......
extensions/apidoc/templates/online/views/index.php
......@@ -26,7 +26,7 @@ foreach($types as $i=>$class):
?>
<tr>
<td><?= $this->context->typeLink($class, $class->name) ?></td>
<td><?= \yii\apidoc\helpers\Markdown::process($class->shortDescription, $class) ?></td>
<td><?= \yii\apidoc\helpers\ApiMarkdown::process($class->shortDescription, $class, true) ?></td>
</tr>
<?php endforeach; ?>
</table>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment