Skip to content

Commit 5a7f62c

Browse files
ChemaclassChemaclass
committed
feat: group api page top by namespaces
1 parent 406aec7 commit 5a7f62c

File tree

7 files changed

+121
-81
lines changed

7 files changed

+121
-81
lines changed

‎build/src/php/FileGenerator/Application/ApiMarkdownGenerator.php‎

Lines changed: 23 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -21,17 +21,29 @@ public function generate(): array
2121
{
2222
$result = $this->zolaHeaders();
2323

24-
/** @var list<PhelFunction> $groupedPhelFns */
25-
$groupedPhelFns = $this->apiFacade->getPhelFunctions();
26-
27-
foreach ($groupedPhelFns as $fn) {
28-
$result[] = "## `{$fn->name()}`";
29-
$result[] = "<small><strong>Namespace</strong> `{$fn->namespace()}`</small>";
30-
$result[] = $fn->doc();
31-
if ($fn->githubUrl() !== '') {
32-
$result[] = sprintf('<small>[[View source](%s)]</small>', $fn->githubUrl());
33-
}elseif ($fn->docUrl() !== '') {
34-
$result[] = sprintf('<small>[[Read more](%s)]</small>', $fn->docUrl());
24+
/** @var list<PhelFunction> $phelFns */
25+
$phelFns = $this->apiFacade->getPhelFunctions();
26+
27+
$groupedByNamespace = [];
28+
foreach ($phelFns as $fn) {
29+
$groupedByNamespace[$fn->namespace()][] = $fn;
30+
}
31+
32+
foreach ($groupedByNamespace as $namespace => $fns) {
33+
34+
$result[] = "";
35+
$result[] = "---";
36+
$result[] = "";
37+
$result[] = "## `{$namespace}`";
38+
39+
foreach ($fns as $fn) {
40+
$result[] = "### `{$fn->nameWithNamespace()}`";
41+
$result[] = $fn->doc();
42+
if ($fn->githubUrl() !== '') {
43+
$result[] = sprintf('<small>[[View source](%s)]</small>', $fn->githubUrl());
44+
} elseif ($fn->docUrl() !== '') {
45+
$result[] = sprintf('<small>[[Read more](%s)]</small>', $fn->docUrl());
46+
}
3547
}
3648
}
3749

‎build/src/php/FileGenerator/Application/ApiSearchGenerator.php‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -46,14 +46,14 @@ public function generateSearchIndex(): array
4646
$anchor = $groupKey;
4747
$groupFnNameAppearances[$groupKey]++;
4848
} else {
49-
$sanitizedFnName = str_replace(['/', ...self::SPECIAL_ENDING_CHARS], ['-', ''], $fn->fnName());
49+
$sanitizedFnName = str_replace(['/', ...self::SPECIAL_ENDING_CHARS], ['-', ''], $fn->name());
5050
$anchor = rtrim($sanitizedFnName, '-') . '-' . $groupFnNameAppearances[$groupKey]++;
5151
}
5252

5353
$result[] = [
5454
'id' => 'api_' . $fn->name(),
55-
'fnName' => $fn->name(),
56-
'fnSignature' => $fn->signature(),
55+
'name' => $fn->nameWithNamespace(),
56+
'signature' => $fn->signature(),
5757
'desc' => $this->formatDescription($fn->description()),
5858
'anchor' => $anchor,
5959
'type' => 'api',

‎build/tests/php/FileGenerator/Domain/ApiMarkdownGeneratorTest.php‎

Lines changed: 31 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -36,9 +36,10 @@ public function test_generate_page_with_one_phel_function(): void
3636
$apiFacade->method('getPhelFunctions')
3737
->willReturn([
3838
PhelFunction::fromArray([
39-
'fnName' => 'function-1',
39+
'name' => 'function-1',
4040
'doc' => 'The doc from function 1',
4141
'groupKey' => 'group-1',
42+
'namespace' => 'ns-1',
4243
]),
4344
]);
4445

@@ -52,7 +53,11 @@ public function test_generate_page_with_one_phel_function(): void
5253
'aliases = [ "/api" ]',
5354
'+++',
5455
'',
55-
'## `function-1`',
56+
'',
57+
'---',
58+
'',
59+
'## `ns-1`',
60+
'### `ns-1/function-1`',
5661
'The doc from function 1',
5762
];
5863

@@ -65,12 +70,14 @@ public function test_generate_page_with_multiple_phel_functions_in_same_group():
6570
$apiFacade->method('getPhelFunctions')
6671
->willReturn([
6772
PhelFunction::fromArray([
68-
'fnName' => 'function-1',
73+
'name' => 'function-1',
6974
'doc' => 'The doc from function 1',
75+
'namespace' => 'core',
7076
]),
7177
PhelFunction::fromArray([
72-
'fnName' => 'function-2',
78+
'name' => 'function-2',
7379
'doc' => 'The doc from function 2',
80+
'namespace' => 'core',
7481
]),
7582
]);
7683

@@ -84,9 +91,13 @@ public function test_generate_page_with_multiple_phel_functions_in_same_group():
8491
'aliases = [ "/api" ]',
8592
'+++',
8693
'',
87-
'## `function-1`',
94+
'',
95+
'---',
96+
'',
97+
'## `core`',
98+
'### `function-1`',
8899
'The doc from function 1',
89-
'## `function-2`',
100+
'### `function-2`',
90101
'The doc from function 2',
91102
];
92103

@@ -99,12 +110,14 @@ public function test_generate_page_with_multiple_phel_functions_in_different_gro
99110
$apiFacade->method('getPhelFunctions')
100111
->willReturn([
101112
PhelFunction::fromArray([
102-
'fnName' => 'function-1',
113+
'name' => 'function-1',
103114
'doc' => 'The doc from function 1',
115+
'namespace' => 'ns-1',
104116
]),
105117
PhelFunction::fromArray([
106-
'fnName' => 'function-2',
118+
'name' => 'function-2',
107119
'doc' => 'The doc from function 2',
120+
'namespace' => 'ns-2',
108121
]),
109122
]);
110123

@@ -118,9 +131,17 @@ public function test_generate_page_with_multiple_phel_functions_in_different_gro
118131
'aliases = [ "/api" ]',
119132
'+++',
120133
'',
121-
'## `function-1`',
134+
'',
135+
'---',
136+
'',
137+
'## `ns-1`',
138+
'### `ns-1/function-1`',
122139
'The doc from function 1',
123-
'## `function-2`',
140+
'',
141+
'---',
142+
'',
143+
'## `ns-2`',
144+
'### `ns-2/function-2`',
124145
'The doc from function 2',
125146
];
126147

