Skip to content

Commit f9aa867

Browse files
williamdeswilliamdes
committed
feat: implement a custom footer link
Ref: silverstripe/api.silverstripe.org#65
1 parent 64983cd commit f9aa867

File tree

7 files changed

+152
-6
lines changed

7 files changed

+152
-6
lines changed

‎CHANGELOG.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1313
- Fixed: "Error: The ProgressBar is not started" (#19)
1414
- Fixed: ""3" @param tags are expected but only "4" found" (#21)
1515
- Reworked the `@param` tag error detection and added new error messages
16-
- Added: A shebang to all the new PHARs distributed.
16+
- Added: A shebang to all the new PHARs distributed
17+
- Added: Support for a custom `footer_link` configuration
1718

1819
## [5.2.1] - 2020-11-30
1920

‎README.rst‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,40 @@ And here is how you can configure different versions:
143143
'default_opened_level' => 2,
144144
]);
145145
146+
147+
And here is how you can configure a footer link below the Doctum link:
148+
149+
All `footer_link` keys are optional.
150+
151+
.. code-block:: php
152+
153+
<?php
154+
155+
use Doctum\Doctum;
156+
use Symfony\Component\Finder\Finder;
157+
158+
$dir = '/path/to/yourlib/src';
159+
$iterator = Finder::create()
160+
->files()
161+
->name('*.php')
162+
->exclude('Resources')
163+
->exclude('Tests')
164+
->in($dir);
165+
166+
return new Doctum($iterator, [
167+
'title' => 'yourlib API',
168+
'source_dir' => dirname($dir) . '/',
169+
'remote_repository' => new GitHubRemoteRepository('yourorg/yourlib', dirname($dir)),
170+
'footer_link' => [
171+
'href' => 'https://github.com/code-lts/doctum',
172+
'rel' => 'noreferrer noopener',
173+
'target' => '_blank',
174+
'before_text' => 'You can edit the configuration',
175+
'link_text' => 'on this', // Required if the href key is set
176+
'after_text' => 'repository',
177+
],
178+
]);
179+
146180
You can find more configuration examples under the ``examples/`` directory of
147181
the source code.
148182

‎src/Doctum.php‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,11 @@ class Doctum implements ArrayAccess
188188
/** @var AbstractRemoteRepository|null */
189189
private $remote_repository = null;
190190

191+
/**
192+
* @var array<string,string>|null
193+
*/
194+
private $footer_link = null;
195+
191196
/**
192197
* include parent properties and methods on class pages
193198
*
@@ -376,6 +381,7 @@ private function getBuiltProject(): Project
376381
'title' => $this->title,
377382
'source_url' => $this->source_url,
378383
'insert_todos' => $this->insert_todos,
384+
'footer_link' => $this->footer_link,
379385
'sort_class_properties' => $this->sort_class_properties,
380386
'sort_class_methods' => $this->sort_class_methods,
381387
'sort_class_constants' => $this->sort_class_constants,

‎src/Project.php‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -520,4 +520,26 @@ public function getViewSourceUrl($relativePath, $line)
520520

521521
return '';
522522
}
523+
524+
public function hasFooterLink(): bool
525+
{
526+
return $this->getConfig('footer_link') !== null && is_array($this->getConfig('footer_link'));
527+
}
528+
529+
/**
530+
* @return array<string,string>
531+
* @phpstan-return array{href: string, rel: string, target: string, before_text: string, link_text: string, after_text: string}
532+
*/
533+
public function getFooterLink(): array
534+
{
535+
$link = $this->getConfig('footer_link');
536+
return [
537+
'href' => $link['href'] ?? '',
538+
'target' => $link['target'] ?? '',
539+
'rel' => $link['rel'] ?? '',
540+
'before_text' => $link['before_text'] ?? '',
541+
'link_text' => $link['link_text'] ?? '',
542+
'after_text' => $link['after_text'] ?? '',
543+
];
544+
}
523545
}

