diff --git a/action.yml b/action.yml index 8a1d7e88..97ca0d24 100644 --- a/action.yml +++ b/action.yml @@ -5,228 +5,118 @@ branding: icon: "check-circle" color: "green" inputs: - style: - description: | - The style rules to use. + thread-comments: + description: >- + Set this option to 'true' or 'false' to enable or disable the use of + thread comments as feedback. Set this to 'update' to update an existing comment + if one exists; the value 'true' will always delete an old comment and post a new one + if necessary. Defaults to false. + required: false + default: 'false' + no-lgtm: + description: >- + Set this option to true or false to enable or disable the use of a thread comment that + basically says 'Looks Good To Me' (when all checks pass). Defaults to true. + See `thread-comments` option for further details. + required: false + default: true + step-summary: + description: > + Set this option to true to append content as part of workflow's job summary. Defaults to false. - - Set this to `file` to have clang-format use the closest relative .clang-format file. - - Set this to a blank string (`''`) to disable the use of clang-format entirely. - - Any code style supported by the specified version of clang-format. + See implementation details in GitHub's documentation about + [Adding a job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary). + This option is independent of the `thread-comments` option, rather this option uses the same content that + the `thread-comments` option would use. + required: false + default: false + file-annotations: + description: Set this option to false to disable the use of file annotations as feedback. Defaults to true. + required: false + default: true + style: + description: > + The style rules to use (defaults to 'llvm'). + Set this to 'file' to have clang-format use the closest relative .clang-format file. required: false default: "llvm" - minimum-version: '1.2.0' extensions: - description: The file extensions to run the action against. This is a comma-separated string. + description: > + The file extensions to run the action against. + This comma-separated string defaults to 'c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx'. required: false default: "c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx" - minimum-version: '1.2.0' tidy-checks: - description: | - Comma-separated list of globs with optional `-` prefix. - Globs are processed in order of appearance in the list. - Globs without `-` prefix add checks with matching names to the set, - globs with the `-` prefix remove checks with matching names from the set of enabled checks. - This option's value is appended to the value of the 'Checks' option in a .clang-tidy file (if any). - - - It is possible to disable clang-tidy entirely by setting this option to `'-*'`. - - It is also possible to rely solely on a .clang-tidy config file by specifying this option as a blank string (`''`). + description: > + A string of regex-like patterns specifying what checks clang-tidy will use. + This defaults to 'boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*'. See also clang-tidy docs for more info. required: false default: "boost-*,bugprone-*,performance-*,readability-*,portability-*,modernize-*,clang-analyzer-*,cppcoreguidelines-*" - minimum-version: '1.2.0' repo-root: description: > - The relative path to the repository root directory. - This path is relative to the path designated as the runner's `GITHUB_WORKSPACE` environment variable. + The relative path to the repository root directory. The default value '.' is relative to the runner's GITHUB_WORKSPACE environment variable. required: false - default: '.' - minimum-version: '1.2.0' + default: "." version: - description: | - The desired version of the [clang-tools](https://github.com/cpp-linter/clang-tools-pip) to use. - Accepted options are strings which can be 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8 or 7. - - - Set this option to a blank string (`''`) to use the platform's default installed version. - - This value can also be a path to where the clang tools are installed (if using a custom install location). + 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." required: false - default: 12 - minimum-version: '1.2.0' + default: "12" verbosity: - description: | - This controls the action's verbosity in the workflow's logs. - Supported options are `info` or `debug`. - This option does not affect the verbosity of resulting thread comments or file annotations. - - The verbosity can also be engaged by enabling debug logs when - [re-running jobs or workflows](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs). + description: A hidden option to control the action's log verbosity. This is the `logging` level (defaults to `info`). required: false default: info - minimum-version: '1.3.0' lines-changed-only: - description: | - This controls what part of the files are analyzed. The following values are accepted: - - - `false`: All lines in a file are analyzed. - - `true`: Only lines in the diff that contain additions are analyzed. - - `diff`: All lines in the diff are analyzed (including unchanged lines but not subtractions). - - !!! info "Important" - This feature requires special permissions to perform successfully. - See our [documented permissions](permissions.md) + description: Set this option to 'true' to only analyze changes in the event's diff. Defaults to 'false'. required: false default: false - minimum-version: '1.5.0' - required-permission: 'content: read #file-changes' files-changed-only: - description: | - Set this option to false to analyze any source files in the repo. - This is automatically enabled if [`lines-changed-only`](#lines-changed-only) is enabled. - - !!! info "Important" - This feature requires special permissions to perform successfully. - See our [documented permissions](permissions.md) + description: Set this option to 'false' to analyze any source files in the repo. Defaults to 'true'. required: false default: true - minimum-version: '1.3.0' - required-permission: 'content: read #file-changes' ignore: - description: | + description: > Set this option with string of path(s) to ignore. - - In the case of multiple paths, you can use a pipe character (`|`) - to separate the multiple paths. Multiple lines are forbidden as an input to this option; - it must be a single string. + - In the case of multiple paths, you can use a pipe character ('|') + to separate the multiple paths. Multiple lines are forbidden as input to this option. - This can also have files, but the file's relative path has to be specified as well. - - There is no need to use `./` for each entry; a blank string (`''`) represents - the [`repo-root`](#repo-root) path. - - Submodules are automatically ignored. Hidden directories (beginning with a `.`) are also ignored - automatically. - - Prefix a path with a bang (`!`) to make it explicitly _not_ ignored. The order of - multiple paths does _not_ take precedence. The `!` prefix can be applied to - a submodule's path (if desired) but not hidden directories. - - Glob patterns are not supported here. All asterisk characters (`*`) are literal. - required: false - default: '.github' - minimum-version: '1.3.0' - thread-comments: - description: | - This controls the behavior of posted thread comments as feedback. The following options are supported: - - - `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). - - `update`: update an existing thread comment if one already exists. This option does not trigger a new notification for every thread comment update. - - `false`: disable the use of thread comments. - - !!! info "Important" - This feature requires special permissions to perform successfully. - See our [documented permissions](permissions.md) - - > [!NOTE] - > 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. - required: false - default: 'false' - minimum-version: '2.6.2' - required-permission: 'issues: write #thread-comments' - no-lgtm: - description: | - Set this option to true or false to enable or disable the use of a - thread comment or pull request review that basically says 'Looks Good To Me' (when all checks pass). - The default value, `true` means no LGTM comment posted. - - See [`thread-comments`](#thread-comments), [`tidy-review`](#tidy-review), - and [`format-review`](#format-review) options for further details. - required: false - default: true - minimum-version: '2.6.2' - step-summary: - description: | - Set this option to true to append content as part of workflow's job summary. - - See implementation details in GitHub's documentation about - [Adding a job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary). - This option is independent of the [`thread-comments`](#thread-comments) option, - rather this option uses the same content that the - [`thread-comments`](#thread-comments) option would use. - - > [!NOTE] - > The [`no-lgtm`](#no-lgtm) option is _not_ applied to step summaries. - required: false - default: false - minimum-version: '2.6.0' - file-annotations: - description: | - Set this option to false to disable the use of file annotations as feedback. - required: false - default: true - minimum-version: '1.4.3' + - There is no need to use './' for each entry; a blank string ('') represents + the repo-root path (specified by the `repo-root` input option). + - Path(s) containing a space should be inside single quotes. + - Submodules are automatically ignored. + - Prefix a path with a bang (`!`) to make it explicitly not ignored - order of + multiple paths does take precedence. The `!` prefix can be applied to + submodules if desired. + - Glob patterns are not supported here. All asterisk characters ('*') are literal. + required: false + default: ".github" database: - description: The directory containing compilation database (like compile_commands.json) file. + description: The directory containing compile_commands.json file. required: false default: "" - minimum-version: '1.4.0' extra-args: - 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. - - !!! example - - ``` yaml - extra-args: '-std=c++17 -Wall' - ``` - This will be passed to clang-tidy as multiple `--extra-arg` options: - ``` - clang-tidy --extra-arg=-std=c++17 --extra-arg=-Wall - ``` + 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. required: false default: "" - minimum-version: '2.1.0' tidy-review: - description: | - Set this option to `true` to enable Pull Request reviews from clang-tidy. - - !!! info "Important" - This feature requires special permissions to perform successfully. - See our [documented permissions](permissions.md). - - See also [the PR review feature caveats](pr-review-caveats.md). - - > [!NOTE] - > The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews. + 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 required: false default: false - experimental: true - minimum-version: '2.9.0' - required-permission: 'pull_request: write #pull-request-reviews' format-review: - description: | - Set this option to `true` to enable Pull Request reviews from clang-format. - - !!! info "Important" - This feature requires special permissions to perform successfully. - See our [documented permissions](permissions.md). - - See also [the PR review feature caveats](pr-review-caveats.md). - - > [!NOTE] - > The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews. + 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 required: false default: false - minimum-version: '2.9.0' - required-permission: 'pull_request: write #pull-request-reviews' outputs: checks-failed: description: An integer that can be used as a boolean value to indicate if any checks failed by clang-tidy and clang-format. value: ${{ steps.cpp-linter-unix.outputs.checks-failed || steps.cpp-linter-windows.outputs.checks-failed }} - minimum-version: '1.2.0' clang-tidy-checks-failed: description: An integer that can be used as a boolean value to indicate if any checks failed by clang-tidy only. value: ${{ steps.cpp-linter-unix.outputs.clang-tidy-checks-failed || steps.cpp-linter-windows.outputs.clang-tidy-checks-failed }} - minimum-version: '2.7.2' clang-format-checks-failed: description: An integer that can be used as a boolean value to indicate if any checks failed by clang-format only. value: ${{ steps.cpp-linter-unix.outputs.clang-format-checks-failed || steps.cpp-linter-windows.outputs.clang-format-checks-failed }} - minimum-version: '2.7.2' runs: using: "composite" steps: diff --git a/docs/badge_hook.py b/docs/badge_hook.py index 9e2d699c..dd826dec 100644 --- a/docs/badge_hook.py +++ b/docs/badge_hook.py @@ -52,8 +52,8 @@ def _badge_for_version(text: str, page: Page, files: Files): icon = "material-tag-outline" href = f"https://github.com/cpp-linter/cpp-linter-action/releases/v{text}" return _badge( - icon=f'[:{icon}:]({href} "minimum version")', - text=f'[{text}]({href} "minimum version")', + icon=f'[:{icon}:]({href} "required version")', + text=f'[{text}]({href} "required version")', ) diff --git a/docs/gen_io_doc.py b/docs/gen_io_doc.py deleted file mode 100644 index ad1e4fe2..00000000 --- a/docs/gen_io_doc.py +++ /dev/null @@ -1,69 +0,0 @@ -from pathlib import Path -from typing import Union -import yaml -import mkdocs_gen_files - -FILENAME = "inputs-outputs.md" - -with mkdocs_gen_files.open(FILENAME, "w") as io_doc: - action_yml = Path(__file__).parent.parent / "action.yml" - action_dict = yaml.safe_load(action_yml.read_bytes()) - doc = "".join( - [ - "---\ntitle: Inputs and Outputs\n---\n\n" - "\n\n", - "# Inputs and Outputs\n\n", - "These are the action inputs and outputs offered by cpp-linter-action.\n", - ] - ) - assert "inputs" in action_dict - doc += "\n## Inputs\n" - for action_input, input_metadata in action_dict["inputs"].items(): - doc += f"### `{action_input}`\n\n" - - assert "minimum-version" in input_metadata - min_ver = input_metadata["minimum-version"] - doc += f"\n" - - assert "default" in input_metadata - default: Union[str, bool] = input_metadata["default"] - if isinstance(default, bool): - default = str(default).lower() - elif isinstance(default, str): - default = repr(default) # add quotes around value - doc += f"\n" - - if "experimental" in input_metadata and input_metadata["experimental"] is True: - doc += "\n" - - if "required-permission" in input_metadata: - permission = input_metadata["required-permission"] - doc += f"\n" - - assert "description" in input_metadata - doc += "\n" + input_metadata["description"] + "\n" - - assert "outputs" in action_dict - doc += ( - "\n## Outputs\n\nThis action creates 3 output variables. Even if the linting " - "checks fail for source files this action will still pass, but users' CI " - "workflows can use this action's outputs to exit the workflow early if that is " - "desired.\n" - ) - for action_output, output_metadata in action_dict["outputs"].items(): - doc += f"\n### `{action_output}`\n\n" - - assert "minimum-version" in output_metadata - min_ver = output_metadata["minimum-version"] - doc += f"\n" - - - assert "description" in output_metadata - doc += "\n" + output_metadata["description"] + "\n" - - print(doc, file=io_doc) - -mkdocs_gen_files.set_edit_path(FILENAME, "gen_io_doc.py") diff --git a/docs/inputs-outputs.md b/docs/inputs-outputs.md new file mode 100644 index 00000000..c986a3e9 --- /dev/null +++ b/docs/inputs-outputs.md @@ -0,0 +1,225 @@ +# Inputs and Outputs + +These are the action inputs and outputs offered by cpp-linter-action. + +## Inputs + +### `style` + + + + +The style rules to use. + +- Set this to 'file' to have clang-format use the closest relative .clang-format file. +- Set this to a blank string (`''`) to disable the use of clang-format entirely. +- Any code style supported by the specified version of clang-format. + +### `extensions` + + + + +The file extensions to run the action against. This is a comma-separated string. + +### `tidy-checks` + + + + +Comma-separated list of globs with optional `-` prefix. Globs are processed in order of appearance in the list. Globs without `-` prefix add checks with matching names to the set, globs with the `-` prefix remove checks with matching names from the set of enabled checks. This option's value is appended to the value of the 'Checks' option in a .clang-tidy file (if any). + - It is possible to disable clang-tidy entirely by setting this option to `'-*'`. + - It is also possible to rely solely on a .clang-tidy config file by specifying this option as a blank string (`''`). + +### `repo-root` + + + + +The relative path to the repository root directory. This path is relative to the path designated as the runner's `GITHUB_WORKSPACE` environment variable. + +### `version` + + + + +The desired version of the [clang-tools](https://github.com/cpp-linter/clang-tools-pip) to use. Accepted options are strings which can be 18, 17, 16, 15, 14, 13, 12, 11, 10, 9, 8 or 7. + +- Set this option to a blank string (`''`) to use the platform's default installed version. +- This value can also be a path to where the clang tools are installed (if using a custom install location). + +### `verbosity` + + + + +This controls the action's verbosity in the workflow's logs. Supported options are `info` or `debug`. This option does not affect the verbosity of resulting thread comments or file annotations. + +The verbosity can also be engaged by enabling debug logs when [re-running jobs or workflows](https://docs.github.com/en/actions/managing-workflow-runs/re-running-workflows-and-jobs). + +### `lines-changed-only` + + + + + +This controls what part of the files are analyzed. The following values are accepted: + +- `false`: All lines in a file are analyzed. +- `true`: Only lines in the diff that contain additions are analyzed. +- `diff`: All lines in the diff are analyzed (including unchanged lines but not subtractions). + +!!! info "Important" + This feature requires special permissions to perform successfully. + See our [documented permissions](permissions.md) + +### `files-changed-only` + + + + + +Set this option to false to analyze any source files in the repo. This is automatically enabled if lines-changed-only is enabled. + +!!! info "Important" + This feature requires special permissions to perform successfully. + See our [documented permissions](permissions.md) + +### `ignore` + + + + +Set this option with string of path(s) to ignore. + +- In the case of multiple paths, you can use a pipe character (`|`) + to separate the multiple paths. Multiple lines are forbidden as an input to this option; it must be a single string. +- This can also have files, but the file's relative path has to be specified + as well. +- There is no need to use `./` for each entry; a blank string (`''`) represents + the repo-root path (specified by the [`repo-root`](#repo-root) input option). +- Submodules are automatically ignored. Hidden directories (beginning with a `.`) are also ignored automatically. +- Prefix a path with a bang (`!`) to make it explicitly _not_ ignored. The order of + multiple paths does _not_ take precedence. The `!` prefix can be applied to + a submodule's path (if desired) but not hidden directories. +- Glob patterns are not supported here. All asterisk characters (`*`) are literal. + +### `thread-comments` + + + + + +This controls the behavior of posted thread comments as feedback. The following options are supported: + +- `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). +- `update`: update an existing thread comment if one already exists. This option does not trigger a new notification for every thread comment update. +- `false`: disable the use of thread comments. + +!!! info "Important" + This feature requires special permissions to perform successfully. + See our [documented permissions](permissions.md) + +> [!NOTE] +> 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. + +### `no-lgtm` + + + + +Set this option to true or false to enable or disable the use of a thread comment or pull request review that basically says 'Looks Good To Me' (when all checks pass). +The default value, `true` means no LGTM comment posted. + +See [`thread-comments`](#thread-comments), [`tidy-review`](#tidy-review), and [`format-review`](#format-review) options for further details. + +### `step-summary` + + + + +Set this option to true to append content as part of workflow's job summary. + +See implementation details in GitHub's documentation about +[Adding a job summary](https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#adding-a-job-summary). +This option is independent of the [`thread-comments`](#thread-comments) option, rather this option uses the same content that the [`thread-comments`](#thread-comments) option would use. + +Note: The [`no-lgtm`](#no-lgtm) option is _not_ applied to step summaries. + +### `file-annotations` + + + + +Set this option to `false` to disable the use of file annotations as feedback. + +### `database` + + + + +The directory containing compilation database (like compile_commands.json) file. + +### `extra-args` + + + + +A string of extra arguments passed to clang-tidy for use as compiler arguments (like `-std=c++14 -Wall`). + +### `tidy-review` + + + + + + +Set this option to `true` to enable Pull Request reviews from clang-tidy. + +!!! info "Important" + This feature requires special permissions to perform successfully. + See our [documented permissions](permissions.md). + + See also [the PR review feature caveats](pr-review-caveats.md). + +> [!NOTE] +> The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews. + +### `format-review` + + + + + +Set this option to `true` to enable Pull Request reviews from clang-format. + +!!! info "Important" + This feature requires special permissions to perform successfully. + See our [documented permissions](permissions.md). + + See also [the PR review feature caveats](pr-review-caveats.md). + +> [!NOTE] +> The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews. + +## Outputs + +This action creates 3 output variables. Even if the linting checks fail for source files this action will still pass, but users' CI workflows can use this action's outputs to exit the workflow early if that is desired. + +### `checks-failed` + + + +The total number of concerns raised by both clang-format and clang-tidy. + +### `clang-tidy-checks-failed` + + + +The total number of concerns raised by clang-tidy only. + +### `clang-format-checks-failed` + + + +The total number of concerns raised by clang-format only. diff --git a/docs/requirements.txt b/docs/requirements.txt index 11cd1d4c..894d190f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,6 +1,4 @@ markdown-gfm-admonition mkdocs -mkdocs-gen-files mkdocs-include-markdown-plugin mkdocs-material -pyyaml diff --git a/mkdocs.yml b/mkdocs.yml index 6069e734..54879cb1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,7 +3,7 @@ site_description: "Developer documentation from sources." site_url: "https://cpp-linter.github.io/cpp-linter-action" repo_url: "https://github.com/cpp-linter/cpp-linter-action" repo_name: "cpp-linter/cpp-linter-action" -edit_uri: "edit/main/docs/" +edit_uri: "" nav: - index.md - inputs-outputs.md @@ -20,8 +20,6 @@ theme: - content.tooltips - content.code.annotate - content.code.copy - - content.action.view - - content.action.edit - navigation.footer - search.suggest - search.share @@ -29,8 +27,6 @@ theme: - toc.follow logo: images/logo.png favicon: images/favicon.ico - icon: - repo: fontawesome/brands/github palette: # Palette toggle for automatic mode - media: "(prefers-color-scheme)" @@ -68,9 +64,6 @@ extra_css: plugins: - search - include-markdown - - gen-files: - scripts: - - docs/gen_io_doc.py markdown_extensions: - pymdownx.superfences