chore: Automate content generation of some Priority docs

docs/Reference/Task Formats/Dataview Format.md

@@ -104,14 +104,16 @@ For more information, see [[Dates]].
 > [!Info]
 > These names were chosen for use in Tasks, and are not known to dataview. They can of course be searched in dataview.
 
-```markdown
-- [ ] #task Lowest priority [priority:: lowest]
-- [ ] #task Low priority [priority:: low]
+<!-- snippet: DocsSamplesForTaskFormats.test.Serializer_Priorities_dataview-snippet.approved.md -->
+```md
+- [ ] #task Lowest priority  [priority:: lowest]
+- [ ] #task Low priority  [priority:: low]
 - [ ] #task Normal priority
-- [ ] #task Medium priority [priority:: medium]
-- [ ] #task High priority [priority:: high]
-- [ ] #task Highest priority [priority:: highest]
+- [ ] #task Medium priority  [priority:: medium]
+- [ ] #task High priority  [priority:: high]
+- [ ] #task Highest priority  [priority:: highest]
 ```
+<!-- endSnippet -->
 
 For more information, see [[Priority]].
 

docs/Reference/Task Formats/Tasks Emoji Format.md

@@ -22,14 +22,16 @@ For more information, see [[Dates]].
 
 ## Tasks Emoji Format for Priorities
 
-```markdown
-- [ ] #task Lowest priority ⏬️
+<!-- snippet: DocsSamplesForTaskFormats.test.Serializer_Priorities_tasksPluginEmoji-snippet.approved.md -->
+```md
+- [ ] #task Lowest priority ⏬
 - [ ] #task Low priority 🔽
 - [ ] #task Normal priority
 - [ ] #task Medium priority 🔼
 - [ ] #task High priority ⏫
 - [ ] #task Highest priority 🔺
 ```
+<!-- endSnippet -->
 
 For more information, see [[Priority]].
 

resources/sample_vaults/Tasks-Demo/Formats/Dataview Format.md

@@ -12,13 +12,17 @@ The fields shown below can be surrounded by either `[]` or `()`.
 
 ## Dataview Format for Priorities
 
+<!-- placeholder to force blank line before included text --> <!-- include: DocsSamplesForTaskFormats.test.Serializer_Priorities_dataview-include.approved.md -->
+
 - [ ] #task Lowest priority  [priority:: lowest]
 - [ ] #task Low priority  [priority:: low]
 - [ ] #task Normal priority
 - [ ] #task Medium priority  [priority:: medium]
 - [ ] #task High priority  [priority:: high]
 - [ ] #task Highest priority  [priority:: highest]
 
+<!-- placeholder to force blank line after included text --> <!-- endInclude -->
+
 ## Dataview Format for Recurrence
 
 - [ ] #task Is a recurring task  [repeat:: every day when done]

resources/sample_vaults/Tasks-Demo/Formats/Tasks Format.md

@@ -10,13 +10,17 @@
 
 ## Tasks Format for Priorities
 
+<!-- placeholder to force blank line before included text --> <!-- include: DocsSamplesForTaskFormats.test.Serializer_Priorities_tasksPluginEmoji-include.approved.md -->
+
 - [ ] #task Lowest priority ⏬
 - [ ] #task Low priority 🔽
 - [ ] #task Normal priority
 - [ ] #task Medium priority 🔼
 - [ ] #task High priority ⏫
 - [ ] #task Highest priority 🔺
 
+<!-- placeholder to force blank line after included text --> <!-- endInclude -->
+
 ## Tasks Format for Recurrence
 
 - [ ] #task Is a recurring task 🔁 every day when done

src/Query/Filter/PriorityField.ts

