Skip to content
This repository has been archived by the owner on Nov 5, 2018. It is now read-only.

Commit

Permalink
More updates
Browse files Browse the repository at this point in the history
  • Loading branch information
@mtdowling
mtdowling committed Apr 21, 2015
1 parent 31d76c5 commit dcde8cc
Show file tree
Hide file tree
Showing 3 changed files with 188 additions and 106 deletions.
144 changes: 77 additions & 67 deletions build/docs/classes/DocsBuilder.php
View file
Expand Up @@ -140,73 +140,6 @@ private function createHtmlForToc(Service $service, array $operations)
return $html;
}

private function createHtmlForOperation(Service $service, $name, Operation $operation)
{
$html = new HtmlDocument;

// Name
$html->section(3, $html->glyph('cog') . ' ' . $name, null, 'method-title');

// Code
$html->elem('pre', 'opcode', '$result = $client-&gt;<code>' . lcfirst($name) . '</code>([...]);');

// Description
if ($description = $service->docs->getOperationDocs($name)) {
$html->elem('div', 'well', $description);
}

// Parameters
$inputShapes = new ShapeIterator($operation->getInput(), $service->docs);
$inputExample = new ExampleBuilder($name);
$inputDocs = new ThemeBuilder($name);
foreach ($inputShapes as $shape) {
$inputExample->addShape($shape);
$inputDocs->addShape($shape);
}
$html->section(3, 'Parameters', $name)
->elem('h5', null, 'Formatting Example')
->elem('pre', null, htmlentities($inputExample->getCode()))
->elem('h5', null, 'Parameter Details')
->open('ul')->append($inputDocs->getHtml())->close()
->close();

// Results
$html->section(3, 'Results', $name);
if (count($operation->getOutput()->getMembers())) {
$outputShapes = new ShapeIterator($operation->getOutput(), $service->docs);
$outputExample = new ExampleBuilder($name, false);
$outputDocs = new ThemeBuilder($name, false);
foreach ($outputShapes as $shape) {
$outputExample->addShape($shape);
$outputDocs->addShape($shape);
}
$html->elem('h5', null, 'Formatting Example')
->elem('pre', null, htmlentities($outputExample->getCode()))
->elem('h5', null, 'Results Details')
->open('ul')->append($outputDocs->getHtml())->close();
} else {
$html->elem('div', 'alert alert-info', 'The results for this operation are always empty.');
}
$html->close();

// Errors
$html->section(3, 'Errors', $name);
if ($errors = $operation->getErrors()) {
foreach ($errors as $error) {
$html->open('div', 'panel panel-default')
->open('div', 'panel-heading')->elem('h5', 'panel-title', $error['name'])->close()
->elem('div', 'panel-body', $service->docs->getErrorDocs($error->getName())
?: 'This error does not currently have a description.')
->close();
}
} else {
$html->elem('p', null, 'There are no errors described for this operation.');
}
$html->close();

return $html->close();
}

private function writeThemeFile($name, $contents)
{
$name = str_replace('.html', '', $name);
Expand Down Expand Up @@ -340,4 +273,81 @@ private function createHtmlForPaginators(HtmlDocument $html, Api $service)
$html->close();
$html->close(); // Opening section
}

private function createHtmlForOperation(Service $service, $name, Operation $operation)
{
$html = new HtmlDocument;

// Name
$html->section(3, $html->glyph('cog') . ' ' . $name, null, 'method-title');

// Code
$html->elem('pre', 'opcode', '$result = $client-&gt;<code>' . lcfirst($name) . '</code>([...]);');

// Description
if ($description = $service->docs->getOperationDocs($name)) {
$html->elem('div', 'operation-docs', $description);
}

// Parameters
$inputShapes = new ShapeIterator($operation->getInput(), $service->docs);
$inputExample = new ExampleBuilder($name);
$inputDocs = new ParameterHtmlBuilder($name);
foreach ($inputShapes as $shape) {
$inputExample->addShape($shape);
$inputDocs->addShape($shape);
}
$html
->section(4, 'Parameters', $name)
->elem('h5', null, 'Formatting Example')
->elem('pre', null, htmlentities($inputExample->getCode()))
->elem('h5', null, 'Parameter Details')
->open('div', 'tree param-tree')
->open('ul', 'complex-shape')
->append($inputDocs->getHtml())
->close()
->close()
->close();

// Results
$html->section(4, 'Results', $name);
if (!count($operation->getOutput()->getMembers())) {
$html->elem('div', 'alert alert-info', 'The results for this operation are always empty.');
} else {
$outputShapes = new ShapeIterator($operation->getOutput(), $service->docs);
$outputExample = new ExampleBuilder($name, false);
$outputDocs = new ParameterHtmlBuilder($name, false);
foreach ($outputShapes as $shape) {
$outputExample->addShape($shape);
$outputDocs->addShape($shape);
}
$html
->elem('h5', null, 'Formatting Example')
->elem('pre', null, htmlentities($outputExample->getCode()))
->elem('h5', null, 'Results Details')
->open('div', 'tree param-tree')
->open('ul', 'complex-shape')
->append($outputDocs->getHtml())
->close()
->close();
}
$html->close();

// Errors
$html->section(4, 'Errors', $name);
if ($errors = $operation->getErrors()) {
foreach ($errors as $error) {
$html->open('div', 'panel panel-default')
->open('div', 'panel-heading')->elem('h5', 'panel-title', $error['name'])->close()
->elem('div', 'panel-body', $service->docs->getErrorDocs($error->getName())
?: 'This error does not currently have a description.')
->close();
}
} else {
$html->elem('p', null, 'There are no errors described for this operation.');
}
$html->close();

return $html->close();
}
}
77 changes: 45 additions & 32 deletions build/docs/classes/ThemeBuilder.php → build/docs/classes/ParameterHtmlBuilder.php
View file
Expand Up @@ -2,9 +2,9 @@
namespace Aws\Build\Docs;

