{"id":27624226,"url":"https://github.com/karar-hayder/docxwriter-json","last_synced_at":"2026-04-29T17:02:41.271Z","repository":{"id":289118875,"uuid":"970182288","full_name":"karar-hayder/DocxWriter-JSON","owner":"karar-hayder","description":"DocxWriter is a Python library for generating professional Word documents from JSON. Automate reports, add tables, lists, images, and apply custom styles — all from clean, structured data.","archived":false,"fork":false,"pushed_at":"2025-04-21T16:05:46.000Z","size":22,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-04-21T17:23:04.910Z","etag":null,"topics":["automation","document-automation","documentation","docx","json","json-to-docx","python","python-docx","reporting","text-processing","tool","word-document"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/karar-hayder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-21T15:59:05.000Z","updated_at":"2025-04-21T16:05:49.000Z","dependencies_parsed_at":"2025-04-21T17:33:17.402Z","dependency_job_id":null,"html_url":"https://github.com/karar-hayder/DocxWriter-JSON","commit_stats":null,"previous_names":["karar-hayder/docxwriter-json"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karar-hayder%2FDocxWriter-JSON","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karar-hayder%2FDocxWriter-JSON/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karar-hayder%2FDocxWriter-JSON/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/karar-hayder%2FDocxWriter-JSON/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/karar-hayder","download_url":"https://codeload.github.com/karar-hayder/DocxWriter-JSON/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250422915,"owners_count":21428038,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","document-automation","documentation","docx","json","json-to-docx","python","python-docx","reporting","text-processing","tool","word-document"],"created_at":"2025-04-23T11:23:41.623Z","updated_at":"2026-04-29T17:02:41.215Z","avatar_url":"https://github.com/karar-hayder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DocxWriter\n\nA powerful Python library for creating professionally formatted Word documents from JSON data. This tool allows you to generate complex documents with various elements like headings, paragraphs, tables, lists, images, and more.\n\n## Features\n\n- Create professionally formatted Word documents\n- Support for multiple document elements\n- Consistent styling and formatting\n- Customizable styles and themes\n- Hidden watermark support\n- Error handling and logging\n- Type hints for better code maintainability\n\n## Installation\n\n1. Clone the repository:\n\n    ```bash\n    git clone https://github.com/karar-hayder/DocxWriter-JSON.git\n    cd DocxWriter\n    ```\n\n2. Create and activate a virtual environment:\n\n    ```bash\n    python -m venv .venv\n    source .venv/bin/activate  # On Windows: .venv\\Scripts\\activate\n    ```\n\n3. Install dependencies:\n\n    ```bash\n    pip install -r requirements.txt\n    ```\n\n## Project Structure\n\nDocxWriter has been restructured into a modular package for better maintainability and extensibility:\n\n```txt\nDocxWriter/\n├── docxwriter/              # Main package directory\n│   ├── __init__.py          # Package initialization\n│   ├── __main__.py          # Entry point for command-line usage\n│   ├── compat.py            # Compatibility layer for backward compatibility\n│   ├── document_creator.py  # Main document creation class\n│   ├── components/          # Document components\n│   │   ├── __init__.py\n│   │   └── styles.py        # Document styles\n│   └── utils/               # Utility modules\n│       ├── __init__.py\n│       ├── logger.py        # Logging utilities\n│       └── paths.py         # Path utilities\n├── writer.py                # Backward compatibility wrapper\n├── styles.py                # Backward compatibility wrapper\n├── tests.py                 # Test suite\n├── setup.py                 # Package setup script\n├── requirements.txt         # Dependencies\n├── examples/                # Example data files\n├── README.md                # This file\n└── CONTRIBUTING.md          # Contribution guidelines\n```\n\n## Usage Options\n\nDocxWriter can be used in several ways:\n\n1. **Direct script execution (backward compatible):**\n\n   ```python\n   python writer.py\n   ```\n\n2. **As a module:**\n\n   ```python\n   python -m docxwriter -i data.json -o output\n   ```\n\n3. **As a library in your code:**\n\n   ```python\n   from docxwriter.document_creator import DocumentCreator\n   \n   # Create a document creator\n   creator = DocumentCreator(output_dir=\"output\")\n   \n   # Create a document from JSON file\n   creator.create_document_from_json(\"data.json\")\n   ```\n\n## Command Line Options\n\nWhen used as a module, DocxWriter supports several command line options:\n\n```txt\nusage: python -m docxwriter [-h] [-i INPUT] [-o OUTPUT_DIR] [-w WATERMARK] [--no-watermark]\n\nCreate Word documents from JSON data.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -i INPUT, --input INPUT\n                        Input JSON file (default: data.json)\n  -o OUTPUT_DIR, --output-dir OUTPUT_DIR\n                        Output directory (default: data)\n  -w WATERMARK, --watermark WATERMARK\n                        Custom watermark text (default: predefined text)\n  --no-watermark        Disable watermark\n```\n\n## Usage\n\n### Basic Structure\n\nCreate a `data.json` file with your document content. The basic structure is:\n\n```json\n{\n    \"title\": \"Document Title\",\n    \"file_name\": \"output.docx\",\n    \"content\": {\n        \"Section 1\": \"Regular paragraph text\",\n        \"Section 2\": {\n            \"table\": [\n                [\"Header 1\", \"Header 2\"],\n                [\"Data 1\", \"Data 2\"]\n            ]\n        }\n    }\n}\n```\n\n### Document Elements\n\n#### 1. Title\n\nThe document title is specified in the root of the JSON:\n\n```json\n{\n    \"title\": \"Your Document Title\",\n    \"file_name\": \"output.docx\",\n    \"content\": { ... }\n}\n```\n\n#### 2. Sections\n\nRegular sections with headings and text:\n\n```json\n{\n    \"Section Name\": \"Section content text. This can be multiple paragraphs separated by double newlines.\"\n}\n```\n\n#### 3. Tables\n\nCreate tables with headers and data:\n\n```json\n{\n    \"Table Section\": {\n        \"table\": [\n            [\"Header 1\", \"Header 2\", \"Header 3\"],\n            [\"Row 1 Col 1\", \"Row 1 Col 2\", \"Row 1 Col 3\"],\n            [\"Row 2 Col 1\", \"Row 2 Col 2\", \"Row 2 Col 3\"]\n        ],\n        \"style\": \"Table Grid\",\n        \"header_rows\": 1\n    }\n}\n```\n\n#### 4. Lists\n\nCreate bulleted or numbered lists:\n\n```json\n{\n    \"List Section\": {\n        \"list\": [\n            \"First item\",\n            \"Second item\",\n            \"Third item\"\n        ],\n        \"list_type\": \"bullet\",  // or \"number\"\n        \"level\": 0  // 0 for top level, 1 for nested, etc.\n    }\n}\n```\n\n#### 5. Images\n\nAdd images to your document:\n\n```json\n{\n    \"Image Section\": {\n        \"image\": \"path/to/your/image.jpg\",\n        \"width\": 6.0,  // in inches\n        \"height\": 4.0  // in inches\n    }\n}\n```\n\n#### 6. Page Breaks\n\nAdd page breaks:\n\n```json\n{\n    \"Page Break Section\": {\n        \"page_break\": true\n    }\n}\n```\n\n#### 7. Styled Text\n\nUse different styles for text:\n\n```json\n{\n    \"Warning Section\": {\n        \"style\": \"Warning\",\n        \"text\": \"This is a warning message\"\n    },\n    \"Error Section\": {\n        \"style\": \"Error\",\n        \"text\": \"This is an error message\"\n    },\n    \"Success Section\": {\n        \"style\": \"Success\",\n        \"text\": \"This is a success message\"\n    },\n    \"Code Section\": {\n        \"style\": \"Code\",\n        \"text\": \"This is code text\"\n    }\n}\n```\n\n### Available Styles\n\n1. Text Styles:\n   - Normal\n   - Title\n   - Subtitle\n   - Heading 1-3\n   - Abstract\n   - Quote\n   - Code\n   - Warning\n   - Error\n   - Success\n\n2. List Styles:\n   - List Bullet\n   - List Number\n\n3. Table Styles:\n   - Table Grid\n\n4. Special Styles:\n   - Caption\n   - Footnote\n   - Header\n   - Footer\n   - Hidden (for watermark)\n\n### Example JSON\n\nHere's a complete example showing various elements:\n\n```json\n{\n    \"title\": \"Sample Document\",\n    \"file_name\": \"sample.docx\",\n    \"content\": {\n        \"Introduction\": \"This is the introduction section with regular paragraph text.\",\n        \n        \"Data Table\": {\n            \"table\": [\n                [\"Name\", \"Age\", \"City\"],\n                [\"John\", \"25\", \"New York\"],\n                [\"Jane\", \"30\", \"Los Angeles\"]\n            ],\n            \"style\": \"Table Grid\",\n            \"header_rows\": 1\n        },\n        \n        \"Features\": {\n            \"list\": [\n                \"Feature 1\",\n                \"Feature 2\",\n                \"Feature 3\"\n            ],\n            \"list_type\": \"bullet\"\n        },\n        \n        \"Important Notice\": {\n            \"style\": \"Warning\",\n            \"text\": \"This is an important warning message!\"\n        },\n        \n        \"Code Example\": {\n            \"style\": \"Code\",\n            \"text\": \"def hello_world():\\n    print('Hello, World!')\"\n        },\n        \n        \"New Page\": {\n            \"page_break\": true\n        },\n        \n        \"Image Section\": {\n            \"image\": \"path/to/image.jpg\",\n            \"width\": 6.0,\n            \"height\": 4.0\n        }\n    }\n}\n```\n\n## Running the Script\n\nSimply run the script with Python:\n\n```bash\npython writer.py\n```\n\nThe script will:\n\n1. Read the data.json file\n2. Create a Word document with the specified content\n3. Apply all formatting and styles\n4. Add a watermark\n5. Save the document in the `data` directory\n\n## Output\n\nThe generated document will be saved in the `data` directory with the filename specified in your JSON file. The document will include:\n\n- Professional formatting\n- Consistent styling\n- All specified elements (tables, lists, images, etc.)\n- A hidden watermark\n- Proper spacing and margins\n\n## Error Handling\n\nThe script includes comprehensive error handling for:\n\n- Missing JSON file\n- Invalid JSON format\n- Missing required fields\n- Image loading errors\n- Style application errors\n\nAll errors are logged with timestamps and appropriate error messages.\n\n## Contributing\n\nFeel free to submit issues and enhancement requests!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarar-hayder%2Fdocxwriter-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkarar-hayder%2Fdocxwriter-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkarar-hayder%2Fdocxwriter-json/lists"}