@@ -94,28 +94,47 @@ export class PriorityField extends Field {
 
     public grouper(): GrouperFunction {
         return (task: Task) => {
-            let priorityName = 'ERROR';
-            switch (task.priority) {
-                case Priority.High:
-                    priorityName = 'High';
-                    break;
-                case Priority.Highest:
-                    priorityName = 'Highest';
-                    break;
-                case Priority.Medium:
-                    priorityName = 'Medium';
-                    break;
-                case Priority.None:
-                    priorityName = 'None';
-                    break;
-                case Priority.Low:
-                    priorityName = 'Low';
-                    break;
-                case Priority.Lowest:
-                    priorityName = 'Lowest';
-                    break;
-            }
+            const priorityName = PriorityField.priorityNameUsingNone(task.priority);
             return [`Priority ${task.priority}: ${priorityName}`];
         };
     }
+
+    /**
+     * Get the name of a {@link Priority} value, returning 'None' for {@link Priority.None}
+     * @param priority
+     * @see priorityNameUsingNormal
+     */
+    public static priorityNameUsingNone(priority: Priority) {
+        let priorityName = 'ERROR';
+        switch (priority) {
+            case Priority.High:
+                priorityName = 'High';
+                break;
+            case Priority.Highest:
+                priorityName = 'Highest';
+                break;
+            case Priority.Medium:
+                priorityName = 'Medium';
+                break;
+            case Priority.None:
+                priorityName = 'None';
+                break;
+            case Priority.Low:
+                priorityName = 'Low';
+                break;
+            case Priority.Lowest:
+                priorityName = 'Lowest';
+                break;
+        }
+        return priorityName;
+    }
+
+    /**
+     * Get the name of a {@link Priority} value, returning 'Normal' for {@link Priority.None}
+     * @param priority
+     * @see priorityNameUsingNone
+     */
+    public static priorityNameUsingNormal(priority: Priority) {
+        return PriorityField.priorityNameUsingNone(priority).replace('None', 'Normal');
+    }
 }

src/Task.ts

@@ -15,6 +15,10 @@ import { compareByDate } from './lib/DateTools';
  * When sorting, make sure low always comes after none. This way any tasks with low will be below any exiting
  * tasks that have no priority which would be the default.
  *
+ * Values can be converted to strings with:
+ * - {@link priorityNameUsingNone} in {@link PriorityField}
+ * - {@link priorityNameUsingNormal} in {@link PriorityField}
+ *
  * @export
  * @enum {number}
  */

tests/Query/Filter/PriorityField.test.ts

@@ -16,6 +16,19 @@ function testTaskFilterForTaskWithPriority(filter: string, priority: Priority, e
     testFilter(filterOrError, builder.priority(priority), expected);
 }
 
