Add documentation linting tools and style guide

Co-authored-by: timosachsenberg <[email protected]>

Author: Copilot

.editorconfig

@@ -0,0 +1,26 @@
+# EditorConfig helps maintain consistent coding styles
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+
+[*.{md,rst}]
+indent_style = space
+indent_size = 3
+max_line_length = 120
+
+[*.py]
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml}]
+indent_style = space
+indent_size = 2
+
+[Makefile]
+indent_style = tab

README.md

@@ -53,7 +53,6 @@ Now, open index.html file to view the changes or output of OpenMS ReadTheDocs do
 
 ## Contributing to OpenMS Docs
 
-Please read our [contributing guidelines](.github/CONTRIBUTING.md), before starting with contributing to OpenMS
-Documentation.
+Please read our [contributing guidelines](.github/CONTRIBUTING.md) and [style guide](STYLE_GUIDE.md), before starting with contributing to OpenMS Documentation.
 
 Let us know what you would like to read in OpenMS documentation using [GitHub issues](https://github.com/OpenMS/OpenMS-docs/issues/new/choose)!

STYLE_GUIDE.md

@@ -0,0 +1,93 @@
+# OpenMS Documentation Style Guide
+
+This document supplements the [Contributing Guidelines](.github/CONTRIBUTING.md) with specific style conventions for OpenMS documentation.
+
+## Terminology and Capitalization
+
+### Product and Technology Names
+
+Use proper capitalization for all OpenMS-related products and technologies:
+
+- **OpenMS** - Always capitalize both 'O' and 'MS'. Never use 'openMS', 'Openms', or 'openms' (except in URLs or file paths)
+- **pyOpenMS** - Python bindings, with lowercase 'py' prefix
+- **TOPP** (The OpenMS Proteomics Pipeline) - Always in all caps
+- **TOPPView** - Visualization tool, with camelCase
+- **KNIME** - Always in all caps
+
+### File Formats and Technical Terms
+
+- **mzML**, **mzTab** - Lowercase 'mz' followed by format name
+- **LC-MS** - Use hyphen, both parts capitalized
+- Use {term}\`technical term\` for glossary references
+
+## Links and URLs
+
+- **Always use HTTPS** instead of HTTP where available
+- For external links, verify they work before committing
+- Use reference-style links for frequently used URLs
+- Format: `[Link Text](https://example.com)`
+
+## Code and File References
+
+- Use backticks for code, commands, and file paths: \`filename.txt\`
+- Use {path}\`path,to,file\` for OpenMS-specific path references
+- Always specify language for code blocks:
+
+\`\`\`python
+print("Hello OpenMS")
+\`\`\`
+
+## Whitespace and Formatting
+
+- **No trailing whitespace** - Lines should not end with spaces or tabs
+- **Line length**: Maximum 120 characters (soft limit)
+- **Blank lines**: Use one blank line between sections
+- Use UTF-8 encoding for all files
+
+## Images and Figures
+
+- Always provide descriptive alt text: `![Descriptive text](path/to/image.png)`
+- Reference figures with anchors: `(Figure_1)=` and `<a href="#figure-1">Figure 1</a>`
+- Store images in `docs/_images/` with descriptive subdirectories
+
+## Admonitions
+
+Use appropriate admonition types:
+
+\`\`\`markdown
+\`\`\`{note}
+Important information for readers
+\`\`\`
+
+\`\`\`{warning}
+Critical warnings about potential issues
+\`\`\`
+
+\`\`\`{tip}
+Helpful tips and best practices
+\`\`\`
+\`\`\`
+
+## Version References
+
+- Reference "latest" for stable releases
+- Reference "develop" for development version
+- Be explicit about version requirements when necessary
+
+## Common Mistakes to Avoid
+
+1. ❌ `openMS` → ✅ `OpenMS`
+2. ❌ `Toppview` → ✅ `TOPPView`
+3. ❌ `http://example.com` → ✅ `https://example.com`
+4. ❌ Trailing spaces → ✅ Clean line endings
+5. ❌ `TODO: fix this` → ✅ Open an issue instead
+
+## Tools
+
+- Use `.editorconfig` file settings in your editor
+- Run `make html` to build and check documentation locally
+- Check for broken links before committing
+
+## Questions?
+
+Join us on [Discord](https://discord.gg/aJyWqf6uCn) or [GitHub Discussions](https://github.com/OpenMS/OpenMS-docs/discussions).

lint_docs.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""
+Documentation linting script for OpenMS-docs.
+Checks for common style and consistency issues.
+"""
+
+import os
+import re
+import sys
+from pathlib import Path
+
+
+class DocLinter:
+    def __init__(self):
+        self.errors = []
+        self.warnings = []
+
+    def check_file(self, filepath):
+        """Check a single file for issues."""
+        with open(filepath, 'r', encoding='utf-8', errors='ignore') as f:
+            content = f.read()
+            lines = content.split('\n')
+
+        for i, line in enumerate(lines, 1):
+            # Check for trailing whitespace
+            if line.endswith(' ') or line.endswith('\t'):
+                self.errors.append(f"{filepath}:{i}: Trailing whitespace")
+
+            # Check for insecure HTTP links (excluding specific domains)
+            if 'http://' in line and not any(x in line for x in ['localhost', 'openms.org', 'openms.de', 'rforge.net']):
+                self.warnings.append(f"{filepath}:{i}: Consider using HTTPS instead of HTTP")
+
+            # Check for inconsistent terminology
+            if re.search(r'\b(openMS|Openms)\b', line):
+                # Check if it's not in a URL, path, filename, or image directive
+                if not re.search(r'(https?://|\.openms|/openms|openms-|openms\.|image::|\.\.\s+figure::|\{image\})', line):
+                    self.errors.append(f"{filepath}:{i}: Use 'OpenMS' instead of variant spelling")
+
+            if re.search(r'\b(Toppview)\b', line):
+                # Check if it's not in a URL, path, or image
+                if not re.search(r'(https?://|/toppview|toppview-|image::|\.\.\s+figure::)', line, re.IGNORECASE):
+                    self.errors.append(f"{filepath}:{i}: Use 'TOPPView' (correct capitalization)")
+
+            # Check for TODO/FIXME in markdown comments (but allow in code blocks)
+            if re.search(r'<!--.*TODO.*-->', line) or re.search(r'<!--.*FIXME.*-->', line):
+                self.warnings.append(f"{filepath}:{i}: TODO/FIXME comment found - consider creating an issue")
+
+    def check_directory(self, directory):
+        """Check all documentation files in a directory."""
+        for root, dirs, files in os.walk(directory):
+            for file in files:
+                if file.endswith('.md') or file.endswith('.rst'):
+                    filepath = os.path.join(root, file)
+                    self.check_file(filepath)
+
+    def report(self):
+        """Print the linting report."""
+        print(f"\n{'='*60}")
+        print("OpenMS Documentation Linting Report")
+        print(f"{'='*60}\n")
+
+        if self.errors:
+            print(f"❌ ERRORS ({len(self.errors)}):")
+            for error in self.errors[:20]:  # Show first 20
+                print(f"   {error}")
+            if len(self.errors) > 20:
+                print(f"   ... and {len(self.errors) - 20} more")
+            print()
+
+        if self.warnings:
+            print(f"⚠️  WARNINGS ({len(self.warnings)}):")
+            for warning in self.warnings[:20]:  # Show first 20
+                print(f"   {warning}")
+            if len(self.warnings) > 20:
+                print(f"   ... and {len(self.warnings) - 20} more")
+            print()
+
+        if not self.errors and not self.warnings:
+            print("✅ No issues found! Documentation looks good.")
+            print()
+
+        return len(self.errors)
+
+
+def main():
+    """Main entry point."""
+    linter = DocLinter()
+
+    # Check docs directory
+    docs_dir = Path(__file__).parent / 'docs'
+    if docs_dir.exists():
+        linter.check_directory(docs_dir)
+    else:
+        print(f"Error: docs directory not found at {docs_dir}")
+        return 1
+
+    # Generate report
+    error_count = linter.report()
+
+    # Return error code if errors found
+    return 1 if error_count > 0 else 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())