feat: implement a custom footer link

Ref: silverstripe/api.silverstripe.org#65
code-lts · Dec 19, 2020 · f9aa867 · f9aa867
1 parent 64983cd
commit f9aa867
Show file tree

Hide file tree

Showing 7 changed files with 152 additions and 6 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,7 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Fixed: "Error: The ProgressBar is not started" (#19)
 - Fixed: ""3" @param tags are expected but only "4" found" (#21)
 - Reworked the `@param` tag error detection and added new error messages
-- Added: A shebang to all the new PHARs distributed.
+- Added: A shebang to all the new PHARs distributed
+- Added: Support for a custom `footer_link` configuration
 
 ## [5.2.1] - 2020-11-30
 

diff --git a/README.rst b/README.rst
@@ -143,6 +143,40 @@ And here is how you can configure different versions:
         'default_opened_level' => 2,
     ]);
 
+
+And here is how you can configure a footer link below the Doctum link:
+
+All `footer_link` keys are optional.
+
+.. code-block:: php
+
+    <?php
+
+    use Doctum\Doctum;
+    use Symfony\Component\Finder\Finder;
+
+    $dir = '/path/to/yourlib/src';
+    $iterator = Finder::create()
+        ->files()
+        ->name('*.php')
+        ->exclude('Resources')
+        ->exclude('Tests')
+        ->in($dir);
+
+    return new Doctum($iterator, [
+        'title'                => 'yourlib API',
+        'source_dir'           => dirname($dir) . '/',
+        'remote_repository'    => new GitHubRemoteRepository('yourorg/yourlib', dirname($dir)),
+        'footer_link'          => [
+            'href'        => 'https://github.com/code-lts/doctum',
+            'rel'         => 'noreferrer noopener',
+            'target'      => '_blank',
+            'before_text' => 'You can edit the configuration',
+            'link_text'   => 'on this', // Required if the href key is set
+            'after_text'  => 'repository',
+        ],
+    ]);
+
 You can find more configuration examples under the ``examples/`` directory of
 the source code.
 

diff --git a/src/Doctum.php b/src/Doctum.php
@@ -188,6 +188,11 @@ class Doctum implements ArrayAccess
     /** @var AbstractRemoteRepository|null */
     private $remote_repository = null;
 
+    /**
+     * @var array<string,string>|null
+     */
+    private $footer_link = null;
+
     /**
      * include parent properties and methods on class pages
      *
@@ -376,6 +381,7 @@ private function getBuiltProject(): Project
             'title' => $this->title,
             'source_url' => $this->source_url,
             'insert_todos' => $this->insert_todos,
+            'footer_link' => $this->footer_link,
             'sort_class_properties' => $this->sort_class_properties,
             'sort_class_methods' => $this->sort_class_methods,
             'sort_class_constants' => $this->sort_class_constants,

diff --git a/src/Project.php b/src/Project.php
@@ -520,4 +520,26 @@ public function getViewSourceUrl($relativePath, $line)
 
         return '';
     }
+
+    public function hasFooterLink(): bool
+    {
+        return $this->getConfig('footer_link') !== null && is_array($this->getConfig('footer_link'));
+    }
+
+    /**
+     * @return array<string,string>
+     * @phpstan-return array{href: string, rel: string, target: string, before_text: string, link_text: string, after_text: string}
+     */
+    public function getFooterLink(): array
+    {
+        $link = $this->getConfig('footer_link');
+        return [
+            'href' => $link['href'] ?? '',
+            'target' => $link['target'] ?? '',
+            'rel' => $link['rel'] ?? '',
+            'before_text' => $link['before_text'] ?? '',
+            'link_text' => $link['link_text'] ?? '',
+            'after_text' => $link['after_text'] ?? '',
+        ];
+    }
 }
diff --git a/src/Resources/themes/default/layout/layout.twig b/src/Resources/themes/default/layout/layout.twig
@@ -75,5 +75,14 @@
         {{ 'Generated by %sDoctum, a API Documentation generator and fork of Sami%s.'|trans|format(
             '<a href="https://github.com/code-lts/doctum">', '</a>'
         )|raw }}
