better docs

review readme files

Author: 2bndy5

README.md

@@ -1,16 +1,26 @@
 <!-- markdownlint-disable MD041 -->
+
+[file-annotations]: https://cpp-linter.github.io/cpp_linter_rs/cli#-a---file-annotations
+[thread-comments]: https://cpp-linter.github.io/cpp_linter_rs/cli#-g---thread-comments
+[step-summary]: https://cpp-linter.github.io/cpp_linter_rs/cli#-w---step-summary
+[tidy-review]: https://cpp-linter.github.io/cpp_linter_rs/cli#-d---tidy-review
+[format-review]: https://cpp-linter.github.io/cpp_linter_rs/cli#-m---format-review
+
+[format-annotations-preview]: docs/src/images/annotations-clang-format.png
+[tidy-annotations-preview]: docs/src/images/annotations-clang-tidy.png
+[step-summary-preview]: docs/src/images/step-summary.png
+[thread-comment-preview]: docs/src/images/comment.png
+[tidy-review-preview]: docs/src/images/tidy-review.png
+[format-review-preview]: docs/src/images/format-review.png
+[format-suggestion-preview]: docs/src/images/format-suggestion.png
+
 [![Python packaging][py-build-badge]][py-build-ci]
 [![Binary executable builds][bin-build-badge]][bin-build-ci]
 [![node-js builds][node-ci-badge]][node-ci]
 [![Test CI][test-ci-badge]][test-ci]
 [![Docs][docs-ci-badge]][docs-site]
 [![Pre-commit-ci][pre-commit-badge]][pre-commit-ci]
-
 [![codecov-status][codecov-badge]][codecov-project]
-[![docs.rs][docs-rs-badge]][docs-rs]
-[![PyPI - Version][pypi-badge]][pypi-pkg]
-[![Crates.io Version][crates-io-badge]][crates-io-pkg]
-[![NPM Version][npm-badge]][npm-pkg]
 
 [py-build-ci]: https://github.com/cpp-linter/cpp_linter_rs/actions/workflows/python-packaging.yml
 [py-build-badge]: https://github.com/cpp-linter/cpp_linter_rs/actions/workflows/python-packaging.yml/badge.svg
@@ -30,20 +40,78 @@
 [docs-rs]: https://docs.rs/cpp-linter
 [pypi-badge]: https://img.shields.io/pypi/v/cpp-linter
 [pypi-pkg]: https://pypi.org/project/cpp-linter/
+[test-pypi-badge]: https://img.shields.io/pypi/v/cpp-linter?pypiBaseUrl=https%3A%2F%2Ftest.pypi.org&label=test-pypi
+[test-pypi-pkg]: https://test.pypi.org/project/cpp-linter/
 [crates-io-badge]: https://img.shields.io/crates/v/cpp-linter
 [crates-io-pkg]: https://crates.io/crates/cpp-linter
 [npm-badge]: https://img.shields.io/npm/v/%40cpp-linter%2Fcpp-linter
 [npm-pkg]: https://www.npmjs.com/package/@cpp-linter/cpp-linter
 
 # C/C++ Linting Package
 
