Improve API documentation page

Author: JesusValeraDev

build/src/ApiGenerator/Application/ApiMarkdownGenerator.php

@@ -5,13 +5,12 @@
 namespace PhelWeb\ApiGenerator\Application;
 
 use Phel\Api\Transfer\PhelFunction;
-use Phel\Lang\Symbol;
 use Phel\Shared\Facade\ApiFacadeInterface;
 
 final readonly class ApiMarkdownGenerator
 {
     public function __construct(
-        private ApiFacadeInterface $apiFacade
+        private ApiFacadeInterface $apiFacade,
     ) {
     }
 
@@ -24,11 +23,12 @@ public function generate(): array
         $phelFns = $this->apiFacade->getPhelFunctions();
         $groupedByNamespace = $this->groupFunctionsByNamespace($phelFns);
 
+        $namespaces = [];
         foreach ($groupedByNamespace as $namespace => $functions) {
-            $result = array_merge($result, $this->buildNamespaceSection($namespace, $functions));
+            $namespaces[] = $this->buildNamespaceSection($namespace, $functions);
         }
 
-        return $result;
+        return array_merge($result, ...$namespaces);
     }
 
     /**
@@ -50,18 +50,12 @@ private function groupFunctionsByNamespace(array $phelFns): array
      */
     private function buildNamespaceSection(string $namespace, array $functions): array
     {
-        $lines = [
-            '',
-            '---',
-            '',
-            "## `{$namespace}`",
-        ];
-
+        $elements = [];
         foreach ($functions as $fn) {
-            $lines = array_merge($lines, $this->buildFunctionSection($fn));
+            $elements[] = $this->buildFunctionSection($fn);
         }
 
-        return $lines;
+        return array_merge(['', '---', '', "## `{$namespace}`", ''], ...$elements);
     }
 
     /**
@@ -75,7 +69,16 @@ private function buildFunctionSection(PhelFunction $fn): array
             $lines[] = $deprecation;
         }
 
-        $lines[] = $fn->doc;
+        // Handle exceptional documentation blocks
+        if ($fn->name === 'with-mock-wrapper' || $fn->name === 'with-mocks') {
+            $input = preg_replace('/```phel/', '```clojure', $fn->doc, 1);
+            $input = preg_replace('/^[ \t]+/m', '', $input);
+            $input = preg_replace('/(?<!\n)\n(```phel)/', "\n\n$1", $input);
+        } else {
+            $input = $fn->doc;
+        }
+
+        $lines[] = $input;
 
         if ($example = $this->buildExampleSection($fn)) {
             $lines = array_merge($lines, $example);
@@ -88,6 +91,7 @@ private function buildFunctionSection(PhelFunction $fn): array
         if ($sourceLink = $this->buildSourceLink($fn)) {
             $lines[] = $sourceLink;
         }
+        $lines[] = '';
 
         return $lines;
     }
@@ -100,7 +104,7 @@ private function buildDeprecationNotice(PhelFunction $fn): ?string
 
         $message = sprintf(
             '<small><span style="color: red; font-weight: bold;">Deprecated</span>: %s',
-            $fn->meta['deprecated']
+            $fn->meta['deprecated'],
         );
 
         if (isset($fn->meta['superseded-by'])) {
@@ -109,7 +113,7 @@ private function buildDeprecationNotice(PhelFunction $fn): ?string
             $message .= sprintf(
                 ' &mdash; Use [`%s`](#%s) instead',
                 $supersededBy,
-                $anchor
+                $anchor,
             );
         }
 
@@ -129,7 +133,7 @@ private function buildExampleSection(PhelFunction $fn): ?array
             '',
             '**Example:**',
             '',
-            '```phel',
+            '```clojure',
             $fn->meta['example'],
             '```',
         ];
@@ -158,10 +162,7 @@ private function buildSeeAlsoSection(PhelFunction $fn): ?array
      */
     private function extractFunctionNames(mixed $seeAlso): array
     {
-        return array_map(
-            fn(Symbol $symbol) => $symbol->getName(),
-            iterator_to_array($seeAlso)
-        );
+        return iterator_to_array($seeAlso);
     }
 
     /**
@@ -171,12 +172,8 @@ private function extractFunctionNames(mixed $seeAlso): array
     private function buildFunctionLinks(array $functionNames): array
     {
         return array_map(
-            fn(string $func) => sprintf(
-                '[`%s`](#%s)',
-                $func,
-                $this->sanitizeAnchor($func)
-            ),
-            $functionNames
+            fn(string $func) => sprintf('[`%s`](#%s)', $func, $this->sanitizeAnchor($func)),
+            $functionNames,
         );
     }
 
@@ -219,7 +216,6 @@ private function buildZolaHeaders(): array
             'template = "page-api.html"',
             'aliases = [ "/api" ]',
             '+++',
-            '',
         ];
     }
 }

build/tests/php/ApiGenerator/Domain/ApiMarkdownGeneratorTest.php

@@ -24,7 +24,6 @@ public function test_generate_page_without_phel_functions(): void
             'template = "page-api.html"',
             'aliases = [ "/api" ]',
             '+++',
-            '',
         ];
 
         self::assertEquals($expected, $generator->generate());
@@ -53,12 +52,13 @@ public function test_generate_page_with_one_phel_function(): void
             'aliases = [ "/api" ]',
             '+++',
             '',
-            '',
             '---',
             '',
             '## `ns-1`',
+            '',
             '### `ns-1/function-1`',
             'The doc from function 1',
+            '',
         ];
 
         self::assertEquals($expected, $generator->generate());
@@ -91,14 +91,16 @@ public function test_generate_page_with_multiple_phel_functions_in_same_group():
             'aliases = [ "/api" ]',
             '+++',
             '',
-            '',
             '---',
             '',
             '## `core`',
+            '',
             '### `function-1`',
             'The doc from function 1',
+            '',
             '### `function-2`',
             'The doc from function 2',
+            '',
         ];
 
         self::assertEquals($expected, $generator->generate());
@@ -131,18 +133,21 @@ public function test_generate_page_with_multiple_phel_functions_in_different_gro
             'aliases = [ "/api" ]',
             '+++',
             '',
-            '',
             '---',
             '',
             '## `ns-1`',
+            '',
             '### `ns-1/function-1`',
             'The doc from function 1',
             '',
+            '',
             '---',
             '',
             '## `ns-2`',
+            '',
             '### `ns-2/function-2`',
             'The doc from function 2',
+            '',
         ];
 
         self::assertEquals($expected, $generator->generate());