feat: Add visual debugging aids for Tasks developers

[claremacrae]

Description

Add two hidden settings to help developers understand what is going on behind the scenes in the plugin's code.

Note that if sorting is disabled manually in the settings, the explain instruction does report this.

From the additions to the CONTRIBUTING file:

---

How do I enable hidden debugging/visualisation facilities?

[!Released]
Introduced in Tasks 1.26.0.

There are some hidden Tasks settings options to turn on some hidden facilities to aid visualising the behaviour of the plugin.

The default values are:

  "debugSettings": {
    "ignoreSortInstructions": false,
    "showTaskHiddenData": false
  }

The data.json file needs to be edited manually to turn these on: The options are not exposed in the settings UI.

This is what these options do:

• ignoreSortInstructions:
  • Turns off all sorting of tasks, that is, it disables both the default sort order and the default sort order.
  • This can be useful if you need a stable order of tasks in order to easily inspect the impact of editing a task line.
• showTaskHiddenData:
  • This adjusts the rendering of Task objects to display some extra information, to make the plugin's behaviour easier to inspect.
  • The values display are:
    • Line 1:
      • task.sectionStart
      • task.sectionIndex
      • task.precedingHeader
      • task.path
    • Line 2:
      • task.originalMarkdown
  • Here is an example of the extra output:
    🐛 4 . 6 . 'Steps to world domination' . 'ACME.md'
    '- [ ] #task Feed the baby 🔽 📅 2021-11-21'

---

Motivation and Context

I have been spending many hours understanding how the task.sectionStart and task.sectionIndex values change under a myriad of different scenarios, and it has been tremendously helpful to see the values displayed directly in Obsidian, rather than having to read through reams of console debug output.

How has this been tested?

In the test vault, in Obsidian.

Screenshots (if appropriate)

The following screenshot gives a wealth of information about the behaviour of the plugin:

• 1: I had believed that the task.sectionStart was the 0-based line number of the previous heading, but this shows that it is the 0-based line number at the start of the list containing the task
• 2: When toggling tasks rendered in Reading mode, we cannot rely on task.precedingHeader as it is not populated
• 3: When toggling embedded tasks in Reading mode, we also cannot rely on the task.sectionStart and task.sectionIndex values, as they are 0

Types of changes

Changes visible to users:

• New feature (prefix: feat - non-breaking change which adds functionality)
  • But only of use to developers

Internal changes:

• Tests (prefix: test - additions and improvements to unit tests and the smoke tests)
• Other Docs added in CONTRIBUTING.md

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