DIG-1359: Documentation, error handling and code improvements for usability

[mshadbolt]

Relates to:

DIG-1343
DIG-1331

Summary of changes:

.gitignore:

• add pycharm and libreoffice annoying files

CSVConvert.py

• import csv and use to read csvs in read_mapping_template() so that quoted CSVs are read accurately
• improve helper text for arguments
• Some minor automatic formatting changes, typo fixes
• Add check_for_sheet_inconsistencies() method to check that sheets identified in the mapping template are consistent with sheets given as input. (quick and dirty but not sure if best or most friendly way)
• Exit the program if fatal errors are found

generate_mapping_docs.py

• generates nicely readable documentation from docstrings in mappings.py and adds to mapping_functions.md
• Could consider incorporating this into github actions

mapping_functions.md

• add index of mapping functions automatically generated by generate_mapping_docs.py
• Add further information about input to mapping functions

mappings.py

• add more descriptive docstrings to all functions

schema.py

• update to read schema with openapi-spec-validator so it throws error if the spec is invalid.

requirements.txt

• add openapi-spec-validator and pdoc3

sample_inputs

• add a functions file to the available sample_inputs

validate_coverage.py

• remove unused args and imports
• add exceptions for file not found or invalid json file

Test and moh templates

• correct a few more indexed_on errors

Some concerns/questions/ideas:

• It probably won't have consequences but it makes me nervous that mappings.float() overrides the inbuilt python method for casting as float
• The method mappings.boolean() defaults to True if it doesn't match the listed options, this seems a little risky
• Would it be worth implementing a more formal logging system so that messages can be split into those useful for a candig developer debugging versus a user trying to use the script?

[daisieh]

Teeny code changes requested in CSVConvert. Otherwise, looks awesome and thank you so much for cleaning up all of our nonsense!

[daisieh]

Looks awesome! Thanks!