Class yii\apidoc\templates\bootstrap\GuideRenderer
Inheritance | yii\apidoc\templates\bootstrap\GuideRenderer » yii\apidoc\templates\html\GuideRenderer » yii\apidoc\renderers\GuideRenderer » yii\apidoc\renderers\BaseRenderer » yii\base\Component |
---|---|
Uses Traits | yii\apidoc\templates\bootstrap\RendererTrait |
Available since extension's version | 2.0 |
Source Code | https://github.com/yiisoft/yii2-apidoc/blob/master/templates/bootstrap/GuideRenderer.php |
Public Properties
Property | Type | Description | Defined By |
---|---|---|---|
$apiContext | yii\apidoc\models\Context | The yii\apidoc\models\Context currently being rendered. | yii\apidoc\renderers\BaseRenderer |
$apiUrl | yii\apidoc\renderers\BaseRenderer | ||
$controller | \yii\console\Controller | The apidoc controller instance. | yii\apidoc\renderers\BaseRenderer |
$extensions | array | Official Yii extensions | yii\apidoc\templates\bootstrap\RendererTrait |
$guidePrefix | yii\apidoc\renderers\BaseRenderer | ||
$guideUrl | yii\apidoc\renderers\BaseRenderer | ||
$layout | yii\apidoc\templates\bootstrap\GuideRenderer | ||
$pageTitle | string | String to use as the title of the generated page. | yii\apidoc\renderers\BaseRenderer |
$view | \yii\web\View | The view instance. | yii\apidoc\templates\html\GuideRenderer |
Public Methods
Method | Description | Defined By |
---|---|---|
createSubjectLink() | Creates a link to a subject | yii\apidoc\renderers\BaseRenderer |
createTypeLink() | Creates a link to a type (class, interface or trait) | yii\apidoc\renderers\BaseRenderer |
generateApiUrl() | Generate an url to a type in apidocs | yii\apidoc\templates\html\GuideRenderer |
generateGuideUrl() | Generate an url to a guide page | yii\apidoc\renderers\BaseRenderer |
getGuideReferences() | yii\apidoc\templates\html\GuideRenderer | |
getNavTypes() | Returns nav TypeDocs | yii\apidoc\templates\bootstrap\RendererTrait |
getView() | yii\apidoc\templates\html\GuideRenderer | |
init() | yii\apidoc\templates\html\GuideRenderer | |
render() | Renders a set of files given into target directory. | yii\apidoc\templates\bootstrap\GuideRenderer |
Protected Methods
Method | Description | Defined By |
---|---|---|
afterMarkdownProcess() | Callback that is called after markdown is processed. | yii\apidoc\templates\html\GuideRenderer |
filterTypes() | Returns types of a given class | yii\apidoc\templates\bootstrap\RendererTrait |
fixMarkdownLinks() | Adds guide name to link URLs in markdown | yii\apidoc\templates\html\GuideRenderer |
generateGuideFileName() | Given markdown file name generates resulting html file name | yii\apidoc\templates\html\GuideRenderer |
generateLink() | Generate link markup | yii\apidoc\templates\html\GuideRenderer |
getTypeCategory() | Returns category of TypeDoc | yii\apidoc\templates\bootstrap\RendererTrait |
loadGuideStructure() | Loads guide structure from a set of files | yii\apidoc\renderers\GuideRenderer |
Constants
Constant | Value | Description | Defined By |
---|---|---|---|
GUIDE_PREFIX | 'guide-' | Deprecated since 2.0.1 use $guidePrefix instead which allows configuring this options | yii\apidoc\renderers\BaseRenderer |
Property Details
Method Details
Defined in: yii\apidoc\templates\html\GuideRenderer::afterMarkdownProcess()
Callback that is called after markdown is processed.
You may override it to do some post processing. The default implementation fixes some markdown links using fixMarkdownLinks() on the output.
protected string afterMarkdownProcess ( $file, $output, $renderer ) | ||
$file | string |
The file that has been processed. |
$output | string |
The rendered HTML output. |
$renderer | yii\apidoc\helpers\ApiMarkdown |
The renderer instance. |
protected function afterMarkdownProcess($file, $output, $renderer)
{
return $this->fixMarkdownLinks($output);
}
Defined in: yii\apidoc\renderers\BaseRenderer::createSubjectLink()
Creates a link to a subject
public string createSubjectLink ( $subject, string $title = null, array $options = [] ) | ||
$subject | yii\apidoc\models\PropertyDoc|yii\apidoc\models\MethodDoc|yii\apidoc\models\ConstDoc|yii\apidoc\models\EventDoc | |
$title | string|null | |
$options | array |
Additional HTML attributes for the link. |
public function createSubjectLink($subject, string $title = null, array $options = []): string
{
if ($title === null) {
$title = $subject->shortName;
}
if (($type = $this->apiContext->getType($subject->definedBy)) === null) {
return $subject->shortName;
}
$link = $this->generateApiUrl($type->name) . '#' . $subject->shortName . '-detail';
return $this->generateLink($title, $link, $options);
}
Defined in: yii\apidoc\renderers\BaseRenderer::createTypeLink()
Creates a link to a type (class, interface or trait)
public string createTypeLink ( $types, $context = null, $title = null, $options = [] ) | ||
$types | yii\apidoc\models\ClassDoc|yii\apidoc\models\InterfaceDoc|yii\apidoc\models\TraitDoc|yii\apidoc\models\ClassDoc[]|yii\apidoc\models\InterfaceDoc[]|yii\apidoc\models\TraitDoc[]|string|string[] | |
$context | yii\apidoc\models\BaseDoc | |
$title | string |
A title to be used for the link TODO check whether [[yii...|Class]] is supported |
$options | array |
Additional HTML attributes for the link. |
public function createTypeLink($types, $context = null, $title = null, $options = [])
{
if (!is_array($types)) {
$types = [$types];
}
if (count($types) > 1) {
$title = null;
}
$links = [];
foreach ($types as $type) {
$postfix = '';
if (is_string($type)) {
if (!empty($type) && substr_compare($type, '[]', -2, 2) === 0) {
$postfix = '[]';
$type = substr($type, 0, -2);
}
if ($type === '$this' && $context instanceof TypeDoc) {
$title = '$this';
$type = $context;
} elseif (($t = $this->apiContext->getType(ltrim($type, '\\'))) !== null) {
$type = $t;
} elseif (!empty($type) && $type[0] !== '\\' && ($t = $this->apiContext->getType($this->resolveNamespace($context) . '\\' . ltrim($type, '\\'))) !== null) {
$type = $t;
} else {
ltrim($type, '\\');
}
}
if (is_object($type) && \method_exists($type, '__toString')) {
$type = (string)$type;
}
if (is_string($type)) {
$linkText = ltrim($type, '\\');
if ($title !== null) {
$linkText = $title;
$title = null;
}
$phpTypes = [
'callable',
'array',
'string',
'boolean',
'bool',
'integer',
'int',
'float',
'object',
'resource',
'null',
'false',
'true',
];
$phpTypeAliases = [
'true' => 'boolean',
'false' => 'boolean',
'bool' => 'boolean',
'int' => 'integer',
];
$phpTypeDisplayAliases = [
'bool' => 'boolean',
'int' => 'integer',
];
// 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, 'https://www.php.net/class.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
} elseif (in_array($type, $phpTypes)) {
if (isset($phpTypeDisplayAliases[$type])) {
$linkText = $phpTypeDisplayAliases[$type];
}
if (isset($phpTypeAliases[$type])) {
$type = $phpTypeAliases[$type];
}
$links[] = $this->generateLink($linkText, 'https://www.php.net/language.types.' . strtolower(ltrim($type, '\\')), $options) . $postfix;
} else {
$links[] = $type . $postfix;
}
} elseif ($type instanceof BaseDoc) {
$linkText = $type->name;
if ($title !== null) {
$linkText = $title;
$title = null;
}
$links[] = $this->generateLink($linkText, $this->generateApiUrl($type->name), $options) . $postfix;
}
}
return implode('|', $links);
}
Defined in: yii\apidoc\templates\bootstrap\RendererTrait::filterTypes()
Returns types of a given class
protected array filterTypes ( $types, $navClasses ) | ||
$types | yii\apidoc\models\TypeDoc[] | |
$navClasses | string |
protected function filterTypes($types, $navClasses)
{
switch ($navClasses) {
case 'app':
$types = array_filter($types, function ($val) {
return strncmp($val->name, 'yii\\', 4) !== 0;
});
break;
case 'yii':
$self = $this;
$types = array_filter($types, function ($val) use ($self) {
if ($val->name === 'Yii' || $val->name === 'YiiRequirementChecker') {
return true;
}
if (strlen($val->name) < 5) {
return false;
}
$subName = substr($val->name, 4, strpos($val->name, '\\', 5) - 4);
return strncmp($val->name, 'yii\\', 4) === 0 && !in_array($subName, $self->extensions);
});
break;
default:
$types = array_filter($types, function ($val) use ($navClasses) {
return strncmp($val->name, "yii\\$navClasses\\", strlen("yii\\$navClasses\\")) === 0;
});
}
return $types;
}
Defined in: yii\apidoc\templates\html\GuideRenderer::fixMarkdownLinks()
Adds guide name to link URLs in markdown
protected string fixMarkdownLinks ( $content ) | ||
$content | string |
protected function fixMarkdownLinks($content)
{
$content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="' . $this->guidePrefix . '\1.html\2"', $content);
return $content;
}
Defined in: yii\apidoc\templates\html\GuideRenderer::generateApiUrl()
Generate an url to a type in apidocs
public mixed generateApiUrl ( $typeName ) | ||
$typeName |
public function generateApiUrl($typeName)
{
return rtrim($this->apiUrl, '/') . '/' . strtolower(str_replace('\\', '-', $typeName)) . '.html';
}
Defined in: yii\apidoc\templates\html\GuideRenderer::generateGuideFileName()
Given markdown file name generates resulting html file name
protected string generateGuideFileName ( $file ) | ||
$file | string |
Markdown file name |
protected function generateGuideFileName($file)
{
return $this->guidePrefix . basename($file, '.md') . '.html';
}
Defined in: yii\apidoc\renderers\BaseRenderer::generateGuideUrl()
Generate an url to a guide page
public string generateGuideUrl ( $file ) | ||
$file | string |
public function generateGuideUrl($file)
{
//skip parsing external url
if ( (strpos($file, 'https://') !== false) || (strpos($file, 'http://') !== false) ) {
return $file;
}
$hash = '';
if (($pos = strpos($file, '#')) !== false) {
$hash = substr($file, $pos);
$file = substr($file, 0, $pos);
}
return rtrim($this->guideUrl, '/') . '/' . $this->guidePrefix . basename($file, '.md') . '.html' . $hash;
}
Defined in: yii\apidoc\templates\html\GuideRenderer::generateLink()
Generate link markup
protected mixed generateLink ( $text, $href, $options = [] ) | ||
$text | ||
$href | ||
$options | array |
Additional HTML attributes for the link. |
protected function generateLink($text, $href, $options = [])
{
$options['href'] = $href;
return Html::a($text, null, $options);
}
public void getGuideReferences ( ) |
public function getGuideReferences()
{
// TODO implement for api docs
$refs = [];
foreach ($this->markDownFiles as $file) {
$refName = 'guide-' . basename($file, '.md');
$refs[$refName] = ['url' => $this->generateGuideFileName($file)];
}
return $refs;
}
Defined in: yii\apidoc\templates\bootstrap\RendererTrait::getTypeCategory()
Returns category of TypeDoc
protected string getTypeCategory ( $type ) | ||
$type | yii\apidoc\models\TypeDoc |
protected function getTypeCategory($type)
{
$extensions = $this->extensions;
$navClasses = 'app';
if (isset($type)) {
if ($type->name == 'Yii' || $type->name == 'YiiRequirementChecker') {
$navClasses = 'yii';
} elseif (strncmp($type->name, 'yii\\', 4) == 0) {
$navClasses = 'yii';
$subName = substr($type->name, 4);
if (($pos = strpos($subName, '\\')) !== false) {
$subNamespace = substr($subName, 0, $pos);
if (in_array($subNamespace, $extensions)) {
$navClasses = $subNamespace;
}
}
}
}
return $navClasses;
}
public \yii\web\View getView ( ) | ||
return | \yii\web\View |
The view instance |
---|
public function getView()
{
if ($this->_view === null) {
$this->_view = new View();
$assetPath = Yii::getAlias($this->_targetDir) . '/assets';
if (!is_dir($assetPath)) {
mkdir($assetPath);
}
$this->_view->assetManager = new AssetManager([
'basePath' => $assetPath,
'baseUrl' => './assets',
]);
}
return $this->_view;
}
Defined in: yii\apidoc\templates\html\GuideRenderer::init()
public void init ( ) |
public function init()
{
parent::init();
if ($this->pageTitle === null) {
$this->pageTitle = 'The Definitive Guide to Yii 2.0';
}
}
Defined in: yii\apidoc\renderers\GuideRenderer::loadGuideStructure()
Loads guide structure from a set of files
protected array loadGuideStructure ( $files ) | ||
$files | array |
protected function loadGuideStructure($files)
{
$chapters = [];
foreach ($files as $file) {
$contents = file_get_contents($file);
if (basename($file) == 'README.md') {
$indexAnalyzer = new IndexFileAnalyzer();
$chapters = $indexAnalyzer->analyze($contents);
break;
}
if (preg_match("/^(.*)\n=+/", $contents, $matches)) {
$headlines[$file] = $matches[1];
} else {
$headlines[$file] = basename($file);
}
}
return $chapters;
}
Renders a set of files given into target directory.
public void render ( $files, $targetDir ) | ||
$files | array | |
$targetDir | string |
public function render($files, $targetDir)
{
$types = array_merge($this->apiContext->classes, $this->apiContext->interfaces, $this->apiContext->traits);
$extTypes = [];
foreach ($this->extensions as $k => $ext) {
$extType = $this->filterTypes($types, $ext);
if (empty($extType)) {
unset($this->extensions[$k]);
continue;
}
$extTypes[$ext] = $extType;
}
parent::render($files, $targetDir);
if ($this->controller !== null) {
$this->controller->stdout('generating search index...');
}
$indexer = new ApiIndexer();
$indexer->indexFiles(FileHelper::findFiles($targetDir, ['only' => ['*.html']]), $targetDir);
$js = $indexer->exportJs();
file_put_contents($targetDir . '/jssearch.index.js', $js);
if ($this->controller !== null) {
$this->controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
}
}