Class yii\apidoc\commands\GuideController

All Classes | Properties | Methods
Inheritanceyii\apidoc\commands\GuideController » yii\apidoc\components\BaseController » yii\console\Controller
Available since extension's version2.0
Source Code https://github.com/yiisoft/yii2-apidoc/blob/master/commands/GuideController.php

This command can render documentation stored as markdown files such as the yii guide or your own applications documentation setup.

Public Properties

Hide inherited properties

Property Type Description Defined By
$apiDocs string Path or URL to the api docs to allow links to classes and properties/methods. yii\apidoc\commands\GuideController
$exclude string|array Files to exclude. yii\apidoc\components\BaseController
$guidePrefix string Prefix to prepend to all output file names generated for the guide. yii\apidoc\commands\GuideController
$pageTitle string Page title yii\apidoc\components\BaseController
$template string Template to use for rendering yii\apidoc\components\BaseController

Public Methods

Hide inherited methods

Method Description Defined By
actionIndex() Renders API documentation files yii\apidoc\commands\GuideController
options() yii\apidoc\commands\GuideController

Protected Methods

Hide inherited methods

Method Description Defined By
findFiles() Finds files yii\apidoc\commands\GuideController
findRenderer() yii\apidoc\commands\GuideController
loadContext() Loads context from cache yii\apidoc\components\BaseController
normalizeTargetDir() Checks that target directory is valid. Asks questions in tricky cases. yii\apidoc\components\BaseController
searchFiles() Finds files to process yii\apidoc\components\BaseController
storeContext() Writes context into cache file yii\apidoc\components\BaseController
updateContext() yii\apidoc\components\BaseController

Property Details

Hide inherited properties

$apiDocs public property

Path or URL to the api docs to allow links to classes and properties/methods.

public string $apiDocs = null
$guidePrefix public property

Prefix to prepend to all output file names generated for the guide.

public string $guidePrefix = 'guide-'

Method Details

Hide inherited methods

actionIndex() public method

Renders API documentation files

public integer actionIndex ( array $sourceDirs, $targetDir )
$sourceDirs array
$targetDir string
return integer

Status code.

 

                public function actionIndex(array $sourceDirs, $targetDir)
{
    $renderer = $this->findRenderer($this->template);
    $targetDir = $this->normalizeTargetDir($targetDir);
    if ($targetDir === false || $renderer === false) {
        return 1;
    }
    if ($this->pageTitle !== null) {
        $renderer->pageTitle = $this->pageTitle;
    }
    if ($renderer->guideUrl === null) {
        $renderer->guideUrl = './';
    }
    $renderer->guidePrefix = $this->guidePrefix;
    // setup reference to apidoc
    if ($this->apiDocs !== null) {
        $path = $this->apiDocs;
        if ($renderer->apiUrl === null) {
            $renderer->apiUrl = $path;
        }
        // use relative paths relative to targetDir
        if (strncmp($path, '.', 1) === 0) {
            $renderer->apiContext = $this->loadContext("$targetDir/$path");
        } else {
            $renderer->apiContext = $this->loadContext($path);
        }
    } elseif (file_exists($targetDir . '/cache/apidoc.data')) {
        if ($renderer->apiUrl === null) {
            $renderer->apiUrl = './';
        }
        $renderer->apiContext = $this->loadContext($targetDir);
    } else {
        $renderer->apiContext = new Context();
    }
    $this->updateContext($renderer->apiContext);
    // read blocktypes translations
    ApiMarkdown::$blockTranslations = [];
    foreach($sourceDirs as $dir) {
        if (is_file("$dir/blocktypes.json")) {
            ApiMarkdown::$blockTranslations = Json::decode(file_get_contents("$dir/blocktypes.json"), true);
        }
    }
    // search for files to process
    if (($files = $this->searchFiles($sourceDirs)) === false) {
        return 1;
    }
    $renderer->controller = $this;
    $renderer->render($files, $targetDir);
    $this->stdout('Publishing images...');
    foreach ($sourceDirs as $source) {
        $imageDir = rtrim($source, '/\\') . '/images';
        if (file_exists($imageDir)) {
            FileHelper::copyDirectory($imageDir, $targetDir . '/images');
        }
    }
    $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    return 0;
}
findFiles() protected method

