Comprehensive specification for markdown formatting (part 1)

[kalbfled]

User Story - Business Need

• Ticket is understood, and QA has been contacted (if the ticket has a QA label).

User Story(ies)

As a Notify front- or back-end developer,
I want a comprehensive repository of templates (expressed as markdown) and the html and plain text message body that should result from the templates
So that we avoid regressions when updating Mistune, implementing new features, etc.

Additional Info and Resources

The motivation for this ticket comes from #169 and #181. We need a source of truth for the conversion of markdown templates to html or plain text. This should reflect exactly what is and is not supported in placeholder substitution, the levels of nested lists, etc.

An acceptable solution for this ticket is the creation and population of this directory structure:
- notification_utils/ (repo top level)
|-- tests/test_files/
|---- markdown/
|---- html/
|---- plain_text/

• The contents of markdown/ should be text files where each file contains markdown to be tested.
• The contents of html/ should be text files with the same names (minus extension) as the files in markdown/. The files should contain the html body that should be created from the associated markdown. This should include all expected CSS styling.
• The contents of plain_text/ are analogous to html/, but the files should contain the plain text body.

For example:
notification_utils/tests/test_files/markdown/test1.md

Hello, ((name)).

notification_utils/tests/test_files/markdown/test1.html

<p>Hello, ((name)).</p>

Note that the above is not complete. HTML e-mails also include a header with a VA image for branding.
notification_utils/tests/test_files/markdown/test1.txt

Hello, ((name)).\n

An associated unit test will loop through the files in the markdown/ folder, run each file's contents through the appropriate conversion code, and compare the output to the expected output in the html/ and plain_text/ folders. This will happen without substitution, which will be addressed in a subsequent ticket.

In the existing code, content and personalizations are turned into a message body (html or plain text) by calling the str function on one of the various template classes in template.py. This is overly complicated, restrictive, brittle, and likely to be refactored significantly. Work for this ticket should not assume anything about the final implementation.

Engineering Checklist

• Prescribed directory structure created
• Create test files for all the basic Github markdown elements supported by Notify.
  • headers
  • emphasis (bold, strong, italics, etc.)
  • ordered lists
  • unordered lists
  • links (not "action links")
  • block quotes
  • horizontal rule (a.k.a. thematic break)
• Create test files for "action links," which are Notify specific.
• Create any additional test cases you think are necessary.

Acceptance Criteria

• This work is added to the sprint review slide deck (key win bullet point and demo slide)
• All test files described above exist in the folders markdown/, html/, and plain_text/

QA Considerations

Out of Scope

• Do not write any unit tests yet.

[cris-oddball]

@kalbfled please add something to the QA Considerations section as to the expected ask from QA here.