Skip to content

Commit 89a7647

Browse files
ArtARTs36ArtARTs36
authored
[Docs] Update docs (#55)
* move examples to array item * upd doc * update rules page * print generic type * remove unless * remove unless * print rule description * print rule description * print rule description * update doc * add test * add doc * add doc * add doc * up doc * up doc * update comment * add space * change linter token
1 parent 50c285c commit 89a7647

19 files changed

+332
-62
lines changed

‎.github/workflows/review.yml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,7 @@ jobs:
3838

3939
- name: Review Pull Request
4040
env:
41-
MR_LINTER_GITHUB_HTTP_TOKEN: ${{ secrets.GITHUB_TOKEN }}
41+
MR_LINTER_GITHUB_HTTP_TOKEN: ${{ secrets.MR_LINTER_GITHUB_HTTP_TOKEN }}
4242
MR_LINTER_TELEGRAM_BOT_TOKEN: ${{ secrets.MR_LINTER_TELEGRAM_BOT_TOKEN }}
4343
MR_LINTER_TELEGRAM_CHAT_ID: ${{ secrets.MR_LINTER_TELEGRAM_CHAT_ID }}
4444
MR_LINTER_TIMEZONE: 'Europe/Moscow'

‎.mr-linter.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -111,3 +111,12 @@ comments:
111111
{% for note in result.notes %}
112112
- {{ note.description | raw }}
113113
{% endfor %}
114+
when:
115+
result.notes:
116+
isEmpty: false
117+
118+
- template: |
119+
I didn't find any notes in your Pull Request.
120+
when:
121+
result.notes:
122+
isEmpty: true

‎docs/Builder/ConfigJsonSchema/RuleSchemaGenerator.php

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -130,17 +130,17 @@ private function createRuleParamSchema(string $ruleClass, \ArtARTs36\MergeReques
130130
$paramSchema['description'] = $param->description;
131131
}
132132

133-
if ($param->hasExamples()) {
133+
if ($param->hasExamples() && ! $param->type->isGeneric()) {
134134
$paramSchema['examples'] = array_map(fn (Example $ex) => $ex->value, $param->examples);
135135
}
136136

137137
if ($param->type->isGeneric()) {
138-
$generic = $param->type->getObjectGeneric();
138+
$objGeneric = $param->type->getObjectGeneric();
139139

140-
if ($generic !== null) {
140+
if ($objGeneric !== null) {
141141
$genericProps = [];
142142

143-
foreach (Reflector::mapProperties($generic) as $property) {
143+
foreach (Reflector::mapProperties($objGeneric) as $property) {
144144
$genericProps[$property->name] = [
145145
'type' => JsonType::to($property->type->class ?? $property->type->name->value),
146146
];
@@ -160,6 +160,10 @@ private function createRuleParamSchema(string $ruleClass, \ArtARTs36\MergeReques
160160
$item['description'] = $param->description;
161161
}
162162

163+
if ($param->hasExamples()) {
164+
$item['examples'] = array_map(fn (Example $ex) => $ex->value, $param->examples);
165+
}
166+
163167
$paramSchema['items'] = [
164168
$item,
165169
];

‎docs/Builder/RulesPageBuilder.php

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,7 @@
66
use ArtARTs36\MergeRequestLinter\Application\Rule\Rules\DefaultRules;
77
use ArtARTs36\MergeRequestLinter\DocBuilder\ConfigJsonSchema\JsonType;
88
use ArtARTs36\MergeRequestLinter\Infrastructure\Text\Renderer\TwigRenderer;
9+
use ArtARTs36\MergeRequestLinter\Shared\DataStructure\Arrayee;
910
use ArtARTs36\MergeRequestLinter\Shared\DataStructure\ArrayMap;
1011
use ArtARTs36\MergeRequestLinter\Shared\Reflection\Instantiator\Finder;
1112
use ArtARTs36\MergeRequestLinter\Shared\Reflection\Instantiator\InstantiatorFinder;
@@ -41,16 +42,24 @@ public function build(): string
4142
$params = [];
4243

4344
foreach ($this->ruleConstructorFinder->find($ruleClass)->params() as $paramName => $param) {
45+
$paramType = JsonType::to($param->type->name());
46+
47+
if ($paramType === null) {
48+
continue;
49+
}
50+
4451
$params[] = [
4552
'name' => $paramName,
46-
'type' => JsonType::to($param->type->name()),
53+
'type' => $paramType,
4754
'generic' => $param->type->isGeneric() ? JsonType::to($param->type->generic) : null,
55+
'description' => $param->description,
56+
'examples' => new Arrayee($param->examples),
4857
];
4958
}
5059

5160
$rules[] = [
5261
'name' => $ruleName,
53-
'params' => $params,
62+
'params' => new Arrayee($params),
5463
'description' => $comment,
5564
'path' => $path,
5665
];
@@ -59,7 +68,7 @@ public function build(): string
5968
return TwigRenderer::create()->render(
6069
file_get_contents(__DIR__ . '/templates/rules.md.twig'),
6170
[
62-
'rules' => $rules,
71+
'rules' => new Arrayee($rules),
6372
],
6473
);
6574
}

‎docs/Builder/templates/rules.md.twig

Lines changed: 27 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,32 @@
22

33
Currently is available that rules:
44

5-
| Name | Description | Parameters |
6-
| ------------ | ------------ | ------------ |
5+
<table>
6+
<tbody>
7+
<tr>
8+
<td>Rule</td>
9+
<td>Description</td>
10+
<td colspan="3">Parameters</td>
11+
</tr>
712
{% for rule in rules %}
8-
| {{ rule.name }} | {{ rule.description }} |{% if rule.params|length == 0 %} None {% endif %}
9-
{% for param in rule.params%} `{{ param.name }}` - {{ param.type }} {% if param.generic %} of {{ param.generic }}s {% endif %} <br/> {% endfor%} |
13+
<tr>
14+
<td rowspan="{{ max(rule.params.count, 1) }}">{{ rule.name }}</td>
15+
{% if rule.params.isEmpty %}
16+
<td colspan="4">{{ rule.description }}</td>
17+
{% else %}
18+
<td rowspan="{{ max(rule.params.count, 1) }}">{{ rule.description }}</td>
19+
<td>{{ rule.params.first.name }}</td>
20+
<td>{{ rule.params.first.description }} {% if rule.params.first.examples.count > 0 %}<br/> Examples: {% for example in rule.params.first.examples %} {{ example }}{% if loop.last == false %},{% endif%} {% endfor %}{% endif %}</td>
21+
<td>{{ rule.params.first.type }}{% if rule.params.first.generic %} of {{ rule.params.first.generic }}s {% endif %}</td>
22+
{% endif %}
23+
</tr>
24+
{% for param in rule.params.skip(1) %}
25+
<tr>
26+
<td>{{ param.name }}</td>
27+
<td>{{ param.description }} {% if rule.params.first.examples.count > 0 %}<br/> Examples: {% for example in rule.params.first.examples %} {{ example }}{% if loop.last == false %},{% endif%} {% endfor %}{% endif %}</td>
28+
<td>{{ param.type }}{% if param.generic %} of {{ param.generic }}s {% endif %}</td>
29+
</tr>
1030
{% endfor %}
31+
{% endfor %}
32+
</tbody>
33+
</table>

‎docs/rules.md

Lines changed: 149 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,152 @@
22

33
Currently is available that rules:
44

5-
| Name | Description | Parameters |
6-
| ------------ | ------------ | ------------ |
7-
| @mr-linter/changed_files_limit | Check count changed files on a {limit}. | `limit` - integer <br/> |
8-
| @mr-linter/description_contains_links_of_any_domains | Merge Request must contain links of any {domains}. | `domains` - array of strings <br/> |
9-
| @mr-linter/description_contains_links_of_all_domains | Merge Request must contain links of all {domains}. | `domains` - array of strings <br/> |
10-
| @mr-linter/description_not_empty | The description must be filled. | None |
11-
| @mr-linter/has_all_labels | Merge Request must have all {labels} | `labels` - array of strings <br/> |
12-
| @mr-linter/has_any_labels | Merge Request must have any labels. | None |
13-
| @mr-linter/has_any_labels_of | Merge Request must have any {labels}. | `labels` - array of strings <br/> |
14-
| @mr-linter/jira/has_issue_link | The description must have a link to Jira on a {domain} with {projectCode}. | `domain` - string <br/> `projectCode` - string <br/> |
15-
| @mr-linter/youtrack/has_issue_link | The description must have a link to YouTrack issue on a {domain} with {projectCode}. | `domain` - string <br/> `projectCode` - string <br/> |
16-
| @mr-linter/title_must_starts_with_any_prefix | The title must starts with any {prefixes} | `prefixes` - array of strings <br/> |
17-
| @mr-linter/has_changes | Merge Request must have changes in {files}. | `changes` - array of objects <br/> |
18-
| @mr-linter/title_starts_with_task_number | Title must starts with task number of project {projectName}. Mask: {projectName}-number | `projectName` - string <br/> |
19-
| @mr-linter/branch_starts_with_task_number | Source branch must starts with task number of project {projectName}. Mask: {projectName}-number | `projectName` - string <br/> |
20-
| @mr-linter/forbid_changes | Forbid changes for files. | `files` - array of strings <br/> |
21-
| @mr-linter/update_changelog | Changelog must be contained new tag. | `file` - string <br/> `tags` - object <br/> |
22-
| @mr-linter/diff_limit | The request must contain no more than {linesMax} changes. | `linesMax` - integer <br/> `fileLinesMax` - integer <br/> |
23-
| @mr-linter/no_ssh_keys | Prevent ssh keys from being included in the merge request. | `sshKeyFinder` - <br/> `stopOnFirstFailure` - boolean <br/> |
24-
| @mr-linter/disable_file_extensions | Disable adding files of certain extensions. | `extensions` - array of strings <br/> |
5+
<table>
6+
<tbody>
7+
<tr>
8+
<td>Rule</td>
9+
<td>Description</td>
10+
<td colspan="3">Parameters</td>
11+
</tr>
12+
<tr>
13+
<td rowspan="1">@mr-linter/changed_files_limit</td>
14+
<td rowspan="1">Check count changed files on a {limit}.</td>
15+
<td>limit</td>
16+
<td>Number of maximum possible changes </td>
17+
<td>integer</td>
18+
</tr>
19+
<tr>
20+
<td rowspan="1">@mr-linter/description_contains_links_of_any_domains</td>
21+
<td rowspan="1">Merge Request must contain links of any {domains}.</td>
22+
<td>domains</td>
23+
<td>Array of domains </td>
24+
<td>array of strings </td>
25+
</tr>
26+
<tr>
27+
<td rowspan="1">@mr-linter/description_contains_links_of_all_domains</td>
28+
<td rowspan="1">Merge Request must contain links of all {domains}.</td>
29+
<td>domains</td>
30+
<td>Array of domains </td>
31+
<td>array of strings </td>
32+
</tr>
33+
<tr>
34+
<td rowspan="1">@mr-linter/description_not_empty</td>
35+
<td colspan="4">The description must be filled.</td>
36+
</tr>
37+
<tr>
38+
<td rowspan="1">@mr-linter/has_all_labels</td>
39+
<td rowspan="1">Merge Request must have all {labels}</td>
40+
<td>labels</td>
41+
<td>Array of labels </td>
42+
<td>array of strings </td>
43+
</tr>
44+
<tr>
45+
<td rowspan="1">@mr-linter/has_any_labels</td>
46+
<td colspan="4">Merge Request must have any labels.</td>
47+
</tr>
48+
<tr>
49+
<td rowspan="1">@mr-linter/has_any_labels_of</td>
50+
<td rowspan="1">Merge Request must have any {labels}.</td>
51+
<td>labels</td>
52+
<td>Array of labels </td>
53+
<td>array of strings </td>
54+
</tr>
55+
<tr>
56+
<td rowspan="2">@mr-linter/jira/has_issue_link</td>
57+
<td rowspan="2">The description must have a link to Jira on a {domain} with {projectCode}.</td>
58+
<td>domain</td>
59+
<td>Domain of Jira instance </td>
60+
<td>string</td>
61+
</tr>
62+
<tr>
63+
<td>projectCode</td>
64+
<td>Project code </td>
65+
<td>string</td>
66+
</tr>
67+
<tr>
68+
<td rowspan="2">@mr-linter/youtrack/has_issue_link</td>
69+
<td rowspan="2">The description must have a link to YouTrack issue on a {domain} with {projectCode}.</td>
70+
<td>domain</td>
71+
<td>Domain hosting the YouTrack instance <br/> Examples: &quot;yt.my-company.ru&quot; </td>
72+
<td>string</td>
73+
</tr>
74+
<tr>
75+
<td>projectCode</td>
76+
<td>Project code <br/> Examples: &quot;yt.my-company.ru&quot; </td>
77+
<td>string</td>
78+
</tr>
79+
<tr>
80+
<td rowspan="1">@mr-linter/title_must_starts_with_any_prefix</td>
81+
<td rowspan="1">The title must starts with any {prefixes}</td>
82+
<td>prefixes</td>
83+
<td>Array of prefixes </td>
84+
<td>array of strings </td>
85+
</tr>
86+
<tr>
87+
<td rowspan="1">@mr-linter/has_changes</td>
88+
<td rowspan="1">Merge Request must have changes in {files}.</td>
89+
<td>changes</td>
90+
<td>Array of need changes </td>
91+
<td>array of objects </td>
92+
</tr>
93+
<tr>
94+
<td rowspan="1">@mr-linter/title_starts_with_task_number</td>
95+
<td rowspan="1">Title must starts with task number of project {projectName}. Mask: {projectName}-number</td>
96+
<td>projectName</td>
97+
<td>Project name </td>
98+
<td>string</td>
99+
</tr>
100+
<tr>
101+
<td rowspan="1">@mr-linter/branch_starts_with_task_number</td>
102+
<td rowspan="1">Source branch must starts with task number of project {projectName}. Mask: {projectName}-number</td>
103+
<td>projectName</td>
104+
<td>Project name <br/> Examples: &quot;VIP&quot; </td>
105+
<td>string</td>
106+
</tr>
107+
<tr>
108+
<td rowspan="1">@mr-linter/forbid_changes</td>
109+
<td rowspan="1">Forbid changes for files.</td>
110+
<td>files</td>
111+
<td>A set of files forbidden to be changed. </td>
112+
<td>array of strings </td>
113+
</tr>
114+
<tr>
115+
<td rowspan="2">@mr-linter/update_changelog</td>
116+
<td rowspan="2">Changelog must be contained new tag.</td>
117+
<td>file</td>
118+
<td>Relative path to changelog file </td>
119+
<td>string</td>
120+
</tr>
121+
<tr>
122+
<td>tags</td>
123+
<td>Tags parsing options </td>
124+
<td>object</td>
125+
</tr>
126+
<tr>
127+
<td rowspan="2">@mr-linter/diff_limit</td>
128+
<td rowspan="2">The request must contain no more than {linesMax} changes.</td>
129+
<td>linesMax</td>
130+
<td>Maximum allowed number of changed lines </td>
131+
<td>integer</td>
132+
</tr>
133+
<tr>
134+
<td>fileLinesMax</td>
135+
<td>Maximum allowed number of changed lines in a file </td>
136+
<td>integer</td>
137+
</tr>
138+
<tr>
139+
<td rowspan="1">@mr-linter/no_ssh_keys</td>
140+
<td rowspan="1">Prevent ssh keys from being included in the merge request.</td>
141+
<td>stopOnFirstFailure</td>
142+
<td>When the value is true, the search will stop after the first found key </td>
143+
<td>boolean</td>
144+
</tr>
145+
<tr>
146+
<td rowspan="1">@mr-linter/disable_file_extensions</td>
147+
<td rowspan="1">Disable adding files of certain extensions.</td>
148+
<td>extensions</td>
149+
<td>Array of file extensions <br/> Examples: &quot;pem&quot;, &quot;pub&quot;, &quot;php&quot; </td>
150+
<td>array of strings </td>
151+
</tr>
152+
</tbody>
153+
</table>

0 commit comments

Comments
 (0)