chore: Automate content generation of some Priority docs

[claremacrae]

Description

Summary

Use approval test files as snippets for docs and sample markdown files.

Background:

• https://publish.obsidian.md/tasks-contributing/Testing/Approval+Tests
• https://publish.obsidian.md/tasks-contributing/Documentation/Embedding+code+and+data+in+documentation

Detail

User visible changes:

• The file format samples for Priority emojis are now machine-generated in:
  • user docs
  • Tasks-Demo vault
• A side-effect is that some minor white-space errors were fixed

Code changes:

• Added helper functions in PriorityField to convert Priority enum values to string

Tests

• New file tests/TaskSerializer/DocsSamplesForTaskFormats.test.ts generates *.approved.md files showing how Priority values are represented in Emoji and dataview file formats.
  • These files are designed to be embedded in to documentation and markdown files
  • When new formats are added, new sample files will be created automatically
  • When priorities are renamed, or more priorities are added, when the tests are run, the approved files will be updated, and mdsnippets can be run automatically for via the GitHub Action to update the docs and sample vault automatically
• withAllPriorities() is exported, and now includes a useful description for each task, so the tasks are suitable for inclusion in documentation
• Verify functions in tests/TestingTools/VerifyMarkdownTable.ts now use Visual Studio Code's diff tool for showing and approving differences in approval test files
  • This was the only diff tool I could find, in the ones I have available, that handles Emojis correctly, not corrupting them when editing lines containing Emojis.
  • WARNING: this may need more thought if there are any contributors who don't have VSCode installed, and are reviewing Approval Test diffs

Notes

• There are other locations in the docs that list the available priorities, such as the list of group names when grouping by priority. These may may be updated in separate steps.

Motivation and Context

• Start of work towards reducing many repetitious edits in the user docs and sample vault

How has this been tested?

• With new tests
• Viewing the changed markdown files in Obsidian, in Source and Reading modes

Screenshots (if appropriate)

Types of changes

Changes visible to users:

• Documentation (prefix: docs - improvements to any documentation content for users)
• Sample vault (prefix: vault - improvements to the Tasks-Demo sample vault)

Internal changes:

• Refactor (prefix: refactor - non-breaking change which only improves the design or structure of existing code, and making no changes to its external behaviour)
• Tests (prefix: test - additions and improvements to unit tests and the smoke tests)

Checklist

• My code follows the code style of this project and passes yarn run lint.
• My change requires a change to the documentation.
• I have updated the documentation accordingly.
• My change has adequate Unit Test coverage.

Terms

• My contribution follow this project's contributing guide
• I agree to follow this project's Code of Conduct

[claremacrae]

@ilandikov You might be interested in this as:

• it's the start of what I was describing when we last paired
• it changes the behaviour of withAllPriorities(), which might conflict with what you are working on
• if you had time to look at it, I would welcome any feedback you had

[ilandikov]

Looks good =)

So the idea here is to use approvals as snippets for docs? Did I get it right?

[claremacrae]

So the idea here is to use approvals as snippets for docs? Did I get it right?

Yes, nice summary. Also for including in markdown files in the Test Vault.