From 136ede4b5210ff142fc61874182d8bf1e2025575 Mon Sep 17 00:00:00 2001 From: Justin Cherniak Date: Sat, 28 Oct 2017 20:37:53 -0700 Subject: [PATCH 1/3] Add new template for running yii2-apidoc on a user-submitted project, and instructions for use --- README.md | 12 +++++++ commands/ApiController.php | 8 ++++- renderers/BaseRenderer.php | 4 +++ templates/project/ApiRenderer.php | 53 +++++++++++++++++++++++++++++ templates/project/GuideRenderer.php | 23 +++++++++++++ 5 files changed, 99 insertions(+), 1 deletion(-) create mode 100644 templates/project/ApiRenderer.php create mode 100644 templates/project/GuideRenderer.php diff --git a/README.md b/README.md index 7dabc9ce..ab952802 100644 --- a/README.md +++ b/README.md @@ -112,6 +112,18 @@ Special Markdown Syntax We have a special Syntax for linking to classes in the API documentation. See the [code style guide](https://github.com/yiisoft/yii2/blob/master/docs/internals/core-code-style.md#markdown) for details. +Generating documentation for your own project +--------------------------------------------- + +To generate API documentation for your own project, use the "project" template and specify the README.md of your repository using the "readmeUrl" parameter + + apidoc api YOUR_REPO_PATH OUTPUT_PATH --exclude="vendor" --template="project" --readmeUrl="file://YOUR_REPO_PATH/README.md" --pageTitle="TITLE_OF_YOUR_DOCS" + +To also include links to the Yii2 documentation, you can do + + apidoc api "YOUR_REPO_PATH,vendor/yiisoft/yii2" OUTPUT_PATH --exclude="vendor" --template="project" --readmeUrl="file://YOUR_REPO_PATH/README.md" --pageTitle="TITLE_OF_YOUR_DOCS" + + Creating your own templates --------------------------- diff --git a/commands/ApiController.php b/commands/ApiController.php index a3d66f64..9c41e582 100644 --- a/commands/ApiController.php +++ b/commands/ApiController.php @@ -31,6 +31,11 @@ class ApiController extends BaseController */ public $guidePrefix = 'guide-'; + /** + * @var string URL for the README to use for the index of the guide. + */ + public $readmeUrl = "https://raw.github.com/yiisoft/yii2-framework/master/README.md"; + // TODO add force update option /** @@ -49,6 +54,7 @@ public function actionIndex(array $sourceDirs, $targetDir) $renderer->apiUrl = './'; $renderer->guidePrefix = $this->guidePrefix; + $renderer->readmeUrl = $this->readmeUrl; if ($this->pageTitle !== null) { $renderer->pageTitle = $this->pageTitle; @@ -177,6 +183,6 @@ protected function findRenderer($template) */ public function options($actionID) { - return array_merge(parent::options($actionID), ['guide', 'guidePrefix']); + return array_merge(parent::options($actionID), ['guide', 'guidePrefix', 'readmeUrl']); } } diff --git a/renderers/BaseRenderer.php b/renderers/BaseRenderer.php index c5a5a895..2a179102 100644 --- a/renderers/BaseRenderer.php +++ b/renderers/BaseRenderer.php @@ -52,6 +52,10 @@ abstract class BaseRenderer extends Component public $controller; public $guideUrl; + /** + * @var string URL for the README to use for the index of the guide. + */ + public $readmeUrl; public function init() { diff --git a/templates/project/ApiRenderer.php b/templates/project/ApiRenderer.php new file mode 100644 index 00000000..7b9be1a5 --- /dev/null +++ b/templates/project/ApiRenderer.php @@ -0,0 +1,53 @@ + + * @since 2.0 + */ +class ApiRenderer extends \yii\apidoc\templates\bootstrap\ApiRenderer +{ + use \yii\apidoc\templates\bootstrap\RendererTrait; + + public $layout = '@yii/apidoc/templates/bootstrap/layouts/api.php'; + public $indexView = '@yii/apidoc/templates/bootstrap/views/index.php'; + + /** + * @inheritdoc + */ + public function render($context, $targetDir) + { + // render view files + parent::render($context, $targetDir); + + if ($this->controller !== null) { + $this->controller->stdout('generating extension index files...'); + } + + $types = array_merge($context->classes, $context->interfaces, $context->traits); + + $appTypes = $this->filterTypes($types, 'app'); + + // It's a hack, but we'll go with it for now. + $readme = @file_get_contents($this->readmeUrl); + $indexFileContent = $this->renderWithLayout($this->indexView, [ + 'docContext' => $context, + 'types' => $appTypes ?: null, + 'readme' => $readme ?: null, + ]); + + file_put_contents($targetDir . '/index.html', $indexFileContent); + } +} diff --git a/templates/project/GuideRenderer.php b/templates/project/GuideRenderer.php new file mode 100644 index 00000000..016f425c --- /dev/null +++ b/templates/project/GuideRenderer.php @@ -0,0 +1,23 @@ + + * @since 2.0 + */ +class GuideRenderer extends \yii\apidoc\templates\bootstrap\GuideRenderer +{ + use \yii\apidoc\templates\bootstrap\RendererTrait; +} From 3e09f52910918e1bdf5fbf6d5f7727e0e9e948ff Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Thu, 22 Feb 2018 19:03:47 +0100 Subject: [PATCH 2/3] Update ApiController.php --- commands/ApiController.php | 1 + 1 file changed, 1 insertion(+) diff --git a/commands/ApiController.php b/commands/ApiController.php index 9c41e582..f8f937f5 100644 --- a/commands/ApiController.php +++ b/commands/ApiController.php @@ -33,6 +33,7 @@ class ApiController extends BaseController /** * @var string URL for the README to use for the index of the guide. + * @since 2.0.7 */ public $readmeUrl = "https://raw.github.com/yiisoft/yii2-framework/master/README.md"; From 7a2b2d71800f9612d4dd816f289220e351fec9fa Mon Sep 17 00:00:00 2001 From: Carsten Brandt Date: Thu, 22 Feb 2018 19:04:25 +0100 Subject: [PATCH 3/3] Update BaseRenderer.php --- renderers/BaseRenderer.php | 1 + 1 file changed, 1 insertion(+) diff --git a/renderers/BaseRenderer.php b/renderers/BaseRenderer.php index 2a179102..f40b23ed 100644 --- a/renderers/BaseRenderer.php +++ b/renderers/BaseRenderer.php @@ -54,6 +54,7 @@ abstract class BaseRenderer extends Component /** * @var string URL for the README to use for the index of the guide. + * @since 2.0.7 */ public $readmeUrl;