‎build/tests/php/FileGenerator/Domain/ApiSearchGeneratorTest.php‎

Lines changed: 44 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,8 @@ public function test_generate_search_index_one_item(): void
1717
$apiFacade->method('getPhelFunctions')
1818
->willReturn([
1919
PhelFunction::fromArray([
20-
'fnName' => 'table?',
21-
'fnSignature' => '(table? x)',
20+
'name' => 'table?',
21+
'signature' => '(table? x)',
2222
'desc' => 'doc for table?',
2323
'groupKey' => 'table'
2424
]),
@@ -30,8 +30,8 @@ public function test_generate_search_index_one_item(): void
3030
$expected = [
3131
[
3232
'id' => 'api_table?',
33-
'fnName' => 'table?',
34-
'fnSignature' => '(table? x)',
33+
'name' => 'table?',
34+
'signature' => '(table? x)',
3535
'desc' => 'doc for table?',
3636
'anchor' => 'table',
3737
'type' => 'api',
@@ -51,14 +51,14 @@ public function test_multiple_items_in_different_groups(): void
5151
$apiFacade->method('getPhelFunctions')
5252
->willReturn([
5353
PhelFunction::fromArray([
54-
'fnName' => 'table',
55-
'fnSignature' => '(table & xs)',
54+
'name' => 'table',
55+
'signature' => '(table & xs)',
5656
'desc' => 'doc for table',
5757
'groupKey' => 'table',
5858
]),
5959
PhelFunction::fromArray([
60-
'fnName' => 'not',
61-
'fnSignature' => '(not x)',
60+
'name' => 'not',
61+
'signature' => '(not x)',
6262
'desc' => 'doc for not',
6363
'groupKey' => 'not',
6464
]),
@@ -70,16 +70,16 @@ public function test_multiple_items_in_different_groups(): void
7070
$expected = [
7171
[
7272
'id' => 'api_table',
73-
'fnName' => 'table',
74-
'fnSignature' => '(table & xs)',
73+
'name' => 'table',
74+
'signature' => '(table & xs)',
7575
'desc' => 'doc for table',
7676
'anchor' => 'table',
7777
'type' => 'api',
7878
],
7979
[
8080
'id' => 'api_not',
81-
'fnName' => 'not',
82-
'fnSignature' => '(not x)',
81+
'name' => 'not',
82+
'signature' => '(not x)',
8383
'desc' => 'doc for not',
8484
'anchor' => 'not',
8585
'type' => 'api',
@@ -99,14 +99,14 @@ public function test_multiple_items_in_the_same_group(): void
9999
$apiFacade->method('getPhelFunctions')
100100
->willReturn([
101101
PhelFunction::fromArray([
102-
'fnName' => 'table',
103-
'fnSignature' => '(table & xs)',
102+
'name' => 'table',
103+
'signature' => '(table & xs)',
104104
'desc' => 'doc for table',
105105
'groupKey' => 'table',
106106
]),
107107
PhelFunction::fromArray([
108-
'fnName' => 'table?',
109-
'fnSignature' => '(table? x)',
108+
'name' => 'table?',
109+
'signature' => '(table? x)',
110110
'desc' => 'doc for table?',
111111
'groupKey' => 'table',
112112
]),
@@ -118,16 +118,16 @@ public function test_multiple_items_in_the_same_group(): void
118118
$expected = [
119119
[
120120
'id' => 'api_table',
121-
'fnName' => 'table',
122-
'fnSignature' => '(table & xs)',
121+
'name' => 'table',
122+
'signature' => '(table & xs)',
123123
'desc' => 'doc for table',
124124
'anchor' => 'table',
125125
'type' => 'api',
126126
],
127127
[
128128
'id' => 'api_table?',
129-
'fnName' => 'table?',
130-
'fnSignature' => '(table? x)',
129+
'name' => 'table?',
130+
'signature' => '(table? x)',
131131
'desc' => 'doc for table?',
132132
'anchor' => 'table-1',
133133
'type' => 'api',
@@ -147,14 +147,14 @@ public function test_fn_name_with_slash_in_the_middle(): void
147147
$apiFacade->method('getPhelFunctions')
148148
->willReturn([
149149
PhelFunction::fromArray([
150-
'fnName' => 'http/response',
151-
'fnSignature' => '',
150+
'name' => 'http/response',
151+
'signature' => '',
152152
'desc' => '',
153153
'groupKey' => 'http-response',
154154
]),
155155
PhelFunction::fromArray([
156-
'fnName' => 'http/response?',
157-
'fnSignature' => '',
156+
'name' => 'http/response?',
157+
'signature' => '',
158158
'desc' => '',
159159
'groupKey' => 'http-response-1',
160160
]),
@@ -166,16 +166,16 @@ public function test_fn_name_with_slash_in_the_middle(): void
166166
$expected = [
167167
[
168168
'id' => 'api_http/response',
169-
'fnName' => 'http/response',
170-
'fnSignature' => '',
169+
'name' => 'http/response',
170+
'signature' => '',
171171
'desc' => '',
172172
'anchor' => 'http-response',
173173
'type' => 'api',
174174
],
175175
[
176176
'id' => 'api_http/response?',
177-
'fnName' => 'http/response?',
178-
'fnSignature' => '',
177+
'name' => 'http/response?',
178+
'signature' => '',
179179
'desc' => '',
180180
'anchor' => 'http-response-1',
181181
'type' => 'api',
@@ -195,14 +195,14 @@ public function test_fn_name_ending_with_minus(): void
195195
$apiFacade->method('getPhelFunctions')
196196
->willReturn([
197197
PhelFunction::fromArray([
198-
'fnName' => 'defn',
199-
'fnSignature' => '',
198+
'name' => 'defn',
199+
'signature' => '',
200200
'desc' => '',
201201
'groupKey' => 'defn',
202202
]),
203203
PhelFunction::fromArray([
204-
'fnName' => 'defn-',
205-
'fnSignature' => '',
204+
'name' => 'defn-',
205+
'signature' => '',
206206
'desc' => '',
207207
'groupKey' => 'defn',
208208
]),
@@ -214,16 +214,16 @@ public function test_fn_name_ending_with_minus(): void
214214
$expected = [
215215
[
216216
'id' => 'api_defn',
217-
'fnName' => 'defn',
218-
'fnSignature' => '',
217+
'name' => 'defn',
218+
'signature' => '',
219219
'desc' => '',
220220
'anchor' => 'defn',
221221
'type' => 'api',
222222
],
223223
[
224224
'id' => 'api_defn-',
225-
'fnName' => 'defn-',
226-
'fnSignature' => '',
225+
'name' => 'defn-',
226+
'signature' => '',
227227
'desc' => '',
228228
'anchor' => 'defn-1',
229229
'type' => 'api',
@@ -243,14 +243,14 @@ public function test_fn_name_with_upper_case(): void
243243
$apiFacade->method('getPhelFunctions')
244244
->willReturn([
245245
PhelFunction::fromArray([
246-
'fnName' => 'NAN',
247-
'fnSignature' => '',
246+
'name' => 'NAN',
247+
'signature' => '',
248248
'desc' => '',
249249
'groupKey' => 'nan',
250250
]),
251251
PhelFunction::fromArray([
252-
'fnName' => 'nan?',
253-
'fnSignature' => '',
252+
'name' => 'nan?',
253+
'signature' => '',
254254
'desc' => '',
255255
'groupKey' => 'nan',
256256
]),
@@ -262,16 +262,16 @@ public function test_fn_name_with_upper_case(): void
262262
$expected = [
263263
[
264264
'id' => 'api_NAN',
265-
'fnName' => 'NAN',
266-
'fnSignature' => '',
265+
'name' => 'NAN',
266+
'signature' => '',
267267
'desc' => '',
268268
'anchor' => 'nan',
269269
'type' => 'api',
270270
],
271271
[
272272
'id' => 'api_nan?',
273-
'fnName' => 'nan?',
274-
'fnSignature' => '',
273+
'name' => 'nan?',
274+
'signature' => '',
275275
'desc' => '',
276276
'anchor' => 'nan-1',
277277
'type' => 'api',

0 commit comments

Comments
 (0)