/**
* Builds HTML for operations.
* Builds HTML for operation input and output parameters.
*/
class ThemeBuilder
class ParameterHtmlBuilder
{
private $html;
private $operation;
Expand All @@ -31,53 +31,45 @@ public function addShape(array $shape)
$this->skipLevel--;
return;
} elseif ($shape['name'] === 'closer') {
$this->html->close();
$this->html->close();
$this->html->close();
return;
}

// Write the parameter key.
$this->html->open('li', 'parameter');
$this->html->open('div', $shape['complex'] ? 'notlast' : 'last');

$key = htmlentities($shape['param'] . ' => ' . $this->getTypeLabel($shape));
$this->html->open('h4', ['id' => $this->getPathAnchor($shape['path'])])
->elem('span', 'param-title', $key);
$this->html->open('div', ['class' => 'param-name', 'id' => $this->getPathAnchor($shape['path'])]);
$this->html->elem('span', 'param-title', $key);
if ($this->isInput && $shape['required']) {
$this->html->elem('span', 'required label label-danger', 'required');
}
$this->html->close(true);

if (is_array($shape['enum'])) {
$message = $this->getEnumConstraint($shape);
$this->html->elem('div', 'alert alert-info', "<b>Constraint:</b> {$message}");
}

if ($shape['min'] || $shape['max']) {
$message = $this->addMinMaxConstraint($shape);
$this->html->elem('div', 'alert alert-info', "<b>Constraint:</b> {$message}");
}
$this->addConstraintHtml($shape);

if ($shape['docs']) {
$this->html->elem('div', 'well', $shape['docs']);
$this->html->elem('div', 'param-docs', $shape['docs']);
}

// Write the parameter value.
if ($shape['complex']) {
if ($shape['recursive']) {
$path = implode('.', $shape['recursive']);
$this->html->elem('div', 'alert alert-warning', '<strong>This '
. 'is a recursive parameter.</strong> Click <a href="#'
. $this->getPathAnchor($path) . '">here</a> to jump back to'
. ' <code>' . htmlentities($path) . '</code>.');
$this->html->close();
} elseif (!in_array($shape['complex'], ['structure', 'list', 'map', 'mixed'])) {
$this->skipLevel += 2;
$this->html->close();
} else {
$this->html->open('ul');
}
} else {
if (!$shape['complex']) {
$this->html->close();
} elseif ($shape['recursive']) {
$path = implode('.', $shape['recursive']);
$this->html->elem('div', 'alert alert-warning', '<strong>This '
. 'is a recursive parameter.</strong> Click <a href="#'
. $this->getPathAnchor($path) . '">here</a> to jump back to'
. ' <code>' . htmlentities($path) . '</code>.');
$this->html->close();
} elseif (!in_array($shape['complex'], ['structure', 'list', 'map', 'mixed'])) {
$this->skipLevel += 2;
$this->html->close();
} else {
$this->html->open('ul', 'complex-shape');
}
}

Expand Down Expand Up @@ -137,12 +129,12 @@ private function getTypeLabel($shape)

switch ($shape['type']) {
case 'structure':
return ($shape['complex']) ? 'array<string,mixed>' : 'array';
return ($shape['complex']) ? 'array<string, mixed>' : 'array';
case 'map':
$type = 'array';
if ($subType = $shape['complex']) {
$subType = $this->getTypeLabel($subType);
$type .= "<string,{$subType}>";
$type .= "<string, {$subType}>";
}
return $type;
case 'list':
Expand All @@ -155,9 +147,30 @@ private function getTypeLabel($shape)
case 'timestamp':
return 'string|int|\\DateTime';
case 'stream':
return 'GuzzleHttp\\Stream\\Stream';
return 'Psr\\Http\\Message\\StreamInterface';
default:
return $shape['type'];
}
}

private function addConstraintHtml($shape)
{
$constraints = [];
if (is_array($shape['enum'])) {
$constraints[] = $this->getEnumConstraint($shape);
}

if ($shape['min'] || $shape['max']) {
$constraints[] = $this->addMinMaxConstraint($shape);
}

if ($constraints) {
$constraintHtml = '<ul>';
foreach ($constraints as $c) {
$constraintHtml .= '<li>' . $c . '</li>';
}
$constraintHtml .= '</ul>';
$this->html->elem('div', 'param-constraints', $constraintHtml);
}
}
}

0 comments on commit dcde8cc

Please sign in to comment.