+        {%- if project.hasFooterLink() -%}
+            {% set link = project.getFooterLink() %}
+            <br/>
+            {{- link.before_text }}
+            {%- if link.href is not empty -%}
+                {{ " " }}<a href="{{ link.href }}" rel="{{ link.rel }}" target="{{ link.target }}">{{ link.link_text }}</a>{{ " " }}
+            {%- endif -%}
+            {{ link.after_text -}}
+        {%- endif -%}
     </div>
 {%- endblock -%}
diff --git a/tests/AbstractTestCase.php b/tests/AbstractTestCase.php
@@ -11,10 +11,13 @@
  */
 abstract class AbstractTestCase extends TestCase
 {
-    protected function getProject(): Project
+    /**
+     * @param array<string,mixed> $config
+     */
+    protected function getProject(array $config = []): Project
     {
         $store = new ArrayStore();
-        return new Project($store);
+        return new Project($store, null, $config);
     }
 
     protected function getTestConfigFilePath(): string

diff --git a/tests/ProjectTest.php b/tests/ProjectTest.php
@@ -2,13 +2,12 @@
 
 namespace Doctum\Tests;
 
-use PHPUnit\Framework\TestCase;
 use Doctum\Project;
 use Doctum\Reflection\ClassReflection;
 use Doctum\Store\ArrayStore;
 use Doctum\Version\Version;
 
-class ProjectTest extends TestCase
+class ProjectTest extends AbstractTestCase
 {
     public function testSwitchVersion(): void
     {
@@ -45,8 +44,80 @@ public function testSwitchVersion(): void
             [
                 'C21\\C2' => $class2,
                 'C31\\C32\\C3' => $class3,
-             ],
+            ],
             $project->getProjectClasses()
         );
     }
+
+    public function testHasFooterLink(): void
+    {
+        $project = $this->getProject();
+
+        $this->assertFalse($project->hasFooterLink());
+
+        $project = $this->getProject([
+            'footer_link' => [
+                'href'        => 'https://github.com/code-lts/doctum',
+                'rel'         => 'noreferrer noopener',
+                'target'      => '_blank',
+                'before_text' => 'You can edit the configuration',
+                'link_text'   => 'on this', // Required if the href key is set
+                'after_text'  => 'repository',
+            ],
+        ]);
+
+        $this->assertTrue($project->hasFooterLink());
+
+        $project = $this->getProject([
+            'footer_link'          => [],
+        ]);
+
+        $this->assertTrue($project->hasFooterLink());
+
+        $project = $this->getProject([
+            'footer_link'          => null,
+        ]);
+
+        $this->assertFalse($project->hasFooterLink());
+
+        $project = $this->getProject([
+            'footer_link'          => 'https://example.com',
+        ]);
+
+        $this->assertFalse($project->hasFooterLink());
+    }
+
+    public function testGetFooterLink(): void
+    {
+        $project = $this->getProject();
+
+        $this->assertSame($project->getFooterLink(), [
+            'href' => '',
+            'target' => '',
+            'rel' => '',
+            'before_text' => '',
+            'link_text' => '',
+            'after_text' => '',
+        ]);
+
+        $project = $this->getProject([
+            'footer_link' => [
+                'href'        => 'https://github.com/code-lts/doctum',
+                'rel'         => 'noreferrer noopener',
+                'target'      => '_blank',
+                'before_text' => 'You can edit the configuration',
+                'link_text'   => 'on this', // Required if the href key is set
+                'after_text'  => 'repository',
+            ],
+        ]);
+
+        $this->assertSame($project->getFooterLink(), [
+            'href'        => 'https://github.com/code-lts/doctum',
+            'target'      => '_blank',
+            'rel'         => 'noreferrer noopener',
+            'before_text' => 'You can edit the configuration',
+            'link_text'   => 'on this',
+            'after_text'  => 'repository',
+        ]);
+    }
 }