Skip to content
This repository was archived by the owner on Apr 9, 2026. It is now read-only.

Commit bc2664c

Browse files
Copilottimosachsenberg
Copilot
and
timosachsenberg
committed
Add comprehensive documentation review and CI integration guide
Co-authored-by: timosachsenberg <5803621+timosachsenberg@users.noreply.github.com>
1 parent 07f63e3 commit bc2664c

2 files changed

Lines changed: 270 additions & 0 deletions

File tree

‎CI_INTEGRATION_GUIDE.md‎

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,141 @@
1+
# Suggested CI/CD Enhancement: Documentation Linting
2+
3+
This document provides instructions for integrating the `lint_docs.py` script into the existing GitHub Actions workflow.
4+
5+
## Option 1: Add to Existing Workflow (Recommended)
6+
7+
Add a linting step to `.github/workflows/main.yml` before the Sphinx build:
8+
9+
```yaml
10+
# Add this step after "Install dependencies" and before "Run sphinx build"
11+
- name: Lint documentation
12+
run: python3 lint_docs.py
13+
```
14+
15+
### Complete modified section:
16+
```yaml
17+
# install deps
18+
- name: Install dependencies
19+
run: pip install -r requirements.txt
20+
21+
# NEW: Lint documentation for consistency
22+
- name: Lint documentation
23+
run: python3 lint_docs.py
24+
25+
# build docs. "-n" for nitpick link checking
26+
- name: Run sphinx build. No warnings allowed but keep going.
27+
run: sphinx-build -M html ./docs build -W --keep-going -n
28+
```
29+
30+
## Option 2: Separate Linting Workflow
31+
32+
Create `.github/workflows/lint.yml`:
33+
34+
```yaml
35+
name: Documentation Lint
36+
37+
on:
38+
pull_request:
39+
paths:
40+
- 'docs/**'
41+
- '*.md'
42+
- '*.rst'
43+
44+
jobs:
45+
lint:
46+
runs-on: ubuntu-latest
47+
steps:
48+
- uses: actions/checkout@v4
49+
50+
- uses: actions/setup-python@v4
51+
with:
52+
python-version: '3.11'
53+
54+
- name: Lint documentation
55+
run: python3 lint_docs.py
56+
57+
- name: Comment on PR
58+
if: failure()
59+
uses: actions/github-script@v6
60+
with:
61+
script: |
62+
github.rest.issues.createComment({
63+
issue_number: context.issue.number,
64+
owner: context.repo.owner,
65+
repo: context.repo.repo,
66+
body: '⚠️ Documentation linting failed. Please run `python3 lint_docs.py` locally and fix the issues.'
67+
})
68+
```
69+
70+
## Option 3: Pre-commit Hook (Local Development)
71+
72+
Create `.pre-commit-config.yaml`:
73+
74+
```yaml
75+
repos:
76+
- repo: local
77+
hooks:
78+
- id: lint-docs
79+
name: Lint OpenMS Documentation
80+
entry: python3 lint_docs.py
81+
language: system
82+
pass_filenames: false
83+
files: \.(md|rst)$
84+
```
85+
86+
Then contributors can install pre-commit hooks:
87+
```bash
88+
pip install pre-commit
89+
pre-commit install
90+
```
91+
92+
## Benefits of CI Integration
93+
94+
1. **Automated checks**: Catches style issues before merge
95+
2. **Consistency**: Ensures all contributors follow the same standards
96+
3. **Educational**: Provides immediate feedback to contributors
97+
4. **Maintainability**: Reduces manual review burden
98+
99+
## Linter Exit Codes
100+
101+
- `0`: No errors found
102+
- `1`: Errors found (will fail CI build)
103+
104+
## Current Checks
105+
106+
The linter currently checks for:
107+
- ✅ Trailing whitespace
108+
- ✅ Insecure HTTP links
109+
- ✅ Inconsistent terminology
110+
- ✅ TODO/FIXME comments
111+
112+
## Future Enhancements
113+
114+
Consider adding additional tools:
115+
1. **markdownlint** - Markdown style checking
116+
2. **proselint** - Prose quality checking
117+
3. **codespell** - Spell checking
118+
4. **vale** - Style guide enforcement
119+
120+
## Testing the Linter
121+
122+
Test locally before committing:
123+
```bash
124+
# Run linter
125+
python3 lint_docs.py
126+
127+
# Build documentation
128+
make html
129+
130+
# Both should pass before creating a PR
131+
```
132+
133+
## Recommendation
134+
135+
Start with **Option 1** (adding to existing workflow) as it:
136+
- Requires minimal changes
137+
- Provides immediate feedback
138+
- Doesn't add extra CI complexity
139+
- Can be easily removed if needed
140+
141+
The linter is non-disruptive since it currently passes with no errors on the codebase.