‎src/Resources/themes/default/layout/layout.twig‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,5 +75,14 @@
7575
{{ 'Generated by %sDoctum, a API Documentation generator and fork of Sami%s.'|trans|format(
7676
'<a href="https://github.com/code-lts/doctum">', '</a>'
7777
)|raw }}
78+
{%- if project.hasFooterLink() -%}
79+
{% set link = project.getFooterLink() %}
80+
<br/>
81+
{{- link.before_text }}
82+
{%- if link.href is not empty -%}
83+
{{ " " }}<a href="{{ link.href }}" rel="{{ link.rel }}" target="{{ link.target }}">{{ link.link_text }}</a>{{ " " }}
84+
{%- endif -%}
85+
{{ link.after_text -}}
86+
{%- endif -%}
7887
</div>
7988
{%- endblock -%}

‎tests/AbstractTestCase.php‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,13 @@
1111
*/
1212
abstract class AbstractTestCase extends TestCase
1313
{
14-
protected function getProject(): Project
14+
/**
15+
* @param array<string,mixed> $config
16+
*/
17+
protected function getProject(array $config = []): Project
1518
{
1619
$store = new ArrayStore();
17-
return new Project($store);
20+
return new Project($store, null, $config);
1821
}
1922

2023
protected function getTestConfigFilePath(): string

‎tests/ProjectTest.php‎

Lines changed: 74 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,13 +2,12 @@
22

33
namespace Doctum\Tests;
44

5-
use PHPUnit\Framework\TestCase;
65
use Doctum\Project;
76
use Doctum\Reflection\ClassReflection;
87
use Doctum\Store\ArrayStore;
98
use Doctum\Version\Version;
109

11-
class ProjectTest extends TestCase
10+
class ProjectTest extends AbstractTestCase
1211
{
1312
public function testSwitchVersion(): void
1413
{
@@ -45,8 +44,80 @@ public function testSwitchVersion(): void
4544
[
4645
'C21\\C2' => $class2,
4746
'C31\\C32\\C3' => $class3,
48-
],
47+
],
4948
$project->getProjectClasses()
5049
);
5150
}
51+
52+
public function testHasFooterLink(): void
53+
{
54+
$project = $this->getProject();
55+
56+
$this->assertFalse($project->hasFooterLink());
57+
58+
$project = $this->getProject([
59+
'footer_link' => [
60+
'href' => 'https://github.com/code-lts/doctum',
61+
'rel' => 'noreferrer noopener',
62+
'target' => '_blank',
63+
'before_text' => 'You can edit the configuration',
64+
'link_text' => 'on this', // Required if the href key is set
65+
'after_text' => 'repository',
66+
],
67+
]);
68+
69+
$this->assertTrue($project->hasFooterLink());
70+
71+
$project = $this->getProject([
72+
'footer_link' => [],
73+
]);
74+
75+
$this->assertTrue($project->hasFooterLink());
76+
77+
$project = $this->getProject([
78+
'footer_link' => null,
79+
]);
80+
81+
$this->assertFalse($project->hasFooterLink());
82+
83+
$project = $this->getProject([
84+
'footer_link' => 'https://example.com',
85+
]);
86+
87+
$this->assertFalse($project->hasFooterLink());
88+
}
89+
90+
public function testGetFooterLink(): void
91+
{
92+
$project = $this->getProject();
93+
94+
$this->assertSame($project->getFooterLink(), [
95+
'href' => '',
96+
'target' => '',
97+
'rel' => '',
98+
'before_text' => '',
99+
'link_text' => '',
100+
'after_text' => '',
101+
]);
102+
103+
$project = $this->getProject([
104+
'footer_link' => [
105+
'href' => 'https://github.com/code-lts/doctum',
106+
'rel' => 'noreferrer noopener',
107+
'target' => '_blank',
108+
'before_text' => 'You can edit the configuration',
109+
'link_text' => 'on this', // Required if the href key is set
110+
'after_text' => 'repository',
111+
],
112+
]);
113+
114+
$this->assertSame($project->getFooterLink(), [
115+
'href' => 'https://github.com/code-lts/doctum',
116+
'target' => '_blank',
117+
'rel' => 'noreferrer noopener',
118+
'before_text' => 'You can edit the configuration',
119+
'link_text' => 'on this',
120+
'after_text' => 'repository',
121+
]);
122+
}
52123
}

0 commit comments

Comments
 (0)