Comparable Modules and Scripts out there

[davidverweij]

Just as an exercise, I searched for comparable .csv to .docx packages on GitHub. I think their approaches might be educational to see how we fair, and if we need to adopt some approaches. Most repositories I found were little, or not at all, documented, or were clearly for personal and one-off use, a few I found interesting:

• csv-fill-docx: a .js approach, which is heavily based on docxtemplater (or docxtpl for Python. This Docxtemplater allows something similar to our dependency on docx-mailmerge, but with custom fields in Word - more readable and editable by end-users. Possibly worth-while checking out for Python (if any exists).
• gendoc does something similar as csv-fill-docx, and uses docxtemplater, but requires a .json file to be edited as input rather than all via the CLI. It thereby allows multiple 'batches' to be executed with different .csv and .docx files, which might increase workflow on a larger scale.
• doc-csv, in Python, looks a tad more complicated, but adds a timestamp to the output folder - allowing multiple to exists, even when done in a batch (although it doesn't include milliseconds).
• csv2docx has the same name, but creates the output .docx from scratch - rather than based on (mailmerge) fields. In particular, the .csv needs to be formatted in a specific way, see also their test case. This did make me think, our repo should clearly communicate the use of mailmerge field. In addition, I presume these mailmerge fields will remain to exists for a while - but it is worth noting this is another dependency - unlike docxtemplater that has their own fields using text, instead of fields (e.g. {%name})
• csv2docx another identical named repo as ours, but using a node.js approach. Again, docxtemplater is used. Documentation on this repo is not there.

This is only the result of a quick search by me on GitHub, but I thought it is good to keep an eye on what is already done and/or can be done. For now, I'd say we are on the right track and should focus on the rigour and easy of use of our script as is, then we can explore how to go next. At the same time, I am all for making sure this software does one thing and does it well.

[jawrainey]

Great market research and excellent points @davidverweij. From what I can see, the above python implementations have not been published as packages on pypi. I had a quick look on pypi, and there are some packages that share similarities, most relevant being burocracy that uses mailmerge from a dict rather than CSV and can also output to powerpoint -- view it on pypi or github. Importantly, no package exists named csv2docx on pypi or readthedocs, which means we can use csv2docx.

As I see it, our solution differs in several ways:

1. It will be packaged on pypi;
2. It is both a CLI and library;
3. It is designed for spreadsheets whereas the others primarily use dict/json to structure and popular the docx template. Focusing on spreadsheets is important as services such as google forms are often used to recruit participants and would simplify creating certificates, i.e. my previous use case;
4. We use current python features/tools/practices that others mostly do not. Useful for other developers to see how packages are developed in 2020 and us as a learning experience.

Point 3 is where our solution has most utility and uniqueness amongst the "competition".

[jawrainey]

I forgot to add that I agree that we could better communicate the use of mailmerge, especially in the description. How about we:

• Expand the short description in the README where we say "...template with mailmerge fields." to include which library we use and what mailmerge fields are, e.g. "... template with mailmerge fields (using docx-mailmerge). Mail Merge is a docx feature for to simplify creating and printing documents from data in spreadsheets." Maybe do not include the mail merge description in the pyproject file since that will appear in pypi.
• Change the title "Demo and preparing your files" to "Configuring Mail Merge Fields in your template"?