Class yii\apidoc\commands\ApiController
| Inheritance | yii\apidoc\commands\ApiController » yii\apidoc\components\BaseController » yii\console\Controller |
|---|---|
| Available since extension's version | 2.0 |
| Source Code | https://github.com/yiisoft/yii2-apidoc/blob/master/commands/ApiController.php |
Generate class API documentation.
Public Properties
| Property | Type | Description | Defined By |
|---|---|---|---|
| $exclude | string|array|null | Files to exclude. | yii\apidoc\components\BaseController |
| $guide | string | Url to where the guide files are located | yii\apidoc\commands\ApiController |
| $guidePrefix | string | Prefix to prepend to all guide file names. | yii\apidoc\commands\ApiController |
| $pageTitle | string|null | yii\apidoc\components\BaseController | |
| $readmeUrl | string | URL for the README to use for the index of the guide. | yii\apidoc\commands\ApiController |
| $repoUrl | string|null | Repository url (e.g. "https://github.com/yiisoft/yii2"). | yii\apidoc\commands\ApiController |
| $template | string | Template to use for rendering | yii\apidoc\components\BaseController |
Public Methods
| Method | Description | Defined By |
|---|---|---|
| actionIndex() | Renders API documentation files | yii\apidoc\commands\ApiController |
| options() | yii\apidoc\commands\ApiController |
Protected Methods
| Method | Description | Defined By |
|---|---|---|
| findFiles() | Finds files | yii\apidoc\commands\ApiController |
| findRenderer() | yii\apidoc\commands\ApiController | |
| 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
Prefix to prepend to all guide file names.
URL for the README to use for the index of the guide.
Repository url (e.g. "https://github.com/yiisoft/yii2"). Optional, used for resolving relative links within a repository (e.g. "docs/guide/README.md"). If you don't have such links you can skip this. Otherwise, skipping this will cause generation of broken links because they will be not resolved and left as is.
Method Details
Renders API documentation files
| public integer actionIndex ( array $sourceDirs, string $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;
}
$renderer->apiUrl = './';
$renderer->guidePrefix = $this->guidePrefix;
$renderer->readmeUrl = $this->readmeUrl;
if ($this->pageTitle !== null) {
$renderer->pageTitle = $this->pageTitle;
}
// setup reference to guide
if ($this->guide !== null) {
$renderer->guideUrl = $guideUrl = $this->guide;
} else {
$guideUrl = './';
$renderer->guideUrl = $targetDir;
if (file_exists($renderer->generateGuideUrl('README.md'))) {
$renderer->guideUrl = $guideUrl;
} else {
$renderer->guideUrl = null;
}
}
$renderer->repoUrl = $this->repoUrl !== null ? rtrim($this->repoUrl, '/') : null;
// search for files to process
if (($files = $this->searchFiles($sourceDirs)) === false) {
return 1;
}
// load context from cache
$context = $this->loadContext($targetDir);
$this->stdout('Checking for updated files... ');
foreach ($context->files as $file => $sha) {
if (!file_exists($file)) {
$this->stdout('At least one file has been removed. Rebuilding the context...');
$context = new Context();
if (($files = $this->searchFiles($sourceDirs)) === false) {
return 1;
}
break;
}
if (sha1_file($file) === $sha) {
unset($files[$file]);
}
}
$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
// process files
$fileCount = count($files);
$this->stdout($fileCount . ' file' . ($fileCount == 1 ? '' : 's') . ' to update.' . PHP_EOL);
Console::startProgress(0, $fileCount, 'Processing files... ', false);
$done = 0;
foreach ($files as $file) {
try {
$context->addFile($file);
} catch (\Exception $e) {
$context->errors[] = "Unable to process \"$file\": " . $e->getMessage();
}
Console::updateProgress(++$done, $fileCount);
}
$context->processFiles();
Console::endProgress(true);
$this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
// save processed data to cache
$this->storeContext($context, $targetDir);
$this->updateContext($context);
// render models
$renderer->controller = $this;
$renderer->render($context, $targetDir);
if (!empty($context->errors)) {
$errors = array_map(unserialize(...), array_unique(array_map(serialize(...), $context->errors)));
ArrayHelper::multisort($errors, 'file');
file_put_contents($targetDir . '/errors.txt', print_r($errors, true));
$this->stdout(count($errors) . " errors have been logged to $targetDir/errors.txt\n", Console::FG_RED, Console::BOLD);
}
if (!empty($context->warnings)) {
$warnings = array_map(unserialize(...), array_unique(array_map(serialize(...), $context->warnings)));
ArrayHelper::multisort($warnings, 'file');
file_put_contents($targetDir . '/warnings.txt', print_r($warnings, true));
$this->stdout(count($warnings) . " warnings have been logged to $targetDir/warnings.txt\n", Console::FG_YELLOW, Console::BOLD);
}
return 0;
}
Finds files
| protected array findFiles ( mixed $path, mixed $except = [] ) | ||
| $path | mixed | |
| $except | mixed |
List of names to exclude from search. |
| return | array |
Files found. |
|---|---|---|
protected function findFiles($path, $except = [])
{
if (empty($except)) {
$except = ['vendor/', 'tests/'];
}
$path = FileHelper::normalizePath($path);
$options = [
'filter' => function ($path) {
if (is_file($path)) {
$file = basename((string) $path);
if ($file[0] < 'A' || $file[0] > 'Z') {
return false;
}
}
return null;
},
'only' => ['*.php'],
'except' => $except,
];
return FileHelper::findFiles($path, $options);
}
| protected yii\apidoc\renderers\ApiRenderer|false findRenderer ( mixed $template ) | ||
| $template | mixed | |
protected function findRenderer($template)
{
// find renderer by class name
if (class_exists($template)) {
return new $template();
}
$rendererClass = 'yii\\apidoc\\templates\\' . $template . '\\ApiRenderer';
if (!class_exists($rendererClass)) {
$this->stderr('Renderer not found.' . PHP_EOL);
return false;
}
return new $rendererClass();
}
Defined in: yii\apidoc\components\BaseController::loadContext()
Loads context from cache
| protected yii\apidoc\models\Context loadContext ( string $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;
}
Defined in: yii\apidoc\components\BaseController::normalizeTargetDir()
Checks that target directory is valid. Asks questions in tricky cases.
| protected boolean|string normalizeTargetDir ( string $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;
}
| public options ( mixed $actionID ) | ||
| $actionID | mixed | |
public function options($actionID)
{
return array_merge(parent::options($actionID), ['guide', 'guidePrefix', 'readmeUrl', 'repoUrl']);
}
Defined in: yii\apidoc\components\BaseController::searchFiles()
Finds files to process
| protected array|false searchFiles ( array $sourceDirs ) | ||
| $sourceDirs | array | |
| return | array|false |
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;
}
Defined in: yii\apidoc\components\BaseController::storeContext()
Writes context into cache file
| protected mixed storeContext ( yii\apidoc\models\Context $context, string $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));
}
| protected mixed updateContext ( yii\apidoc\models\Context $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);
}