Skip to content

Commit

Permalink
Support subgroups in UI; simplify data passed to templates
Browse files Browse the repository at this point in the history
  • Loading branch information
@shalvah
shalvah committed Jul 9, 2022
1 parent b6b7fd2 commit 2ebf40b
Show file tree
Hide file tree
Showing 9 changed files with 162 additions and 108 deletions.
1 change: 1 addition & 0 deletions camel/Extraction/Metadata.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ class Metadata extends BaseDTO
{
public ?string $groupName;
public ?string $subgroup;
public ?string $subgroupDescription;

/**
* Name of the group that this group should be placed just before.
Expand Down
13 changes: 13 additions & 0 deletions camel/Output/OutputEndpointData.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@

use Illuminate\Http\UploadedFile;
use Illuminate\Routing\Route;
use Illuminate\Support\Str;
use Knuckles\Camel\BaseDTO;
use Knuckles\Camel\Extraction\Metadata;
use Knuckles\Camel\Extraction\ResponseCollection;
Expand Down Expand Up @@ -149,6 +150,18 @@ public function endpointId(): string
return $this->httpMethods[0] . str_replace(['/', '?', '{', '}', ':', '\\', '+', '|'], '-', $this->uri);
}

public function name(): string
{
return $this->metadata->title ?: ($this->httpMethods[0] . " " . $this->uri);
}

public function fullSlug(): string
{
$groupSlug = Str::slug($this->metadata->groupName);
$endpointId = $this->endpointId();
return "$groupSlug-$endpointId";
}

public function hasResponses(): bool
{
return count($this->responses) > 0;
Expand Down
7 changes: 7 additions & 0 deletions resources/css/theme-default.style.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -492,6 +492,9 @@ html {
white-space: nowrap;
text-overflow: ellipsis
}
.tocify-wrapper .tocify-item.level-3>a {
padding: 0 25px;
}

.tocify-wrapper li,
.tocify-wrapper ul {
Expand Down Expand Up @@ -532,6 +535,10 @@ html {
font-size: 12px
}

.tocify-wrapper .tocify-subheader .tocify-item.level-3>a {
padding-left: 35px;
}

.tocify-wrapper .tocify-subheader>li:last-child {
box-shadow: none
}
Expand Down
13 changes: 7 additions & 6 deletions resources/views/themes/default/endpoint.blade.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
/** @var Knuckles\Camel\Output\OutputEndpointData $endpoint */
@endphp

<h2 id="{!! Str::slug($group['name']) !!}-{!! $endpoint->endpointId() !!}">{{ $endpoint->metadata->title ?: ($endpoint->httpMethods[0]." ".$endpoint->uri)}}</h2>
<h2 id="{!! $endpoint->fullSlug() !!}">{{ $endpoint->name() }}</h2>

<p>
@component('scribe::components.badges.auth', ['authenticated' => $endpoint->metadata->authenticated])
Expand Down Expand Up @@ -97,11 +97,12 @@
@if($endpoint->metadata->authenticated && $metadata['auth']['location'] === 'header')
<p>
<label id="auth-{{ $endpoint->endpointId() }}" hidden>{{ $metadata['auth']['name'] }} header:
<b><code>{{ $metadata['auth']['prefix'] }}</code></b><input type="text"
name="{{ $metadata['auth']['name'] }}"
data-prefix="{{ $metadata['auth']['prefix'] }}"
data-endpoint="{{ $endpoint->endpointId() }}"
data-component="header"></label>
<b><code>{{ $metadata['auth']['prefix'] }}</code></b>
<input type="text"
name="{{ $metadata['auth']['name'] }}"
data-prefix="{{ $metadata['auth']['prefix'] }}"
data-endpoint="{{ $endpoint->endpointId() }}"
data-component="header"></label>
</p>
@endif
@if(count($endpoint->urlParameters))
Expand Down
15 changes: 13 additions & 2 deletions resources/views/themes/default/groups.blade.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,19 @@

{!! Parsedown::instance()->text($group['description']) !!}

@foreach($group['endpoints'] as $endpoint)
@include("scribe::themes.default.endpoint")
@foreach($group['subgroups'] as $subgroupName => $subgroup)
@if($subgroupName !== "")
<h2 id="{!! Str::slug($group['name']) !!}-{!! Str::slug($subgroupName) !!}">{{ $subgroupName }}</h2>
@php($subgroupDescription = collect($subgroup)->first(fn ($e) => $e->metadata->subgroupDescription)?->metadata?->subgroupDescription)
@if($subgroupDescription)
<p>
{!! Parsedown::instance()->text($subgroupDescription) !!}
</p>
@endif
@endif
@foreach($subgroup as $endpoint)
@include("scribe::themes.default.endpoint")
@endforeach
@endforeach
@endforeach

110 changes: 20 additions & 90 deletions resources/views/themes/default/sidebar.blade.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -23,101 +23,31 @@
</div>

<div id="toc">
@php
$previousH1 = null;
$inSubHeading = false;
$headingsCount = 0;
@endphp
@foreach($headingsBeforeEndpoints as $heading)
@if($heading['level'] === 1)
@if($previousH1)
</ul>
@endif
@if($inSubHeading)
@php($inSubHeading = false)
</ul>
@endif
<ul id="tocify-header-{{ $headingsCount }}" class="tocify-header">
<li class="tocify-item level-1" data-unique="{!! $heading['slug'] !!}">
<a href="#{!! $heading['slug'] !!}">{!! $heading['text'] !!}</a>
</li>
@php($previousH1 = $heading)
@php($headingsCount += 1)
@elseif ($heading['level'] === 2 && $previousH1)
@if(!$inSubHeading)
<ul id="tocify-subheader-{!! $previousH1['slug'] !!}" class="tocify-subheader">
@php($inSubHeading = true)
@endif
<li class="tocify-item level-2"
data-unique="{!! $previousH1['slug'] !!}-{!! $heading['slug'] !!}">
<a href="#{!! $heading['slug'] !!}">{{ $heading['text'] }}</a>
</li>
@endif

@if($loop->last)
@if($inSubHeading)
</ul>
@endif
</ul>
@endif
@endforeach

@foreach($groupedEndpoints as $group)
<ul id="tocify-header-{{ $loop->index + $headingsCount }}" class="tocify-header">
<li class="tocify-item level-1" data-unique="{!! Str::slug($group['name']) !!}">
<a href="#{!! Str::slug($group['name']) !!}">{!! $group['name'] !!}</a>
@foreach($headings as $h1)
<ul id="tocify-header-{{ $h1['slug'] }}" class="tocify-header">
<li class="tocify-item level-1" data-unique="{!! $h1['slug'] !!}">
<a href="#{!! $h1['slug'] !!}">{!! $h1['name'] !!}</a>
</li>
@if (count($group['endpoints']) > 0)
<ul id="tocify-subheader-{!! Str::slug($group['name']) !!}" class="tocify-subheader">
@endif
@foreach($group['endpoints'] as $endpoint)
<li class="tocify-item level-2" data-unique="{!! Str::slug($group['name']) !!}-{!! $endpoint->endpointId() !!}">
<a href="#{!! Str::slug($group['name']) !!}-{!! $endpoint->endpointId() !!}">{{ $endpoint->metadata->title ?: ($endpoint->httpMethods[0]." ".$endpoint->uri)}}</a>
</li>
@endforeach
@if (count($group['endpoints']) > 0)
@if(count($h1['subheadings']) > 0)
<ul id="tocify-subheader-{!! $h1['slug'] !!}" class="tocify-subheader">
@foreach($h1['subheadings'] as $h2)
<li class="tocify-item level-2" data-unique="{!! $h2['slug'] !!}">
<a href="#{!! $h2['slug'] !!}">{!! $h2['name'] !!}</a>
</li>
@if(count($h2['subheadings']) > 0)
<ul id="tocify-subheader-{!! $h2['slug'] !!}" class="tocify-subheader">
@foreach($h2['subheadings'] as $h3)
<li class="tocify-item level-3" data-unique="{!! $h3['slug'] !!}">
<a href="#{!! $h3['slug'] !!}">{!! $h3['name'] !!}</a>
</li>
@endforeach
</ul>
@endif
@endforeach
</ul>
@endif
</ul>
@endforeach

@php($previousH1 = null)
@php($inSubHeading = false)
@php($headingsCount += count($groupedEndpoints))

@foreach($headingsAfterEndpoints as $heading)
@if($heading['level'] === 1)
@if($previousH1)
</ul>
@endif
@if($inSubHeading)
@php($inSubHeading = false)
</ul>
@endif
<ul id="tocify-header-{{ $headingsCount }}" class="tocify-header">
<li class="tocify-item level-1" data-unique="{!! $heading['slug'] !!}">
<a href="#{!! $heading['slug'] !!}">{!! $heading['text'] !!}</a>
</li>
@php($previousH1 = $heading)
@php($headingsCount += 1)
@elseif ($heading['level'] === 2 && $previousH1)
@if(!$inSubHeading)
<ul id="tocify-subheader-{!! $previousH1['slug'] !!}" class="tocify-subheader">
@php($inSubHeading = true)
@endif
<li class="tocify-item level-2"
data-unique="{!! $previousH1['slug'] !!}-{!! $heading['slug'] !!}">
<a href="#{!! $heading['slug'] !!}">{{ $heading['text'] }}</a>
</li>
@endif

@if($loop->last)
@if($inSubHeading)
</ul>
@endif
</ul>
@endif
@endforeach
</div>

@if(isset($metadata['links']))
Expand Down
22 changes: 20 additions & 2 deletions src/Extracting/Strategies/Metadata/GetFromDocBlocks.php
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ public function getMetadataFromDocBlock(DocBlock $methodDocBlock, DocBlock $clas
'groupName' => $routeGroupName,
'groupDescription' => $routeGroupDescription,
'subgroup' => $this->getEndpointSubGroup($methodDocBlock, $classDocBlock),
'subgroupDescription' => $this->getEndpointSubGroupDescription($methodDocBlock, $classDocBlock),
'title' => $routeTitle ?: $methodDocBlock->getShortDescription(),
'description' => $methodDocBlock->getLongDescription()->getContents(),
'authenticated' => $this->getAuthStatusFromDocBlock($methodDocBlock, $classDocBlock),
Expand Down Expand Up @@ -101,13 +102,30 @@ protected function getEndpointGroupDetails(DocBlock $methodDocBlock, DocBlock $c
protected function getEndpointSubGroup(DocBlock $methodDocBlock, DocBlock $controllerDocBlock): ?string
{
foreach ($methodDocBlock->getTags() as $tag) {
if ($tag->getName() === 'subgroup') {
if (strtolower($tag->getName()) === 'subgroup') {
return trim($tag->getContent());
}
}

foreach ($controllerDocBlock->getTags() as $tag) {
if ($tag->getName() === 'subgroup') {
if (strtolower($tag->getName()) === 'subgroup') {
return trim($tag->getContent());
}
}

return null;
}

protected function getEndpointSubGroupDescription(DocBlock $methodDocBlock, DocBlock $controllerDocBlock): ?string
{
foreach ($methodDocBlock->getTags() as $tag) {
if (strtolower($tag->getName()) === 'subgroupdescription') {
return trim($tag->getContent());
}
}

foreach ($controllerDocBlock->getTags() as $tag) {
if (strtolower($tag->getName()) === 'subgroupdescription') {
return trim($tag->getContent());
}
}
Expand Down
Loading

0 comments on commit 2ebf40b

Please sign in to comment.