How should we return reasoning for our own documentation?

[baltpeter]

For reasonings that point to our own research documentation, we currently return the (relative) path to the Markdown file in process(). Here's how that looks in cli as an example:

I'm unsure whether that's the correct way to go. We could also replace the path with the URL to the hosted documentation on trackers.tweasel.org.

Even if we decide against doing that, I think we should at least:

• Update the docstring to explain what the Markdown paths means and how to get to the Markdown file as well as how to construct the URL to the hosted documentation. (The docstring really needs to be updated either way—first-party documentation is not "a more in-depth research report.)

  TrackHAR/src/index.ts

  Lines 171 to 181 in b219141

  	/**
  	* An explanation of how we concluded that this is information is actually the type of data we labelled it as. This
  	* can either be a standardized description, or a URL to a more in-depth research report.
  	*/
  	reasoning:
  	| 'obvious property name'
  	| 'obvious observed values'
  	| 'observed values match known device parameters'
  	| `https://${string}`
  	| `http://${string}`
  	| `${string}.md`;

• Replace the path with the URL in cli.

[baltpeter]

One potential reason I can think of for not replacing the path with a URL: One might want to get the research documentation as of the version of TrackHAR they are using and not the (potentially) updated one on our site.

However, then I realized that we don't actually ship the documentation as part of the bundle, which seems like an oversight to me. (Though it does raise additional questions, like should we maybe export it as a JS object or something since you can't exactly easily access Markdown files bundled in a JS package…).

[zner0L]

We decided to:

• Add the research docs to the bundle. To do that we compile them into a format that is easily accessible from javascript (e.g. JSON)
• In the adapters, the id for the reasoning file is kept as the path of the markdown file in the research-docs folder.
• We provide a utility function to access the bundled text as well as generate a (in the future hopefully versioned, cf. Versioning tracker-wiki#23) URL to the hosted docs on https://trackers.tweasel.org