+describe('priority naming', () => {
+    it.each(Object.values(Priority))('should name priority value: "%i"', (priority) => {
+        const name = PriorityField.priorityNameUsingNone(priority);
+        expect(name).not.toEqual('ERROR'); // if this fails, code needs to be updated for a new priority
+    });
+
+    it('should name default priority correctly', () => {
+        const none = Priority.None;
+        expect(PriorityField.priorityNameUsingNone(none)).toEqual('None');
+        expect(PriorityField.priorityNameUsingNormal(none)).toEqual('Normal');
+    });
+});
+
 describe('priority is', () => {
     it('priority is highest', () => {
         const filter = 'priority is highest';
@@ -229,11 +242,16 @@ describe('grouping by priority', () => {
     });
 });
 
-function withAllPriorities(): Task[] {
+export function withAllPriorities(): Task[] {
     const tasks: Task[] = [];
     const allPriorities = Object.values(Priority);
     allPriorities.forEach((priority) => {
-        const task = new TaskBuilder().priority(priority).build();
+        // This description is chosen to be useful for including tasks in user docs, so
+        // changing it will change documentation and sample vault content.
+        const priorityName = PriorityField.priorityNameUsingNormal(priority);
+        const description = `#task ${priorityName} priority`;
+
+        const task = new TaskBuilder().priority(priority).description(description).build();
         tasks.push(task);
     });
     return tasks;

tests/TaskSerializer/DocsSamplesForTaskFormats.test.Serializer_Priorities_dataview-include.approved.md

@@ -0,0 +1,10 @@
+<!-- placeholder to force blank line before included text -->
+
+- [ ] #task Lowest priority  [priority:: lowest]
+- [ ] #task Low priority  [priority:: low]
+- [ ] #task Normal priority
+- [ ] #task Medium priority  [priority:: medium]
+- [ ] #task High priority  [priority:: high]
+- [ ] #task Highest priority  [priority:: highest]
+
+<!-- placeholder to force blank line after included text -->

tests/TaskSerializer/DocsSamplesForTaskFormats.test.Serializer_Priorities_dataview-snippet.approved.md

@@ -0,0 +1,6 @@
+- [ ] #task Lowest priority  [priority:: lowest]
+- [ ] #task Low priority  [priority:: low]
+- [ ] #task Normal priority
+- [ ] #task Medium priority  [priority:: medium]
+- [ ] #task High priority  [priority:: high]
+- [ ] #task Highest priority  [priority:: highest]

tests/TaskSerializer/DocsSamplesForTaskFormats.test.Serializer_Priorities_tasksPluginEmoji-include.approved.md

@@ -0,0 +1,10 @@
+<!-- placeholder to force blank line before included text -->
+
+- [ ] #task Lowest priority ⏬
+- [ ] #task Low priority 🔽
+- [ ] #task Normal priority
+- [ ] #task Medium priority 🔼
+- [ ] #task High priority ⏫
+- [ ] #task Highest priority 🔺
+
+<!-- placeholder to force blank line after included text -->

tests/TaskSerializer/DocsSamplesForTaskFormats.test.Serializer_Priorities_tasksPluginEmoji-snippet.approved.md

@@ -0,0 +1,6 @@
+- [ ] #task Lowest priority ⏬
+- [ ] #task Low priority 🔽
+- [ ] #task Normal priority
+- [ ] #task Medium priority 🔼
+- [ ] #task High priority ⏫
+- [ ] #task Highest priority 🔺

tests/TaskSerializer/DocsSamplesForTaskFormats.test.ts

@@ -0,0 +1,22 @@
+import { TASK_FORMATS, updateSettings } from '../../src/Config/Settings';
+import { verifyMarkdown, verifyMarkdownForDocs } from '../TestingTools/VerifyMarkdownTable';
+import { withAllPriorities } from '../Query/Filter/PriorityField.test';
+
+describe('Serializer', () => {
+    describe('Priorities', () => {
+        function allPriorityLines() {
+            const tasks = withAllPriorities().reverse();
+            return tasks.map((t) => t.toFileLineString()).join('\n');
+        }
+
+        it.each(Object.keys(TASK_FORMATS))('%s-snippet', (key: string) => {
+            updateSettings({ taskFormat: key as keyof TASK_FORMATS });
+            verifyMarkdown(allPriorityLines());
+        });
+
+        it.each(Object.keys(TASK_FORMATS))('%s-include', (key: string) => {
+            updateSettings({ taskFormat: key as keyof TASK_FORMATS });
+            verifyMarkdownForDocs(allPriorityLines());
+        });
+    });
+});

tests/TestingTools/VerifyMarkdownTable.ts

@@ -1,12 +1,36 @@
-import { Options } from 'approvals/lib/Core/Options';
+import { type ConfigModifier, Options } from 'approvals/lib/Core/Options';
 import { verify } from 'approvals/lib/Providers/Jest/JestApprovals';
 
-function verifyMarkdown(output: string) {
+// This import fails with Approvals.NodeJS 6.2.1:
+// error TS1371: This import is never used as a value and must use 'import type' because 'importsNotUsedAsValues' is set to 'error'.
+// import { JestReporter } from 'approvals/lib/Providers/Jest/JestReporter';
+
+export function verifyMarkdown(output: string) {
     let options = new Options();
     options = options.forFile().withFileExtention('md');
-    verify(output, options);
+
+    const configModifier: ConfigModifier = (c) => {
+        c.reporters = [
+            // Built-in reporters listed at:
+            // https://github.com/approvals/Approvals.NodeJS#built-in-reporters
+            'vscode', // VS Code diff works well with files containing emojis
+            //-----------------
+            // Last one is jest reporter, that should write diffs to console in
+            // Continuous Integration builds, such as GitHub Actions
+            // new JestReporter(), // disabled due to import error - see above
+        ];
+        return c;
+    };
+
+    verify(output, options.withConfig(configModifier));
 }
 
+/**
+ * Write out markdown block for including directly in documentation.
+ * To embed the approved file directly in user docs, write line like this, and then run mdsnippets:
+ *      include: output-file-name.approved.md
+ * @param markdown
+ */
 export function verifyMarkdownForDocs(markdown: string) {
     let output = '<!-- placeholder to force blank line before included text -->\n\n';
     output += markdown;