Finds files

protected array findFiles ( $path, $except = [] )
$path
$except array

List of names to exclude from search.
return array

Files found.

 

                protected function findFiles($path, $except = [])
{
    $path = FileHelper::normalizePath($path);
    $options = [
        'only' => ['*.md'],
        'except' => $except,
    ];
    return FileHelper::findFiles($path, $options);
}
findRenderer() protected method

protected yii\apidoc\renderers\GuideRenderer findRenderer ( $template )
$template string 

                protected function findRenderer($template)
{
    // find renderer by class name
    if (class_exists($template)) {
        return new $template();
    }
    $rendererClass = 'yii\\apidoc\\templates\\' . $template . '\\GuideRenderer';
    if (!class_exists($rendererClass)) {
        $this->stderr('Renderer not found.' . PHP_EOL);
        return false;
    }
    return new $rendererClass();
}
loadContext() protected method

Defined in: yii\apidoc\components\BaseController::loadContext()

Loads context from cache

protected yii\apidoc\models\Context loadContext ( $location )
$location string 

                protected function loadContext($location)
{
    $context = new Context();
    $cacheFile = $location . '/cache/apidoc.data';
    $this->stdout('Loading apidoc data from cache... ');
    if (file_exists($cacheFile)) {
        $context = unserialize(file_get_contents($cacheFile));
        $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    } else {
        $this->stdout('no data available.' . PHP_EOL, Console::FG_YELLOW);
    }
    return $context;
}
normalizeTargetDir() protected method

Defined in: yii\apidoc\components\BaseController::normalizeTargetDir()

Checks that target directory is valid. Asks questions in tricky cases.

protected boolean|string normalizeTargetDir ( $target )
$target string 

                protected function normalizeTargetDir($target)
{
    $target = rtrim(Yii::getAlias($target), '\\/');
    if (file_exists($target)) {
        if (is_dir($target) && !$this->confirm('TargetDirectory already exists. Overwrite?', true)) {
            $this->stderr('User aborted.' . PHP_EOL);
            return false;
        }
        if (is_file($target)) {
            $this->stderr("Error: Target directory \"$target\" is a file!" . PHP_EOL);
            return false;
        }
    } else {
        mkdir($target, 0777, true);
    }
    return $target;
}
options() public method

public void options ( $actionID )
$actionID 

                public function options($actionID)
{
    return array_merge(parent::options($actionID), ['apiDocs', 'guidePrefix']);
}
searchFiles() protected method

Defined in: yii\apidoc\components\BaseController::searchFiles()

Finds files to process

protected array|boolean searchFiles ( $sourceDirs )
$sourceDirs array
return array|boolean

List of files to process or false on failure

 

                protected function searchFiles($sourceDirs)
{
    $this->stdout('Searching files to process... ');
    $files = [];
    if (is_array($this->exclude)) {
        $exclude = $this->exclude;
    } elseif (is_string($this->exclude)) {
        $exclude = explode(',', $this->exclude);
    } else {
        $exclude = [];
    }
    foreach ($sourceDirs as $source) {
        foreach ($this->findFiles($source, $exclude) as $fileName) {
            $files[$fileName] = $fileName;
        }
    }
    $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    if (empty($files)) {
        $this->stderr('Error: No files found to process.' . PHP_EOL);
        return false;
    }
    return $files;
}
storeContext() protected method

Defined in: yii\apidoc\components\BaseController::storeContext()

Writes context into cache file

protected void storeContext ( $context, $location )
$context yii\apidoc\models\Context
$location string 

                protected function storeContext($context, $location)
{
    $cacheFile = $location . '/cache/apidoc.data';
    if (!is_dir($dir = dirname($cacheFile))) {
        mkdir($dir, 0777, true);
    }
    file_put_contents($cacheFile, serialize($context));
}
updateContext() protected method

Defined in: yii\apidoc\components\BaseController::updateContext()

protected void updateContext ( $context )
$context yii\apidoc\models\Context 

                protected function updateContext($context)
{
    $this->stdout('Updating cross references and backlinks... ');
    $context->updateReferences();
    $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
}