From dca9b94969655f41786f6957d3828b6ba89dc955 Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Thu, 20 Nov 2025 01:34:17 +0100 Subject: [PATCH 1/4] ref: extract methods in ApiMarkdownGenerator for better readability --- .../Application/ApiMarkdownGenerator.php | 237 ++++++++++++++---- composer.json | 9 +- composer.lock | 98 ++++++-- config.toml | 2 +- 4 files changed, 272 insertions(+), 74 deletions(-) diff --git a/build/src/ApiGenerator/Application/ApiMarkdownGenerator.php b/build/src/ApiGenerator/Application/ApiMarkdownGenerator.php index 031d550..68dcb5c 100644 --- a/build/src/ApiGenerator/Application/ApiMarkdownGenerator.php +++ b/build/src/ApiGenerator/Application/ApiMarkdownGenerator.php @@ -5,6 +5,7 @@ namespace PhelWeb\ApiGenerator\Application; use Phel\Api\Transfer\PhelFunction; +use Phel\Lang\Symbol; use Phel\Shared\Facade\ApiFacadeInterface; final readonly class ApiMarkdownGenerator @@ -19,68 +20,206 @@ public function __construct( */ public function generate(): array { - $result = $this->zolaHeaders(); - - /** @var list $phelFns */ + $result = $this->buildZolaHeaders(); $phelFns = $this->apiFacade->getPhelFunctions(); + $groupedByNamespace = $this->groupFunctionsByNamespace($phelFns); + + foreach ($groupedByNamespace as $namespace => $functions) { + $result = array_merge($result, $this->buildNamespaceSection($namespace, $functions)); + } + + return $result; + } - $groupedByNamespace = []; + /** + * @param list $phelFns + * @return array> + */ + private function groupFunctionsByNamespace(array $phelFns): array + { + $grouped = []; foreach ($phelFns as $fn) { - $groupedByNamespace[$fn->namespace][] = $fn; + $grouped[$fn->namespace][] = $fn; } + return $grouped; + } - foreach ($groupedByNamespace as $namespace => $fns) { - - $result[] = ""; - $result[] = "---"; - $result[] = ""; - $result[] = "## `{$namespace}`"; - - /** @var PhelFunction $fn */ - foreach ($fns as $fn) { - $result[] = "### `{$fn->nameWithNamespace()}`"; - if (isset($fn->meta['deprecated'])) { - $deprecatedMessage = sprintf( - 'Deprecated: %s', - $fn->meta['deprecated'] - ); - if (isset($fn->meta['superseded-by'])) { - $supersededBy = $fn->meta['superseded-by']; - $deprecatedMessage .= sprintf( - ' — Use [`%s`](#%s) instead', - $supersededBy, - $supersededBy - ); - } - $deprecatedMessage .= ''; - $result[] = $deprecatedMessage; - } - $result[] = $fn->doc; - if ($fn->githubUrl !== '') { - $result[] = sprintf('[[View source](%s)]', $fn->githubUrl); - } elseif ($fn->docUrl !== '') { - $result[] = sprintf('[[Read more](%s)]', $fn->docUrl); - } - } + /** + * @param list $functions + * @return list + */ + private function buildNamespaceSection(string $namespace, array $functions): array + { + $lines = [ + '', + '---', + '', + "## `{$namespace}`", + ]; + + foreach ($functions as $fn) { + $lines = array_merge($lines, $this->buildFunctionSection($fn)); } - return $result; + return $lines; } /** * @return list */ - private function zolaHeaders(): array + private function buildFunctionSection(PhelFunction $fn): array { - $result = []; - $result[] = '+++'; - $result[] = 'title = "API"'; - $result[] = 'weight = 110'; - $result[] = 'template = "page-api.html"'; - $result[] = 'aliases = [ "/api" ]'; - $result[] = '+++'; - $result[] = ''; + $lines = ["### `{$fn->nameWithNamespace()}`"]; - return $result; + if ($deprecation = $this->buildDeprecationNotice($fn)) { + $lines[] = $deprecation; + } + + $lines[] = $fn->doc; + + if ($example = $this->buildExampleSection($fn)) { + $lines = array_merge($lines, $example); + } + + if ($seeAlso = $this->buildSeeAlsoSection($fn)) { + $lines = array_merge($lines, $seeAlso); + } + + if ($sourceLink = $this->buildSourceLink($fn)) { + $lines[] = $sourceLink; + } + + return $lines; + } + + private function buildDeprecationNotice(PhelFunction $fn): ?string + { + if (!isset($fn->meta['deprecated'])) { + return null; + } + + $message = sprintf( + 'Deprecated: %s', + $fn->meta['deprecated'] + ); + + if (isset($fn->meta['superseded-by'])) { + $supersededBy = $fn->meta['superseded-by']; + $anchor = $this->sanitizeAnchor($supersededBy); + $message .= sprintf( + ' — Use [`%s`](#%s) instead', + $supersededBy, + $anchor + ); + } + + return $message . ''; + } + + /** + * @return list|null + */ + private function buildExampleSection(PhelFunction $fn): ?array + { + if (!isset($fn->meta['example'])) { + return null; + } + + return [ + '', + '**Example:**', + '', + '```phel', + $fn->meta['example'], + '```', + ]; + } + + /** + * @return list|null + */ + private function buildSeeAlsoSection(PhelFunction $fn): ?array + { + if (!isset($fn->meta['see-also'])) { + return null; + } + + $functionNames = $this->extractFunctionNames($fn->meta['see-also']); + $links = $this->buildFunctionLinks($functionNames); + + return [ + '', + '**See also:** ' . implode(', ', $links), + ]; + } + + /** + * @return list + */ + private function extractFunctionNames(mixed $seeAlso): array + { + return array_map( + fn(Symbol $symbol) => $symbol->getName(), + iterator_to_array($seeAlso) + ); + } + + /** + * @param list $functionNames + * @return list + */ + private function buildFunctionLinks(array $functionNames): array + { + return array_map( + fn(string $func) => sprintf( + '[`%s`](#%s)', + $func, + $this->sanitizeAnchor($func) + ), + $functionNames + ); + } + + private function buildSourceLink(PhelFunction $fn): ?string + { + if ($fn->githubUrl !== '') { + return sprintf('[[View source](%s)]', $fn->githubUrl); + } + + if ($fn->docUrl !== '') { + return sprintf('[[Read more](%s)]', $fn->docUrl); + } + + return null; + } + + /** + * Sanitize function name to match Zola's anchor generation. + * Removes special characters that Zola doesn't include in anchors. + * + * Examples: + * "empty?" becomes "empty" + * "set!" becomes "set" + * "php-array-to-map" stays "php-array-to-map" + */ + private function sanitizeAnchor(string $funcName): string + { + return preg_replace('/[^a-zA-Z0-9_-]/', '', $funcName); + } + + /** + * @return list + */ + private function buildZolaHeaders(): array + { + return [ + '+++', + 'title = "API"', + 'weight = 110', + 'template = "page-api.html"', + 'aliases = [ "/api" ]', + '+++', + '', + ]; } } diff --git a/composer.json b/composer.json index 225f5fd..59d8816 100644 --- a/composer.json +++ b/composer.json @@ -11,7 +11,7 @@ "require": { "php": ">=8.3", "ext-json": "*", - "phel-lang/phel-lang": "^0.26", + "phel-lang/phel-lang": "dev-main", "gacela-project/gacela": "^1.12" }, "require-dev": { @@ -46,5 +46,12 @@ "post-update-cmd": [ "php build/update-phel-version.php" ] + }, + "repositories": [ + { + "type": "path", + "url": "/Users/chema/Code/phel-lang/phel-lang" } + ] + } diff --git a/composer.lock b/composer.lock index ab61ecb..c037a4c 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "ea61b8a3d17d6af0a6cbf284b949e651", + "content-hash": "bb0b9827f5c2d4c467d3bb370193d32f", "packages": [ { "name": "gacela-project/container", @@ -160,17 +160,11 @@ }, { "name": "phel-lang/phel-lang", - "version": "v0.26.0", - "source": { - "type": "git", - "url": "https://github.com/phel-lang/phel-lang.git", - "reference": "2ccab192ffe8a4a25410bbfae5fb8762b7fb450d" - }, + "version": "dev-main", "dist": { - "type": "zip", - "url": "https://api.github.com/repos/phel-lang/phel-lang/zipball/2ccab192ffe8a4a25410bbfae5fb8762b7fb450d", - "reference": "2ccab192ffe8a4a25410bbfae5fb8762b7fb450d", - "shasum": "" + "type": "path", + "url": "/Users/chema/Code/phel-lang/phel-lang", + "reference": "9474b9c8f7113e5776197deca9fc45d04fb5945f" }, "require": { "gacela-project/gacela": "^1.12", @@ -202,7 +196,72 @@ "src/Phel.php" ] }, - "notification-url": "https://packagist.org/downloads/", + "autoload-dev": { + "psr-4": { + "PhelTest\\": "tests/php" + } + }, + "scripts": { + "csfix": [ + "./vendor/bin/php-cs-fixer fix" + ], + "csrun": [ + "./vendor/bin/php-cs-fixer fix --dry-run" + ], + "fix": [ + "@rector", + "@csfix" + ], + "phpbench": [ + "./vendor/bin/phpbench run --report=aggregate --ansi" + ], + "phpbench-base": [ + "./vendor/bin/phpbench run --tag=baseline --report=aggregate --progress=plain --ansi" + ], + "phpbench-ref": [ + "./vendor/bin/phpbench run --ref=baseline --report=aggregate --progress=plain --ansi" + ], + "phpstan": [ + "./vendor/bin/phpstan --memory-limit=1G" + ], + "psalm": [ + "./vendor/bin/psalm --no-cache" + ], + "rector": [ + "./vendor/bin/rector process" + ], + "rectorrun": [ + "./vendor/bin/rector process --dry-run" + ], + "static-clear-cache": [ + "vendor/bin/psalm --clear-cache", + "vendor/bin/phpstan clear-result-cache" + ], + "test": [ + "@test-all" + ], + "test-all": [ + "@static-clear-cache", + "@test-quality", + "@test-compiler", + "@test-core" + ], + "test-compiler": [ + "./vendor/bin/phpunit --testsuite=unit,integration --log-junit=data/log-junit.xml" + ], + "test-compiler:coverage": [ + "XDEBUG_MODE=coverage ./vendor/bin/phpunit --testsuite=unit,integration --coverage-html=data/coverage-html --coverage-xml=data/coverage-xml --log-junit=data/coverage-xml/junit.xml" + ], + "test-core": [ + "./bin/phel test" + ], + "test-quality": [ + "@csrun", + "@psalm", + "@phpstan", + "@rectorrun" + ] + }, "license": [ "MIT" ], @@ -225,17 +284,9 @@ "lisp", "phel" ], - "support": { - "issues": "https://github.com/phel-lang/phel-lang/issues", - "source": "https://github.com/phel-lang/phel-lang/tree/v0.26.0" - }, - "funding": [ - { - "url": "https://chemaclass.com/sponsor", - "type": "custom" - } - ], - "time": "2025-11-16T15:58:36+00:00" + "transport-options": { + "relative": false + } }, { "name": "phpunit/php-timer", @@ -3721,6 +3772,7 @@ "aliases": [], "minimum-stability": "dev", "stability-flags": { + "phel-lang/phel-lang": 20, "roave/security-advisories": 20 }, "prefer-stable": true, diff --git a/config.toml b/config.toml index f2bef92..6065381 100644 --- a/config.toml +++ b/config.toml @@ -28,4 +28,4 @@ extra_syntaxes_and_themes = ["syntaxes"] # Put all your custom variables here repo_content_url = "https://github.com/phel-lang/phel-lang.org/blob/master/content/" -phel_version = "v0.26.0" +phel_version = "v0.26.0-beta#e7dcc5f" From 32bd92d531462c1a2f52ae2074898669e01f2e46 Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Thu, 20 Nov 2025 01:37:01 +0100 Subject: [PATCH 2/4] remove smooth scroll behaviour --- css/base.css | 1 - 1 file changed, 1 deletion(-) diff --git a/css/base.css b/css/base.css index 230a6c1..e31ee2d 100644 --- a/css/base.css +++ b/css/base.css @@ -12,7 +12,6 @@ } html { - scroll-behavior: smooth; background-color: white; -webkit-text-size-adjust: 100%; -moz-tab-size: 4; From d01a27bdab468c0fb9e81384bfb366877fa60b1c Mon Sep 17 00:00:00 2001 From: Chemaclass Date: Thu, 20 Nov 2025 01:54:51 +0100 Subject: [PATCH 3/4] update phel --- composer.json | 7 --- composer.lock | 135 ++++++++++++++++---------------------------------- config.toml | 2 +- 3 files changed, 45 insertions(+), 99 deletions(-) diff --git a/composer.json b/composer.json index 59d8816..acf13c6 100644 --- a/composer.json +++ b/composer.json @@ -46,12 +46,5 @@ "post-update-cmd": [ "php build/update-phel-version.php" ] - }, - "repositories": [ - { - "type": "path", - "url": "/Users/chema/Code/phel-lang/phel-lang" } - ] - } diff --git a/composer.lock b/composer.lock index c037a4c..0d74f29 100644 --- a/composer.lock +++ b/composer.lock @@ -4,7 +4,7 @@ "Read more about it at https://getcomposer.org/doc/01-basic-usage.md#installing-dependencies", "This file is @generated automatically" ], - "content-hash": "bb0b9827f5c2d4c467d3bb370193d32f", + "content-hash": "cacf2b085f71571868bce9b046fc74b9", "packages": [ { "name": "gacela-project/container", @@ -161,10 +161,16 @@ { "name": "phel-lang/phel-lang", "version": "dev-main", + "source": { + "type": "git", + "url": "https://github.com/phel-lang/phel-lang.git", + "reference": "e82dc40486b1c3d1e094cd1d97be6764e7cad5d3" + }, "dist": { - "type": "path", - "url": "/Users/chema/Code/phel-lang/phel-lang", - "reference": "9474b9c8f7113e5776197deca9fc45d04fb5945f" + "type": "zip", + "url": "https://api.github.com/repos/phel-lang/phel-lang/zipball/e82dc40486b1c3d1e094cd1d97be6764e7cad5d3", + "reference": "e82dc40486b1c3d1e094cd1d97be6764e7cad5d3", + "shasum": "" }, "require": { "gacela-project/gacela": "^1.12", @@ -184,6 +190,7 @@ "symfony/var-dumper": "^7.3", "vimeo/psalm": "^6.13" }, + "default-branch": true, "bin": [ "bin/phel" ], @@ -196,72 +203,7 @@ "src/Phel.php" ] }, - "autoload-dev": { - "psr-4": { - "PhelTest\\": "tests/php" - } - }, - "scripts": { - "csfix": [ - "./vendor/bin/php-cs-fixer fix" - ], - "csrun": [ - "./vendor/bin/php-cs-fixer fix --dry-run" - ], - "fix": [ - "@rector", - "@csfix" - ], - "phpbench": [ - "./vendor/bin/phpbench run --report=aggregate --ansi" - ], - "phpbench-base": [ - "./vendor/bin/phpbench run --tag=baseline --report=aggregate --progress=plain --ansi" - ], - "phpbench-ref": [ - "./vendor/bin/phpbench run --ref=baseline --report=aggregate --progress=plain --ansi" - ], - "phpstan": [ - "./vendor/bin/phpstan --memory-limit=1G" - ], - "psalm": [ - "./vendor/bin/psalm --no-cache" - ], - "rector": [ - "./vendor/bin/rector process" - ], - "rectorrun": [ - "./vendor/bin/rector process --dry-run" - ], - "static-clear-cache": [ - "vendor/bin/psalm --clear-cache", - "vendor/bin/phpstan clear-result-cache" - ], - "test": [ - "@test-all" - ], - "test-all": [ - "@static-clear-cache", - "@test-quality", - "@test-compiler", - "@test-core" - ], - "test-compiler": [ - "./vendor/bin/phpunit --testsuite=unit,integration --log-junit=data/log-junit.xml" - ], - "test-compiler:coverage": [ - "XDEBUG_MODE=coverage ./vendor/bin/phpunit --testsuite=unit,integration --coverage-html=data/coverage-html --coverage-xml=data/coverage-xml --log-junit=data/coverage-xml/junit.xml" - ], - "test-core": [ - "./bin/phel test" - ], - "test-quality": [ - "@csrun", - "@psalm", - "@phpstan", - "@rectorrun" - ] - }, + "notification-url": "https://packagist.org/downloads/", "license": [ "MIT" ], @@ -284,9 +226,17 @@ "lisp", "phel" ], - "transport-options": { - "relative": false - } + "support": { + "issues": "https://github.com/phel-lang/phel-lang/issues", + "source": "https://github.com/phel-lang/phel-lang/tree/main" + }, + "funding": [ + { + "url": "https://chemaclass.com/sponsor", + "type": "custom" + } + ], + "time": "2025-11-20T00:43:08+00:00" }, { "name": "phpunit/php-timer", @@ -1692,12 +1642,12 @@ "source": { "type": "git", "url": "https://github.com/Roave/SecurityAdvisories.git", - "reference": "6c7e6e7ebf679f9228c82ec3f7a432b4e8df538e" + "reference": "070af2db86d1502f430fd627a045e7b078abf63f" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/Roave/SecurityAdvisories/zipball/6c7e6e7ebf679f9228c82ec3f7a432b4e8df538e", - "reference": "6c7e6e7ebf679f9228c82ec3f7a432b4e8df538e", + "url": "https://api.github.com/repos/Roave/SecurityAdvisories/zipball/070af2db86d1502f430fd627a045e7b078abf63f", + "reference": "070af2db86d1502f430fd627a045e7b078abf63f", "shasum": "" }, "conflict": { @@ -1750,7 +1700,7 @@ "aws/aws-sdk-php": "<3.288.1", "azuracast/azuracast": "<0.18.3", "b13/seo_basics": "<0.8.2", - "backdrop/backdrop": "<1.27.3|>=1.28,<1.28.2", + "backdrop/backdrop": "<=1.32", "backpack/crud": "<3.4.9", "backpack/filemanager": "<2.0.2|>=3,<3.0.9", "bacula-web/bacula-web": "<9.7.1", @@ -1847,6 +1797,7 @@ "derhansen/sf_event_mgt": "<4.3.1|>=5,<5.1.1|>=7,<7.4", "desperado/xml-bundle": "<=0.1.7", "dev-lancer/minecraft-motd-parser": "<=1.0.5", + "devcode-it/openstamanager": "<=2.9.4", "devgroup/dotplant": "<2020.09.14-dev", "digimix/wp-svg-upload": "<=1", "directmailteam/direct-mail": "<6.0.3|>=7,<7.0.3|>=8,<9.5.2", @@ -1876,10 +1827,11 @@ "drupal/commerce_alphabank_redirect": "<1.0.3", "drupal/commerce_eurobank_redirect": "<2.1.1", "drupal/config_split": "<1.10|>=2,<2.0.2", - "drupal/core": ">=6,<6.38|>=7,<7.102|>=8,<10.3.14|>=10.4,<10.4.5|>=11,<11.0.13|>=11.1,<11.1.5", + "drupal/core": ">=6,<6.38|>=7,<7.102|>=8,<10.4.9|>=10.5,<10.5.6|>=11,<11.1.9|>=11.2,<11.2.8", "drupal/core-recommended": ">=7,<7.102|>=8,<10.2.11|>=10.3,<10.3.9|>=11,<11.0.8", "drupal/currency": "<3.5", "drupal/drupal": ">=5,<5.11|>=6,<6.38|>=7,<7.102|>=8,<10.2.11|>=10.3,<10.3.9|>=11,<11.0.8", + "drupal/email_tfa": "<2.0.6", "drupal/formatter_suite": "<2.1", "drupal/gdpr": "<3.0.1|>=3.1,<3.1.2", "drupal/google_tag": "<1.8|>=2,<2.0.8", @@ -1895,6 +1847,7 @@ "drupal/quick_node_block": "<2", "drupal/rapidoc_elements_field_formatter": "<1.0.1", "drupal/reverse_proxy_header": "<1.1.2", + "drupal/simple_multistep": "<2", "drupal/simple_oauth": ">=6,<6.0.7", "drupal/spamspan": "<3.2.1", "drupal/tfa": "<1.10", @@ -1987,7 +1940,7 @@ "geshi/geshi": "<=1.0.9.1", "getformwork/formwork": "<1.13.1|>=2.0.0.0-beta1,<2.0.0.0-beta4", "getgrav/grav": "<1.7.46", - "getkirby/cms": "<3.9.8.3-dev|>=3.10,<3.10.1.2-dev|>=4,<4.7.1", + "getkirby/cms": "<3.9.8.3-dev|>=3.10,<3.10.1.2-dev|>=4,<4.7.1|>=5,<5.1.4", "getkirby/kirby": "<3.9.8.3-dev|>=3.10,<3.10.1.2-dev|>=4,<4.7.1", "getkirby/panel": "<2.5.14", "getkirby/starterkit": "<=3.7.0.2", @@ -2167,6 +2120,7 @@ "modx/revolution": "<=3.1", "mojo42/jirafeau": "<4.4", "mongodb/mongodb": ">=1,<1.9.2", + "mongodb/mongodb-extension": "<1.21.2", "monolog/monolog": ">=1.8,<1.12", "moodle/moodle": "<4.4.11|>=4.5.0.0-beta,<4.5.7|>=5.0.0.0-beta,<5.0.3", "moonshine/moonshine": "<=3.12.5", @@ -2174,10 +2128,9 @@ "movim/moxl": ">=0.8,<=0.10", "movingbytes/social-network": "<=1.2.1", "mpdf/mpdf": "<=7.1.7", - "munkireport/comment": "<4.1", + "munkireport/comment": "<4", "munkireport/managedinstalls": "<2.6", "munkireport/munki_facts": "<1.5", - "munkireport/munkireport": ">=2.5.3,<5.6.3", "munkireport/reportdata": "<3.5", "munkireport/softwareupdate": "<1.6", "mustache/mustache": ">=2,<2.14.1", @@ -2262,7 +2215,7 @@ "phpmailer/phpmailer": "<6.5", "phpmussel/phpmussel": ">=1,<1.6", "phpmyadmin/phpmyadmin": "<5.2.2", - "phpmyfaq/phpmyfaq": "<3.2.5|==3.2.5|>=3.2.10,<=4.0.1", + "phpmyfaq/phpmyfaq": "<=4.0.13", "phpoffice/common": "<0.2.9", "phpoffice/math": "<=0.2", "phpoffice/phpexcel": "<=1.8.2", @@ -2483,7 +2436,7 @@ "thelia/thelia": ">=2.1,<2.1.3", "theonedemon/phpwhois": "<=4.2.5", "thinkcmf/thinkcmf": "<6.0.8", - "thorsten/phpmyfaq": "<=4.0.1|>=4.0.7,<4.0.13", + "thorsten/phpmyfaq": "<=4.0.13", "tikiwiki/tiki-manager": "<=17.1", "timber/timber": ">=0.16.6,<1.23.1|>=1.24,<1.24.1|>=2,<2.1", "tinymce/tinymce": "<7.2", @@ -2676,7 +2629,7 @@ "type": "tidelift" } ], - "time": "2025-11-14T21:05:13+00:00" + "time": "2025-11-19T21:05:11+00:00" }, { "name": "sebastian/cli-parser", @@ -3720,16 +3673,16 @@ }, { "name": "theseer/tokenizer", - "version": "1.3.0", + "version": "1.3.1", "source": { "type": "git", "url": "https://github.com/theseer/tokenizer.git", - "reference": "d74205c497bfbca49f34d4bc4c19c17e22db4ebb" + "reference": "b7489ce515e168639d17feec34b8847c326b0b3c" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/theseer/tokenizer/zipball/d74205c497bfbca49f34d4bc4c19c17e22db4ebb", - "reference": "d74205c497bfbca49f34d4bc4c19c17e22db4ebb", + "url": "https://api.github.com/repos/theseer/tokenizer/zipball/b7489ce515e168639d17feec34b8847c326b0b3c", + "reference": "b7489ce515e168639d17feec34b8847c326b0b3c", "shasum": "" }, "require": { @@ -3758,7 +3711,7 @@ "description": "A small library for converting tokenized PHP source code into XML and potentially other formats", "support": { "issues": "https://github.com/theseer/tokenizer/issues", - "source": "https://github.com/theseer/tokenizer/tree/1.3.0" + "source": "https://github.com/theseer/tokenizer/tree/1.3.1" }, "funding": [ { @@ -3766,7 +3719,7 @@ "type": "github" } ], - "time": "2025-11-13T13:44:09+00:00" + "time": "2025-11-17T20:03:58+00:00" } ], "aliases": [], @@ -3781,7 +3734,7 @@ "php": ">=8.3", "ext-json": "*" }, - "platform-dev": [], + "platform-dev": {}, "platform-overrides": { "php": "8.3" }, diff --git a/config.toml b/config.toml index 6065381..f2bef92 100644 --- a/config.toml +++ b/config.toml @@ -28,4 +28,4 @@ extra_syntaxes_and_themes = ["syntaxes"] # Put all your custom variables here repo_content_url = "https://github.com/phel-lang/phel-lang.org/blob/master/content/" -phel_version = "v0.26.0-beta#e7dcc5f" +phel_version = "v0.26.0" From bbc90e884224215b183cadb41e0ce487cc60b72a Mon Sep 17 00:00:00 2001 From: JesusValera Date: Wed, 26 Nov 2025 00:02:06 +0100 Subject: [PATCH 4/4] Improve API documentation page --- .../Application/ApiMarkdownGenerator.php | 52 +++++++++---------- .../Domain/ApiMarkdownGeneratorTest.php | 13 +++-- composer.lock | 23 ++++---- 3 files changed, 45 insertions(+), 43 deletions(-) diff --git a/build/src/ApiGenerator/Application/ApiMarkdownGenerator.php b/build/src/ApiGenerator/Application/ApiMarkdownGenerator.php index 68dcb5c..6cb003b 100644 --- a/build/src/ApiGenerator/Application/ApiMarkdownGenerator.php +++ b/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('/(?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( 'Deprecated: %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( ' — 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" ]', '+++', - '', ]; } } diff --git a/build/tests/php/ApiGenerator/Domain/ApiMarkdownGeneratorTest.php b/build/tests/php/ApiGenerator/Domain/ApiMarkdownGeneratorTest.php index 8ec0997..fbf7e60 100644 --- a/build/tests/php/ApiGenerator/Domain/ApiMarkdownGeneratorTest.php +++ b/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()); diff --git a/composer.lock b/composer.lock index 0d74f29..7c926b8 100644 --- a/composer.lock +++ b/composer.lock @@ -164,12 +164,12 @@ "source": { "type": "git", "url": "https://github.com/phel-lang/phel-lang.git", - "reference": "e82dc40486b1c3d1e094cd1d97be6764e7cad5d3" + "reference": "c6c96d7562ffbf9427889f2892e3764af774fbad" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/phel-lang/phel-lang/zipball/e82dc40486b1c3d1e094cd1d97be6764e7cad5d3", - "reference": "e82dc40486b1c3d1e094cd1d97be6764e7cad5d3", + "url": "https://api.github.com/repos/phel-lang/phel-lang/zipball/c6c96d7562ffbf9427889f2892e3764af774fbad", + "reference": "c6c96d7562ffbf9427889f2892e3764af774fbad", "shasum": "" }, "require": { @@ -236,7 +236,7 @@ "type": "custom" } ], - "time": "2025-11-20T00:43:08+00:00" + "time": "2025-11-25T23:00:43+00:00" }, { "name": "phpunit/php-timer", @@ -1642,12 +1642,12 @@ "source": { "type": "git", "url": "https://github.com/Roave/SecurityAdvisories.git", - "reference": "070af2db86d1502f430fd627a045e7b078abf63f" + "reference": "ccd1dbf6d6823ddeb0c9d800a77740abff191e07" }, "dist": { "type": "zip", - "url": "https://api.github.com/repos/Roave/SecurityAdvisories/zipball/070af2db86d1502f430fd627a045e7b078abf63f", - "reference": "070af2db86d1502f430fd627a045e7b078abf63f", + "url": "https://api.github.com/repos/Roave/SecurityAdvisories/zipball/ccd1dbf6d6823ddeb0c9d800a77740abff191e07", + "reference": "ccd1dbf6d6823ddeb0c9d800a77740abff191e07", "shasum": "" }, "conflict": { @@ -1773,7 +1773,7 @@ "contao/comments-bundle": ">=2,<4.13.40|>=5.0.0.0-RC1-dev,<5.3.4", "contao/contao": ">=3,<3.5.37|>=4,<4.4.56|>=4.5,<4.13.56|>=5,<5.3.38|>=5.4.0.0-RC1-dev,<5.6.1", "contao/core": "<3.5.39", - "contao/core-bundle": "<4.13.56|>=5,<5.3.38|>=5.4,<5.6.1", + "contao/core-bundle": "<4.13.57|>=5,<5.3.42|>=5.4,<5.6.5", "contao/listing-bundle": ">=3,<=3.5.30|>=4,<4.4.8", "contao/managed-edition": "<=1.5", "corveda/phpsandbox": "<1.3.5", @@ -1938,7 +1938,7 @@ "genix/cms": "<=1.1.11", "georgringer/news": "<1.3.3", "geshi/geshi": "<=1.0.9.1", - "getformwork/formwork": "<1.13.1|>=2.0.0.0-beta1,<2.0.0.0-beta4", + "getformwork/formwork": "<2.2", "getgrav/grav": "<1.7.46", "getkirby/cms": "<3.9.8.3-dev|>=3.10,<3.10.1.2-dev|>=4,<4.7.1|>=5,<5.1.4", "getkirby/kirby": "<3.9.8.3-dev|>=3.10,<3.10.1.2-dev|>=4,<4.7.1", @@ -2220,6 +2220,7 @@ "phpoffice/math": "<=0.2", "phpoffice/phpexcel": "<=1.8.2", "phpoffice/phpspreadsheet": "<1.30|>=2,<2.1.12|>=2.2,<2.4|>=3,<3.10|>=4,<5", + "phppgadmin/phppgadmin": "<=7.13", "phpseclib/phpseclib": "<2.0.47|>=3,<3.0.36", "phpservermon/phpservermon": "<3.6", "phpsysinfo/phpsysinfo": "<3.4.3", @@ -2344,7 +2345,7 @@ "slim/slim": "<2.6", "slub/slub-events": "<3.0.3", "smarty/smarty": "<4.5.3|>=5,<5.1.1", - "snipe/snipe-it": "<8.1.18", + "snipe/snipe-it": "<=8.3.4", "socalnick/scn-social-auth": "<1.15.2", "socialiteproviders/steam": "<1.1", "solspace/craft-freeform": ">=5,<5.10.16", @@ -2629,7 +2630,7 @@ "type": "tidelift" } ], - "time": "2025-11-19T21:05:11+00:00" + "time": "2025-11-25T21:05:31+00:00" }, { "name": "sebastian/cli-parser",