Add search field for API documentation

.github/workflows/ci.yml

@@ -0,0 +1,42 @@
+# https://help.github.com/en/categories/automating-your-workflow-with-github-actions
+
+on:
+  - pull_request
+  - push
+
+name: CI
+
+jobs:
+
+  tests:
+    name: Tests on PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ['7.4']
+    steps:
+      - uses: actions/checkout@v2
+
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+          tools: composer
+
+      - name: Get composer cache directory
+        id: composer-cache
+        run: echo "::set-output name=dir::$(composer config cache-files-dir)"
+
+      - name: Cache dependencies
+        uses: actions/cache@v2
+        with:
+          path: ${{ steps.composer-cache.outputs.dir }}
+          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
+          restore-keys: ${{ runner.os }}-composer-
+
+      - name: Install dependencies
+        run: composer install --no-interaction --no-ansi --no-progress
+
+      - name: Run tests
+        run: vendor/bin/phpunit

.gitignore

@@ -1,4 +1,8 @@
 .vscode
 .phel-repl-history
+.phpunit.result.cache
+
+/content/documentation/api.md
 /public
+/static/api_search.js
 /vendor

README.md

@@ -15,5 +15,5 @@ zola build # build & publish
 
 ```bash
 composer install # install phel as composer dependency
-php build/api-page.php > content/documentation/api.md
+composer build   # build the API documentation page & the API search index
 ```

build/api-page.php

@@ -2,50 +2,19 @@
 
 declare(strict_types=1);
 
-use Gacela\Framework\Gacela;
-use Phel\Lang\Keyword;
-use Phel\Lang\TypeFactory;
-use Phel\Run\RunFacade;
-use Symfony\Component\Console\Input\ArrayInput;
-use Symfony\Component\Console\Output\ConsoleOutput;
-
 require __DIR__ . '/../vendor/autoload.php';
 
+use Gacela\Framework\Gacela;
+use PhelDocBuild\FileGenerator\Facade;
+
 Gacela::bootstrap(__DIR__, [
     'config' => [
         'type' => 'php',
         'path' => 'phel-config.php',
         'path_local' => 'phel-config-local.php',
     ],
 ]);
-$rf = new RunFacade();
-$rf->getRunCommand()->run(new ArrayInput(['path' => __DIR__ . '/src/doc.phel']), new ConsoleOutput());
-
-echo "+++\n";
-echo "title = \"API\"\n";
-echo "weight = 110\n";
-echo "template = \"page-api.html\"\n";
-echo "+++\n\n";
-
-$normalizedData = [];
-foreach ($GLOBALS['__phel'] as $ns => $functions) {
-    $normalizedNs = str_replace('phel\\', '', $ns);
-    $moduleName = $normalizedNs === 'core' ? '' : $normalizedNs . '/';
-    foreach ($functions as $fnName => $fn) {
-        $fullFnName = $moduleName . $fnName;
-
-        $normalizedData[$fullFnName] = $GLOBALS['__phel_meta'][$ns][$fnName] ?? TypeFactory::getInstance()->emptyPersistentMap();
-    }
-}
-
-ksort($normalizedData);
-foreach ($normalizedData as $fnName => $meta) {
-    $doc = $meta[Keyword::create('doc')] ?? '';
-    $isPrivate = $meta[Keyword::create('private')] ?? false;
 
-    if (!$isPrivate) {
-        echo "## `$fnName`\n\n";
-        echo $doc;
-        echo "\n\n";
-    }
-}
+$fileGeneratorFacade = new Facade();
+$fileGeneratorFacade->generateMdPage();
+$fileGeneratorFacade->generateApiSearch();

build/phel-config.php

@@ -1,7 +1,7 @@
 <?php
 
 return [
-    'src-dirs' => ['/src'],
+    'src-dirs' => ['/src/phel'],
     'test-dirs' => [],
     'vendor-dir' => '/../vendor'
 ];

build/src/php/FileGenerator/Config.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhelDocBuild\FileGenerator;
+
+use Gacela\Framework\AbstractConfig;
+
+final class Config extends AbstractConfig
+{
+    public function getSrcDir(): string
+    {
+        return __DIR__ . '/../..';
+    }
+}

build/src/php/FileGenerator/DependencyProvider.php

@@ -0,0 +1,22 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhelDocBuild\FileGenerator;
+
+use Gacela\Framework\AbstractDependencyProvider;
+use Gacela\Framework\Container\Container;
+use Phel\Run\RunFacade;
+
+/**
+ * @method Factory getFactory()
+ */
+final class DependencyProvider extends AbstractDependencyProvider
+{
+    public const FACADE_PHEL_RUN = 'FACADE_PHEL_RUN';
+
+    public function provideModuleDependencies(Container $container): void
+    {
+        $container->set(self::FACADE_PHEL_RUN, fn() => new RunFacade());
+    }
+}

