Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add new template for running yii2-apidoc on a user-submitted project #151

Open
wants to merge 4 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -240,6 +240,18 @@ Special Markdown Syntax
We have a special Syntax for linking to a class 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
---------------------------

Expand Down
9 changes: 8 additions & 1 deletion commands/ApiController.php
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,12 @@ class ApiController extends BaseController
*/
public $repoUrl;

/**
* @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";
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why URL instead of local file path?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That URL was hard-coded in the bootstrap template which I copied. For it to work without changing the command line params, it has to match the value that was in the previous template.



// TODO add force update option
/**
Expand All @@ -56,6 +62,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;
Expand Down Expand Up @@ -195,6 +202,6 @@ protected function findRenderer($template)
*/
public function options($actionID)
{
return array_merge(parent::options($actionID), ['guide', 'guidePrefix', 'repoUrl']);
return array_merge(parent::options($actionID), ['guide', 'guidePrefix', 'readmeUrl', 'repoUrl']);
}
}
7 changes: 6 additions & 1 deletion renderers/BaseRenderer.php
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,12 @@ abstract class BaseRenderer extends Component
public $controller;
public $guideUrl;

/**
* @var string URL for the README to use for the index of the guide.
* @since 2.0.7
*/
public $readmeUrl;

/**
* @var string[]
*/
Expand Down Expand Up @@ -87,7 +93,6 @@ abstract class BaseRenderer extends Component
'int' => 'integer',
];


public function init()
{
ApiMarkdown::$renderer = $this;
Expand Down
53 changes: 53 additions & 0 deletions templates/project/ApiRenderer.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/

namespace yii\apidoc\templates\project;

use Yii;
use yii\apidoc\helpers\ApiIndexer;
use yii\helpers\Console;
use yii\helpers\FileHelper;

/**
*
* @author Carsten Brandt <[email protected]>
* @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);
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Silencing errors isn't good.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose I could throw an exception here. Would that be preferred?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just for the record, Bootstrap template silences errors, too:

$readme = @file_get_contents("https://raw.github.com/yiisoft/yii2-framework/master/README.md");

$indexFileContent = $this->renderWithLayout($this->indexView, [
'docContext' => $context,
'types' => $appTypes ?: null,
'readme' => $readme ?: null,
]);

file_put_contents($targetDir . '/index.html', $indexFileContent);
}
}
23 changes: 23 additions & 0 deletions templates/project/GuideRenderer.php
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
<?php
/**
* @link http://www.yiiframework.com/
* @copyright Copyright (c) 2008 Yii Software LLC
* @license http://www.yiiframework.com/license/
*/

namespace yii\apidoc\templates\project;

use Yii;
use yii\apidoc\helpers\ApiIndexer;
use yii\helpers\Console;
use yii\helpers\FileHelper;

/**
*
* @author Carsten Brandt <[email protected]>
* @since 2.0
*/
class GuideRenderer extends \yii\apidoc\templates\bootstrap\GuideRenderer
{
use \yii\apidoc\templates\bootstrap\RendererTrait;
}
Loading