Skip to content
This repository has been archived by the owner on May 18, 2021. It is now read-only.

Generate Matlab documentation #134

Merged
merged 18 commits into from
Jun 19, 2020
Merged

Generate Matlab documentation #134

merged 18 commits into from
Jun 19, 2020

Conversation

jcohenadad
Copy link
Member

@jcohenadad jcohenadad commented Jun 18, 2020

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:
  • 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 jcohenadad marked this pull request as draft June 18, 2020 15:08
@jcohenadad
Copy link
Member Author

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:
image

@jcohenadad jcohenadad changed the title Converting to a Matlab toolbox Converting to a Matlab toolbox and generate Matlab documentation Jun 19, 2020
@jcohenadad
Copy link
Member Author

jcohenadad commented Jun 19, 2020

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
Copy link
Member Author

jcohenadad commented Jun 19, 2020

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:
Screen Shot 2020-06-19 at 12 09 37 PM

@jcohenadad jcohenadad marked this pull request as ready for review June 19, 2020 16:12
@po09i
Copy link
Member

po09i commented Jun 19, 2020

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
Copy link
Member Author

jcohenadad commented Jun 19, 2020

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
Copy link
Member Author

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
Copy link
Contributor

rtopfer commented Jun 19, 2020

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
Copy link
Member Author

jcohenadad commented Jun 19, 2020

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
Copy link
Member Author

Missing page issue fixed in c240021. 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
Copy link
Member Author

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

@jcohenadad jcohenadad requested review from po09i and rtopfer June 19, 2020 19:21
@po09i
Copy link
Member

po09i commented Jun 19, 2020

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
Copy link
Member Author

jcohenadad commented Jun 19, 2020

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 jcohenadad changed the title Converting to a Matlab toolbox and generate Matlab documentation Generate Matlab documentation Jun 19, 2020
Copy link
Member

@po09i po09i left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@jcohenadad jcohenadad merged commit dcdfda0 into master Jun 19, 2020
@jcohenadad jcohenadad deleted the jca/toolbox branch June 19, 2020 19:41
@jcohenadad
Copy link
Member Author

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants