Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
3. Usage
4. Additional Details
5. Roadmap

About The Project

This project was created based on requirements to simply output reports based on Microsoft Excel (.xlsx) data onto reports created in Microsoft Word (.docx) format.

(back to top)

Built With

As this project should be scalable and easy to interface with, it was important to use software that is used in everyday workflows. Because of this, we are using a Python-based solution due to its flexibility and availability.

• Python
• Microsoft Word
• Microsoft Excel

(back to top)

Getting Started

Prerequisites

• Python
  • Install the latest version of Python available here
• Microsoft Office
  • Microsoft Word
  • Microsoft Excel

Usage

1. Configure "config.xlsx," which is located at the root of the project. This Excel file identifies the following information for each report that should be generated:

   • Source Data location (Full path to Excel Input file)
   • Input Template location (Full path to Word Template file to be referenced)
   • Template Config location (Full path to Excel Template Config file)
   • Output File location (Full path to desired Word document output location)
   • Active flag (Mark TRUE to execute, FALSE to skip)

2. Creating templates

   • Create a .docx file with the desired template format:
     • Add singular text field replacements using a double-curly brace format.
       • Ex.) {{ variable_ a }}
     • Add tables as desired, using the following criteria:
       • Identify table start
         • Ex.) {%tr for row in example_data %}
       • Identify table columns
         • Ex.) {{ row['column_a'] }}
       • Identify table end
         • Ex.) {%tr endfor %}
     • Add charts as desired

3. Configuring templates

   • Create a .xlsx file to map template fields to your source data:

     • Update the 'Config' tab to manage how the program processes your Template file:

       • Name (The name of the template configuration variable)
         • Ex.) update_text
       • Value (A true/false configuration for the variable)
         • Ex.) TRUE or FALSE

     • Update the 'Text' tab to identify text field replacements based on the following information:

       • Template Field Name (The name of the variable in the template)
         • Ex.) variable_a
       • Source Tab (The tab of the Source Data file to reference)
         • Ex.) General
       • Source Row (The row of the tab in the Source Data file to reference)
         • Ex.) Variable A
       • Format (The format the data should be outputted in)
         • Ex.) Currency
       • Precision (The number of figures after the decimal place in numeric formats, defaults to 2)
         • Ex.) 2

     • Update the 'Table' tab to identify table replacements based on the following information:

       • Template Table Name (The name of the table in the template)
         • Ex.) example_data
       • Template Column Name (The name of the column in the template)
         • Ex.) column_a
       • Source Tab (The tab of the Source Data file to reference)
         • Ex.) Example Data
       • Source Column (The name of the column within the tab to reference)
         • Ex.) Column A
       • Format (The format the data should be outputted in)
         • Ex.) Currency
       • Precision (The number of figures after the decimal place in numeric formats, defaults to 2)
         • Ex.) 2

     • Update the 'Chart' tab to identify chart replacements based on the following information:

       • Template Chart Alt Name (The Alt Text of the chart in the template)
         • Ex.) Ownership Pie Chart
       • Source Tab (The tab of the Source Data file to replace the chart data with)
         • Ex.) Chart Data

     • Update the 'Color' tab to identify color replacements based on the following information:

       • Color Name (The name of the color in the template's selected theme)
         • Ex.) accent1
       • Value (The hexadecimal value of the color)
         • Ex.) 0F9ED5

     • Update the 'Image' tab to identify image replacements based on the following information:

       • Template Image Alt Name (The Alt Text of the image in your template)
         • Ex.) Company Logo White
       • Value (Full path to Excel Template Config file)
         • Ex.) C:\User\Documents\company-logo.png

4. Run the Generator

   • Execute run.bat by double clicking on it. Ensure that run.bat is pointing to a valid installation of Python.

(back to top)

Additional Details

1. Template configuration

The below list indicates which configuration options are available for Docx Report Generator templates.

Name	Description	Value
update_text	Determines if Text replacements in the "Text" tab of your Template Configuration should be processed.	Boolean (True/False)
update_table	Determines if Table replacements in the "Table" tab of your Template Configuration should be processed.	Boolean (True/False)
update_chart	Determines if Chart replacements in the "Chart" tab of your Template Configuration should be processed.	Boolean (True/False)
update_colors	Determines if Color replacements in the "Colors" tab of your Template Configuration should be processed.	Boolean (True/False)
update_images	Determines if Image replacements in the "Images" tab of your Template Configuration should be processed.	Boolean (True/False)
output_pdf	Determines if the Word document should be converted to a PDF after processing. Currently only available on Windows.	Boolean (True/False)

2. Data type formatting

To allow data types to work, ensure information in Excel is properly stored as text, date, or numeric format based on the desired output formats.

Format	Example Output	Precision Available
Text	Any text!	[ ]
Short Date	2025-03-31	[ ]
Medium Date	Mar 31st, 2025	[ ]
Long Date	March 31st, 2025	[ ]
Decimal	251, 250.67	[X]
Currency	$15.67, ($62.38)	[X]
Percent	1%, 2.14%	[X]

3. Chart formatting

To use the automatic chart updating functionality, give your charts a unique "Alt Text" value that's easily identifiable through the configuration document.

4. Color formatting

To use custom color formatting, ensure charts, shapes, text, and all other elements of templates are built by selecting prebuilt or custom color themes.

Color Name	Word Equivalent	Notes
dk1	Text/Background - Dark 1	Setting to automatic will prevent this from functioning properly.
lt2	Text/Background - Light 1	Setting to automatic will prevent this from functioning properly.
dk2	Text/Background - Dark 2
lt2	Text/Background - Light 2
accent1	Accent 1
accent2	Accent 2
accent3	Accent 3
accent4	Accent 4
accent5	Accent 5
accent6	Accent 6
hlink	Hyperlink
folHlink	Followed Hyperlink

5. Image formatting

To use the image replacement functionality, give your images an "Alt Text" value that's easily identifiable through the configuration document.

(back to top)

Roadmap

• Initial Release
• Add data types definitions to Text and Tables
• Add Additional Templates w/ Examples
• Add automatic Chart updating
• Add automatic PDF conversion availability

See the open issues for a full list of proposed features (and known issues).

(back to top)