Skip to content

Commit 264bd07

Browse files
2bndy52bndy5
committed
use mkdocs-gen-files plugin
- remove static docs/inputs-outputs.md - gitignore docs/inputs-outputs.md - add script to generate docs/inputs-outputs.md dynamically on build
1 parent 599f02b commit 264bd07

File tree

5 files changed

+240
-288
lines changed

5 files changed

+240
-288
lines changed

‎action.yml

Lines changed: 161 additions & 62 deletions
Original file line numberDiff line numberDiff line change
@@ -5,118 +5,217 @@ branding:
55
icon: "check-circle"
66
color: "green"
77
inputs:
8-
thread-comments:
9-
description: >-
10-
Set this option to 'true' or 'false' to enable or disable the use of
11-
thread comments as feedback. Set this to 'update' to update an existing comment
12-
if one exists; the value 'true' will always delete an old comment and post a new one
13-
if necessary. Defaults to false.
14-
required: false
15-
default: 'false'
16-
no-lgtm:
17-
description: >-
18-
Set this option to true or false to enable or disable the use of a thread comment that
19-
basically says 'Looks Good To Me' (when all checks pass). Defaults to true.
20-
See `thread-comments` option for further details.
21-
required: false
22-
default: true
23-
step-summary:
24-
description: >
25-
Set this option to true to append content as part of workflow's job summary. Defaults to false.
26-
27-
See implementation details in GitHub's documentation about
28-
[Adding a job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary).
29-
This option is independent of the `thread-comments` option, rather this option uses the same content that
30-
the `thread-comments` option would use.
31-
required: false
32-
default: false
33-
file-annotations:
34-
description: Set this option to false to disable the use of file annotations as feedback. Defaults to true.
35-
required: false
36-
default: true
378
style:
38-
description: >
39-
The style rules to use (defaults to 'llvm').
40-
Set this to 'file' to have clang-format use the closest relative .clang-format file.
9+
description: |
10+
The style rules to use.
11+
12+
- Set this to 'file' to have clang-format use the closest relative .clang-format file.
13+
- Set this to a blank string (`''`) to disable the use of clang-format entirely.
14+
- Any code style supported by the specified version of clang-format.
4115
required: false
4216
default: "llvm"
17+
min-version: '1.2.0'
4318
extensions:
44-
description: >
45-
The file extensions to run the action against.
46-
This comma-separated string defaults to 'c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx'.
19+
description: The file extensions to run the action against. This is a comma-separated string.
4720
required: false
4821
default: "c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx"
22+
min-version: '1.2.0'
4923
tidy-checks:
50-
description: >
51-
A string of regex-like patterns specifying what checks clang-tidy will use.
52-
This defaults to 'boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*'. See also clang-tidy docs for more info.
24+
description: |
25+
Comma-separated list of globs with optional `-` prefix.
26+
Globs are processed in order of appearance in the list.
27+
Globs without `-` prefix add checks with matching names to the set,
28+
globs with the `-` prefix remove checks with matching names from the set of enabled checks.
29+
This option's value is appended to the value of the 'Checks' option in a .clang-tidy file (if any).
30+
31+
- It is possible to disable clang-tidy entirely by setting this option to `'-*'`.
32+
- It is also possible to rely solely on a .clang-tidy config file by specifying this option as a blank string (`''`).
5333
required: false
5434
default: "boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*"
35+
min-version: '1.2.0'
5536
repo-root:
5637
description: >
57-
The relative path to the repository root directory. The default value '.' is relative to the runner's GITHUB_WORKSPACE environment variable.
38+
The relative path to the repository root directory.
39+
This path is relative to the path designated as the runner's `GITHUB_WORKSPACE` environment variable.
5840
required: false
59-
default: "."
41+
default: '.'
42+
min-version: '1.2.0'
6043
version:
61-
description: "The desired version of the clang tools to use. Accepted options are strings which can be 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8 or 7. Defaults to 12."
44+
description: |
45+
The desired version of the [clang-tools](https://github.com/cpp-linter/clang-tools-pip) to use.
46+
Accepted options are strings which can be 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8 or 7.
47+
48+
- Set this option to a blank string (`''`) to use the platform's default installed version.
49+
- This value can also be a path to where the clang tools are installed (if using a custom install location).
6250
required: false
63-
default: "12"
51+
default: 12
52+
min-version: '1.2.0'
6453
verbosity:
65-
description: A hidden option to control the action's log verbosity. This is the `logging` level (defaults to `info`).
54+
description: |
55+
This controls the action's verbosity in the workflow's logs.
56+
Supported options are `info` or `debug`.
57+
This option does not affect the verbosity of resulting thread comments or file annotations.
58+
59+
The verbosity can also be engaged by enabling debug logs when
60+
[re-running jobs or workflows](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs).
6661
required: false
6762
default: info
63+
min-version: '1.3.0'
6864
lines-changed-only:
69-
description: Set this option to 'true' to only analyze changes in the event's diff. Defaults to 'false'.
65+
description: |
66+
This controls what part of the files are analyzed. The following values are accepted:
67+
68+
- `false`: All lines in a file are analyzed.
69+
- `true`: Only lines in the diff that contain additions are analyzed.
70+
- `diff`: All lines in the diff are analyzed (including unchanged lines but not subtractions).
71+
72+
!!! info "Important"
73+
This feature requires special permissions to perform successfully.
74+
See our [documented permissions](permissions.md)
7075
required: false
7176
default: false
77+
min-version: '1.5.0'
78+
required-permission: 'content: read #file-changes'
7279
files-changed-only:
73-
description: Set this option to 'false' to analyze any source files in the repo. Defaults to 'true'.
80+
description: |
81+
Set this option to false to analyze any source files in the repo. This is automatically enabled if lines-changed-only is enabled.
82+
83+
!!! info "Important"
84+
This feature requires special permissions to perform successfully.
85+
See our [documented permissions](permissions.md)
7486
required: false
7587
default: true
88+
min-version: '1.3.0'
89+
required-permission: 'content: read #file-changes'
7690
ignore:
77-
description: >
91+
description: |
7892
Set this option with string of path(s) to ignore.
7993
80-
- In the case of multiple paths, you can use a pipe character ('|')
81-
to separate the multiple paths. Multiple lines are forbidden as input to this option.
94+
- In the case of multiple paths, you can use a pipe character (`|`)
95+
to separate the multiple paths. Multiple lines are forbidden as an input to this option;
96+
it must be a single string.
8297
- This can also have files, but the file's relative path has to be specified
8398
as well.
84-
- There is no need to use './' for each entry; a blank string ('') represents
85-
the repo-root path (specified by the `repo-root` input option).
86-
- Path(s) containing a space should be inside single quotes.
87-
- Submodules are automatically ignored.
88-
- Prefix a path with a bang (`!`) to make it explicitly not ignored - order of
89-
multiple paths does take precedence. The `!` prefix can be applied to
90-
submodules if desired.
91-
- Glob patterns are not supported here. All asterisk characters ('*') are literal.
92-
required: false
93-
default: ".github"
99+
- There is no need to use `./` for each entry; a blank string (`''`) represents
100+
the [`repo-root`](#repo-root) path.
101+
- Submodules are automatically ignored. Hidden directories (beginning with a `.`) are also ignored
102+
automatically.
103+
- Prefix a path with a bang (`!`) to make it explicitly _not_ ignored. The order of
104+
multiple paths does _not_ take precedence. The `!` prefix can be applied to
105+
a submodule's path (if desired) but not hidden directories.
106+
- Glob patterns are not supported here. All asterisk characters (`*`) are literal.
107+
required: false
108+
default: '.github'
109+
min-version: '1.3.0'
110+
thread-comments:
111+
description: |
112+
This controls the behavior of posted thread comments as feedback. The following options are supported:
113+
114+
- `true`: enable the use of thread comments. This will always delete an outdated thread comment and post a new comment (triggering a notification for every comment).
115+
- `update`: update an existing thread comment if one already exists. This option does not trigger a new notification for every thread comment update.
116+
- `false`: disable the use of thread comments.
117+
118+
!!! info "Important"
119+
This feature requires special permissions to perform successfully.
120+
See our [documented permissions](permissions.md)
121+
122+
> [!NOTE]
123+
> If run on a private repository, then this feature is disabled because the GitHub REST API behaves differently for thread comments on a private repository.
124+
required: false
125+
default: 'false'
126+
min-version: '2.6.2'
127+
required-permission: 'issues: write #thread-comments'
128+
no-lgtm:
129+
description: |
130+
Set this option to true or false to enable or disable the use of a
131+
thread comment or pull request review that basically says 'Looks Good To Me' (when all checks pass).
132+
The default value, `true` means no LGTM comment posted.
133+
134+
See [`thread-comments`](#thread-comments), [`tidy-review`](#tidy-review),
135+
and [`format-review`](#format-review) options for further details.
136+
required: false
137+
default: true
138+
min-version: '2.6.2'
139+
step-summary:
140+
description: |
141+
Set this option to true to append content as part of workflow's job summary.
142+
143+
See implementation details in GitHub's documentation about
144+
[Adding a job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary).
145+
This option is independent of the [`thread-comments`](#thread-comments) option,
146+
rather this option uses the same content that the
147+
[`thread-comments`](#thread-comments) option would use.
148+
149+
> [!NOTE]
150+
> The [`no-lgtm`](#no-lgtm) option is _not_ applied to step summaries.
151+
required: false
152+
default: false
153+
min-version: '2.6.0'
154+
file-annotations:
155+
description: |
156+
Set this option to false to disable the use of file annotations as feedback. Defaults to true.
157+
required: false
158+
default: true
159+
min-version: '1.4.3'
94160
database:
95-
description: The directory containing compile_commands.json file.
161+
description: The directory containing compilation database (like compile_commands.json) file.
96162
required: false
97163
default: ""
164+
min-version: '1.4.0'
98165
extra-args:
99-
description: A string of extra arguments passed to clang-tidy for use as compiler arguments. Multiple arguments are separated by spaces so the argument name and value should use an '=' sign instead of a space.
166+
description: |
167+
A string of extra arguments passed to clang-tidy for use as compiler arguments.
168+
Multiple arguments are separated by spaces so the argument name and value should
169+
use an '=' sign instead of a space.
100170
required: false
101171
default: ""
172+
min-version: '2.1.0'
102173
tidy-review:
103-
description: Set this to true to enable PR reviews from clang-tidy. See also https://cpp-linter.github.io/cpp-linter/pr_review_caveats.html
174+
description: |
175+
Set this option to `true` to enable Pull Request reviews from clang-tidy.
176+
177+
!!! info "Important"
178+
This feature requires special permissions to perform successfully.
179+
See our [documented permissions](permissions.md).
180+
181+
See also [the PR review feature caveats](pr-review-caveats.md).
182+
183+
> [!NOTE]
184+
> The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews.
104185
required: false
105186
default: false
187+
experimental: true
188+
min-version: '2.9.0'
189+
required-permission: 'pull_request: write #pull-request-reviews'
106190
format-review:
107-
description: Set this to true to enable PR reviews from clang-format.See also https://cpp-linter.github.io/cpp-linter/pr_review_caveats.html
191+
description: |
192+
Set this option to `true` to enable Pull Request reviews from clang-format.
193+
194+
!!! info "Important"
195+
This feature requires special permissions to perform successfully.
196+
See our [documented permissions](permissions.md).
197+
198+
See also [the PR review feature caveats](pr-review-caveats.md).
199+
200+
> [!NOTE]
201+
> The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews.
108202
required: false
109203
default: false
204+
min-version: '2.9.0'
205+
required-permission: 'pull_request: write #pull-request-reviews'
110206
outputs:
111207
checks-failed:
112208
description: An integer that can be used as a boolean value to indicate if any checks failed by clang-tidy and clang-format.
113209
value: ${{ steps.cpp-linter-unix.outputs.checks-failed || steps.cpp-linter-windows.outputs.checks-failed }}
210+
min-version: '1.2.0'
114211
clang-tidy-checks-failed:
115212
description: An integer that can be used as a boolean value to indicate if any checks failed by clang-tidy only.
116213
value: ${{ steps.cpp-linter-unix.outputs.clang-tidy-checks-failed || steps.cpp-linter-windows.outputs.clang-tidy-checks-failed }}
214+
min-version: '2.7.2'
117215
clang-format-checks-failed:
118216
description: An integer that can be used as a boolean value to indicate if any checks failed by clang-format only.
119217
value: ${{ steps.cpp-linter-unix.outputs.clang-format-checks-failed || steps.cpp-linter-windows.outputs.clang-format-checks-failed }}
218+
min-version: '2.7.2'
120219
runs:
121220
using: "composite"
122221
steps:

‎docs/gen_io_doc.py

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
from pathlib import Path
2+
from typing import Union
3+
import yaml
4+
import mkdocs_gen_files
5+
6+
FILENAME = "inputs-outputs.md"
7+
8+
with mkdocs_gen_files.open(FILENAME, "w") as io_doc:
9+
action_yml = Path(__file__).parent.parent / "action.yml"
10+
action_dict = yaml.safe_load(action_yml.read_bytes())
11+
doc = "".join(
12+
[
13+
"---\ntitle: Inputs and Outputs\n---\n\n"
14+
"<!--\n",
15+
" this page was generated from action.yml ",
16+
"using the gen_io_doc.py script.\n",
17+
" CHANGES TO inputs-outputs.md WILL BE LOST & OVERWRITTEN\n-->\n\n",
18+
"# Inputs and Outputs\n\n",
19+
"These are the action inputs and outputs offered by cpp-linter-action.\n",
20+
]
21+
)
22+
assert "inputs" in action_dict
23+
doc += "\n## Inputs\n"
24+
for action_input, input_metadata in action_dict["inputs"].items():
25+
doc += f"### `{action_input}`\n\n"
26+
27+
assert "min-version" in input_metadata
28+
min_ver = input_metadata["min-version"]
29+
doc += f"<!-- md:version {min_ver} -->\n"
30+
31+
assert "default" in input_metadata
32+
default: Union[str, bool] = input_metadata["default"]
33+
if isinstance(default, bool):
34+
default = str(default).lower()
35+
elif isinstance(default, str):
36+
default = repr(default) # add quotes around value
37+
doc += f"<!-- md:default {default} -->\n"
38+
39+
if "experimental" in input_metadata and input_metadata["experimental"] is True:
40+
doc += "<!-- md:flag experimental -->\n"
41+
42+
if "required-permission" in input_metadata:
43+
permission = input_metadata["required-permission"]
44+
doc += f"<!-- md:permission {permission} -->\n"
45+
46+
assert "description" in input_metadata
47+
doc += "\n" + input_metadata["description"] + "\n"
48+
49+
assert "outputs" in action_dict
50+
doc += (
51+
"\n## Outputs\n\nThis action creates 3 output variables. Even if the linting "
52+
"checks fail for source files this action will still pass, but users' CI "
53+
"workflows can use this action's outputs to exit the workflow early if that is "
54+
"desired.\n"
55+
)
56+
for action_output, output_metadata in action_dict["outputs"].items():
57+
doc += f"\n### `{action_output}`\n\n"
58+
59+
assert "min-version" in output_metadata
60+
min_ver = output_metadata["min-version"]
61+
doc += f"<!-- md:version {min_ver} -->\n"
62+
63+
64+
assert "description" in output_metadata
65+
doc += "\n" + output_metadata["description"] + "\n"
66+
67+
print(doc, file=io_doc)
68+
69+
mkdocs_gen_files.set_edit_path(FILENAME, "gen_io_doc.py")

0 commit comments

Comments
 (0)