From d4202dcac7e45400beb7d6b6359929734ef2b3e6 Mon Sep 17 00:00:00 2001 From: Brendan <2bndy5@gmail.com> Date: Wed, 28 Feb 2024 18:37:18 -0800 Subject: [PATCH] docs overhaul (#198) - inputs and outputs are in a dedicated page - README and docs landing page auto-sync with MD substitutions - permissions are noted where needed (per feature) - adds pr-review-caveats doc - add examples recipes (resolves #195) - demo folder moved to docs/examples and corresponding CI adjusted - use readthedocs to build doc previews in PRs --- .github/workflows/cpp-linter.yml | 9 +- .pre-commit-config.yaml | 2 + .readthedocs.yaml | 19 ++ README.md | 224 ++++------------- docs/badge_hook.py | 83 +++++++ {demo => docs/examples/demo}/.clang-format | 0 {demo => docs/examples/demo}/.clang-tidy | 0 .../examples/demo}/compile_flags.txt | 0 {demo => docs/examples/demo}/demo.cpp | 0 {demo => docs/examples/demo}/demo.hpp | 0 docs/examples/index.md | 36 +++ docs/examples/only-PR-comments.yml | 30 +++ docs/examples/only-clang-format.yml | 28 +++ docs/examples/only-clang-tidy.yml | 28 +++ docs/index.md | 31 +-- docs/inputs-outputs.md | 225 ++++++++++++++++++ docs/permissions.md | 45 ++++ docs/pr-review-caveats.md | 84 +++++++ docs/requirements.txt | 1 + docs/stylesheets/extra.css | 198 +++++++++++++++ mkdocs.yml | 47 +++- 21 files changed, 894 insertions(+), 196 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/badge_hook.py rename {demo => docs/examples/demo}/.clang-format (100%) rename {demo => docs/examples/demo}/.clang-tidy (100%) rename {demo => docs/examples/demo}/compile_flags.txt (100%) rename {demo => docs/examples/demo}/demo.cpp (100%) rename {demo => docs/examples/demo}/demo.hpp (100%) create mode 100644 docs/examples/index.md create mode 100644 docs/examples/only-PR-comments.yml create mode 100644 docs/examples/only-clang-format.yml create mode 100644 docs/examples/only-clang-tidy.yml create mode 100644 docs/inputs-outputs.md create mode 100644 docs/permissions.md create mode 100644 docs/pr-review-caveats.md diff --git a/.github/workflows/cpp-linter.yml b/.github/workflows/cpp-linter.yml index c06cfba3..90642586 100644 --- a/.github/workflows/cpp-linter.yml +++ b/.github/workflows/cpp-linter.yml @@ -2,9 +2,14 @@ name: cpp-linter on: push: - paths-ignore: "docs/**" + paths: + - "!**" + - "docs/examples/demo/*" pull_request: - paths-ignore: "docs/**" + paths: + - "!**" + - "docs/examples/demo/*" + jobs: cpp-linter: diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 5b051175..7999b299 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -6,4 +6,6 @@ repos: - id: end-of-file-fixer - id: check-added-large-files - id: check-yaml + # special mkdocs config to include inline icons fails (see `pymdownx.emoji` in mkdocs.yml) + args: ['--unsafe'] # use `--unsafe` to workaround yaml loading - id: requirements-txt-fixer diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..015eb5de --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,19 @@ +# Read the Docs configuration file for MkDocs projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +mkdocs: + configuration: mkdocs.yml + +# Optionally declare the Python requirements required to build your docs +python: + install: + - requirements: docs/requirements.txt diff --git a/README.md b/README.md index b06ad600..f6ee90da 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,21 @@ - +[file-annotations]: https://cpp-linter.github.io/cpp-linter-action/inputs-outputs/#file-annotations +[thread-comments]: https://cpp-linter.github.io/cpp-linter-action/inputs-outputs/#thread-comments +[step-summary]: https://cpp-linter.github.io/cpp-linter-action/inputs-outputs/#step-summary +[tidy-review]: https://cpp-linter.github.io/cpp-linter-action/inputs-outputs/#tidy-review +[format-review]: https://cpp-linter.github.io/cpp-linter-action/inputs-outputs/#format-review + +[io-doc]: https://cpp-linter.github.io/cpp-linter-action/inputs-outputs +[recipes-doc]: https://cpp-linter.github.io/cpp-linter-action/examples + +[format-annotations-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/annotations-clang-format.png +[tidy-annotations-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/annotations-clang-tidy.png +[thread-comment-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/comment.png +[step-summary-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/step-summary.png +[tidy-review-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/tidy-review.png +[format-review-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/format-review.png +[format-suggestion-preview]: https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/format-suggestion.png + + # C/C++ Linter Action | clang-format & clang-tidy @@ -8,7 +25,11 @@ [![MkDocs Deploy](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/mkdocs-deploy.yml/badge.svg)](https://github.com/cpp-linter/cpp-linter-action/actions/workflows/mkdocs-deploy.yml) ![GitHub](https://img.shields.io/github/license/cpp-linter/cpp-linter-action?label=license&logo=github) -A Github Action for linting C/C++ code integrating clang-tidy and clang-format to collect feedback provided in the form of [`file-annotations`](#file-annotations), [`thread-comments`](#thread-comments), workflow [`step-summary`](#step-summary), and Pull Request reviews (with [`tidy-review`](#tidy-review) or [`format-review`](#format-review)). +A Github Action for linting C/C++ code integrating clang-tidy and clang-format +to collect feedback provided in the form of +[`file-annotations`][file-annotations], [`thread-comments`][thread-comments], +workflow [`step-summary`][step-summary], and Pull Request reviews (with +[`tidy-review`][tidy-review] or [`format-review`][format-review]). > [!WARNING] > We only support Linux runners using a Debian based Linux OS (like Ubuntu and many others). @@ -41,218 +62,69 @@ Create a new GitHub Actions workflow in your project, e.g. at [.github/workflows The content of the file should be in the following format. ```yaml -name: cpp-linter - -on: pull_request - -jobs: - cpp-linter: - runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: cpp-linter/cpp-linter-action@v2 id: linter env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} with: - style: file - # The following value will only update a single comment - # in a pull request's thread. Set it to false to disable the comment. - # Set it to true to post a new comment (and delete the old comment). + style: 'file' # Use .clang-format config file + tidy-checks: '' # Use .clang-tidy config file + # only 'update' a single comment in a pull request's thread. thread-comments: ${{ github.event_name == 'pull_request' && 'update' }} - - name: Fail fast?! if: steps.linter.outputs.checks-failed > 0 - run: echo "Some files failed the linting checks!" - # for actual deployment - # run: exit 1 + run: exit 1 ``` -### Optional Inputs - -#### `style` - -- **Description**: 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. -- Default: 'llvm' - -#### `extensions` - -- **Description**: The file extensions to run the action against. This is a comma-separated string. -- Default: 'c,h,C,H,cpp,hpp,cc,hh,c++,h++,cxx,hxx' - -#### `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 (`''`). -- Default: 'boost-\*,bugprone-\*,performance-\*,readability-\*,portability-\*,modernize-\*,clang-analyzer-\*,cppcoreguidelines-\*' - -#### `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. -- 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 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). -- 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). -- Default: 'info' - -#### `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). -- Default: false. - -#### `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 is enabled. -- Default: true -- NOTE: The `GITHUB_TOKEN` should be supplied when running on a private repository with this option enabled, otherwise the runner does not not have the privilege to list changed files for an event. See [Authenticating with the GITHUB_TOKEN](https://docs.github.com/en/actions/reference/authentication-in-a-workflow) - -#### `ignore` - -- **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. - - 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` 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. -- Default: '.github' - -#### `thread-comments` - -- **Description**: Set this option to true to enable 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. - - To use thread comments, the `GITHUB_TOKEN` (provided by Github to each repository) must be declared as an environment - variable. See [Authenticating with the GITHUB_TOKEN](https://docs.github.com/en/actions/reference/authentication-in-a-workflow) -- Default: false -- 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. +For all explanations of our available input parameters and output variables, see our +[Inputs and Outputs document][io-doc]. -#### `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). - - See [`thread-comments`](#thread-comments), [`tidy-review`](#tidy-review), and [`format-review`](#format-review) options for further details. -- Default: true (meaning no LGTM comment used) - -#### `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. -- Default: false - -#### `file-annotations` - -- **Description**: Set this option to false to disable the use of file annotations as feedback. -- Default: true - -#### `database` - -- **Description**: The directory containing compilation database (like compile_commands.json) file. -- Default: '' - -#### `extra-args` - -- **Description**: A string of extra arguments passed to clang-tidy for use as compiler arguments (like `-std=c++14 -Wall`). -- Default: '' - -#### `tidy-review` - -**Beta feature** 🚧 - -- **Description**: Set this option to true to enable Pull Request reviews from clang-tidy. - - To use Pull Request reviews, the `GITHUB_TOKEN` (provided by Github to each repository) must be declared as an environment - variable. See [Authenticating with the GITHUB_TOKEN](https://docs.github.com/en/actions/reference/authentication-in-a-workflow) - - See also [the PR review feature caveats](https://cpp-linter.github.io/cpp-linter/pr_review_caveats.html) - - Note: The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews. -- Default: false - -#### `format-review` - -- **Description**: Set this option to true to enable Pull Request reviews from clang-format. - - To use Pull Request reviews, the `GITHUB_TOKEN` (provided by Github to each repository) must be declared as an environment - variable. See [Authenticating with the GITHUB_TOKEN](https://docs.github.com/en/actions/reference/authentication-in-a-workflow) - - See also [the PR review feature caveats](https://cpp-linter.github.io/cpp-linter/pr_review_caveats.html) - - Note: The [`no-lgtm`](#no-lgtm) option is applicable to Pull Request reviews. -- Default: false - -### 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. +See also our [example recipes][recipes-doc]. ## Example - - ### Annotations -Using [`file-annotations`](#file-annotations): +Using [`file-annotations`][file-annotations]: #### clang-format annotations -![clang-format annotations](https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/annotations-clang-format.png) +![clang-format annotations][format-annotations-preview] #### clang-tidy annotations -![clang-tidy annotations](https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/annotations-clang-tidy.png) +![clang-tidy annotations][tidy-annotations-preview] ### Thread Comment -Using [`thread-comments`](#thread-comments): +Using [`thread-comments`][thread-comments]: -![sample comment](https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/comment.png) +![sample thread-comment][thread-comment-preview] ### Step Summary -Using [`step-summary`](#step-summary): +Using [`step-summary`][step-summary]: -![step summary](https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/step-summary.png) +![step summary][step-summary-preview] ### Pull Request Review -Using only clang-tidy ([`tidy-review`](#tidy-review)): +#### Only clang-tidy + +Using [`tidy-review`][tidy-review]: + +![sample tidy-review][tidy-review-preview] -![sample tidy-review](https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/tidy-review.png) +#### Only clang-format -Using only clang-format ([`format-review`](#format-review)): +Using [`format-review`][format-review]: -![sample format-review](https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/format-review.png) +![sample format-review][format-review-preview] -![sample tidy-review](https://raw.githubusercontent.com/cpp-linter/cpp-linter-action/main/docs/images/format-suggestion.png) +![sample format-suggestion][format-suggestion-preview] - ## Add C/C++ Linter Action badge in README @@ -274,4 +146,4 @@ To provide feedback (requesting a feature or reporting a bug) please post to [is The scripts and documentation in this project are released under the [MIT License](https://github.com/cpp-linter/cpp-linter-action/blob/main/LICENSE) - + diff --git a/docs/badge_hook.py b/docs/badge_hook.py new file mode 100644 index 00000000..dd826dec --- /dev/null +++ b/docs/badge_hook.py @@ -0,0 +1,83 @@ +"""A mkdocs hook that injects an HTML syntax used to generate badges at build time.""" +import re +from re import Match +from mkdocs.config.defaults import MkDocsConfig +from mkdocs.structure.files import Files +from mkdocs.structure.pages import Page + + +def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files: Files): + # Replace callback + def replace(match: Match): + badge_type, args = match.groups() + args = args.strip() + if badge_type == "version": + return _badge_for_version(args, page, files) + elif badge_type == "flag": + return _badge_for_flags(args, page, files) + elif badge_type == "permission": + return _badge_for_permissions(args, page, files) + elif badge_type == "default": + return _badge_for_default(args, page, files) + + # Otherwise, raise an error + raise RuntimeError(f"Unknown badge type: {badge_type}") + + # Find and replace all external asset URLs in current page + return re.sub(r"", replace, markdown, flags=re.I | re.M) + + +# ----------------------------------------------------------------------------- +# Helper functions + +def _badge_for_flags(arg, page: Page, files: Files): + if arg == "experimental": + return _badge_for_experimental(page, files) + raise ValueError(f"Unsupported badge flag: {arg}") + +# Create badge +def _badge(icon: str, text: str = ""): + return "".join( + [ + '', + *([f'{icon}'] if icon else []), + *([f'{text}'] if text else []), + "", + ] + ) + + +# Create badge for version +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} "required version")', + text=f'[{text}]({href} "required version")', + ) + + +# Create badge for default value +def _badge_for_default(text: str, page: Page, files: Files): + return _badge(icon="Default", text=f"`#!yaml {text}`") + + +# Create badge for required value flag +def _badge_for_permissions(args: str, page: Page, files: Files): + match_permission = re.match(r"([^#]+)(.*)", args) + if match_permission is None: + raise ValueError(f"failed to parse permissions from {args}") + permission, link = match_permission.groups()[:2] + permission = permission.strip() + link = "permissions.md" + link + icon = "material-lock" + return _badge( + icon=f'[:{icon}:]({link} "required permissions")', + text=f'[`#!yaml {permission}`]({link} "required permission")', + ) + + +# Create badge for experimental flag +def _badge_for_experimental(page: Page, files: Files): + icon = "material-flask-outline" + return _badge(icon=f":{icon}:{{ .mdx-badge--heart }}", text="experimental") diff --git a/demo/.clang-format b/docs/examples/demo/.clang-format similarity index 100% rename from demo/.clang-format rename to docs/examples/demo/.clang-format diff --git a/demo/.clang-tidy b/docs/examples/demo/.clang-tidy similarity index 100% rename from demo/.clang-tidy rename to docs/examples/demo/.clang-tidy diff --git a/demo/compile_flags.txt b/docs/examples/demo/compile_flags.txt similarity index 100% rename from demo/compile_flags.txt rename to docs/examples/demo/compile_flags.txt diff --git a/demo/demo.cpp b/docs/examples/demo/demo.cpp similarity index 100% rename from demo/demo.cpp rename to docs/examples/demo/demo.cpp diff --git a/demo/demo.hpp b/docs/examples/demo/demo.hpp similarity index 100% rename from demo/demo.hpp rename to docs/examples/demo/demo.hpp diff --git a/docs/examples/index.md b/docs/examples/index.md new file mode 100644 index 00000000..61e361fe --- /dev/null +++ b/docs/examples/index.md @@ -0,0 +1,36 @@ + +[style]: ../inputs-outputs.md#style +[tidy-checks]: ../inputs-outputs.md#tidy-checks +[thread-comments]: ../inputs-outputs.md#thread-comments + +# Recipes + +Here are some example workflows to get started quickly. + +=== "only clang-tidy" + + ``` yaml + --8<-- "docs/examples/only-clang-tidy.yml" + ``` + + 1. See also [`style`][style] + 2. See also [`tidy-checks`][tidy-checks] + +=== "only clang-format" + + ``` yaml + --8<-- "docs/examples/only-clang-format.yml" + ``` + + 1. See also [`style`][style] + 2. See also [`tidy-checks`][tidy-checks] + +=== "only PR comments" + + ``` yaml + --8<-- "docs/examples/only-PR-comments.yml" + ``` + + 1. See also [`style`][style] + 2. See also [`tidy-checks`][tidy-checks] + 3. See also [`thread-comments`][thread-comments] diff --git a/docs/examples/only-PR-comments.yml b/docs/examples/only-PR-comments.yml new file mode 100644 index 00000000..1fc890b8 --- /dev/null +++ b/docs/examples/only-PR-comments.yml @@ -0,0 +1,30 @@ +name: cpp-linter +on: + pull_request: + branches: [main, master, develop] + paths: ['**.c', '**.cpp', '**.h', '**.hpp', '**.cxx', '**.hxx', '**.cc', '**.hh', '**CMakeLists.txt', 'meson.build', '**.cmake'] + push: + branches: [main, master, develop] + paths: ['**.c', '**.cpp', '**.h', '**.hpp', '**.cxx', '**.hxx', '**.cc', '**.hh', '**CMakeLists.txt', 'meson.build', '**.cmake'] + +jobs: + cpp-linter: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + # ... optionally setup build env to create a compilation database + + - uses: cpp-linter/cpp-linter-action@v2 + id: linter + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + style: 'file' # Use .clang-format config file. (1) + tidy-checks: '' # Use .clang-tidy config file. (2) + # only 'update' a single comment in a pull request's thread. (3) + thread-comments: ${{ github.event_name == 'pull_request' && 'update' }} + + - name: Fail fast?! + if: steps.linter.outputs.checks-failed > 0 + run: exit 1 diff --git a/docs/examples/only-clang-format.yml b/docs/examples/only-clang-format.yml new file mode 100644 index 00000000..a216b7e2 --- /dev/null +++ b/docs/examples/only-clang-format.yml @@ -0,0 +1,28 @@ +name: cpp-linter +on: + pull_request: + branches: [main, master, develop] + paths: ['**.c', '**.cpp', '**.h', '**.hpp', '**.cxx', '**.hxx', '**.cc', '**.hh', '**CMakeLists.txt', 'meson.build', '**.cmake'] + push: + branches: [main, master, develop] + paths: ['**.c', '**.cpp', '**.h', '**.hpp', '**.cxx', '**.hxx', '**.cc', '**.hh', '**CMakeLists.txt', 'meson.build', '**.cmake'] + +jobs: + cpp-linter: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + # ... optionally setup build env to create a compilation database + + - uses: cpp-linter/cpp-linter-action@v2 + id: linter + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + style: 'file' # Use .clang-format config file. (1) + tidy-checks: '-*' # disable clang-tidy checks. (2) + + - name: Fail fast?! + if: steps.linter.outputs.clang-format-checks-failed > 0 + run: exit 1 diff --git a/docs/examples/only-clang-tidy.yml b/docs/examples/only-clang-tidy.yml new file mode 100644 index 00000000..9f93f074 --- /dev/null +++ b/docs/examples/only-clang-tidy.yml @@ -0,0 +1,28 @@ +name: cpp-linter +on: + pull_request: + branches: [main, master, develop] + paths: ['**.c', '**.cpp', '**.h', '**.hpp', '**.cxx', '**.hxx', '**.cc', '**.hh', '**CMakeLists.txt', 'meson.build', '**.cmake'] + push: + branches: [main, master, develop] + paths: ['**.c', '**.cpp', '**.h', '**.hpp', '**.cxx', '**.hxx', '**.cc', '**.hh', '**CMakeLists.txt', 'meson.build', '**.cmake'] + +jobs: + cpp-linter: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + # ... optionally setup build env to create a compilation database + + - uses: cpp-linter/cpp-linter-action@v2 + id: linter + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + style: '' # disable clang-format checks. (1) + tidy-checks: '' # Use .clang-tidy config file. (2) + + - name: Fail fast?! + if: steps.linter.outputs.clang-tidy-checks-failed > 0 + run: exit 1 diff --git a/docs/index.md b/docs/index.md index 7322557a..9a55fa3f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,21 +1,22 @@ -{% - include-markdown "../README.md" - start="" - end="" -%} - -### Annotations - -![clang-format annotations](images/annotations-clang-format.png) - -![clang-tidy annotations](images/annotations-clang-tidy.png) +[file-annotations]: inputs-outputs.md#file-annotations +[thread-comments]: inputs-outputs.md#thread-comments +[step-summary]: inputs-outputs.md#step-summary +[tidy-review]: inputs-outputs.md#tidy-review +[format-review]: inputs-outputs.md#format-review -### Thread Comment +[io-doc]: inputs-outputs.md +[recipes-doc]: examples/index.md -![sample comment](images/comment.png) +[format-annotations-preview]: images/annotations-clang-format.png +[tidy-annotations-preview]: images/annotations-clang-tidy.png +[thread-comment-preview]: images/comment.png +[step-summary-preview]: images/step-summary.png +[tidy-review-preview]: images/tidy-review.png +[format-review-preview]: images/format-review.png +[format-suggestion-preview]: images/format-suggestion.png {% include-markdown "../README.md" - start="" - end="" + start="" + end="" %} diff --git a/docs/inputs-outputs.md b/docs/inputs-outputs.md new file mode 100644 index 00000000..639d4c5e --- /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 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/permissions.md b/docs/permissions.md new file mode 100644 index 00000000..f0beb03b --- /dev/null +++ b/docs/permissions.md @@ -0,0 +1,45 @@ +# Token Permissions + +This is an exhaustive list of required permissions organized by features. + +!!! info "Important" + The `GITHUB_TOKEN` environment variable should be supplied when running on a private repository. + Otherwise the runner does not not have the privileges needed for the features mentioned here. + + See also [Authenticating with the `GITHUB_TOKEN`](https://docs.github.com/en/actions/reference/authentication-in-a-workflow) + +## File Changes + +When using [`files-changed-only`](inputs-outputs.md#files-changed-only) or +[`lines-changed-only`](inputs-outputs.md#lines-changed-only) to get the list +of file changes for a CI event, the following permissions are needed: + +```yaml + permissions: + contents: read # (1)! +``` + +1. This permission is also needed to download files if the repository is not checked out before + running cpp-linter (for both push and pull_request events). + +## Thread Comments + +The [`thread-comments`](inputs-outputs.md#thread-comments) feature requires the following permissions: + +```yaml + permissions: + issues: write # (1)! + pull_requests: write # (2)! +``` + +1. for [push events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#push) +2. for [pull_request events](https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#pull_request) + +## Pull Request Reviews + +The [`tidy-review`](inputs-outputs.md#tidy-review) and [`format-review`](inputs-outputs.md#format-review) features require the following permissions: + +```yaml + permissions: + pull_requests: write +``` diff --git a/docs/pr-review-caveats.md b/docs/pr-review-caveats.md new file mode 100644 index 00000000..11059d94 --- /dev/null +++ b/docs/pr-review-caveats.md @@ -0,0 +1,84 @@ +# Pull Request Review Caveats + +[repository settings]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests +[organization settings]: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#preventing-github-actions-from-creating-or-approving-pull-requests +[hiding a comment]: https://docs.github.com/en/communities/moderating-comments-and-conversations/managing-disruptive-comments#hiding-a-comment +[resolve a conversion]: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/commenting-on-a-pull-request#resolving-conversations + +[tidy-review]: inputs-outputs.md#tidy-review +[format-review]: inputs-outputs.md#format-review +[lines-changed-only]: inputs-outputs.md#lines-changed-only +[style]: inputs-outputs.md#style + +!!! abstract + This information is specific to GitHub Pull Requests (often abbreviated as "PR"). + +While the Pull Request review feature has been diligently tested, there are still some caveats to +beware of when using Pull Request reviews. + +## Bot Permissions required +The "GitHub Actions" bot may need to be allowed to approve Pull Requests. +By default, the bot cannot approve Pull Request changes, only request more changes. +This will show as a warning in the workflow logs if the given token (set to the +environment variable `GITHUB_TOKEN`) isn't configured with the proper permissions. + +!!! note "See also" + Refer to the GitHub documentation for [repository settings][] or [organization settings][] + about adjusting the required permissions for GitHub Actions's `secrets.GITHUB_TOKEN`. + + See our [documented permissions](permissions.md#pull-request-reviews). + +## Auto-disabled for certain event types +The feature is auto-disabled for + +- closed Pull Requests +- Pull Requests marked as "draft" +- push events + +## Posts a new review on each run +Clang-tidy and clang-format suggestions are shown in 1 Pull Request review. + +- Users are encouraged to choose either [`tidy-review`][tidy-review] or [`format-review`][format-review]. + Enabling both will likely show duplicate or similar suggestions. + Remember, clang-tidy can be configured to use the same [`style`][style] that clang-format accepts. + There is no current implementation to combine suggestions from both tools (clang-tidy kind of + does that anyway). +- Each generated review is specific to the commit that triggered the Continuous Integration + workflow. +- Outdated reviews are dismissed but not marked as resolved. + Also, the outdated review's summary comment is not automatically hidden. + To reduce the Pull Request's thread noise, users interaction is required. + +!!! note "See also" + Refer to GitHub's documentation about [hiding a comment][]. + Hiding a Pull Request review's summary comment will not resolve the suggestions in the diff. + Please also refer to [resolve a conversion][] to collapse outdated or duplicate suggestions + in the diff. + +GitHub REST API does not provide a way to hide comments or mark review suggestions as resolved. + +!!! tip + We do support an environment variable named `CPP_LINTER_PR_REVIEW_SUMMARY_ONLY`. + If the variable is set to ``true``, then the review only contains a summary comment + with no suggestions posted in the diff. + +## Probable non-exhaustive reviews +If any suggestions did not fit within the Pull Request diff, then the review's summary comment will +indicate how many suggestions were left out. +The full patch of suggestions is always included as a collapsed code block in the review summary +comment. This isn't a problem we can fix. +GitHub won't allow review comments/suggestions to target lines that are not shown in the Pull +Request diff (the summation of file differences in a Pull Request). + +- Users are encouraged to set [`lines-changed-only`][lines-changed-only] to `true`. + This will *help* us keep the suggestions limited to lines that are shown within the Pull + Request diff. + However, there are still some cases where clang-format or clang-tidy will apply fixes to lines + that are not within the diff. + This can't be avoided because the `--line-filter` passed to the clang-tidy (and `--lines` + passed to clang-format) only applies to analysis, not fixes. +- Not every diagnostic from clang-tidy can be automatically fixed. + Some diagnostics require user interaction/decision to properly address. +- Some fixes provided might depend on what compiler is used. + We have made it so clang-tidy takes advantage of any fixes provided by the compiler. + Compilation errors may still prevent clang-tidy from reporting all concerns. diff --git a/docs/requirements.txt b/docs/requirements.txt index 69de84c1..894d190f 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ +markdown-gfm-admonition mkdocs mkdocs-include-markdown-plugin mkdocs-material diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css index bc0c6334..6651c6f7 100644 --- a/docs/stylesheets/extra.css +++ b/docs/stylesheets/extra.css @@ -6,3 +6,201 @@ th { .md-nav--primary .md-nav__title[for="__drawer"] { background-color: #4051b5; } + +@keyframes heart { + + 0%, + 40%, + 80%, + to { + transform: scale(1) + } + + 20%, + 60% { + transform: scale(1.15) + } +} + +.md-typeset .mdx-heart { + animation: heart 1s infinite +} + +.md-typeset .mdx-badge { + font-size: .85em +} + +.md-typeset .mdx-badge--heart { + color: #ff4281; +} + +.md-typeset .mdx-badge--heart.twemoji { + animation: heart 1s infinite +} + +.md-typeset .mdx-badge--right { + float: right; + margin-left: .35em +} + +[dir=ltr] .md-typeset .mdx-badge__icon { + border-top-left-radius: .1rem +} + +[dir=rtl] .md-typeset .mdx-badge__icon { + border-top-right-radius: .1rem +} + +[dir=ltr] .md-typeset .mdx-badge__icon { + border-bottom-left-radius: .1rem +} + +[dir=rtl] .md-typeset .mdx-badge__icon { + border-bottom-right-radius: .1rem +} + +.md-typeset .mdx-badge__icon { + background: var(--md-accent-fg-color--transparent); + padding: .2rem +} + +.md-typeset .mdx-badge__icon:last-child { + border-radius: .1rem +} + +[dir=ltr] .md-typeset .mdx-badge__text { + border-top-right-radius: .1rem +} + +[dir=rtl] .md-typeset .mdx-badge__text { + border-top-left-radius: .1rem +} + +[dir=ltr] .md-typeset .mdx-badge__text { + border-bottom-right-radius: .1rem +} + +[dir=rtl] .md-typeset .mdx-badge__text { + border-bottom-left-radius: .1rem +} + +.md-typeset .mdx-badge__text { + box-shadow: 0 0 0 1px inset var(--md-accent-fg-color--transparent); + padding: .2rem .3rem +} + +.md-typeset .mdx-social { + height: min(27rem, 80vw); + position: relative +} + +.md-typeset .mdx-social:hover .mdx-social__image { + background-color: #e4e4e40d +} + +.md-typeset .mdx-social__layer { + margin-top: 4rem; + position: absolute; + transform-style: preserve-3d; + transition: .25s cubic-bezier(.7, 0, .3, 1) +} + +.md-typeset .mdx-social__layer:hover .mdx-social__label { + opacity: 1 +} + +.md-typeset .mdx-social__layer:hover .mdx-social__image { + background-color: #7f7f7ffc +} + +.md-typeset .mdx-social__layer:hover~.mdx-social__layer { + opacity: 0 +} + +.md-typeset .mdx-social__image { + box-shadow: -.25rem .25rem .5rem #0000000d; + transform: rotate(-40deg) skew(15deg, 15deg) scale(.7); + transition: all .25s +} + +.md-typeset .mdx-social__image img { + display: block +} + +.md-typeset .mdx-social__label { + background-color: var(--md-default-fg-color--light); + color: var(--md-default-bg-color); + display: block; + opacity: 0; + padding: .2rem .4rem; + position: absolute; + transition: all .25s +} + +.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(6) { + transform: translateY(-30px) +} + +.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(5) { + transform: translateY(-20px) +} + +.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(4) { + transform: translateY(-10px) +} + +.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(3) { + transform: translateY(0) +} + +.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(2) { + transform: translateY(10px) +} + +.md-typeset .mdx-social:hover .mdx-social__layer:first-child { + transform: translateY(20px) +} + +.md-typeset .mdx-social:hover .mdx-social__layer:nth-child(0) { + transform: translateY(30px) +} + +.md-banner { + color: var(--md-footer-fg-color--lighter) +} + +.md-banner strong { + white-space: nowrap +} + +.md-banner a, +.md-banner strong { + color: var(--md-footer-fg-color) +} + +.md-banner a:focus, +.md-banner a:hover { + color: currentcolor +} + +.md-banner a:focus .twemoji, +.md-banner a:hover .twemoji { + background-color: var(--md-footer-fg-color); + box-shadow: none +} + +.md-banner .twemoji { + border-radius: 100%; + box-shadow: inset 0 0 0 .05rem currentcolor; + display: inline-block; + height: 1.2rem; + padding: .25rem; + transition: all .25s; + vertical-align: bottom; + width: 1.2rem +} + +.md-banner .twemoji svg { + display: block; + max-height: none +} diff --git a/mkdocs.yml b/mkdocs.yml index ecbbaa42..54879cb1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -6,15 +6,37 @@ repo_name: "cpp-linter/cpp-linter-action" edit_uri: "" nav: - index.md + - inputs-outputs.md + - pr-review-caveats.md + - permissions.md + - examples/index.md - contributing-guidelines.md theme: name: material features: - navigation.top + - content.tabs.link + - content.tooltips + - content.code.annotate + - content.code.copy + - navigation.footer + - search.suggest + - search.share + - navigation.tracking + - toc.follow logo: images/logo.png favicon: images/favicon.ico palette: + # Palette toggle for automatic mode + - media: "(prefers-color-scheme)" + primary: blue + accent: cyan + toggle: + icon: material/brightness-auto + name: Switch to light mode + + # Palette toggle for light mode - media: "(prefers-color-scheme: light)" scheme: default primary: blue @@ -22,13 +44,19 @@ theme: toggle: icon: material/lightbulb-outline name: Switch to dark mode - - media: "(prefers-color-scheme: light)" + + # Palette toggle for dark mode + - media: "(prefers-color-scheme: dark)" scheme: slate primary: blue accent: cyan toggle: icon: material/lightbulb - name: Switch to light mode + name: Switch to system preference +extra: + social: + - icon: fontawesome/brands/github + link: https://github.com/cpp-linter/cpp-linter extra_css: - stylesheets/extra.css @@ -39,9 +67,22 @@ plugins: markdown_extensions: - pymdownx.superfences - - pymdownx.tasklist + - pymdownx.tabbed: + alternate_style: true + - pymdownx.emoji: + emoji_index: !!python/name:material.extensions.emoji.twemoji + emoji_generator: !!python/name:material.extensions.emoji.to_svg - toc: permalink: true - pymdownx.highlight: linenums_style: pymdownx-inline - pymdownx.inlinehilite + - pymdownx.snippets: + check_paths: true + - attr_list + - admonition + - markdown_gfm_admonition + +# Hooks +hooks: + - docs/badge_hook.py