build/src/php/FileGenerator/Domain/ApiSearchGenerator.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhelDocBuild\FileGenerator\Domain;
+
+final class ApiSearchGenerator
+{
+    private const SPECIAL_ENDING_CHARS = ['=', '*', '?', '+', '>', '<', '!'];
+
+    /**
+     * @return array<string,array{fnName:string,fnSignature:string,desc:string,anchor:string}>
+     */
+    public function generateSearchIndex(array $groupNormalizedData): array
+    {
+        /**
+         * Zola ignores the especial chars, and uses instead a number. This variable keep track
+         * of the appearances and uses an autoincrement number to follow the proper link.
+         *
+         * For example, consider the two functions: `table` and `table?`
+         * They belong to the same group `table`, and their anchor will be such as:
+         * table  -> table
+         * table? -> table-1
+         */
+        $groupFnNameAppearances = [];
+
+        $result = [];
+        foreach ($groupNormalizedData as $groupKey => $values) {
+            $groupFnNameAppearances[$groupKey] = 0;
+
+            foreach ($values as ['fnName' => $fnName, 'fnSignature' => $fnSignature, 'desc' => $desc]) {
+                if ($groupFnNameAppearances[$groupKey] === 0) {
+                    $anchor = $groupKey;
+                    $groupFnNameAppearances[$groupKey]++;
+                } else {
+                    $sanitizedFnName = str_replace(['/', ...self::SPECIAL_ENDING_CHARS], ['-', ''], $fnName);
+                    $anchor = rtrim($sanitizedFnName, '-') . '-' . $groupFnNameAppearances[$groupKey]++;
+                }
+
+                $result[] = [
+                    'fnName' => $fnName,
+                    'fnSignature' => $fnSignature,
+                    'desc' => $desc,
+                    'anchor' => $anchor,
+                ];
+            }
+        }
+
+        return $result;
+    }
+}

build/src/php/FileGenerator/Domain/MdPageRenderer.php

@@ -0,0 +1,32 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhelDocBuild\FileGenerator\Domain;
+
+final class MdPageRenderer
+{
+    private OutputInterface $output;
+
+    public function __construct(OutputInterface $output)
+    {
+        $this->output = $output;
+    }
+
+    public function renderMdPage(array $groupNormalizedData): void
+    {
+        $this->output->writeln("+++");
+        $this->output->writeln("title = \"API\"");
+        $this->output->writeln("weight = 110");
+        $this->output->writeln("template = \"page-api.html\"");
+        $this->output->writeln("+++\n");
+
+        foreach ($groupNormalizedData as $values) {
+            foreach ($values as ['fnName' => $fnName, 'doc' => $doc]) {
+                $this->output->writeln("## `$fnName`\n");
+                $this->output->write($doc);
+                $this->output->writeln("\n");
+            }
+        }
+    }
+}

build/src/php/FileGenerator/Domain/OutputInterface.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhelDocBuild\FileGenerator\Domain;
+
+interface OutputInterface
+{
+    public function write(string $line): void;
+
+    public function writeln(string $line): void;
+}

build/src/php/FileGenerator/Domain/PhelFnLoaderInterface.php

@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhelDocBuild\FileGenerator\Domain;
+
+use Phel\Lang\Collections\Map\PersistentMapInterface;
+
+interface PhelFnLoaderInterface
+{
+    /**
+     * @return array<string,PersistentMapInterface>
+     */
+    public function getNormalizedPhelFunctions(): array;
+}

build/src/php/FileGenerator/Domain/PhelFnNormalizer.php

@@ -0,0 +1,68 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhelDocBuild\FileGenerator\Domain;
+
+use Phel\Lang\Keyword;
+
+final class PhelFnNormalizer
+{
+    private PhelFnLoaderInterface $phelFnLoader;
+
+    public function __construct(PhelFnLoaderInterface $phelFnLoader)
+    {
+        $this->phelFnLoader = $phelFnLoader;
+    }
+
+    /**
+     * @return array<string,array{fnName:string,doc:string,fnSignature:string,desc:string}>
+     */
+    public function getNormalizedGroupedPhelFns(): array
+    {
+        $normalizedData = $this->phelFnLoader->getNormalizedPhelFunctions();
+
+        $result = [];
+        foreach ($normalizedData as $fnName => $meta) {
+            $isPrivate = $meta[Keyword::create('private')] ?? false;
+            if ($isPrivate) {
+                continue;
+            }
+
+            $groupKey = preg_replace(
+                '/[^a-zA-Z0-9\-]+/',
+                '',
+                str_replace('/', '-', $fnName)
+            );
+
+            $doc = $meta[Keyword::create('doc')] ?? '';
+            $pattern = '#(```phel\n(?<fnSignature>.*)\n```\n)?(?<desc>.*)#s';
+            preg_match($pattern, $doc, $matches);
+
+            $result[strtolower(rtrim($groupKey, '-'))][] = [
+                'fnName' => $fnName,
+                'doc' => $meta[Keyword::create('doc')] ?? '',
+                'fnSignature' => $matches['fnSignature'] ?? '',
+                'desc' => $this->formatDescription($matches['desc'] ?? ''),
+            ];
+        }
+
+        foreach ($result as $values) {
+            usort($values, static fn(array $a, array $b) => $a['fnName'] <=> $b['fnName']);
+        }
+
+        return $result;
+    }
+
+    /**
+     * The $desc is in Markdown format, the regex transforms links `[printf](https://...)` into `<i>printf</i>`.
+     */
+    private function formatDescription(string $desc): string
+    {
+        return preg_replace(
+            '#\[([^\]]+)\]\(([^\)]+)\)#',
+            '<i>\1</i>',
+            $desc
+        );
+    }
+}

build/src/php/FileGenerator/Facade.php

@@ -0,0 +1,27 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhelDocBuild\FileGenerator;
+
+use Gacela\Framework\AbstractFacade;
+
+/**
+ * @method Factory getFactory()
+ */
+final class Facade extends AbstractFacade
+{
+    public function generateMdPage(): void
+    {
+        $this->getFactory()
+            ->createDocFileGenerator()
+            ->renderMdPage();
+    }
+
+    public function generateApiSearch(): void
+    {
+        $this->getFactory()
+            ->createDocFileGenerator()
+            ->generateApiSearch();
+    }
+}