GuideController.php 3.23 KB
Newer Older
1 2
<?php
/**
3 4 5
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
6 7 8 9
 */

namespace yii\apidoc\commands;

10
use yii\apidoc\components\BaseController;
11 12 13 14 15 16 17 18 19 20
use yii\apidoc\models\Context;
use yii\apidoc\renderers\GuideRenderer;
use yii\helpers\Console;
use yii\helpers\FileHelper;
use Yii;

/**
 * This command can render documentation stored as markdown files such as the yii guide
 * or your own applications documentation setup.
 *
21 22
 * @author Carsten Brandt <mail@cebe.cc>
 * @since 2.0
23 24 25
 */
class GuideController extends BaseController
{
26 27 28 29 30 31 32
    /**
     * @var string path or URL to the api docs to allow links to classes and properties/methods.
     */
    public $apiDocs;

    /**
     * Renders API documentation files
33 34
     * @param array $sourceDirs
     * @param string $targetDir
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80
     * @return int
     */
    public function actionIndex(array $sourceDirs, $targetDir)
    {
        $renderer = $this->findRenderer($this->template);
        $targetDir = $this->normalizeTargetDir($targetDir);
        if ($targetDir === false || $renderer === false) {
            return 1;
        }

        $renderer->guideUrl = './';

        // setup reference to apidoc
        if ($this->apiDocs !== null) {
            $renderer->apiUrl = $this->apiDocs;
            $renderer->apiContext = $this->loadContext($this->apiDocs);
        } elseif (file_exists($targetDir . '/cache/apidoc.data')) {
            $renderer->apiUrl = './';
            $renderer->apiContext = $this->loadContext($targetDir);
        } else {
            $renderer->apiContext = new Context();
        }
        $this->updateContext($renderer->apiContext);

        // 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) {
            FileHelper::copyDirectory(rtrim($source, '/\\') . '/images', $targetDir . '/images');
        }
        $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);

        // generate api references.txt
        $references = [];
        foreach ($files as $file) {
            $references[] = basename($file, '.md');
        }
        file_put_contents($targetDir . '/guide-references.txt', implode("\n", $references));
    }

81

82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114
    /**
     * @inheritdoc
     */
    protected function findFiles($path, $except = [])
    {
        $path = FileHelper::normalizePath($path);
        $options = [
            'only' => ['*.md'],
            'except' => $except,
        ];

        return FileHelper::findFiles($path, $options);
    }

    /**
     * @inheritdoc
     * @return GuideRenderer
     */
    protected function findRenderer($template)
    {
        $rendererClass = 'yii\\apidoc\\templates\\' . $template . '\\GuideRenderer';
        if (!class_exists($rendererClass)) {
            $this->stderr('Renderer not found.' . PHP_EOL);

            return false;
        }

        return new $rendererClass();
    }

    /**
     * @inheritdoc
     */
115
    public function options($actionId)
116
    {
117
        return array_merge(parent::options($actionId), ['apiDocs']);
118
    }
Luciano Baraglia committed
119
}