From 406aec7e493b880302796b5a886b6be3e86bcc48 Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Sat, 6 Sep 2025 13:08:46 +0200 Subject: [PATCH 1/2] deps: update phel-lang --- composer.lock | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/composer.lock b/composer.lock index eaf055f..8836fe0 100644 --- a/composer.lock +++ b/composer.lock @@ -164,12 +164,12 @@ "source": { "type": "git", "url": "https://github.com/phel-lang/phel-lang.git", - "reference": "a7907ce402d779b66fe16e832ea95ab77c84e8bb" + "reference": "43828309586392d1412fb65319198be5ab7cc619" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/phel-lang/phel-lang/zipball/a7907ce402d779b66fe16e832ea95ab77c84e8bb", - "reference": "a7907ce402d779b66fe16e832ea95ab77c84e8bb", + "url": "https://api.github.com/repos/phel-lang/phel-lang/zipball/43828309586392d1412fb65319198be5ab7cc619", + "reference": "43828309586392d1412fb65319198be5ab7cc619", "shasum": "" }, "require": { @@ -236,7 +236,7 @@ "type": "custom" } ], - "time": "2025-09-03T18:14:28+00:00" + "time": "2025-09-06T10:43:50+00:00" }, { "name": "phpunit/php-timer", @@ -1639,12 +1639,12 @@ "source": { "type": "git", "url": "https://github.com/Roave/SecurityAdvisories.git", - "reference": "4fbe7e09e34b1554269750e19674f1f6fd84a4ae" + "reference": "dc5c4ede5c331ae21fb68947ff89672df9b7cc7d" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/Roave/SecurityAdvisories/zipball/4fbe7e09e34b1554269750e19674f1f6fd84a4ae", - "reference": "4fbe7e09e34b1554269750e19674f1f6fd84a4ae", + "url": "https://api.github.com/repos/Roave/SecurityAdvisories/zipball/dc5c4ede5c331ae21fb68947ff89672df9b7cc7d", + "reference": "dc5c4ede5c331ae21fb68947ff89672df9b7cc7d", "shasum": "" }, "conflict": { @@ -2068,7 +2068,7 @@ "marshmallow/nova-tiptap": "<5.7", "matomo/matomo": "<1.11", "matyhtf/framework": "<3.0.6", - "mautic/core": "<5.2.6|>=6.0.0.0-alpha,<6.0.2", + "mautic/core": "<5.2.8|>=6.0.0.0-alpha,<6.0.5", "mautic/core-lib": ">=1.0.0.0-beta,<4.4.13|>=5.0.0.0-alpha,<5.1.1", "maximebf/debugbar": "<1.19", "mdanter/ecc": "<2", @@ -2222,7 +2222,7 @@ "prestashop/blockwishlist": ">=2,<2.1.1", "prestashop/contactform": ">=1.0.1,<4.3", "prestashop/gamification": "<2.3.2", - "prestashop/prestashop": "<8.1.6", + "prestashop/prestashop": "<8.2.3", "prestashop/productcomments": "<5.0.2", "prestashop/ps_contactinfo": "<=3.3.2", "prestashop/ps_emailsubscription": "<2.6.1", @@ -2596,7 +2596,7 @@ "type": "tidelift" } ], - "time": "2025-09-02T17:05:04+00:00" + "time": "2025-09-04T20:05:35+00:00" }, { "name": "sebastian/cli-parser", From 5a7f62c314e50ef30c880df02cb64e52f127a0b0 Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Sat, 6 Sep 2025 14:38:35 +0200 Subject: [PATCH 2/2] feat: group api page top by namespaces --- .../Application/ApiMarkdownGenerator.php | 34 ++++--- .../Application/ApiSearchGenerator.php | 6 +- .../Domain/ApiMarkdownGeneratorTest.php | 41 ++++++--- .../Domain/ApiSearchGeneratorTest.php | 88 +++++++++---------- composer.lock | 8 +- static/search.js | 12 +-- templates/page-api.html | 13 ++- 7 files changed, 121 insertions(+), 81 deletions(-) diff --git a/build/src/php/FileGenerator/Application/ApiMarkdownGenerator.php b/build/src/php/FileGenerator/Application/ApiMarkdownGenerator.php index 3f2e3ec..378e606 100644 --- a/build/src/php/FileGenerator/Application/ApiMarkdownGenerator.php +++ b/build/src/php/FileGenerator/Application/ApiMarkdownGenerator.php @@ -21,17 +21,29 @@ public function generate(): array { $result = $this->zolaHeaders(); - /** @var list $groupedPhelFns */ - $groupedPhelFns = $this->apiFacade->getPhelFunctions(); - - foreach ($groupedPhelFns as $fn) { - $result[] = "## `{$fn->name()}`"; - $result[] = "Namespace `{$fn->namespace()}`"; - $result[] = $fn->doc(); - if ($fn->githubUrl() !== '') { - $result[] = sprintf('[[View source](%s)]', $fn->githubUrl()); - }elseif ($fn->docUrl() !== '') { - $result[] = sprintf('[[Read more](%s)]', $fn->docUrl()); + /** @var list $phelFns */ + $phelFns = $this->apiFacade->getPhelFunctions(); + + $groupedByNamespace = []; + foreach ($phelFns as $fn) { + $groupedByNamespace[$fn->namespace()][] = $fn; + } + + foreach ($groupedByNamespace as $namespace => $fns) { + + $result[] = ""; + $result[] = "---"; + $result[] = ""; + $result[] = "## `{$namespace}`"; + + foreach ($fns as $fn) { + $result[] = "### `{$fn->nameWithNamespace()}`"; + $result[] = $fn->doc(); + if ($fn->githubUrl() !== '') { + $result[] = sprintf('[[View source](%s)]', $fn->githubUrl()); + } elseif ($fn->docUrl() !== '') { + $result[] = sprintf('[[Read more](%s)]', $fn->docUrl()); + } } } diff --git a/build/src/php/FileGenerator/Application/ApiSearchGenerator.php b/build/src/php/FileGenerator/Application/ApiSearchGenerator.php index c1a3223..07776f8 100644 --- a/build/src/php/FileGenerator/Application/ApiSearchGenerator.php +++ b/build/src/php/FileGenerator/Application/ApiSearchGenerator.php @@ -46,14 +46,14 @@ public function generateSearchIndex(): array $anchor = $groupKey; $groupFnNameAppearances[$groupKey]++; } else { - $sanitizedFnName = str_replace(['/', ...self::SPECIAL_ENDING_CHARS], ['-', ''], $fn->fnName()); + $sanitizedFnName = str_replace(['/', ...self::SPECIAL_ENDING_CHARS], ['-', ''], $fn->name()); $anchor = rtrim($sanitizedFnName, '-') . '-' . $groupFnNameAppearances[$groupKey]++; } $result[] = [ 'id' => 'api_' . $fn->name(), - 'fnName' => $fn->name(), - 'fnSignature' => $fn->signature(), + 'name' => $fn->nameWithNamespace(), + 'signature' => $fn->signature(), 'desc' => $this->formatDescription($fn->description()), 'anchor' => $anchor, 'type' => 'api', diff --git a/build/tests/php/FileGenerator/Domain/ApiMarkdownGeneratorTest.php b/build/tests/php/FileGenerator/Domain/ApiMarkdownGeneratorTest.php index 1a153c2..b61196f 100644 --- a/build/tests/php/FileGenerator/Domain/ApiMarkdownGeneratorTest.php +++ b/build/tests/php/FileGenerator/Domain/ApiMarkdownGeneratorTest.php @@ -36,9 +36,10 @@ public function test_generate_page_with_one_phel_function(): void $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'function-1', + 'name' => 'function-1', 'doc' => 'The doc from function 1', 'groupKey' => 'group-1', + 'namespace' => 'ns-1', ]), ]); @@ -52,7 +53,11 @@ public function test_generate_page_with_one_phel_function(): void 'aliases = [ "/api" ]', '+++', '', - '## `function-1`', + '', + '---', + '', + '## `ns-1`', + '### `ns-1/function-1`', 'The doc from function 1', ]; @@ -65,12 +70,14 @@ public function test_generate_page_with_multiple_phel_functions_in_same_group(): $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'function-1', + 'name' => 'function-1', 'doc' => 'The doc from function 1', + 'namespace' => 'core', ]), PhelFunction::fromArray([ - 'fnName' => 'function-2', + 'name' => 'function-2', 'doc' => 'The doc from function 2', + 'namespace' => 'core', ]), ]); @@ -84,9 +91,13 @@ public function test_generate_page_with_multiple_phel_functions_in_same_group(): 'aliases = [ "/api" ]', '+++', '', - '## `function-1`', + '', + '---', + '', + '## `core`', + '### `function-1`', 'The doc from function 1', - '## `function-2`', + '### `function-2`', 'The doc from function 2', ]; @@ -99,12 +110,14 @@ public function test_generate_page_with_multiple_phel_functions_in_different_gro $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'function-1', + 'name' => 'function-1', 'doc' => 'The doc from function 1', + 'namespace' => 'ns-1', ]), PhelFunction::fromArray([ - 'fnName' => 'function-2', + 'name' => 'function-2', 'doc' => 'The doc from function 2', + 'namespace' => 'ns-2', ]), ]); @@ -118,9 +131,17 @@ public function test_generate_page_with_multiple_phel_functions_in_different_gro 'aliases = [ "/api" ]', '+++', '', - '## `function-1`', + '', + '---', + '', + '## `ns-1`', + '### `ns-1/function-1`', 'The doc from function 1', - '## `function-2`', + '', + '---', + '', + '## `ns-2`', + '### `ns-2/function-2`', 'The doc from function 2', ]; diff --git a/build/tests/php/FileGenerator/Domain/ApiSearchGeneratorTest.php b/build/tests/php/FileGenerator/Domain/ApiSearchGeneratorTest.php index 1acc7e1..b9d3cb5 100644 --- a/build/tests/php/FileGenerator/Domain/ApiSearchGeneratorTest.php +++ b/build/tests/php/FileGenerator/Domain/ApiSearchGeneratorTest.php @@ -17,8 +17,8 @@ public function test_generate_search_index_one_item(): void $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'table?', - 'fnSignature' => '(table? x)', + 'name' => 'table?', + 'signature' => '(table? x)', 'desc' => 'doc for table?', 'groupKey' => 'table' ]), @@ -30,8 +30,8 @@ public function test_generate_search_index_one_item(): void $expected = [ [ 'id' => 'api_table?', - 'fnName' => 'table?', - 'fnSignature' => '(table? x)', + 'name' => 'table?', + 'signature' => '(table? x)', 'desc' => 'doc for table?', 'anchor' => 'table', 'type' => 'api', @@ -51,14 +51,14 @@ public function test_multiple_items_in_different_groups(): void $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'table', - 'fnSignature' => '(table & xs)', + 'name' => 'table', + 'signature' => '(table & xs)', 'desc' => 'doc for table', 'groupKey' => 'table', ]), PhelFunction::fromArray([ - 'fnName' => 'not', - 'fnSignature' => '(not x)', + 'name' => 'not', + 'signature' => '(not x)', 'desc' => 'doc for not', 'groupKey' => 'not', ]), @@ -70,16 +70,16 @@ public function test_multiple_items_in_different_groups(): void $expected = [ [ 'id' => 'api_table', - 'fnName' => 'table', - 'fnSignature' => '(table & xs)', + 'name' => 'table', + 'signature' => '(table & xs)', 'desc' => 'doc for table', 'anchor' => 'table', 'type' => 'api', ], [ 'id' => 'api_not', - 'fnName' => 'not', - 'fnSignature' => '(not x)', + 'name' => 'not', + 'signature' => '(not x)', 'desc' => 'doc for not', 'anchor' => 'not', 'type' => 'api', @@ -99,14 +99,14 @@ public function test_multiple_items_in_the_same_group(): void $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'table', - 'fnSignature' => '(table & xs)', + 'name' => 'table', + 'signature' => '(table & xs)', 'desc' => 'doc for table', 'groupKey' => 'table', ]), PhelFunction::fromArray([ - 'fnName' => 'table?', - 'fnSignature' => '(table? x)', + 'name' => 'table?', + 'signature' => '(table? x)', 'desc' => 'doc for table?', 'groupKey' => 'table', ]), @@ -118,16 +118,16 @@ public function test_multiple_items_in_the_same_group(): void $expected = [ [ 'id' => 'api_table', - 'fnName' => 'table', - 'fnSignature' => '(table & xs)', + 'name' => 'table', + 'signature' => '(table & xs)', 'desc' => 'doc for table', 'anchor' => 'table', 'type' => 'api', ], [ 'id' => 'api_table?', - 'fnName' => 'table?', - 'fnSignature' => '(table? x)', + 'name' => 'table?', + 'signature' => '(table? x)', 'desc' => 'doc for table?', 'anchor' => 'table-1', 'type' => 'api', @@ -147,14 +147,14 @@ public function test_fn_name_with_slash_in_the_middle(): void $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'http/response', - 'fnSignature' => '', + 'name' => 'http/response', + 'signature' => '', 'desc' => '', 'groupKey' => 'http-response', ]), PhelFunction::fromArray([ - 'fnName' => 'http/response?', - 'fnSignature' => '', + 'name' => 'http/response?', + 'signature' => '', 'desc' => '', 'groupKey' => 'http-response-1', ]), @@ -166,16 +166,16 @@ public function test_fn_name_with_slash_in_the_middle(): void $expected = [ [ 'id' => 'api_http/response', - 'fnName' => 'http/response', - 'fnSignature' => '', + 'name' => 'http/response', + 'signature' => '', 'desc' => '', 'anchor' => 'http-response', 'type' => 'api', ], [ 'id' => 'api_http/response?', - 'fnName' => 'http/response?', - 'fnSignature' => '', + 'name' => 'http/response?', + 'signature' => '', 'desc' => '', 'anchor' => 'http-response-1', 'type' => 'api', @@ -195,14 +195,14 @@ public function test_fn_name_ending_with_minus(): void $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'defn', - 'fnSignature' => '', + 'name' => 'defn', + 'signature' => '', 'desc' => '', 'groupKey' => 'defn', ]), PhelFunction::fromArray([ - 'fnName' => 'defn-', - 'fnSignature' => '', + 'name' => 'defn-', + 'signature' => '', 'desc' => '', 'groupKey' => 'defn', ]), @@ -214,16 +214,16 @@ public function test_fn_name_ending_with_minus(): void $expected = [ [ 'id' => 'api_defn', - 'fnName' => 'defn', - 'fnSignature' => '', + 'name' => 'defn', + 'signature' => '', 'desc' => '', 'anchor' => 'defn', 'type' => 'api', ], [ 'id' => 'api_defn-', - 'fnName' => 'defn-', - 'fnSignature' => '', + 'name' => 'defn-', + 'signature' => '', 'desc' => '', 'anchor' => 'defn-1', 'type' => 'api', @@ -243,14 +243,14 @@ public function test_fn_name_with_upper_case(): void $apiFacade->method('getPhelFunctions') ->willReturn([ PhelFunction::fromArray([ - 'fnName' => 'NAN', - 'fnSignature' => '', + 'name' => 'NAN', + 'signature' => '', 'desc' => '', 'groupKey' => 'nan', ]), PhelFunction::fromArray([ - 'fnName' => 'nan?', - 'fnSignature' => '', + 'name' => 'nan?', + 'signature' => '', 'desc' => '', 'groupKey' => 'nan', ]), @@ -262,16 +262,16 @@ public function test_fn_name_with_upper_case(): void $expected = [ [ 'id' => 'api_NAN', - 'fnName' => 'NAN', - 'fnSignature' => '', + 'name' => 'NAN', + 'signature' => '', 'desc' => '', 'anchor' => 'nan', 'type' => 'api', ], [ 'id' => 'api_nan?', - 'fnName' => 'nan?', - 'fnSignature' => '', + 'name' => 'nan?', + 'signature' => '', 'desc' => '', 'anchor' => 'nan-1', 'type' => 'api', diff --git a/composer.lock b/composer.lock index 8836fe0..61374c2 100644 --- a/composer.lock +++ b/composer.lock @@ -164,12 +164,12 @@ "source": { "type": "git", "url": "https://github.com/phel-lang/phel-lang.git", - "reference": "43828309586392d1412fb65319198be5ab7cc619" + "reference": "4e128ee40e9fd09e94c66778f8c1985f8729c020" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/phel-lang/phel-lang/zipball/43828309586392d1412fb65319198be5ab7cc619", - "reference": "43828309586392d1412fb65319198be5ab7cc619", + "url": "https://api.github.com/repos/phel-lang/phel-lang/zipball/4e128ee40e9fd09e94c66778f8c1985f8729c020", + "reference": "4e128ee40e9fd09e94c66778f8c1985f8729c020", "shasum": "" }, "require": { @@ -236,7 +236,7 @@ "type": "custom" } ], - "time": "2025-09-06T10:43:50+00:00" + "time": "2025-09-06T12:34:11+00:00" }, { "name": "phpunit/php-timer", diff --git a/static/search.js b/static/search.js index b538b11..18dc97c 100644 --- a/static/search.js +++ b/static/search.js @@ -131,7 +131,7 @@ function initSearch() { }; const index = elasticlunr(function () { - this.addField("fnName"); + this.addField("name"); this.addField("desc"); this.addField("title"); this.addField("content"); @@ -233,7 +233,7 @@ function showResults(index) { const options = { bool: "OR", fields: { - fnName: {boost: 3}, + name: {boost: 3}, title: {boost: 2}, desc: {boost: 1}, content: {boost: 1} @@ -243,8 +243,8 @@ function showResults(index) { const results = index.search(term, options); if (results.length === 0) { let emptyResult = { - fnName: "Symbol not found", - fnSignature: "", + name: "Symbol not found", + signature: "", desc: "Cannot provide any Phel symbol. Try something else", anchor: "#", type: "api" @@ -286,8 +286,8 @@ function formatSearchResultItem(item) { return `` + `
` + `API: ` - + `${item.fnName} ` - + `${item.fnSignature}` + + `${item.name} ` + + `${item.signature}` + `${item.desc}` + `
`; } diff --git a/templates/page-api.html b/templates/page-api.html index e3da418..b3e69e9 100644 --- a/templates/page-api.html +++ b/templates/page-api.html @@ -9,9 +9,16 @@

{{page.title}}

    - {% for h1 in page.toc %} -
  • - {{ h1.title }} + {% for namespace in page.toc %} +
  • + Namespace: {{ namespace.title }} +
      + {% for fn in namespace.children %} +
    • + {{ fn.title }} +
      • + {% endfor %} +
    • {% endfor %}