Skip to content

Y
yii2
Commit 5ad0efe3 by Carsten Brandt
Options

APIDOC beautification

parent f41f55a0
Showing with 221 additions and 133 deletions
extensions/apidoc/models/FunctionDoc.php
......@@ -73,7 +73,7 @@ class FunctionDoc extends BaseDoc
} elseif ($tag instanceof ReturnTag) {
$this->returnType = $tag->getType();
$this->returnTypes = $tag->getTypes();
$this->return = $tag->getDescription();
$this->return = ucfirst($tag->getDescription());
unset($this->tags[$i]);
}
}
......
extensions/apidoc/renderers/BaseRenderer.php
......@@ -57,9 +57,10 @@ abstract class BaseRenderer extends Component
* @param ClassDoc|InterfaceDoc|TraitDoc|ClassDoc[]|InterfaceDoc[]|TraitDoc[] $types
* @param string $title a title to be used for the link TODO check whether [[yii\...|Class]] is supported
* @param BaseDoc $context
* @param array $options additional HTML attributes for the link.
* @return string
*/
public function createTypeLink($types, $context = null, $title = null)
public function createTypeLink($types, $context = null, $title = null, $options = [])
{
if (!is_array($types)) {
$types = [$types];
......@@ -103,9 +104,9 @@ abstract class BaseRenderer extends Component
// check if it is PHP internal class
if (((class_exists($type, false) || interface_exists($type, false) || trait_exists($type, false)) &&
($reflection = new \ReflectionClass($type)) && $reflection->isInternal())) {
$links[] = $this->generateLink($linkText, 'http://www.php.net/class.' . strtolower(ltrim($type, '\\'))) . $postfix;
$links[] = $this->generateLink($linkText, 'http://www.php.net/class.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
} elseif (in_array($type, $phpTypes)) {
$links[] = $this->generateLink($linkText, 'http://www.php.net/language.types.' . strtolower(ltrim($type, '\\'))) . $postfix;
$links[] = $this->generateLink($linkText, 'http://www.php.net/language.types.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
} else {
$links[] = $type;
}
......@@ -114,10 +115,10 @@ abstract class BaseRenderer extends Component
if ($title !== null) {
$linkText = $title;
}
$links[] = $this->generateLink($linkText, $this->generateApiUrl($type->name)) . $postfix;
$links[] = $this->generateLink($linkText, $this->generateApiUrl($type->name), $options) . $postfix;
}
}
return implode(' | ', $links);
return implode('|', $links);
}
......@@ -125,9 +126,10 @@ abstract class BaseRenderer extends Component
* creates a link to a subject
* @param PropertyDoc|MethodDoc|ConstDoc|EventDoc $subject
* @param string $title
* @param array $options additional HTML attributes for the link.
* @return string
*/
public function createSubjectLink($subject, $title = null)
public function createSubjectLink($subject, $title = null, $options = [])
{
if ($title === null) {
if ($subject instanceof MethodDoc) {
......@@ -146,7 +148,7 @@ abstract class BaseRenderer extends Component
$link .= '#' . $subject->name;
}
$link .= '-detail';
return Html::a($title, null, ['href' => $link]);
return $this->generateLink($title, $link, $options);
}
}
......@@ -175,9 +177,10 @@ abstract class BaseRenderer extends Component
* generate link markup
* @param $text
* @param $href
* @param array $options additional HTML attributes for the link.
* @return mixed
*/
protected abstract function generateLink($text, $href);
protected abstract function generateLink($text, $href, $options = []);
/**
* Generate an url to a type in apidocs
......
extensions/apidoc/templates/bootstrap/assets/css/style.css
......@@ -3,6 +3,10 @@ body {
height: 100%;
}
.guide-content, .api-content {
max-width: 1250px;
}
.wrap {
min-height: 100%;
height: auto;
......@@ -35,9 +39,14 @@ body {
color: #fff;
}
.signature, .signature2 {
padding: 3px;
.signature, .table-striped > tbody > tr > td.signature {
margin: 10px 0 10px 0;
padding: 8px;
color: #000000;
background: rgba(230, 236, 255, 0.81);
border: 1px rgba(191, 207, 255, 0.81) solid;
font-family: "courier new", "times new roman", monospace;
line-height: 1.3em;
white-space: pre-line;
......@@ -45,12 +54,6 @@ body {
word-break: break-all;
}
.signature {
margin: 10px 0 10px 0;
background: #E6ECFF;
border: 1px #BFCFFF solid;
}
blockquote {
font-size: 14px;
}
......@@ -59,7 +62,50 @@ td p {
margin: 0;
}
table.detailTable .paramNameCol { width: 15%; min-width: 100px; }
table.detailTable .paramTypeCol { width: 15%; min-width: 150px; }
table.detailTable .paramDescCol { width: 70%; }
table.detail-table .param-name-col { width: 15%; min-width: 100px; }
table.detail-table .param-type-col { width: 15%; min-width: 150px; }
table.detail-table .param-desc-col { width: 70%; }
table.summary-table .col-method { width: 20%; }
table.summary-table .col-property { width: 20%; }
table.summary-table .col-const { width: 20%; }
table.summary-table .col-event { width: 20%; }
table.summary-table .col-defined { width: 15%; }
.detail-header {
margin-top: 30px;
}
.doc-description {
border-left: solid 1px #ddd;
border-right: solid 1px #ddd;
padding: 10px 8px;
margin: 0;
}
.event-doc .doc-description {
border-bottom: solid 1px #ddd;
}
.doc-description p:last-child {
margin-bottom: 0;
}
.tool-link {
float: right;
color: #ddd;
margin: 0 8px;
}
.icon-hash:before {
content: '#';
font-size: 32px;
font-weight: bold;
/*top: -10px;*/
line-height: 0.5;
}
.tool-link:hover {
color: #bbb;
text-decoration: none;
}
\ No newline at end of file
extensions/apidoc/templates/bootstrap/layouts/api.php
......@@ -44,7 +44,7 @@ $this->beginContent('@yii/apidoc/templates/bootstrap/layouts/main.php'); ?>
'view' => $this,
])?>
</div>
<div class="col-md-9" role="main">
<div class="col-md-9 api-content" role="main">
<?= $content ?>
</div>
</div>
......
extensions/apidoc/templates/bootstrap/layouts/guide.php
......@@ -32,7 +32,7 @@ $this->beginContent('@yii/apidoc/templates/bootstrap/layouts/main.php'); ?>
'view' => $this,
]) ?>
</div>
<div class="col-md-9" role="main">
<div class="col-md-9 guide-content" role="main">
<?= $content ?>
</div>
</div>
......
extensions/apidoc/templates/html/ApiRenderer.php
......@@ -246,8 +246,8 @@ class ApiRenderer extends BaseApiRenderer implements ViewContextInterface
return ($method->isReturnByReference ? '<b>&</b>' : '')
. ($method->returnType === null ? 'void' : $this->createTypeLink($method->returnTypes))
. ' ' . $this->createSubjectLink($method, $method->name)
. ApiMarkdown::highlight('( ' . implode(', ', $params) . ' )', 'php');
. ' <strong>' . $this->createSubjectLink($method, $method->name) . '</strong>'
. ApiMarkdown::highlight(str_replace(' ', ' ', '( ' . implode(', ', $params) . ' )'), 'php');
}
public function generateApiUrl($typeName)
......@@ -271,14 +271,12 @@ class ApiRenderer extends BaseApiRenderer implements ViewContextInterface
}
/**
* generate link markup
* @param $text
* @param $href
* @return mixed
* @inheritdoc
*/
protected function generateLink($text, $href)
protected function generateLink($text, $href, $options = [])
{
return Html::a($text, null, ['href' => $href]);
$options['href'] = $href;
return Html::a($text, null, $options);
}
public function getSourceUrl($type)
......
extensions/apidoc/templates/html/GuideRenderer.php
......@@ -138,14 +138,12 @@ abstract class GuideRenderer extends BaseGuideRenderer
}
/**
* generate link markup
* @param $text
* @param $href
* @return mixed
* @inheritdoc
*/
protected function generateLink($text, $href)
protected function generateLink($text, $href, $options = [])
{
return Html::a($text, null, ['href' => $href]);
$options['href'] = $href;
return Html::a($text, null, $options);
}
/**
......
extensions/apidoc/templates/html/views/constSummary.php
......@@ -18,27 +18,28 @@ if (empty($type->constants)) {
$constants = $type->constants;
ArrayHelper::multisort($constants, 'name');
?>
<div class="summary docConst">
<h2>Constants</h2>
<div class="summary doc-const">
<h2>Constants</h2>
<p><a href="#" class="toggle">Hide inherited constants</a></p>
<p><a href="#" class="toggle">Hide inherited constants</a></p>
<table class="summaryTable table table-striped table-bordered table-hover">
<colgroup>
<col class="col-const" />
<col class="col-description" />
<col class="col-defined" />
</colgroup>
<tr>
<th>Constant</th><th>Value</th><th>Description</th><th>Defined By</th>
</tr>
<?php foreach ($constants as $constant): ?>
<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><?= ApiMarkdown::process($constant->shortDescription . "\n" . $constant->description, $constant->definedBy, true) ?></td>
<td><?= $renderer->createTypeLink($constant->definedBy) ?></td>
<table class="summary-table table table-striped table-bordered table-hover">
<colgroup>
<col class="col-const" />
<col class="col-value" />
<col class="col-description" />
<col class="col-defined" />
</colgroup>
<tr>
<th>Constant</th><th>Value</th><th>Description</th><th>Defined By</th>
</tr>
<?php endforeach; ?>
</table>
<?php foreach ($constants as $constant): ?>
<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><?= ApiMarkdown::process($constant->shortDescription . "\n" . $constant->description, $constant->definedBy, true) ?></td>
<td><?= $renderer->createTypeLink($constant->definedBy) ?></td>
</tr>
<?php endforeach; ?>
</table>
</div>
\ No newline at end of file
extensions/apidoc/templates/html/views/eventDetails.php
......@@ -7,8 +7,11 @@ use yii\helpers\ArrayHelper;
/**
* @var ClassDoc $type
* @var yii\web\View $this
* @var \yii\apidoc\templates\html\ApiRenderer $renderer
*/
$renderer = $this->context;
$events = $type->getNativeEvents();
if (empty($events)) {
return;
......@@ -16,10 +19,24 @@ if (empty($events)) {
ArrayHelper::multisort($events, 'name');
?>
<h2>Event Details</h2>
<div class="event-doc">
<?php foreach ($events as $event): ?>
<div class="detailHeader h3" id="<?= $event->name.'-detail' ?>">
<div class="detail-header h3" id="<?= $event->name.'-detail' ?>">
<a href="#" class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
<?= $renderer->createSubjectLink($event, '<span class="glyphicon icon-hash"></span>', [
'title' => 'direct link to this method',
'class' => 'tool-link hash',
]) ?>
<?php if (($sourceUrl = $renderer->getSourceUrl($event->definedBy, $event->startLine)) !== null): ?>
<a href="<?= str_replace('/blob/', '/edit/', $sourceUrl) ?>" class="tool-link" title="edit on github"><span class="glyphicon glyphicon-pencil"></span></a>
<a href="<?= $sourceUrl ?>" class="tool-link" title="view source on github"><span class="glyphicon glyphicon-eye-open"></span></a>
<?php endif; ?>
<?= $event->name ?>
<span class="detailHeaderTag small">
<span class="detail-header-tag small">
event
<?php if (!empty($event->since)): ?>
(available since version <?= $event->since ?>)
......@@ -27,13 +44,11 @@ ArrayHelper::multisort($events, 'name');
</span>
</div>
<?php /*
<div class="signature">
<?php echo $event->trigger->signature; ?>
</div>*/ ?>
<div class="doc-description">
<?= ApiMarkdown::process($event->description, $type) ?>
<?= ApiMarkdown::process($event->description, $type) ?>
<?= $this->render('seeAlso', ['object' => $event]) ?>
<?= $this->render('seeAlso', ['object' => $event]) ?>
</div>
<?php endforeach; ?>
</div>
extensions/apidoc/templates/html/views/eventSummary.php
......@@ -18,32 +18,33 @@ if (empty($type->events)) {
$events = $type->events;
ArrayHelper::multisort($events, 'name');
?>
<div class="summary docEvent">
<h2>Events</h2>
<div class="summary doc-event">
<h2>Events</h2>
<p><a href="#" class="toggle">Hide inherited events</a></p>
<p><a href="#" class="toggle">Hide inherited events</a></p>
<table class="summaryTable table table-striped table-bordered table-hover">
<colgroup>
<col class="col-event" />
<col class="col-description" />
<col class="col-defined" />
</colgroup>
<tr>
<th>Event</th><th>Type</th><th>Description</th><th>Defined By</th>
</tr>
<?php foreach ($events as $event): ?>
<tr<?= $event->definedBy != $type->name ? ' class="inherited"' : '' ?> id="<?= $event->name ?>">
<td><?= $renderer->createSubjectLink($event) ?></td>
<td><?= $renderer->createTypeLink($event->types) ?></td>
<td>
<?= ApiMarkdown::process($event->shortDescription, $event->definedBy, true) ?>
<?php if (!empty($event->since)): ?>
(available since version <?= $event->since ?>)
<?php endif; ?>
</td>
<td><?= $renderer->createTypeLink($event->definedBy) ?></td>
</tr>
<?php endforeach; ?>
</table>
<table class="summary-table table table-striped table-bordered table-hover">
<colgroup>
<col class="col-event" />
<col class="col-type" />
<col class="col-description" />
<col class="col-defined" />
</colgroup>
<tr>
<th>Event</th><th>Type</th><th>Description</th><th>Defined By</th>
</tr>
<?php foreach ($events as $event): ?>
<tr<?= $event->definedBy != $type->name ? ' class="inherited"' : '' ?> id="<?= $event->name ?>">
<td><?= $renderer->createSubjectLink($event) ?></td>
<td><?= $renderer->createTypeLink($event->types) ?></td>
<td>
<?= ApiMarkdown::process($event->shortDescription, $event->definedBy, true) ?>
<?php if (!empty($event->since)): ?>
(available since version <?= $event->since ?>)
<?php endif; ?>
</td>
<td><?= $renderer->createTypeLink($event->definedBy) ?></td>
</tr>
<?php endforeach; ?>
</table>
</div>
extensions/apidoc/templates/html/views/methodDetails.php
......@@ -21,11 +21,23 @@ ArrayHelper::multisort($methods, 'name');
?>
<h2>Method Details</h2>
<div class="method-doc">
<?php foreach ($methods as $method): ?>
<div class="detailHeader h3" id="<?= $method->name . '()-detail' ?>">
<div class="detail-header h3" id="<?= $method->name . '()-detail' ?>">
<a href="#" class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
<?= $renderer->createSubjectLink($method, '<span class="glyphicon icon-hash"></span>', [
'title' => 'direct link to this method',
'class' => 'tool-link hash',
]) ?>
<?php if (($sourceUrl = $renderer->getSourceUrl($method->definedBy, $method->startLine)) !== null): ?>
<a href="<?= str_replace('/blob/', '/edit/', $sourceUrl) ?>" class="tool-link" title="edit on github"><span class="glyphicon glyphicon-pencil"></span></a>
<a href="<?= $sourceUrl ?>" class="tool-link" title="view source on github"><span class="glyphicon glyphicon-eye-open"></span></a>
<?php endif; ?>
<?= $method->name ?>()
<span class="detailHeaderTag small">
<span class="detail-header-tag small">
<?= $method->visibility ?>
method
<?php if (!empty($method->since)): ?>
......@@ -34,45 +46,42 @@ ArrayHelper::multisort($methods, 'name');
</span>
</div>
<table class="detailTable table table-striped table-bordered table-hover">
<tr><td colspan="3">
<div class="signature2"><?= $renderer->renderMethodSignature($method) ?></div>
</td></tr>
<div class="doc-description">
<p><strong><?= ApiMarkdown::process($method->shortDescription, $type, true) ?></strong></p>
<?= ApiMarkdown::process($method->description, $type) ?>
<?= $this->render('seeAlso', ['object' => $method]) ?>
</div>
<table class="detail-table table table-striped table-bordered table-hover">
<tr><td colspan="3" class="signature"><?= $renderer->renderMethodSignature($method) ?></td></tr>
<?php if (!empty($method->params) || !empty($method->return) || !empty($method->exceptions)): ?>
<?php foreach ($method->params as $param): ?>
<tr>
<td class="paramNameCol"><?= ApiMarkdown::highlight($param->name, 'php') ?></td>
<td class="paramTypeCol"><?= $renderer->createTypeLink($param->types) ?></td>
<td class="paramDescCol"><?= ApiMarkdown::process($param->description, $type) ?></td>
<td class="param-name-col"><?= ApiMarkdown::highlight($param->name, 'php') ?></td>
<td class="param-type-col"><?= $renderer->createTypeLink($param->types) ?></td>
<td class="param-desc-col"><?= ApiMarkdown::process($param->description, $type) ?></td>
</tr>
<?php endforeach; ?>
<?php if (!empty($method->return)): ?>
<tr>
<th class="paramNameCol"><?= 'return' ?></th>
<td class="paramTypeCol"><?= $renderer->createTypeLink($method->returnTypes) ?></td>
<td class="paramDescCol"><?= ApiMarkdown::process($method->return, $type) ?></td>
<th class="param-name-col">return</th>
<td class="param-type-col"><?= $renderer->createTypeLink($method->returnTypes) ?></td>
<td class="param-desc-col"><?= ApiMarkdown::process($method->return, $type) ?></td>
</tr>
<?php endif; ?>
<?php foreach ($method->exceptions as $exception => $description): ?>
<tr>
<th class="paramNameCol"><?= 'throws' ?></th>
<td class="paramTypeCol"><?= $renderer->createTypeLink($exception) ?></td>
<td class="paramDescCol"><?= ApiMarkdown::process($description, $type) ?></td>
<th class="param-name-col">throws</th>
<td class="param-type-col"><?= $renderer->createTypeLink($exception) ?></td>
<td class="param-desc-col"><?= ApiMarkdown::process($description, $type) ?></td>
</tr>
<?php endforeach; ?>
<?php endif; ?>
<?php if (($sourceUrl = $renderer->getSourceUrl($method->definedBy, $method->startLine)) !== null): ?>
<tr>
<td colspan="3">Source Code: <a href="<?= $sourceUrl ?>"><?= $sourceUrl ?></a></td>
</tr>
<?php endif; ?>
</table>
<!-- --><?php //$this->renderPartial('sourceCode',array('object'=>$method)); ?>
<p><strong><?= ApiMarkdown::process($method->shortDescription, $type, true) ?></strong></p>
<?= ApiMarkdown::process($method->description, $type) ?>
<?= $this->render('seeAlso', ['object' => $method]) ?>
<?php endforeach; ?>
</div>
extensions/apidoc/templates/html/views/methodSummary.php
......@@ -19,12 +19,12 @@ if ($protected && count($type->getProtectedMethods()) == 0 || !$protected && cou
return;
} ?>
<div class="summary docMethod">
<div class="summary doc-method">
<h2><?= $protected ? 'Protected Methods' : 'Public Methods' ?></h2>
<p><a href="#" class="toggle">Hide inherited methods</a></p>
<table class="summaryTable table table-striped table-bordered table-hover">
<table class="summary-table table table-striped table-bordered table-hover">
<colgroup>
<col class="col-method" />
<col class="col-description" />
......
extensions/apidoc/templates/html/views/propertyDetails.php
......@@ -21,9 +21,22 @@ ArrayHelper::multisort($properties, 'name');
?>
<h2>Property Details</h2>
<div class="property-doc">
<?php foreach ($properties as $property): ?>
<div class="detailHeader h3" id="<?= $property->name.'-detail' ?>">
<div class="detail-header h3" id="<?= $property->name.'-detail' ?>">
<a href="#" class="tool-link" title="go to top"><span class="glyphicon glyphicon-arrow-up"></span></a>
<?= $renderer->createSubjectLink($property, '<span class="glyphicon icon-hash"></span>', [
'title' => 'direct link to this method',
'class' => 'tool-link hash',
]) ?>
<?php if (($sourceUrl = $renderer->getSourceUrl($property->definedBy, $property->startLine)) !== null): ?>
<a href="<?= str_replace('/blob/', '/edit/', $sourceUrl) ?>" class="tool-link" title="edit on github"><span class="glyphicon glyphicon-pencil"></span></a>
<a href="<?= $sourceUrl ?>" class="tool-link" title="view source on github"><span class="glyphicon glyphicon-eye-open"></span></a>
<?php endif; ?>
<?= $property->name ?>
<span class="detailHeaderTag small">
<?= $property->visibility ?>
......@@ -43,3 +56,4 @@ ArrayHelper::multisort($properties, 'name');
<?= $this->render('seeAlso', ['object' => $property]) ?>
<?php endforeach; ?>
</div>
extensions/apidoc/templates/html/views/propertySummary.php
......@@ -18,12 +18,12 @@ if ($protected && count($type->getProtectedProperties()) == 0 || !$protected &&
return;
} ?>
<div class="summary docProperty">
<div class="summary doc-property">
<h2><?= $protected ? 'Protected Properties' : 'Public Properties' ?></h2>
<p><a href="#" class="toggle">Hide inherited properties</a></p>
<table class="summaryTable table table-striped table-bordered table-hover">
<table class="summary-table table table-striped table-bordered table-hover">
<colgroup>
<col class="col-property" />
<col class="col-type" />
......
extensions/apidoc/templates/html/views/seeAlso.php
......@@ -11,21 +11,22 @@ foreach ($object->tags as $tag) {
if (get_class($tag) == 'phpDocumentor\Reflection\DocBlock\Tag\SeeTag') {
$ref = $tag->getReference();
if (strpos($ref, '://') === false) {
$see[] = '[[' . $ref . ']]';
} else {
$see[] = $ref;
$ref = '[[' . $ref . ']]';
}
$see[] = rtrim(\yii\apidoc\helpers\ApiMarkdown::process($ref . ' ' . $tag->getDescription(), $object->definedBy, true), ". \r\n");
}
}
if (empty($see)) {
return;
} elseif (count($see) == 1) {
echo '<p>See also ' . reset($see) . '.</p>';
} else {
echo '<p>See also:</p><ul>';
foreach ($see as $ref) {
if (substr($ref, -1, 1) != '>') {
$ref .= '.';
}
echo "<li>$ref</li>";
}
echo '</ul>';
}
?>
<div class="SeeAlso">
<h4>See Also</h4>
<ul>
<?php foreach ($see as $ref): ?>
<li><?= \yii\apidoc\helpers\ApiMarkdown::process($ref, $object->definedBy, true) ?></li>
<?php endforeach; ?>
</ul>
</div>
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