Generate Matlab documentation #134

jcohenadad · 2020-06-18T15:08:14Z

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: shimming-toolbox/shimming-toolbox#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 · 2020-06-18T19:58:48Z

Working prototype on b6f246a

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 · 2020-06-19T13:59:55Z

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.

because it has personalized install info

Was hard-coded line. now replaced with global FOLDERHTML

jcohenadad · 2020-06-19T16:12:15Z

Ready to be tested:

Checkout this branch (commit bde1642)
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:

po09i · 2020-06-19T18:10:40Z

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 :

jcohenadad · 2020-06-19T18:45:43Z

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 shimming-toolbox/shimming-toolbox#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 · 2020-06-19T18:54:37Z

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 · 2020-06-19T18:55:51Z

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 · 2020-06-19T19:00:43Z

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 · 2020-06-19T19:13:08Z

Missing page issue fixed in c240021. Output looks like this:

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

jcohenadad · 2020-06-19T19:20:44Z

even better:

po09i · 2020-06-19T19:22:01Z

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 :

shimming-toolbox/shimming-toolbox#134 (comment)

jcohenadad · 2020-06-19T19:25:38Z

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).

po09i

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

jcohenadad · 2020-06-19T19:51:28Z

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

shimming-toolbox/shimming-toolbox#144

Project files

318b158

jcohenadad marked this pull request as draft June 18, 2020 15:08

jcohenadad added 2 commits June 18, 2020 14:13

Added script to auto-generate html and helptoc

4ec0ace

Fixed OS separator issue

b6f246a

jcohenadad added 5 commits June 18, 2020 16:30

Accommodate new GettingStarted.xlm file

1639417

Removed .git from startup

be6f3c0

genToolboxHelp.m: Changed Help output for doc/

efcbb4d

Added info.xml

e871dc0

Updated .gitignore

5cf36f0

jcohenadad changed the title ~~Converting to a Matlab toolbox~~ Converting to a Matlab toolbox and generate Matlab documentation Jun 19, 2020

jcohenadad added 6 commits June 19, 2020 10:43

Now converts mlx file to html; global variable to avoid Contents.m

5c416f5

Removed shimming-toolbox.prj from git

637184e

because it has personalized install info

Removed creation of doc/shimming-toolbox

bbe4144

Was hard-coded line. now replaced with global FOLDERHTML

Updated getting_started.mlx

05a1904

Added html and doc-related files to .gitignore

971ddc9

Removed call to cleanUpHelp because it is buggy

bde1642

jcohenadad marked this pull request as ready for review June 19, 2020 16:12

jcohenadad added 2 commits June 19, 2020 15:08

Removed filesep after tocitem

2ac5b52

Added Contents.m to +imutils

c240021

Pimped up Contents with markup

6be7c9f

jcohenadad requested review from po09i and rtopfer June 19, 2020 19:21

jcohenadad mentioned this pull request Jun 19, 2020

Rt/issue75 shim specs json #92

Draft

Removed unecessary line in Contents.m

b4956d8

jcohenadad changed the title ~~Converting to a Matlab toolbox and generate Matlab documentation~~ Generate Matlab documentation Jun 19, 2020

po09i approved these changes Jun 19, 2020

View reviewed changes

jcohenadad merged commit dcdfda0 into master Jun 19, 2020

jcohenadad deleted the jca/toolbox branch June 19, 2020 19:41

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Generate Matlab documentation #134

Generate Matlab documentation #134

jcohenadad commented Jun 18, 2020 •

edited

Loading

jcohenadad commented Jun 18, 2020

jcohenadad commented Jun 19, 2020 •

edited

Loading

jcohenadad commented Jun 19, 2020 •

edited

Loading

po09i commented Jun 19, 2020

jcohenadad commented Jun 19, 2020 •

edited

Loading

jcohenadad commented Jun 19, 2020

rtopfer commented Jun 19, 2020

jcohenadad commented Jun 19, 2020 •

edited

Loading

jcohenadad commented Jun 19, 2020

jcohenadad commented Jun 19, 2020

po09i commented Jun 19, 2020

jcohenadad commented Jun 19, 2020 •

edited

Loading

po09i left a comment

jcohenadad commented Jun 19, 2020

Generate Matlab documentation #134

Generate Matlab documentation #134

Conversation

jcohenadad commented Jun 18, 2020 • edited Loading

Context

Things to figure out

Tips & tricks

Formatting Matlabs's markup

Publish Live scripts as html

builddocsearchdb: Could not write search database

builddocsearchdb: There is no installed product with this help location

Publish for package files

jcohenadad commented Jun 18, 2020

jcohenadad commented Jun 19, 2020 • edited Loading

jcohenadad commented Jun 19, 2020 • edited Loading

po09i commented Jun 19, 2020

jcohenadad commented Jun 19, 2020 • edited Loading

jcohenadad commented Jun 19, 2020

rtopfer commented Jun 19, 2020

jcohenadad commented Jun 19, 2020 • edited Loading

jcohenadad commented Jun 19, 2020

jcohenadad commented Jun 19, 2020

po09i commented Jun 19, 2020

jcohenadad commented Jun 19, 2020 • edited Loading

po09i left a comment

Choose a reason for hiding this comment

jcohenadad commented Jun 19, 2020

jcohenadad commented Jun 18, 2020 •

edited

Loading

jcohenadad commented Jun 19, 2020 •

edited

Loading

jcohenadad commented Jun 19, 2020 •

edited

Loading

jcohenadad commented Jun 19, 2020 •

edited

Loading

jcohenadad commented Jun 19, 2020 •

edited

Loading

jcohenadad commented Jun 19, 2020 •

edited

Loading