| Name | qtuidoctools JSON |
| Version |
2.0.3
JSON |
| download |
| home_page | None |
| Summary | Tools for working with Qt .ui files |
| upload_time | 2025-09-03 14:29:07 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.11 |
| license | None |
| keywords |
cli
documentation
json
qt
ui
yaml
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# qtuidoctools
Tools for working with Qt .ui files. Written in Python 3.11+
- Copyright (c) 2025 Fontlab Ltd. <opensource@fontlab.com>
- [MIT license](./LICENSE)
---
## 1. What It Does
**qtuidoctools** is a command-line tool that bridges Qt UI files and documentation systems. It extracts widget information from Qt Designer's .ui XML files, converts them to structured YAML documentation, and compiles everything into JSON help files for runtime use.
### 1.1. Primary Use Cases
1. **Documentation Generation**: Extract all widgets from .ui files and create editable YAML documentation files
2. **Help System Building**: Compile YAML documentation into JSON files for in-application help systems
3. **Tooltip Synchronization**: Bidirectionally sync tooltips between UI files and documentation
4. **Documentation Maintenance**: Keep UI changes and documentation in sync across large Qt projects
## 2. Installation
Install the release version from PyPI:
```bash
uv pip install --system qtuidoctools
```
Or install the development version from GitHub:
```bash
uv pip install --system --upgrade git+https://github.com/fontlabcom/qtuidoctools
```
## 3. How It Works
### 3.1. Architecture Overview
The tool consists of three main components:
#### 3.1.1. **CLI Interface** (`__main__.py`)
- **Commands**: `update`, `build`, `cleanup`, `version`
- **Framework**: Fire-based command-line interface
- **Purpose**: Orchestrates the processing pipeline and handles user interactions
#### 3.1.2. **UI Processing Engine** (`qtui.py`)
- **Core Class**: `UIDoc` - handles individual .ui file processing
- **XML Parsing**: Uses lxml to extract widget metadata from Qt Designer XML
- **YAML Generation**: Creates structured documentation files with widget information
- **Tooltip Management**: Synchronizes tooltips between UI and YAML files
#### 3.1.3. **Build System** (`qtuibuild.py`)
- **Core Class**: `UIBuild` - compiles YAML files into JSON
- **Text Processing**: Supports markdown-like formatting via `prepMarkdown()`
- **Cross-referencing**: Allows help tips to reference other widgets
- **JSON Output**: Creates consolidated help files for runtime consumption
### 3.2. Data Flow Pipeline
```
Qt .ui Files → Widget Extraction → YAML Documentation → JSON Help System
↓ ↓ ↓ ↓
XML Parse Metadata Extract Structured Docs Runtime Help
```
#### 3.2.1. Step 1: Widget Extraction
- Parses Qt Designer .ui XML files using lxml
- Extracts widget IDs, names, tooltips, and hierarchical structure
- Handles nested containers and numbered widget indices
- Creates XPath-based widget addressing system
#### 3.2.2. Step 2: YAML Documentation
- Generates one YAML file per .ui file
- Maintains widget metadata in structured, human-editable format
- Uses dict for consistent output ordering (diff-friendly)
- Supports empty widget inclusion for comprehensive documentation
#### 3.2.3. Step 3: Table of Contents (TOC)
- Creates master index (`helptips.yaml`) of all widgets across files
- Tracks widget relationships and cross-references
- Maintains project-wide documentation structure
#### 3.2.4. Step 4: JSON Compilation
- Processes all YAML files into single JSON output
- Applies text formatting and markdown processing
- Resolves cross-references between help tips
- Creates runtime-ready help system data
## 4. Usage Examples
### 4.1. Basic Workflow
1. **Extract widgets from UI files**:
```bash
qtuidoctools update -d path/to/ui/files -t helptips.yaml -o yaml/
```
2. **Build JSON help system**:
```bash
qtuidoctools build -j helptips.json -t helptips.yaml -d yaml/
```
3. **Clean up YAML formatting**:
```bash
qtuidoctools cleanup -o yaml/ -c
```
### 4.2. Advanced Options
**Tooltip synchronization**:
```bash
# Copy YAML help tips to UI tooltips
qtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --tooltipstoxml
# Copy UI tooltips to YAML help tips
qtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --tooltipstoyaml
```
**Debug and verbose output**:
```bash
qtuidoctools update -d ui/ -v # Verbose: DEBUG + timestamp + code location
qtuidoctools update -d ui/ -q # Quiet: warnings and errors only
```
### 4.3. Parallel Processing (Faster Updates)
The `update` command can process multiple `.ui` files in parallel (default: 8 workers). Only the main process writes YAML and TOC; workers save XML per-file (no collisions).
```bash
# Default 8 workers; auto-merge duplicate names (e.g., mainwindow.ui → mainwindow.yaml)
qtuidoctools update -d ui/ -t helptips.yaml -o yaml/
# Conflict policy when merging duplicate-name outputs
qtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --mergeprefer=nonempty # or: first | last
# Strict mode: fail the run if conflicting non-empty values are detected
qtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --mergestrict
# Dry run: do all computation and merging in-memory (no file writes)
qtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --dryrun
# Disable parallelism explicitly
qtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --workers=1
```
## 5. Code Structure
### 5.1. Key Files
- **`qtuidoctools/__init__.py`**: Package metadata and version info
- **`qtuidoctools/__main__.py`**: Fire CLI interface (update, build, cleanup, version)
- **`qtuidoctools/qtui.py`**: Core UI processing logic and `UIDoc` class
- **`qtuidoctools/qtuibuild.py`**: Build system and `UIBuild` class
- **`qtuidoctools/textutils.py`**: Text processing utilities for markdown formatting
- **`qtuidoctools/keymap_db.py`**: Keyboard mapping utilities
### 5.2. Dependencies
- **Fire**: Command-line interface framework
- **lxml** (≥4.4.1): XML parsing for .ui files
- **PyYAML** (≥5.1.1): YAML file processing
- **yaplon**: Enhanced YAML processing with dict support
- **Qt.py** (≥1.2.1): Qt compatibility layer
- **loguru + rich**: colorful, minimal, and readable logs
### 5.3. Processing Logic
#### 5.3.1. Widget Extraction (`UIDoc.extractWidgets()`)
```python
# Simplified extraction flow
1. Parse UI XML with lxml
2. Find all widgets with object names
3. Extract metadata: ID, name, tooltip, type
4. Build hierarchical structure using XPath
5. Generate YAML-friendly data structure
```
#### 5.3.2. YAML Generation (`UIDoc.updateYaml()`)
```python
# YAML structure per widget
widget_id:
h.nam: "Human readable name"
h.tip: "Help tip content"
h.cls: "Widget class name"
# Additional metadata...
```
#### 5.3.3. JSON Compilation (`UIBuild.build()`)
```python
# Build process
1. Load all YAML files from directory
2. Process text with prepMarkdown()
3. Resolve cross-references between tips
4. Compile into single JSON structure
5. Add debug information if requested
```
## 6. Logging
qtuidoctools uses loguru + rich for colorful and concise logs:
- Default: minimal metadata (message only).
- `--verbose`: adds timestamp and code location; DEBUG logs enabled.
- `--quiet`: warnings and errors only.
- File paths are shown relative to the repository root when possible.
Example:
```
✓ ui/panels/filterpanel.ui (12 widgets, 0.43s)
✖ ui/tools/broken.ui - XMLSyntaxError: expected '>'
```
## 7. Why This Architecture?
### 7.1. Design Principles
1. **Separation of Concerns**: CLI, processing, and building are distinct modules
2. **Format Flexibility**: Multiple output formats (YAML for editing, JSON for runtime)
3. **Human-Friendly**: YAML files are editable and version-control friendly
4. **Bidirectional Sync**: Changes can flow from UI to docs or docs to UI
5. **Incremental Updates**: Process only changed files for large projects
### 7.2. Technical Decisions
- **lxml over xml.etree**: Better XPath support and namespace handling
- **dict**: Ensures consistent YAML output for version control
- **Click over argparse**: More sophisticated CLI with nested commands
- **YAML intermediate format**: Human-readable, editable, diff-friendly
- **uv script headers**: Modern Python dependency management
## 8. File Format Examples
### 8.1. Input: Qt .ui File
```xml
<ui version="4.0">
<widget class="QMainWindow" name="MainWindow">
<widget class="QPushButton" name="saveButton">
<property name="toolTip">
<string>Save the current document</string>
</property>
</widget>
</widget>
</ui>
```
### 8.2. Output: YAML Documentation
```yaml
saveButton:
h.nam: 'Save Button'
h.tip: 'Save the current document to disk'
h.cls: 'QPushButton'
```
### 8.3. Output: JSON Help System
```json
{
"saveButton": {
"name": "Save Button",
"tip": "Save the current document to disk",
"class": "QPushButton"
}
}
```
---
Raw data
{
"_id": null,
"home_page": null,
"name": "qtuidoctools",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "cli, documentation, json, qt, ui, yaml",
"author": null,
"author_email": "Adam Twardoch <adam+github@twardoch.com>",
"download_url": "https://files.pythonhosted.org/packages/6d/45/48d6b0085ef6e6f1723fb7bace432742bdfcae44f047a0a2fcef1a578016/qtuidoctools-2.0.3.tar.gz",
"platform": null,
"description": "\n# qtuidoctools\n\nTools for working with Qt .ui files. Written in Python 3.11+\n\n- Copyright (c) 2025 Fontlab Ltd. <opensource@fontlab.com>\n- [MIT license](./LICENSE)\n\n---\n\n## 1. What It Does\n\n**qtuidoctools** is a command-line tool that bridges Qt UI files and documentation systems. It extracts widget information from Qt Designer's .ui XML files, converts them to structured YAML documentation, and compiles everything into JSON help files for runtime use.\n\n### 1.1. Primary Use Cases\n\n1. **Documentation Generation**: Extract all widgets from .ui files and create editable YAML documentation files\n2. **Help System Building**: Compile YAML documentation into JSON files for in-application help systems\n3. **Tooltip Synchronization**: Bidirectionally sync tooltips between UI files and documentation\n4. **Documentation Maintenance**: Keep UI changes and documentation in sync across large Qt projects\n\n## 2. Installation\n\nInstall the release version from PyPI:\n\n```bash\nuv pip install --system qtuidoctools\n```\n\nOr install the development version from GitHub:\n\n```bash\nuv pip install --system --upgrade git+https://github.com/fontlabcom/qtuidoctools\n```\n\n## 3. How It Works\n\n### 3.1. Architecture Overview\n\nThe tool consists of three main components:\n\n#### 3.1.1. **CLI Interface** (`__main__.py`)\n\n- **Commands**: `update`, `build`, `cleanup`, `version`\n- **Framework**: Fire-based command-line interface\n- **Purpose**: Orchestrates the processing pipeline and handles user interactions\n\n#### 3.1.2. **UI Processing Engine** (`qtui.py`)\n\n- **Core Class**: `UIDoc` - handles individual .ui file processing\n- **XML Parsing**: Uses lxml to extract widget metadata from Qt Designer XML\n- **YAML Generation**: Creates structured documentation files with widget information\n- **Tooltip Management**: Synchronizes tooltips between UI and YAML files\n\n#### 3.1.3. **Build System** (`qtuibuild.py`)\n\n- **Core Class**: `UIBuild` - compiles YAML files into JSON\n- **Text Processing**: Supports markdown-like formatting via `prepMarkdown()`\n- **Cross-referencing**: Allows help tips to reference other widgets\n- **JSON Output**: Creates consolidated help files for runtime consumption\n\n### 3.2. Data Flow Pipeline\n\n```\nQt .ui Files \u2192 Widget Extraction \u2192 YAML Documentation \u2192 JSON Help System\n \u2193 \u2193 \u2193 \u2193\n XML Parse Metadata Extract Structured Docs Runtime Help\n```\n\n#### 3.2.1. Step 1: Widget Extraction\n\n- Parses Qt Designer .ui XML files using lxml\n- Extracts widget IDs, names, tooltips, and hierarchical structure\n- Handles nested containers and numbered widget indices\n- Creates XPath-based widget addressing system\n\n#### 3.2.2. Step 2: YAML Documentation\n\n- Generates one YAML file per .ui file\n- Maintains widget metadata in structured, human-editable format\n- Uses dict for consistent output ordering (diff-friendly)\n- Supports empty widget inclusion for comprehensive documentation\n\n#### 3.2.3. Step 3: Table of Contents (TOC)\n\n- Creates master index (`helptips.yaml`) of all widgets across files\n- Tracks widget relationships and cross-references\n- Maintains project-wide documentation structure\n\n#### 3.2.4. Step 4: JSON Compilation\n\n- Processes all YAML files into single JSON output\n- Applies text formatting and markdown processing\n- Resolves cross-references between help tips\n- Creates runtime-ready help system data\n\n## 4. Usage Examples\n\n### 4.1. Basic Workflow\n\n1. **Extract widgets from UI files**:\n\n```bash\nqtuidoctools update -d path/to/ui/files -t helptips.yaml -o yaml/\n```\n\n2. **Build JSON help system**:\n\n```bash\nqtuidoctools build -j helptips.json -t helptips.yaml -d yaml/\n```\n\n3. **Clean up YAML formatting**:\n\n```bash\nqtuidoctools cleanup -o yaml/ -c\n```\n\n### 4.2. Advanced Options\n\n**Tooltip synchronization**:\n\n```bash\n# Copy YAML help tips to UI tooltips\nqtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --tooltipstoxml\n\n# Copy UI tooltips to YAML help tips\nqtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --tooltipstoyaml\n```\n\n**Debug and verbose output**:\n\n```bash\nqtuidoctools update -d ui/ -v # Verbose: DEBUG + timestamp + code location\nqtuidoctools update -d ui/ -q # Quiet: warnings and errors only\n```\n\n### 4.3. Parallel Processing (Faster Updates)\n\nThe `update` command can process multiple `.ui` files in parallel (default: 8 workers). Only the main process writes YAML and TOC; workers save XML per-file (no collisions).\n\n```bash\n# Default 8 workers; auto-merge duplicate names (e.g., mainwindow.ui \u2192 mainwindow.yaml)\nqtuidoctools update -d ui/ -t helptips.yaml -o yaml/\n\n# Conflict policy when merging duplicate-name outputs\nqtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --mergeprefer=nonempty # or: first | last\n\n# Strict mode: fail the run if conflicting non-empty values are detected\nqtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --mergestrict\n\n# Dry run: do all computation and merging in-memory (no file writes)\nqtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --dryrun\n\n# Disable parallelism explicitly\nqtuidoctools update -d ui/ -t helptips.yaml -o yaml/ --workers=1\n```\n\n## 5. Code Structure\n\n### 5.1. Key Files\n\n- **`qtuidoctools/__init__.py`**: Package metadata and version info\n- **`qtuidoctools/__main__.py`**: Fire CLI interface (update, build, cleanup, version)\n- **`qtuidoctools/qtui.py`**: Core UI processing logic and `UIDoc` class\n- **`qtuidoctools/qtuibuild.py`**: Build system and `UIBuild` class\n- **`qtuidoctools/textutils.py`**: Text processing utilities for markdown formatting\n- **`qtuidoctools/keymap_db.py`**: Keyboard mapping utilities\n \n\n### 5.2. Dependencies\n\n- **Fire**: Command-line interface framework\n- **lxml** (\u22654.4.1): XML parsing for .ui files\n- **PyYAML** (\u22655.1.1): YAML file processing\n- **yaplon**: Enhanced YAML processing with dict support\n- **Qt.py** (\u22651.2.1): Qt compatibility layer\n - **loguru + rich**: colorful, minimal, and readable logs\n\n### 5.3. Processing Logic\n\n#### 5.3.1. Widget Extraction (`UIDoc.extractWidgets()`)\n\n```python\n# Simplified extraction flow\n1. Parse UI XML with lxml\n2. Find all widgets with object names\n3. Extract metadata: ID, name, tooltip, type\n4. Build hierarchical structure using XPath\n5. Generate YAML-friendly data structure\n```\n\n#### 5.3.2. YAML Generation (`UIDoc.updateYaml()`)\n\n```python\n# YAML structure per widget\nwidget_id:\n h.nam: \"Human readable name\"\n h.tip: \"Help tip content\"\n h.cls: \"Widget class name\"\n # Additional metadata...\n```\n\n#### 5.3.3. JSON Compilation (`UIBuild.build()`)\n\n```python\n# Build process\n1. Load all YAML files from directory\n2. Process text with prepMarkdown()\n3. Resolve cross-references between tips\n4. Compile into single JSON structure\n5. Add debug information if requested\n```\n\n## 6. Logging\n\nqtuidoctools uses loguru + rich for colorful and concise logs:\n\n- Default: minimal metadata (message only).\n- `--verbose`: adds timestamp and code location; DEBUG logs enabled.\n- `--quiet`: warnings and errors only.\n- File paths are shown relative to the repository root when possible.\n\nExample:\n\n```\n\u2713 ui/panels/filterpanel.ui (12 widgets, 0.43s)\n\u2716 ui/tools/broken.ui - XMLSyntaxError: expected '>'\n```\n\n## 7. Why This Architecture?\n\n### 7.1. Design Principles\n\n1. **Separation of Concerns**: CLI, processing, and building are distinct modules\n2. **Format Flexibility**: Multiple output formats (YAML for editing, JSON for runtime)\n3. **Human-Friendly**: YAML files are editable and version-control friendly\n4. **Bidirectional Sync**: Changes can flow from UI to docs or docs to UI\n5. **Incremental Updates**: Process only changed files for large projects\n\n### 7.2. Technical Decisions\n\n- **lxml over xml.etree**: Better XPath support and namespace handling\n- **dict**: Ensures consistent YAML output for version control\n- **Click over argparse**: More sophisticated CLI with nested commands\n- **YAML intermediate format**: Human-readable, editable, diff-friendly\n- **uv script headers**: Modern Python dependency management\n\n## 8. File Format Examples\n\n### 8.1. Input: Qt .ui File\n\n```xml\n<ui version=\"4.0\">\n <widget class=\"QMainWindow\" name=\"MainWindow\">\n <widget class=\"QPushButton\" name=\"saveButton\">\n <property name=\"toolTip\">\n <string>Save the current document</string>\n </property>\n </widget>\n </widget>\n</ui>\n```\n\n### 8.2. Output: YAML Documentation\n\n```yaml\nsaveButton:\n h.nam: 'Save Button'\n h.tip: 'Save the current document to disk'\n h.cls: 'QPushButton'\n```\n\n### 8.3. Output: JSON Help System\n\n```json\n{\n \"saveButton\": {\n \"name\": \"Save Button\",\n \"tip\": \"Save the current document to disk\",\n \"class\": \"QPushButton\"\n }\n}\n```\n\n--- \n",
"bugtrack_url": null,
"license": null,
"summary": "Tools for working with Qt .ui files",
"version": "2.0.3",
"project_urls": {
"Homepage": "https://twardoch.github.io/qtuidoctools/",
"Issues": "https://github.com/twardoch/qtuidoctools/issues",
"Source": "https://github.com/twardoch/qtuidoctools"
},
"split_keywords": [
"cli",
" documentation",
" json",
" qt",
" ui",
" yaml"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9aa2fb053dffea4da1ce54f35d5762931d5a516d6a559264a5c9ab40562615ce",
"md5": "05dd25a62477a322878c117871152a91",
"sha256": "e34db11726696bd76a83cab486d98423419df9f42ad080c0ef4b3e84ed778dd5"
},
"downloads": -1,
"filename": "qtuidoctools-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "05dd25a62477a322878c117871152a91",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 33321,
"upload_time": "2025-09-03T14:29:06",
"upload_time_iso_8601": "2025-09-03T14:29:06.486526Z",
"url": "https://files.pythonhosted.org/packages/9a/a2/fb053dffea4da1ce54f35d5762931d5a516d6a559264a5c9ab40562615ce/qtuidoctools-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6d4548d6b0085ef6e6f1723fb7bace432742bdfcae44f047a0a2fcef1a578016",
"md5": "973af93f795a26135cccd8e653d0a190",
"sha256": "25416f0290d77f96fa25e02296a3f6d84001f6608e1f8b5f0e9cee4694d84dbe"
},
"downloads": -1,
"filename": "qtuidoctools-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "973af93f795a26135cccd8e653d0a190",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 112959,
"upload_time": "2025-09-03T14:29:07",
"upload_time_iso_8601": "2025-09-03T14:29:07.712321Z",
"url": "https://files.pythonhosted.org/packages/6d/45/48d6b0085ef6e6f1723fb7bace432742bdfcae44f047a0a2fcef1a578016/qtuidoctools-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-03 14:29:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twardoch",
"github_project": "qtuidoctools",
"github_not_found": true,
"lcname": "qtuidoctools"
}
