Merge pull request #95 from SoftwareUnderstanding/copilot/add-gitlab-ci-cd-snippet

docs: exhaustive usage.md — document all CLI flags, config keys, and GitLab CI/CD snippet

Author: Anas-Elhounsri

README.md

@@ -72,168 +72,7 @@ pip install git+https://github.com/SoftwareUnderstanding/RsMetaCheck.git
 
 ## Usage
 
-### GitHub Action
-
-RsMetaCheck can be easily integrated into your CI/CD pipelines as a GitHub Action. We have set it up in GitHub Action in the following repository: [rs-metacheck-action](https://github.com/SoftwareUnderstanding/rs-metacheck-action) and is up in GitHub MarketPlace at [rsmetacheck actions](https://github.com/marketplace/actions/rsmetacheck).
-
-The action will generate `all_pitfalls_results.json`, along with the `pitfalls/` and `somef_outputs/` directories directly in your workflow workspace.
-
-### Run the Detection Tool locally
-
-#### Analyze a Single Repository
-
-```bash
-poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse
-```
-
-#### Analyze a Specific Branch
-
-You can analyze a specific branch of a repository by using the `--branch` or `-b` flag:
-
-```bash
-poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse --branch develop
-```
-
-#### Analyze Multiple Repositories from a JSON File
-
-```bash
-poetry run rsmetacheck --input repositories.json
-```
-
-The `repositories.json` file should be structured as follows:
-
-```json
-{
-  "repositories": [
-    "https://gitlab.com/example/example_repo_1",
-    "https://gitlab.com/example/example_repo_2",
-    "https://github.com/example/example_repo_3"
-  ]
-}
-```
-
-#### Customize Output Paths
-
-```bash
-poetry run rsmetacheck --input repositories.json \
-  --somef-output ./results/somef \
-  --pitfalls-output ./results/pitfalls \
-  --analysis-output ./results/summary.json \
-  --notes-output ./results/notes.json
-```
-
-#### Version Discrepancy Notes
-
-When a metadata version differs from the release version by a small margin (all version components differ by less than 2, e.g., `0.4.3.dev1` vs `0.4.2`), MetaCheck records a **note** rather than a full pitfall. To capture these observations, use the `--notes-output` flag:
-
-```bash
-poetry run rsmetacheck --input https://github.com/example/repo --notes-output ./notes.json
-```
-
-The notes file is only created when there are observations to report and the `--notes-output` path is specified. Its structure is:
-
-```json
-{
-  "total_notes": 1,
-  "notes": [
-    {
-      "repository": "example/repo",
-      "file_name": "repo_output.json",
-      "code": "P001",
-      "note": "Version discrepancy: metadata '0.4.3.dev1' vs release '0.4.2'"
-    }
-  ]
-}
-```
-
-If the version difference is significant (any component differs by 2 or more, e.g., `0.12.4` vs `0.12.1`), it is still flagged as a pitfall.
-
-#### Skip SoMEF and Analyze Existing Outputs
-
-If you've already run SoMEF separately:
-
-```bash
-poetry run rsmetacheck --skip-somef --input somef_outputs/*.json
-```
-
-Or for multiple paths:
-
-```bash
-poetry run rsmetacheck --skip-somef --input my_somef_outputs_1/*.json my_somef_outputs_2/*.json
-```
-
-#### Verbose Output for Passed Checks
-
-By default, the JSON-LD files generated by RsMetaCheck will only contain information about pitfalls and warnings that were actually detected. If you want to include all tests in the final JSON-LD, even tests that the repository successfully passed, use the `--verbose` flag:
-
-```bash
-poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse --verbose
-```
-
-#### Configure Analysis with a Root Config File
-
-You can configure RsMetaCheck with a TOML file at the repository root named `.rsmetacheck.toml` (auto-detected), or pass a custom path with `--config`.
-
-Supported options:
-
-- `ignore`: warnings/pitfalls to ignore (e.g. `P001`, `W002`)
-- `exclude_files`: metadata sources to ignore (glob, filename, or substring match)
-- `parameters`: per-check parameters for configurable checks
-- `profiles`: alternate configurations such as `unstable` or `prerelease`
-
-Example:
-
-```toml
-ignore = ["W002"]
-exclude_files = ["**/generated/**", "tmp_metadata.json"]
-
-[parameters.P001]
-ahead_significant_diff = 2
-
-[parameters.W002]
-stale_after_days = 3
-
-[profiles.unstable]
-ignore = ["W002", "P017"]
-
-[profiles.unstable.parameters.P001]
-ahead_significant_diff = 10
-
-[profiles.prerelease]
-ignore = []
-
-[profiles.prerelease.parameters.P001]
-ahead_significant_diff = 1
-```
-
-Use a specific profile:
-
-```bash
-poetry run rsmetacheck --input https://github.com/example/repo --config-profile unstable
-```
-
-Use a custom config path:
-
-```bash
-poetry run rsmetacheck --input https://github.com/example/repo --config ./ci/rsmetacheck.toml
-```
-
-### Output
-
-The tool will:
-
-- Process all JSON files in the SoMEF output directory (by default `somef_outputs` created by the tool)
-- Display progress messages showing detected pitfalls
-- Generate JSON-LD files of detailed Pitfalls and Warnings detected by the tool in `output_1_pitfalls.jsonld`,
-  `output_2_pitfalls.jsonld`, etc... in `pitfalls` (by default created by the tool) directory
-- Generate a comprehensive report in `all_pitfalls_results.json`
-
-The output file contains:
-
-- EVERSE standardized JSON-LD output of each repository
-- Summary statistics of analyzed repositories
-- Count and percentage for each pitfall type
-- Language-specific breakdown for repositories with target languages
+For full usage instructions — including CLI options, GitHub Action integration, GitLab CI/CD setup, output format, and configuration — please refer to the [usage documentation](https://rsmetacheck.readthedocs.io/en/latest/usage/).
 
 ## Troubleshooting