Find a way to fix documentation duplication

[eozd]

Feature Description

Our current documentation is split into three pieces:

1. function docs
2. matlabbatch docs
3. user manual

We maintain these three pieces by literally copy-pasting the documentation. Since this is very inefficient and error-prone, a better way to handle this process is required.

[irojkov-ph]

Sam's handover comment:

Documentation wise, due the nature of the matlabbatch structure that is used for the GUI, I can see a possibility for using this to keep a single source of truth for docs. A script would take the cfg, and traverse through each batch value and output some sort of markup depending on if it's type, e.g. branch, entry, const etc. This could be latex or html, or markdown. The major drawback being that this would mean the cfg help texts were gospel and whatever was there should be shown in the docs, which makes extending with mathematical notation or finer details tricky.

[dominikbach]

@teddychao it seems this is solved now?

[dominikbach]

Suggestion for improved documentation management:

Function help texts

Definite reference are the function help texts. This is how Matlab works in general, and it is easy for users to access them. In addition, we could/should build a complete online reference from the help texts, see #642 . This would require the following steps:

1. Improve function help texts (Dominik).
2. Create online reference (similar to https://bachlab.github.io/vrthreat/reference/index.html).

Matlabbatch GUI

GUI can use function help texts whereever possible. pspm_help could serve to parse the help texts and make them accessible to the matlabbatch GUI. Where additional information is needed, this can be managed in (and pulled from) a markdown file. This would require the following steps:

1. Improve pspm_help such that arguments is a struct variable where field names correspond to argument names (this should be flattened, i.e. options.overwrite and datafile would be on the same level).
2. Write a test that simply verifies error-free parsing of all pspm function help texts (to avoid accidentally breaking the structure of a help text, which would otherwise go unnoticed in the test suite).
3. Implement these arguments in GUI (Dominik).
4. Manage additional help texts (Dominik).
5. Create pspm_cfg_selector_... functions for common GUI elements (datafile, overwrite, ...) similar to pspm_cfg_channel_selector.
6. Combine these help texts into a matlabbatch reference document.

PDF manual

Split background information from GUI reference for better management.

[teddychao]

My comments are as following,

1. I really agree with Create online reference (similar to https://bachlab.github.io/vrthreat/reference/index.html). I think PsPM users will tend to use the online document rather than the PDF version if both are available since they can navigate between pages using browser with less clicks. The online version can also be easier to maintain with R markdown.
2. We were looking at a method to upload PsPM code help text to document (either PDF/Lyx files or other format). I am unsure if the method has been identified now. I think this would (1) avoid potential conflicts or confusion between the code help text and PDF/Lyx files; (2) get real-time updates from the backend so users can find the latest information; (3) can get cross-reference so users will find the related information with a simple click. I am happy to look into if a method has not been determined.
3. For Matlab-batch GUI, I agree with the comments. I think putting options.overwrite and datafile in the same level will reduce coding complexity, and the exported struct variables will be sorted well. I do not remember the explicit rules I set for writing those help text and reading to .mat files. I will have a look and see if I can make a list, if this is useful.
4. I think "Create pspm_cfgselector... functions for common GUI elements" is a very sensible task. It can improve code robustness and make the GUI more consistent. I am happy to start when I should focus on it.
5. For the "Split background information", my understanding is it wants to build a new document for the background information? I can do it if my understanding is correct.