GuideController.php 3.69 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
    /**
     * @var string path or URL to the api docs to allow links to classes and properties/methods.
     */
    public $apiDocs;
30 31 32 33
    /**
     * @var string prefix to prepend to all output file names generated for the guide.
     */
    public $guidePrefix = 'guide-';
34

35

36 37
    /**
     * Renders API documentation files
38 39
     * @param array $sourceDirs
     * @param string $targetDir
40 41 42 43 44 45 46 47 48 49
     * @return int
     */
    public function actionIndex(array $sourceDirs, $targetDir)
    {
        $renderer = $this->findRenderer($this->template);
        $targetDir = $this->normalizeTargetDir($targetDir);
        if ($targetDir === false || $renderer === false) {
            return 1;
        }

50 51 52
        if ($renderer->guideUrl === null) {
            $renderer->guideUrl = './';
        }
53
        $renderer->guidePrefix = $this->guidePrefix;
54 55 56

        // setup reference to apidoc
        if ($this->apiDocs !== null) {
57
            $path = $this->apiDocs;
58 59 60
            if ($renderer->apiUrl === null) {
                $renderer->apiUrl = $path;
            }
61 62 63 64 65 66
            // use relative paths relative to targetDir
            if (strncmp($path, '.', 1) === 0) {
                $renderer->apiContext = $this->loadContext("$targetDir/$path");
            } else {
                $renderer->apiContext = $this->loadContext($path);
            }
67
        } elseif (file_exists($targetDir . '/cache/apidoc.data')) {
68 69 70
            if ($renderer->apiUrl === null) {
                $renderer->apiUrl = './';
            }
71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86
            $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) {
87 88 89 90
            $imageDir = rtrim($source, '/\\') . '/images';
            if (file_exists($imageDir)) {
                FileHelper::copyDirectory($imageDir, $targetDir . '/images');
            }
91 92 93 94
        }
        $this->stdout('done.' . PHP_EOL, Console::FG_GREEN);
    }

95

96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128
    /**
     * @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
     */
Alexander Makarov committed
129
    public function options($actionID)
130
    {
131
        return array_merge(parent::options($actionID), ['apiDocs', 'guidePrefix']);
132
    }
Luciano Baraglia committed
133
}