-A Python and Rust package for linting C/C++ code with clang-tidy and/or clang-format to collect feedback provided in the form of thread comments, step summary, or file annotations.
+A package for linting C/C++ code with clang-tidy and/or clang-format to collect feedback provided in the form of
+
+- [x] [thread-comments](#thread-comment)
+- [x] [step-summary](#step-summary)
+- [x] [file-annotations](#annotations)
+- [x] [Pull Request Review](#pull-request-review) suggestions
 
 > [!CAUTION]
 > This project is still experimental and subject to drastic changes.
-> Please use the pure python [cpp-linter](https://github.com/cpp-linter/cpp-linter)
+> Please use the [pure python cpp-linter](https://github.com/cpp-linter/cpp-linter)
 > package until this project is ready for deployment.
 
+## Install
+
+This package is available in several programming languages (through their respective package managers).
+
+### Rust
+
+[![Crates.io Version][crates-io-badge]][crates-io-pkg]
+[![docs.rs][docs-rs-badge]][docs-rs]
+
+Install from source code hosted at crates.io:
+
+```text
+cargo install cpp-linter
+```
+
+Install a pre-compiled binary from GitHub releases:
+
+First [install `cargo-binstall`](https://github.com/cargo-bins/cargo-binstall?tab=readme-ov-file#installation).
+
+```text
+cargo binstall cpp-linter
+```
+
+### Python
+
+[![PyPI - Version][pypi-badge]][pypi-pkg]
+
+Install the python package:
+
+```text
+pip install cpp-linter
+```
+
+[![testPyPI - Version][test-pypi-badge]][test-pypi-pkg]
+
+Pre-releases are uploaded to test-pypi:
+
+```text
+pip install -i https://test.pypi.org/simple/ cpp-linter
+```
+
+### Node.js
+
+[![NPM Version][npm-badge]][npm-pkg]
+
+Install the Node.js binding:
+
+```text
+npm -g install @cpp-linter/cpp-linter
+```
+
 ## Usage
 
 For usage in a CI workflow, see
@@ -52,56 +120,103 @@ For usage in a CI workflow, see
 For the description of supported Command Line Interface options, see
 [the CLI documentation](https://cpp-linter.github.io/cpp_linter_rs/cli.html).
 
+## Example
+
+### Annotations
+
+Using [`--file-annotations`][file-annotations]:
+
+#### clang-format annotations
+
+![clang-format annotations][format-annotations-preview]
+
+#### clang-tidy annotations
+
+![clang-tidy annotations][tidy-annotations-preview]
+
+### Thread Comment
+
+Using [`--thread-comments`][thread-comments]:
+
+![sample thread-comment][thread-comment-preview]
+
+### Step Summary
+
+Using [`--step-summary`][step-summary]:
+
+![step summary][step-summary-preview]
+
+### Pull Request Review
+
+#### Only clang-tidy
+
+Using [`--tidy-review`][tidy-review]:
+
+![sample tidy-review][tidy-review-preview]
+
+#### Only clang-format
+
+Using [`--format-review`][format-review]:
+
+![sample format-review][format-review-preview]
+
+![sample format-suggestion][format-suggestion-preview]
+
 ## Have question or feedback?
 
 To provide feedback (requesting a feature or reporting a bug) please post to
 [issues](https://github.com/cpp-linter/cpp_linter_rs/issues).
 
 ## License
 
-The scripts and documentation in this project are released under the [MIT][MIT].
+The scripts and documentation in this project are released under the [MIT].
 
 Dependencies (that are redistributed by us in binary form) have the following
 license agreements:
 
 - [clap](https://crates.io/crates/clap):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 - [git2](https://crates.io/crates/git2):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 
   The following are conditionally included in binaries (using the `openssl-vendored` feature on a
   case-by-case basis) because it is a dependency of git2:
 
   - [openssl](https://crates.io/crates/openssl): Licensed under [Apache 2.0][Apache2]
   - [openssl-probe](https://crates.io/crates/openssl-probe):
-    Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+    Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 
 - [lenient_semver](https://crates.io/crates/lenient_semver):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 - [log](https://crates.io/crates/log):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 - [regex](https://crates.io/crates/regex):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 - [reqwest](https://crates.io/crates/reqwest):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 - [semver](https://crates.io/crates/semver):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 - [serde](https://crates.io/crates/serde):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
-- [serde-xml-rs](https://crates.io/crates/serde-xml-rs): Licensed under [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
+- [serde-xml-rs](https://crates.io/crates/serde-xml-rs): Licensed under [MIT].
 - [serde_json](https://crates.io/crates/serde_json):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
-- [which](https://crates.io/crates/which): Licensed under [MIT][MIT].
-- [tokio](https://crates.io/crates/tokio): Licensed under [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
+- [which](https://crates.io/crates/which): Licensed under [MIT].
+- [tokio](https://crates.io/crates/tokio): Licensed under [MIT].
 - [futures](https://crates.io/crates/futures):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 - [chrono](https://crates.io/crates/chrono):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
 
 The python binding uses
 
 - [pyo3](https://crates.io/crates/pyo3):
-  Dual-licensed under [Apache 2.0][Apache2] or [MIT][MIT].
+  Dual-licensed under [Apache 2.0][Apache2] or [MIT].
+
+The node binding uses
+
+- [napi](https://crates.io/crates/napi): Licensed under [MIT]
+- [napi-derive](https://crates.io/crates/napi-derive): Licensed under [MIT]
 
 [MIT]: https://choosealicense.com/licenses/mit
 [Apache2]: https://choosealicense.com/licenses/apache-2.0/

cspell.config.yml

@@ -1,6 +1,7 @@
 version: "0.2"
 language: en
 words:
+  - binstall
   - Boolish
   - bugprone
   - chrono
@@ -15,6 +16,7 @@ words:
   - iomanip
   - libgit
   - markdownlint
+  - maturin
   - mdbook
   - msvc
   - napi
@@ -25,6 +27,8 @@ words:
   - pybind
   - pyfunction
   - pymodule
+  - pypi
+  - pyproject
   - ratelimit
   - reqwest
   - revparse

docs/src/SUMMARY.md

@@ -6,3 +6,5 @@
 - [Command Line Interface](./cli.md)
 - [Token Permissions](./permissions.md)
 - [Pull Request Review Caveats](./pr-review-caveats.md)
+- [Python Binding](./python.md)
+- [Node.js Binding](./node.md)

docs/src/images/annotations-clang-format.png

@@ -1,4 +1,17 @@
+<!-- markdownlint-disable MD041 MD053 -->
 
-<!-- markdownlint-disable MD041 -->
+[file-annotations]: cli.md#-a---file-annotations
+[thread-comments]: cli.md#-g---thread-comments
+[step-summary]: cli.md#-w---step-summary
+[tidy-review]: cli.md#-d---tidy-review
+[format-review]: cli.md#-m---format-review
 
-{{#include ../../README.md}}
+[format-annotations-preview]: images/annotations-clang-format.png
+[tidy-annotations-preview]: images/annotations-clang-tidy.png
+[step-summary-preview]: images/step-summary.png
+[thread-comment-preview]: images/comment.png
+[tidy-review-preview]: images/tidy-review.png
+[format-review-preview]: images/format-review.png
+[format-suggestion-preview]: images/format-suggestion.png
+
+{{#include ../../README.md:16:}}

docs/src/images/annotations-clang-tidy.png

@@ -0,0 +1,3 @@
+# Node.js Binding
+
+{{#include ../../node-binding/README.md:2:}}

docs/src/images/comment.png

@@ -0,0 +1,3 @@
+# Python Binding
+
+{{#include ../../py-binding/README.md:2:}}

docs/src/images/format-review.png

@@ -1,56 +1,63 @@
-# cpp-linter node binding
+# cpp-linter
 
-The node.js binding generated from rust source code.
+The node.js binding binding for the [cpp_linter_rs][this] rust project
+(built using [napi-rs](https://napi.rs) and [yarn](https://yarnpkg.com)).
 
-This project must use yarn because [napi-rs] uses [yarn] to get platform-specific information.
+[this]: https://github.com/cpp-linter/cpp_linter_rs
 
-[yarn]: https://yarnpkg.com/
-[napi-rs]: https://napi.rs/
+## Install
 
-This repo also doubles as a yarn workspace. So, the lock file exists in repo root folder.
-Furthermore, most scripts that can be executed in this project are available to run from repo root folder (using the same script name).
+Install with `npm`:
+
+```text
+npm -g install @cpp-linter/cpp-linter
+```
 
 ## Usage
 
-After the native module is built using [`yarn-build`](#yarn-build), you can import the binding via the generated `index.js` file (using the `node` console):
+For usage in a CI workflow, see
+[the cpp-linter/cpp-linter-action repository](https://github.com/cpp-linter/cpp-linter-action).
 
-```sh
-cppLinter = require('./index.js')
-await cppLinter.main(['cpp-linter', '--help'])
-```
+For the description of supported Command Line Interface options, see
+[the CLI documentation](https://cpp-linter.github.io/cpp_linter_rs/cli.html).
 
-All CLI arguments are passed as a array of strings to the binding's `main()` function.
-Notice the name of the CLI app (`'cpp-linter'`) is required because the rust argument parsing
-mechanism (`clap` crate) needs to know the name of the program invoked.
+## Development
+
+After the native module is built using [`yarn build:debug`](#yarn-builddebug), you can
+invoke the executable script as a normal CLI app:
+
+```text
+npx cpp-linter --help
+```
 
-## Scripts
+### Scripts
 
-> [!note]
-> If an available script is not described below, it should be considered a convenience tool for the CI workflow.
+If an available script is not described below, it should be considered a convenience
+tool for the CI/CD workflow.
 
-### `yarn build`
+#### `yarn build`
 
-This script builds the native module for distribution.
+This script builds the native module for distribution (with release profile optimizations).
 
-#### `yarn build:debug`
+##### `yarn build:debug`
 
-Same as `yarn build` but does not use the release optimizations.
+Same as `yarn build` but does not use the release profile optimizations.
 You should use this script when testing locally.
 
-### `yarn test`
+#### `yarn test`
 
 This script runs a simple test to ensure the native module was built correctly.
 
-## Folder structure
+### Folder structure
 
 | Name | Description |
 |-----:|:------------|
 | `__test__` | The location of the unit test(s). |
 | `npm` | The required metadata for publishing platform-specific packages to npm. |
 | `src` | The location for all rust sources related to binding the cpp-linter library. |
 | `build.rs` | The cargo-specific build script used when compiling the binding. |
-| `Cargo.toml` | Metadata about the rust package (which _is not_ intended to be published to crates.io). |
-| `package.json` | Metadata about the node.js binding (which _is_ meant to be published to npm). |
+| `Cargo.toml` | Metadata about the binding's rust package (which _is not_ intended to be published to crates.io). |
+| `package.json` | Metadata about the npm package (platform agnostic). |
 | `index.d.ts` | The generated TypeScript typing info the describes the exposing functionality in the built native module. |
 | `index.js` | The generated script that delegates which platform-specific package to import. |
 | `cpp-linter.x-y-z.node` | Then native module built for a specific platform (where `x-y-z` denotes the platform's name using compilation target). |