[DOC] Add sphinx documentation and serve on read the docs#45
[DOC] Add sphinx documentation and serve on read the docs#45kendrickkay merged 11 commits intocvnlab:mainfrom
Conversation
Common base for the matlab and python testing branch to minimize merge conflicts down the line
|
This is just a suggestion: was also curious to see how to set up the Sphinx for combined Python / Matlab project. |
| .. mat:automodule:: matlab | ||
|
|
||
| .. mat:autofunction:: GLMestimatesingletrial | ||
|
|
||
| .. mat:automodule:: matlab.utilities | ||
|
|
||
| .. mat:autofunction:: calccod No newline at end of file |
There was a problem hiding this comment.
This is all that is needed to tell Sphinx to read and render the help sections from specific matlab file
| .. module:: glmsingle.glmsingle | ||
|
|
||
| .. autoclass:: GLM_single | ||
| :members: | ||
| :undoc-members: | ||
| :show-inheritance: | ||
|
|
||
| .. module:: glmsingle.cod.calc_cod | ||
|
|
||
| .. autofunction:: calc_cod No newline at end of file |
There was a problem hiding this comment.
same for python but also shows how to deal with classes and their methods
|
Looks interesting. (But obviously would need clean up.) This is another thing we can earmark for discussion (with Jacob and Ian, too). |
own in the documentation
…arnings and ensure decent rendering
|
Wiki has been added: see here https://glmsingle.readthedocs.io/en/latest/wiki.html |
| % Note that we ultimately compute single-trial response estimates (one estimate for | ||
| % each condition onset), and these will be provided in chronological order. However, | ||
| % by specifying that a given condition occurs more than one time over the course | ||
| % of the experiment, this information can and will be used for cross-validation purposes. | ||
| % | ||
| % Note that we ultimately compute single-trial response estimates (one estimate for | ||
| % each condition onset), and these will be provided in chronological order. However, | ||
| % by specifying that a given condition occurs more than one time over the course | ||
| % of the experiment, this information can and will be used for cross-validation purposes. | ||
| % |
There was a problem hiding this comment.
I did a "quick fix" of the help section of the main matlab function so that it renders correctly
https://glmsingle.readthedocs.io/en/latest/matlab.html
The only change you would have to do to your usually commenting style so that it plays nice with the restrcutured text markup to sphinx expects would be to use lineskip rather than indents for each of the your parameter definition paragraph.
I will still send some typical template function in case you wanted to adopt something that ressembles some of the other typical commenting styles used in sphinx.
There was a problem hiding this comment.
In case you want to browse the whole function directly: see it on my fork
https://github.com/Remi-Gau/GLMsingle/blob/add_sphinx_doc/matlab/GLMestimatesingletrial.m
| % USAGE:: | ||
| % | ||
| % results = GLMestimatesingletrial(design,data,stimdur,tr,outputdir,opt) |
There was a problem hiding this comment.
the double :: + lineskip + indent
is what sphinx uses to render code.
The same way that in markdown:
results = GLMestimatesingletrial(design,data,stimdur,tr,outputdir,opt)is made with this
```matlab
results = GLMestimatesingletrial(design,data,stimdur,tr,outputdir,opt)
```
|
I looked over the links and information and stuff. Seems good. If this is ready to go / merge, we could go ahead and pull the trigger and get this squared away (and then I would conform to the new doc philosophy). |
|
(I presume this merge request is separable from the other ones? If so, we could do this one first, and then proceed to the other ones, next.) |
|
yes those PR should in principle be merged in any order. If there is a merge conflict at some point I will fix it when it happens. After this one is merged there might be some 'configuration' to do:
I will send an email with some of the typical doc formatting you could adopt if you so desired |
|
OK, i replaced the wiki with a simple link to the new "readthedocs" site. Please go ahead and do the remaining todo items listed above. |
|
(PS: I have also majorly updated the wiki.md file on the repo, so I guess these changes will propagate once you link to the repo.) |
2 participants
Small example of a set up to use the Sphinx python package to automatically generate the documentation of the code by reading it from the doc stings (python) or help section (matlab).
This also includes a setup to serve the doc on read the docs.
See the output here: https://glmsingle.readthedocs.io/en/latest/
This example only shows the rendering of the main function but this could be expanded to add more of the utilities function.
Pros: easy to create a website to point users to or even a pdf of the whole documentation (
make latexpdf)Cons: might require to do a light editing of the comments in the code to make them play well with reStructured text (the markup language used by Sphinx) otherwise the rendering is suboptimal.
For a quick intro to all this: https://goodresearch.dev/docs.html#
FYI this is based on the same initial commit as #43 and #44