odoo-docs-validator
Automated style and structure validation for Odoo documentation. Use when creating or modifying RST files to ensure compliance with Odoo's heading hierarchy, line length limits, image metadata requirements, and UI element formatting rules. This skill provides validation scripts and a comprehensive rule reference for maintaining documentation quality.
When & Why to Use This Skill
The Odoo Documentation Validator is a specialized tool designed to automate the style and structural verification of RST files. It ensures full compliance with Odoo's official documentation standards, covering heading hierarchies, line length constraints, image metadata, and internal link integrity to maintain high-quality, professional technical content.
Use Cases
- Automated Style Linting: Quickly validate RST files against Odoo's specific heading symbols and hierarchy rules to ensure consistent document structure across modules.
- Efficient Documentation Refactoring: Use the auto-fix feature to instantly correct heading delimiter lengths and remove trailing whitespace across entire documentation directories.
- Link Integrity Verification: Systematically check :ref: and :doc: tags to prevent broken internal links and ensure seamless navigation within complex documentation sets.
- Quality Assurance for Contributions: Validate image alt tags and UI element formatting before submitting documentation changes to meet Odoo's strict metadata and accessibility requirements.
| name | odoo-docs-validator |
|---|---|
| description | Automated style and structure validation for Odoo documentation. Use when creating or modifying RST files to ensure compliance with Odoo's heading hierarchy, line length limits, image metadata requirements, and UI element formatting rules. This skill provides validation scripts and a comprehensive rule reference for maintaining documentation quality. |
Odoo Documentation Validator
Validate and automatically fix documentation changes against Odoo's official style and structural guidelines.
Quick Start
Validate and Fix a File
Run the validation script on your modified RST file. Use --fix to automatically correct common issues like heading lengths and trailing whitespace.
# Basic validation
python3 scripts/validate_docs.py <path_to_rst_file>
# Validation with auto-fix
python3 scripts/validate_docs.py <path_to_rst_file> --fix
# Recursive validation on a directory
python3 scripts/validate_docs.py content/applications/sales/ -r
Check Internal Links
Verify that all :ref: and :doc: links target valid existing resources.
python3 scripts/check_links.py <path_to_check>
Features
validate_docs.py
- H1 Headings: Ensures exactly one H1 per page, properly overlined and underlined.
- Heading Hierarchy: Validates the correct order of symbols (
=,-,~,*,^). - Delimiter Length: Ensures underlines match the heading text length (Auto-fixable).
- Line Length: Flags lines exceeding 100 characters (excluding URLs).
- Image Metadata: Verifies the presence of
:alt:tags and correct folder structure. - Cleanliness: Detects tabs, trailing whitespace (Auto-fixable), and Git conflict markers.
check_links.py
- Reference Check: Validates
:ref:targets against all explicit labels in the project. - Document Check: Validates
:doc:paths against existing RST files, handling both absolute and relative paths.
Resources
scripts/
validate_docs.py- CLI tool for style and structure validation.check_links.py- CLI tool for internal link verification.
references/
rules.md- Detailed style guide and structural rules.