Generate Matlab documentation

jcohenadad commented 4 years ago

Context

This PR adds the necessary files to generate a Matlab documentation, within Matlab's browser. The various pros are:

Friendly documentation via Matlab's browser,
Possible to show file dependencies
overview of all files in the project

This PR will be the foundation for establishing docstrings conventions: https://github.com/shimming-toolbox/shimming-toolbox/issues/133

Things to figure out

How to create automatic "publish" for all .m files in the project. This "publish" will generate the html files required by Matlab's documentation.
Create a script that would automatically build the helpdoc.xml file (which includes all entries of the doc). Possibly helpful:
- https://www.mathworks.com/matlabcentral/fileexchange/52932-gentoolboxhelp
Do we want to add the html in our git repository?
- I think the answer is no, because those html are copied under Matlab's installation folder (to be displayed under Matlab's doc environment).
To address the previous point: we need to initiate a doc generation for users installing this repository. For package distribution, this might be done automatically.
Contents.m: not needed (see discussion below).

Tips & tricks

Formatting Matlabs's markup

https://www.mathworks.com/help/matlab/matlab_prog/marking-up-matlab-comments-for-publishing.html

Publish Live scripts as html

The function publish converts .m files to html. However, this does not work for Live script .mlx files. The solution is to use:

matlab.internal.liveeditor.openAndConvert('doc/GettingStarted.mlx', 'Help/shimming-toolbox/GettingStarted.html')

builddocsearchdb: Could not write search database

if running into the following error:

>> builddocsearchdb('/Users/julien/code/shimming-toolbox/doc/html')
Error using builddocsearchdb (line 38)
Could not write search database.

The solution is to remove the path to the info.xml file and add it again. Matlab will then parse it.

builddocsearchdb: There is no installed product with this help location

>> builddocsearchdb('/Users/julien/code/shimming-toolbox/Help')
Error using builddocsearchdb (line 32)
There is no installed product with this help location.
Documentation that is not associated with a product will not be displayed in the help browser.

Solution: the path to the output doc/, included in the info.xml file, should be relative. Any change to the info.xml file should be followed by an rmpath/addpath to refresh the parsing of the info.xml file (or , restart Matlab).

Publish for package files

Example for +imutils/ package, command is:

publish('imutils.dicom_to_nifti', options)

jcohenadad commented 4 years ago

Working prototype on b6f246a2c240cda3a3c53c5faead92256fbe0af4

To build Matlab doc:

FileList = genToolboxHelp('/Users/julien/code/shimming-toolbox', 'shimming-toolbox', {'Ui', 'tests', 'misc', 'Img', 'external', 'example', 'docs', 'doc', 'Coils', 'aux_hardware'}, true, false)

Produces:

jcohenadad commented 4 years ago

Adding a Contents.m file within each folder enables to do this:

>> help imutils

  Files
    dicom_to_nifti      - 
    get_nii_coordinates - 
    load_niftis         - 
    read_nii            - Load NIfTI image and header; and, when present, the accompanying .json sidecar

On the other hand, if the Contents.m file is not present in the folder, then it recognizes it as a package, and the help is much nicer:

>> help imutils
Contents of imutils package:

     dicom_to_nifti - converts dicoms into niftis with dcm2bids output
get_nii_coordinates - Return voxel position "world-coordinates" in mm
        load_niftis - Load a nifti acquisition from dcm2bids
           read_nii - Load NIfTI image, header, and (if present) the accompanying .json sidecar

so, we should not have Contents.m files for packages.

EDIT: this mush be a new Matlab feature, but even without Contents.m file for non-packages, it does list all the files. So let's get rid of this Contents.m file.

jcohenadad commented 4 years ago

Ready to be tested:

Checkout this branch (commit bde1642d53d1faa35fba1efff8885b1b0bb0e288)

Generate the doc:

startup
FileList = genToolboxHelp('/Users/julien/code/shimming-toolbox', 'shimming-toolbox', {'doc', 'docs'}, false, true)

Open the doc:
```
doc
```

The Documentation windows pops-up, go at the bottom and click on "shimming-toolbox Toolbox". You should see this: Screen Shot 2020-06-19 at 12 09 37 PM

po09i commented 4 years ago

I followed the procedure and had the problem with builddocsearchdb when running genToolboxHelp. I had to run restart Matlab and run genToolboxHelp again to fix the problem.

We probably want to create a template on how to create new functions so that both the website and the matlab documentation look good.

Every header page shows a page not found : Screen Shot 2020-06-19 at 14 01 42

jcohenadad commented 4 years ago

We probably want to create a template on how to create new functions so that both the website and the matlab documentation look good.

yup! this is the purpose of https://github.com/shimming-toolbox/shimming-toolbox/issues/133. Out of the scope of this PR. Once merged, we can work on this issue.

Every header page shows a page not found :

yup! i'll find a fix to it before merging.

jcohenadad commented 4 years ago

I followed the procedure and had the problem with builddocsearchdb when running genToolboxHelp. I had to run restart Matlab and run genToolboxHelp again to fix the problem.

🤔 mmh that's annoying. if you could find a better fix to it that would be awesome

rtopfer commented 4 years ago

EDIT: this mush be a new Matlab feature, but even without Contents.m file for non-packages, it does list all the files. So let's get rid of this Contents.m file.

Actually it's an old feature that, indeed, doesn't seem completely worked out: It's nice that it prints the contents automatically without the Contents.m file, but it seems to me having a package overview is sensible, and since help package_name displays Contents.m, this seems like the place to put it? E.g. for all the shim material I had started this WIP for issue #75

jcohenadad commented 4 years ago

Actually it's an old feature that, indeed, doesn't seem completely worked out: It's nice that it prints the contents automatically without the Contents.m file, but it seems to me having a package overview is sensible, and since help package_name displays Contents.m, this seems like the place to put it? E.g. for all the shim material I had started this WIP for issue #75

funny you are writing this now, as I am just realizing that the issue described here is caused by a missing Contents.m file 😬. So I am currently creating one per folder, with brief description about the purpose of each folder/package.

for all the shim material I had started this WIP for issue #75

Awesome!

jcohenadad commented 4 years ago

Missing page issue fixed in c240021e064aa64413e7787cd5940ebdb30a78e5. Output looks like this: Screen Shot 2020-06-19 at 3 11 56 PM

I suggest to indicate with (package) when a folder is a package.

jcohenadad commented 4 years ago

even better: Screen Shot 2020-06-19 at 3 19 23 PM

po09i commented 4 years ago

Missing page issue fixed in c240021.

The missing page issue is also for all the other headers, not only +imutils as shown for the "coils" section here :

https://github.com/shimming-toolbox/shimming-toolbox/pull/134#issuecomment-646799509

jcohenadad commented 4 years ago

Missing page issue fixed in c240021.

The missing page issue is also for all the other headers, not only +imutils as shown for the "coils" section here :

#134 (comment)

yes, i was just looking for a proper solution for imutils, which can then be applied to the other folders. At this point, given the large refactoring ahead, i suggest we don't spend time populating entries that will disappear in the short term (e.g. Coil will be replaced by +coil, etc.). The purpose here is to settle on a set of conventions, that will then be applied to the code at large (in subsequent PRs).

jcohenadad commented 4 years ago

Current problem is building the doc the first time throws an error with builddocsearchdb will open an issue for it.

https://github.com/shimming-toolbox/shimming-toolbox/issues/144

shimming-toolbox / shimming-toolbox-matlab