Skip to content

Commit 0130b56

Browse files
author
aelhounsri
committed
Setting up documentation page with MKDocs, will be hosted on Read teh Docs
1 parent 3d1954f commit 0130b56

7 files changed

Lines changed: 172 additions & 28 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18956787.svg)](https://doi.org/10.5281/zenodo.18956787)
2-
![PyPI - Version](https://img.shields.io/pypi/v/rsmetacheck)
2+
[![PyPI - Version](https://img.shields.io/pypi/v/rsmetacheck)](https://pypi.org/project/rsmetacheck/)
33

44
# Research Software MetaCheck (a Pitfall/Warning Detection Tool)
55

@@ -71,33 +71,7 @@ pip install git+https://github.com/SoftwareUnderstanding/RsMetaCheck.git
7171

7272
### GitHub Action
7373

74-
RsMetaCheck can be easily integrated into your CI/CD pipelines as a GitHub Action.
75-
76-
```yaml
77-
name: RsMetaCheck
78-
79-
on:
80-
push:
81-
branches: [main]
82-
pull_request:
83-
branches: [main]
84-
85-
jobs:
86-
check-metadata:
87-
runs-on: ubuntu-latest
88-
steps:
89-
- name: Checkout repository
90-
uses: actions/checkout@v4
91-
92-
- name: Run RsMetaCheck
93-
uses: SoftwareUnderstanding/RsMetaCheck@v0.2.1 # Update to the latest version tag
94-
with:
95-
# Optional: Include passed checks in output (defaults to false)
96-
verbose: "false"
97-
env:
98-
# Optional: Provide token for SoMEF API rate limits
99-
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
100-
```
74+
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).
10175

10276
The action will generate `all_pitfalls_results.json`, along with the `pitfalls/` and `somef_outputs/` directories directly in your workflow workspace.
10377

‎docs/index.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Research Metadata Check (RSMetaCheck) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18956787.svg)](https://doi.org/10.5281/zenodo.18956787) [![PyPI - Version](https://img.shields.io/pypi/v/rsmetacheck)](https://pypi.org/project/rsmetacheck/)
2+
3+
**RSMetaCheck** is an automated tool for detecting common metadata quality issues (pitfalls & warnings) in software repositories.
4+
The tool analyzes SoMEF (Software Metadata Extraction Framework) output files to identify various problems in repository metadata
5+
files such as `codemeta.json`, `package.json`, `setup.py`, `DESCRIPTION`, and others.
6+
7+
## Features
8+
9+
RSMetaCheck identifies **29 different types of metadata quality issues** across multiple programming languages (Python, Java, C++, C, R, Rust).
10+
11+
- **Version Consistency**: Detects mismatches between metadata files and actual software releases.
12+
- **License Validation**: Identifies template placeholders, missing versions, and legal ambiguities in licenses.
13+
- **Link Verification**: Checks for broken URLs in CI configurations, software requirements, and download links.
14+
- **Metadata Formatting**: Validates field structures, author lists, and unique identifiers (DOIs, SWHIDs).
15+
- **Repository Integrity**: Ensures codeRepository fields point to the correct source and avoid git shorthands.

‎docs/installation.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
# Installation
2+
3+
RSMetaCheck requires **Python 3.11**.
4+
5+
## Using Poetry (Recommended)
6+
7+
1. **Clone the repository**:
8+
9+
```bash
10+
git clone https://github.com/SoftwareUnderstanding/RsMetaCheck.git
11+
cd RsMetaCheck
12+
```
13+
14+
2. **Install with Poetry**:
15+
16+
```bash
17+
poetry install
18+
```
19+
20+
3. **Configure SoMEF** (Optional but recommended):
21+
22+
Initially, the installation process runs `somef configure -a` automatically. If you need to reconfigure it (e.g., to add a GitHub token to avoid rate limits), run:
23+
24+
```bash
25+
poetry run somef configure
26+
```
27+
28+
## Using pip
29+
30+
Alternatively, you can install directly from GitHub:
31+
32+
```bash
33+
pip install git+https://github.com/SoftwareUnderstanding/RsMetaCheck.git
34+
```

‎docs/output.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Output
2+
3+
When you run RSMetaCheck, it generates several files containing the results of the analysis.
4+
5+
## Generated Files
6+
7+
* **all_pitfalls_results.json**: A comprehensive report containing summary statistics of all analyzed repositories.
8+
* **pitfalls/*.jsonld**: Detailed JSON-LD files for each analyzed repository, containing the specific pitfalls and warnings detected.
9+
* **somef_outputs/*.json**: The raw metadata extracted by SoMEF for each repository.
10+
11+
## Report Contents
12+
13+
The comprehensive report (`all_pitfalls_results.json`) includes:
14+
15+
1. **Summary Statistics**: Total repositories analyzed, success rate, and overall health.
16+
2. **Pitfall Breakdown**: A count and percentage for each type of pitfall detected across the entire batch.
17+
3. **Language Breakdown**: Statistics specific to different programming languages (Python, Java, R, etc.).
18+
4. **Standardized Output**: Each repository's results are provided in a standardized JSON-LD format.
19+
20+
## Verbose Mode
21+
22+
By default, the output files only contain detected pitfalls and warnings. If you want to include all tests (even those that passed), use the `--verbose` flag during execution:
23+
24+
```bash
25+
poetry run rsmetacheck --input <url> --verbose
26+
```

‎docs/stylesheets/mkdocs.css‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
2+
/* .md-typeset table td:nth-child(1) code,
3+
.md-typeset table th:nth-child(1) code {
4+
white-space: nowrap;
5+
} */
6+
7+
8+
.md-content {
9+
margin-right: 0 !important;
10+
}
11+
12+
.md-main__inner {
13+
max-width: 100% !important;
14+
}
15+
16+
.md-typeset table {
17+
width: 100% !important;
18+
display: table !important;
19+
}
20+
21+
.md-typeset table td:nth-child(1) code {
22+
white-space: nowrap !important;
23+
}
24+
25+
.md-typeset table td:nth-child(3) {
26+
white-space: normal !important;
27+
}

‎docs/usage.md‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Usage
2+
3+
RSMetaCheck can be used as a local command-line tool or integrated into your CI/CD pipeline as a GitHub Action.
4+
5+
## Command Line Interface
6+
7+
### Analyze a Single Repository
8+
9+
```bash
10+
poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse
11+
```
12+
13+
### Analyze a Specific Branch
14+
15+
```bash
16+
poetry run rsmetacheck --input https://github.com/tidyverse/tidyverse --branch develop
17+
```
18+
19+
### Analyze Multiple Repositories from a JSON File
20+
21+
Create a `repositories.json` file:
22+
23+
```json
24+
{
25+
"repositories": [
26+
"https://github.com/example/repo_1",
27+
"https://github.com/example/repo_2"
28+
]
29+
}
30+
```
31+
32+
Run the analysis:
33+
34+
```bash
35+
poetry run rsmetacheck --input repositories.json
36+
```
37+
38+
## GitHub Action
39+
40+
You can integrate RSMetaCheck into your GitHub workflows:
41+
42+
```yaml
43+
name: RsMetaCheck
44+
45+
on: [push, pull_request]
46+
47+
jobs:
48+
check-metadata:
49+
runs-on: ubuntu-latest
50+
steps:
51+
- uses: actions/checkout@v4
52+
- uses: SoftwareUnderstanding/RsMetaCheck@v0.2.1
53+
with:
54+
verbose: "false"
55+
env:
56+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
57+
```

‎mkdocs.yml‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
site_name: RSMetaCheck
2+
theme:
3+
name: material
4+
extra_css:
5+
- stylesheets/mkdocs.css
6+
nav:
7+
- Home: index.md
8+
- Installation: installation.md
9+
- Usage: usage.md
10+
- Output: output.md
11+
- Catalog: catalog.md

0 commit comments

Comments
 (0)