Abstract Class yii\apidoc\templates\html\GuideRenderer

All Classes | Properties | Methods | Constants

Inheritance	yii\apidoc\templates\html\GuideRenderer » yii\apidoc\renderers\GuideRenderer » yii\apidoc\renderers\BaseRenderer » yii\base\Component
Subclasses	yii\apidoc\templates\bootstrap\GuideRenderer, yii\apidoc\templates\pdf\GuideRenderer
Available since extension's version	2.0
Source Code	https://github.com/yiisoft/yii2-apidoc/blob/master/templates/html/GuideRenderer.php

Public Properties

Hide inherited 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
$guidePrefix			yii\apidoc\renderers\BaseRenderer
$guideUrl			yii\apidoc\renderers\BaseRenderer
$layout			yii\apidoc\templates\html\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

Hide inherited 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
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\html\GuideRenderer

Protected Methods

Hide inherited methods

Method	Description	Defined By
afterMarkdownProcess()	Callback that is called after markdown is processed.	yii\apidoc\templates\html\GuideRenderer
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
loadGuideStructure()	Loads guide structure from a set of files	yii\apidoc\renderers\GuideRenderer

Constants

Hide inherited 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

Hide inherited properties

$layout public property

public $layout = null

$view public property

The view instance. This property is read-only.

public \yii\web\View $view = null

Method Details

Hide inherited methods

afterMarkdownProcess() protected method (available since version 2.0.5)

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.

Source code

                protected function afterMarkdownProcess($file, $output, $renderer)
{
    return $this->fixMarkdownLinks($output);
}

createSubjectLink() public method

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.

Source code

                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);
}

createTypeLink() public method

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.

Source code

                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);
}

fixMarkdownLinks() protected method

Adds guide name to link URLs in markdown

protected string fixMarkdownLinks ( $content )
$content	string

Source code

                protected function fixMarkdownLinks($content)
{
    $content = preg_replace('/href\s*=\s*"([^"\/]+)\.md(#.*)?"/i', 'href="' . $this->guidePrefix . '\1.html\2"', $content);
    return $content;
}

generateApiUrl() public method

Generate an url to a type in apidocs

public mixed generateApiUrl ( $typeName )
$typeName

Source code

                public function generateApiUrl($typeName)
{
    return rtrim($this->apiUrl, '/') . '/' . strtolower(str_replace('\\', '-', $typeName)) . '.html';
}

generateGuideFileName() protected method

Given markdown file name generates resulting html file name

protected string generateGuideFileName ( $file )
$file	string	Markdown file name

Source code

                protected function generateGuideFileName($file)
{
    return $this->guidePrefix . basename($file, '.md') . '.html';
}

generateGuideUrl() public method

Defined in: yii\apidoc\renderers\BaseRenderer::generateGuideUrl()

Generate an url to a guide page

public string generateGuideUrl ( $file )
$file	string

Source code

                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;
}

generateLink() protected method

Generate link markup

protected mixed generateLink ( $text, $href, $options = [] )
$text
$href
$options	array	Additional HTML attributes for the link.

Source code

                protected function generateLink($text, $href, $options = [])
{
    $options['href'] = $href;
    return Html::a($text, null, $options);
}

getGuideReferences() public method

public void getGuideReferences ( )

Source code

                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;
}

getView() public method

public \yii\web\View getView ( )
return	\yii\web\View	The view instance

Source code

                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;
}

init() public method

public void init ( )

Source code

                public function init()
{
    parent::init();
    if ($this->pageTitle === null) {
        $this->pageTitle = 'The Definitive Guide to Yii 2.0';
    }
}

loadGuideStructure() protected method

Defined in: yii\apidoc\renderers\GuideRenderer::loadGuideStructure()

Loads guide structure from a set of files

protected array loadGuideStructure ( $files )
$files	array

Source code

                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;
}

render() public method

Renders a set of files given into target directory.

public void render ( $files, $targetDir )
$files	array
$targetDir	string

Source code

                public function render($files, $targetDir)
{
    $this->_targetDir = $targetDir;
    $fileCount = count($files) + 1;
    if ($this->controller !== null) {
        Console::startProgress(0, $fileCount, 'Rendering markdown files: ', false);
    }
    $done = 0;
    $fileData = [];
    $chapters = $this->loadGuideStructure($files);
    foreach ($files as $file) {
        $fileData[$file] = file_get_contents($file);
        if (basename($file) == 'README.md') {
            continue; // to not add index file to nav
        }
    }
    foreach ($fileData as $file => $content) {
        $output = ApiMarkdown::process($content); // TODO generate links to yiiframework.com by default
        $output = $this->afterMarkdownProcess($file, $output, Markdown::$flavors['api']);
        if ($this->layout !== false) {
            $params = [
                'chapters' => $chapters,
                'currentFile' => $file,
                'content' => $output,
            ];
            $output = $this->getView()->renderFile($this->layout, $params, $this);
        }
        $fileName = $this->generateGuideFileName($file);
        file_put_contents($targetDir . '/' . $fileName, $output);
        if ($this->controller !== null) {
            Console::updateProgress(++$done, $fileCount);
        }
    }
    if ($this->controller !== null) {
        Console::updateProgress(++$done, $fileCount);
        Console::endProgress(true);
        $this->controller->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    }
}