# Aditi - AsciiDoc DITA Integration Tool
[](https://badge.fury.io/py/aditi)
[](https://pypi.org/project/aditi/)
[](https://opensource.org/licenses/MIT)
> **Aditi** (Sanskrit: आदिति, "boundless") - A CLI tool that prepares AsciiDoc files for seamless migration to DITA.
Aditi helps technical writers identify and fix compatibility issues when migrating from AsciiDoc to DITA. It uses the Vale linter with comprehensive AsciiDocDITA rules to categorize issues as automatically fixable, partially fixable, or requiring manual review.
## ✨ Key Features
- 🔍 **Comprehensive Analysis**: Detects all 27 AsciiDocDITA compatibility issues
- 🔧 **Smart Auto-Fixing**: Automatically resolves deterministic issues (entities, content types)
- 📊 **Intelligent Categorization**: Sorts issues by fix complexity and priority
- 🚀 **Performance Optimized**: Parallel processing with container resource limits
- 🛡️ **Production Ready**: Robust error handling and graceful interruption support
- 📋 **Clear Reporting**: Visual progress indicators and actionable results
## 🚀 Installation
### Quick Install
```bash
pip install aditi
```
### System Requirements
- **Python**: 3.11 or later
- **Container Runtime**: Podman (preferred) or Docker
- **Platform**: Linux, macOS, Windows (with WSL2)
### Installation Verification
```bash
aditi --help
```
### Container Setup
Aditi will automatically pull the Vale container image on first use. To pre-download:
```bash
# For Podman (default)
podman pull docker.io/jdkato/vale:latest
# For Docker
docker pull docker.io/jdkato/vale:latest
```
## 🏁 Quick Start (5 minutes)
### 1. Initialize Your Project
```bash
cd /path/to/your/asciidoc-project
aditi init
```
**What this does:**
- Downloads Vale container image
- Installs AsciiDocDITA rules
- Creates `.vale.ini` configuration
- Sets up project for analysis
### 2. Configure Access Paths
```bash
aditi journey
```
**Interactive setup:**
- Select directories containing AsciiDoc files
- Configure repository permissions
- Set working preferences
### 3. Analyze Your Files
```bash
# Check all configured files
aditi check
# Check specific files/directories
aditi check docs/ user-guide.adoc
# Focus on specific issues
aditi check --rule ContentType --verbose
```
### 4. Apply Automatic Fixes
```bash
# Preview changes (recommended first step)
aditi fix --dry-run
# Apply fixes interactively
aditi fix
# Apply fixes automatically (CI/CD)
aditi fix --non-interactive
```
## 📚 Complete Example
```bash
# Start fresh project
mkdir my-dita-migration && cd my-dita-migration
# Install and initialize
pip install aditi
aditi init
# Set up paths (follow prompts)
aditi journey
# Analyze current state
aditi check --verbose
# Fix obvious problems first
aditi fix --rule EntityReference # Fix character entities
aditi fix --rule ContentType # Add missing content types
# Review remaining issues
aditi check
# Apply additional fixes as needed
aditi fix --dry-run # Preview all remaining fixes
aditi fix # Apply interactively
```
## 📖 Documentation
| Resource | Description |
|----------|-------------|
| **[Quick Start Guide](docs/QUICKSTART.md)** | Get up and running in under 5 minutes |
| **[Full Documentation](https://rolfedh.github.io/aditi/)** | Complete reference with examples |
| **[Example Files](docs/examples/)** | Sample AsciiDoc files demonstrating each rule |
| **[Troubleshooting](docs/QUICKSTART.md#troubleshooting)** | Common issues and solutions |
## 🎯 Rule Coverage
Aditi implements all **27 AsciiDocDITA rules** with intelligent categorization:
### 🔴 Fully Deterministic (Auto-fixable)
- **EntityReference**: Replaces unsupported character entities
### 🟡 Partially Deterministic (Partial auto-fix)
- **ContentType**: Adds missing content type attributes with placeholders
### 🔵 Non-Deterministic (Manual review required)
- **Structure Rules**: NestedSection, TaskSection, ExampleBlock
- **Content Rules**: AdmonitionTitle, AuthorLine, BlockTitle
- **Format Rules**: DiscreteHeading, ThematicBreak, PageBreak
- **Reference Rules**: CrossReference, LinkAttribute, IncludeDirective
- **And 18 more** covering all DITA compatibility concerns
## ⚠️ Known Limitations
- **Interactive Journey**: The `aditi journey` command requires interactive input
- **Container Dependency**: Requires Podman or Docker for Vale execution
- **Path Restrictions**: Files must be within configured allowed directories
- **Large Files**: Processing very large files (>10MB) may be slower
- **Windows**: Best experience on Linux/macOS; Windows requires WSL2
## 🔮 Future Enhancements
- Non-interactive mode for `journey` command (CI/CD support)
- Direct DITA output generation
- Custom rule configuration
- Integration with popular documentation platforms
- Batch processing optimizations for large repositories
## Development
To contribute to Aditi:
```bash
# Clone the repository
git clone https://github.com/rolfedh/aditi.git
cd aditi
# Install development dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Run linting
ruff check .
mypy .
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Acknowledgments
- Built on the [Vale](https://vale.sh/) linter
- Uses [AsciiDocDITA](https://github.com/jhradilek/asciidoctor-dita-vale) rules by Jaromir Hradilek
- Powered by [Typer](https://typer.tiangolo.com/) and [Rich](https://rich.readthedocs.io/)
Raw data
{
"_id": null,
"home_page": null,
"name": "aditi",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Rolfe Dlugy-Hegwer <rolfedh@github.com>",
"keywords": "asciidoc, dita, documentation, migration, vale, linter",
"author": null,
"author_email": "Rolfe Dlugy-Hegwer <rolfedh@github.com>",
"download_url": "https://files.pythonhosted.org/packages/dd/19/1386624702e240490c2583e2e019567c1a3cb9d6ff6657876ca2eaddf966/aditi-0.1.2.tar.gz",
"platform": null,
"description": "# Aditi - AsciiDoc DITA Integration Tool\n\n[](https://badge.fury.io/py/aditi)\n[](https://pypi.org/project/aditi/)\n[](https://opensource.org/licenses/MIT)\n\n> **Aditi** (Sanskrit: \u0906\u0926\u093f\u0924\u093f, \"boundless\") - A CLI tool that prepares AsciiDoc files for seamless migration to DITA.\n\nAditi helps technical writers identify and fix compatibility issues when migrating from AsciiDoc to DITA. It uses the Vale linter with comprehensive AsciiDocDITA rules to categorize issues as automatically fixable, partially fixable, or requiring manual review.\n\n## \u2728 Key Features\n\n- \ud83d\udd0d **Comprehensive Analysis**: Detects all 27 AsciiDocDITA compatibility issues\n- \ud83d\udd27 **Smart Auto-Fixing**: Automatically resolves deterministic issues (entities, content types)\n- \ud83d\udcca **Intelligent Categorization**: Sorts issues by fix complexity and priority \n- \ud83d\ude80 **Performance Optimized**: Parallel processing with container resource limits\n- \ud83d\udee1\ufe0f **Production Ready**: Robust error handling and graceful interruption support\n- \ud83d\udccb **Clear Reporting**: Visual progress indicators and actionable results\n\n## \ud83d\ude80 Installation\n\n### Quick Install\n\n```bash\npip install aditi\n```\n\n### System Requirements\n\n- **Python**: 3.11 or later\n- **Container Runtime**: Podman (preferred) or Docker\n- **Platform**: Linux, macOS, Windows (with WSL2)\n\n### Installation Verification\n\n```bash\naditi --help\n```\n\n### Container Setup\n\nAditi will automatically pull the Vale container image on first use. To pre-download:\n\n```bash\n# For Podman (default)\npodman pull docker.io/jdkato/vale:latest\n\n# For Docker \ndocker pull docker.io/jdkato/vale:latest\n```\n\n## \ud83c\udfc1 Quick Start (5 minutes)\n\n### 1. Initialize Your Project\n\n```bash\ncd /path/to/your/asciidoc-project\naditi init\n```\n\n**What this does:**\n- Downloads Vale container image\n- Installs AsciiDocDITA rules \n- Creates `.vale.ini` configuration\n- Sets up project for analysis\n\n### 2. Configure Access Paths\n\n```bash\naditi journey\n```\n\n**Interactive setup:**\n- Select directories containing AsciiDoc files\n- Configure repository permissions\n- Set working preferences\n\n### 3. Analyze Your Files\n\n```bash\n# Check all configured files\naditi check\n\n# Check specific files/directories \naditi check docs/ user-guide.adoc\n\n# Focus on specific issues\naditi check --rule ContentType --verbose\n```\n\n### 4. Apply Automatic Fixes\n\n```bash \n# Preview changes (recommended first step)\naditi fix --dry-run\n\n# Apply fixes interactively\naditi fix\n\n# Apply fixes automatically (CI/CD)\naditi fix --non-interactive\n```\n\n## \ud83d\udcda Complete Example\n\n```bash\n# Start fresh project\nmkdir my-dita-migration && cd my-dita-migration\n\n# Install and initialize\npip install aditi\naditi init\n\n# Set up paths (follow prompts)\naditi journey \n\n# Analyze current state\naditi check --verbose\n\n# Fix obvious problems first\naditi fix --rule EntityReference # Fix character entities\naditi fix --rule ContentType # Add missing content types\n\n# Review remaining issues \naditi check\n\n# Apply additional fixes as needed\naditi fix --dry-run # Preview all remaining fixes\naditi fix # Apply interactively\n```\n\n## \ud83d\udcd6 Documentation\n\n| Resource | Description |\n|----------|-------------|\n| **[Quick Start Guide](docs/QUICKSTART.md)** | Get up and running in under 5 minutes |\n| **[Full Documentation](https://rolfedh.github.io/aditi/)** | Complete reference with examples |\n| **[Example Files](docs/examples/)** | Sample AsciiDoc files demonstrating each rule |\n| **[Troubleshooting](docs/QUICKSTART.md#troubleshooting)** | Common issues and solutions |\n\n## \ud83c\udfaf Rule Coverage\n\nAditi implements all **27 AsciiDocDITA rules** with intelligent categorization:\n\n### \ud83d\udd34 Fully Deterministic (Auto-fixable)\n- **EntityReference**: Replaces unsupported character entities\n\n### \ud83d\udfe1 Partially Deterministic (Partial auto-fix) \n- **ContentType**: Adds missing content type attributes with placeholders\n\n### \ud83d\udd35 Non-Deterministic (Manual review required)\n- **Structure Rules**: NestedSection, TaskSection, ExampleBlock\n- **Content Rules**: AdmonitionTitle, AuthorLine, BlockTitle \n- **Format Rules**: DiscreteHeading, ThematicBreak, PageBreak\n- **Reference Rules**: CrossReference, LinkAttribute, IncludeDirective\n- **And 18 more** covering all DITA compatibility concerns\n\n## \u26a0\ufe0f Known Limitations\n\n- **Interactive Journey**: The `aditi journey` command requires interactive input\n- **Container Dependency**: Requires Podman or Docker for Vale execution \n- **Path Restrictions**: Files must be within configured allowed directories\n- **Large Files**: Processing very large files (>10MB) may be slower\n- **Windows**: Best experience on Linux/macOS; Windows requires WSL2\n\n## \ud83d\udd2e Future Enhancements\n\n- Non-interactive mode for `journey` command (CI/CD support)\n- Direct DITA output generation\n- Custom rule configuration\n- Integration with popular documentation platforms\n- Batch processing optimizations for large repositories\n\n## Development\n\nTo contribute to Aditi:\n\n```bash\n# Clone the repository\ngit clone https://github.com/rolfedh/aditi.git\ncd aditi\n\n# Install development dependencies\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Run linting\nruff check .\nmypy .\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Acknowledgments\n\n- Built on the [Vale](https://vale.sh/) linter\n- Uses [AsciiDocDITA](https://github.com/jhradilek/asciidoctor-dita-vale) rules by Jaromir Hradilek\n- Powered by [Typer](https://typer.tiangolo.com/) and [Rich](https://rich.readthedocs.io/)\n",
"bugtrack_url": null,
"license": null,
"summary": "A CLI tool to prepare AsciiDoc files for migration to DITA",
"version": "0.1.2",
"project_urls": {
"Documentation": "https://rolfedh.github.io/aditi/",
"Homepage": "https://github.com/rolfedh/aditi",
"Issues": "https://github.com/rolfedh/aditi/issues",
"Repository": "https://github.com/rolfedh/aditi.git"
},
"split_keywords": [
"asciidoc",
" dita",
" documentation",
" migration",
" vale",
" linter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "588d823aaaec1f3530f26a5bb8aba39016b2d8cffc1744a8dfb7dd808d251466",
"md5": "5dca41daae51caef9820c756ee326b0f",
"sha256": "b487b9cba5c70c4444cf2ad3ec7acbd79719f2d7f548400c47945a4c7342cc79"
},
"downloads": -1,
"filename": "aditi-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5dca41daae51caef9820c756ee326b0f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 82833,
"upload_time": "2025-07-29T15:42:35",
"upload_time_iso_8601": "2025-07-29T15:42:35.924784Z",
"url": "https://files.pythonhosted.org/packages/58/8d/823aaaec1f3530f26a5bb8aba39016b2d8cffc1744a8dfb7dd808d251466/aditi-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "dd191386624702e240490c2583e2e019567c1a3cb9d6ff6657876ca2eaddf966",
"md5": "30e7330bd3ddf6bbdb989eae4dc3e395",
"sha256": "c60d4c1b8664d4d297ea21dc2c08c41e860b30cee5fdb0cafce8a6148e08c7d7"
},
"downloads": -1,
"filename": "aditi-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "30e7330bd3ddf6bbdb989eae4dc3e395",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 106490,
"upload_time": "2025-07-29T15:42:38",
"upload_time_iso_8601": "2025-07-29T15:42:38.299688Z",
"url": "https://files.pythonhosted.org/packages/dd/19/1386624702e240490c2583e2e019567c1a3cb9d6ff6657876ca2eaddf966/aditi-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 15:42:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rolfedh",
"github_project": "aditi",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "aditi"
}
JSON