‎DOCUMENTATION_REVIEW.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
# Documentation Consistency Review Summary
2+
3+
Date: October 2025
4+
Repository: OpenMS/OpenMS-docs
5+
6+
## Issues Identified and Fixed
7+
8+
### 1. Trailing Whitespace (FIXED ✅)
9+
- **Found:** 141 instances across 19 files
10+
- **Impact:** Can cause git diff noise and inconsistent formatting
11+
- **Action:** Removed all trailing whitespace
12+
- **Prevention:** Added `.editorconfig` to enforce clean line endings
13+
14+
### 2. Insecure HTTP Links (FIXED ✅)
15+
- **Found:** 23 HTTP links that could use HTTPS
16+
- **Impact:** Security warnings in browsers, potential MITM vulnerabilities
17+
- **Action:** Updated 22 links to HTTPS (1 R package repo kept as HTTP)
18+
- **Domains updated:**
19+
- nvie.com → https://nvie.com
20+
- cmake.org → https://cmake.org
21+
- dependencywalker.com → https://www.dependencywalker.com
22+
- valgrind.org → https://valgrind.org
23+
- git-scm.com → https://git-scm.com
24+
- openswath.org → https://openswath.org
25+
- r-project.org → https://www.r-project.org
26+
- dx.doi.org → https://doi.org (preferred DOI resolver)
27+
- view.ncbi.nlm.nih.gov → https://pubmed.ncbi.nlm.nih.gov
28+
- msstats.org → https://msstats.org
29+
- bioconductor.org → https://bioconductor.org
30+
31+
### 3. Broken/Malformed Links (FIXED ✅)
32+
- **Found:** 1 broken link in Windows installation guide
33+
- **Issue:** Malformed URL with mixed `.aspx#ControlPanel` syntax
34+
- **Action:** Fixed to proper Microsoft docs URL
35+
36+
### 4. TODO Comments (FIXED ✅)
37+
- **Found:** 2 TODO comments in production documentation
38+
- **Impact:** Looks unprofessional, confuses readers
39+
- **Action:** Removed HTML comments from metabolites tutorial
40+
- **Prevention:** Linter now warns about TODO/FIXME comments
41+
42+
## Terminology Analysis
43+
44+
After comprehensive analysis, terminology was found to be **mostly consistent**:
45+
46+
### Correct Usage Found:
47+
- **OpenMS** - Used correctly in prose and documentation text
48+
- **pyOpenMS** - Used correctly when referring to Python bindings
49+
- **TOPP/TOPPView** - Correctly capitalized in most places
50+
- **KNIME** - Correctly in all caps
51+
52+
### Lowercase Instances (Intentional and Correct):
53+
- File paths: `/openms/`, `openms-docs`
54+
- URLs: `openms.org`, `openms.de`, `openms.readthedocs.io`
55+
- Filenames: `openms-overview.jpg`, `openms-git-workflow.md`
56+
- Package names: `@openms`, `.openms`
57+
58+
**Conclusion:** No systematic terminology issues found. Most lowercase usage is correct for technical contexts (URLs, paths, filenames).
59+
60+
## Tools Created for Ongoing Maintenance
61+
62+
### 1. `.editorconfig`
63+
Automatic formatting rules for editors supporting EditorConfig:
64+
- UTF-8 encoding
65+
- LF line endings
66+
- No trailing whitespace
67+
- Consistent indentation (3 spaces for docs, 4 for Python)
68+
- 120 character line length guideline
69+
70+
### 2. `STYLE_GUIDE.md`
71+
Comprehensive style guide covering:
72+
- Proper terminology and capitalization
73+
- Link formatting guidelines
74+
- Code and file reference formatting
75+
- Image and figure requirements
76+
- Admonition usage
77+
- Common mistakes to avoid
78+
79+
### 3. `lint_docs.py`
80+
Automated linter that checks for:
81+
- Trailing whitespace
82+
- Insecure HTTP links
83+
- Inconsistent terminology (with smart exclusions)
84+
- TODO/FIXME comments
85+
- Can be integrated into CI/CD pipeline
86+
87+
### 4. Updated README
88+
- Now references both contributing guidelines and style guide
89+
- Makes tools discoverable for new contributors
90+
91+
## Recommendations
92+
93+
### For Maintainers
94+
1. **Run linter regularly**: `python3 lint_docs.py` before merging PRs
95+
2. **Consider CI integration**: Add linter to GitHub Actions workflow
96+
3. **Enforce EditorConfig**: Encourage contributors to use EditorConfig-enabled editors
97+
4. **Link checking**: Consider adding automated link checker (e.g., `linkchecker` or `pytest-deadlinks`)
98+
99+
### For Contributors
100+
1. **Read the style guide**: `STYLE_GUIDE.md` before making documentation changes
101+
2. **Use EditorConfig**: Install EditorConfig plugin in your editor
102+
3. **Build locally**: Run `make html` to verify changes before submitting
103+
4. **Check links**: Verify external links work before committing
104+
105+
### Future Improvements (Optional)
106+
1. **Pre-commit hooks**: Add git pre-commit hooks for automatic linting
107+
2. **Automated link checking**: Schedule periodic checks for broken external links
108+
3. **Spell checker**: Consider adding spell-check integration
109+
4. **Markdown linter**: Consider `markdownlint` for additional style checks
110+
5. **Screenshot updates**: Add process for keeping screenshots up-to-date
111+
112+
## Statistics
113+
114+
- **Files analyzed:** 62 documentation files (.md and .rst)
115+
- **Files modified:** 23
116+
- **Lines changed:** ~330
117+
- **Build status:** ✅ Successful
118+
- **Linter status:** ✅ Passing
119+
120+
## Conclusion
121+
122+
The OpenMS documentation is in good shape with only minor consistency issues found. The tools and guidelines added will help maintain high documentation quality going forward. The most important improvements were:
123+
124+
1. Cleaning up formatting (trailing whitespace)
125+
2. Improving security (HTTP → HTTPS)
126+
3. Providing clear style guidelines for future contributors
127+
4. Automating consistency checks
128+
129+
All changes maintain backward compatibility and improve the overall professionalism of the documentation.

0 commit comments

Comments
 (0)