re build sphinx doc

Author: marcobarilari

.gitignore

@@ -6,4 +6,7 @@
 # exclude content of logfiles folders
 *.tsv
 *.mat
-check_my_code_report.txt
+check_my_code_report.txt
+
+# ignore file created by sphynx
+/docs/build

docs/.readthedocs.yml0

@@ -24,3 +24,116 @@ sphinx-quickstart # launch a basic interactive set up of sphinx
 ```
 
 Answer the questions on prompt.
+
+## Setting up conf.py for matlab doc
+
+Following the documentation from
+[matlabdomain for sphinx](https://github.com/sphinx-contrib/matlabdomain).
+
+Specify the extensions you are using:
+
+```python
+extensions = [
+    'sphinxcontrib.matlab',
+    'sphinx.ext.autodoc']
+```
+
+`matlab_src_dir` in `docs/source/conf.py` should have the path (relative to `conf.py`)
+to the folder containing your matlab code:
+
+```python
+matlab_src_dir = os.path.dirname(os.path.abspath('../../src'))
+```
+
+## reStructured text markup
+
+reStructured text mark up
+[primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html).
+
+## "Templates"
+
+There are different ways you can document the help section of your matlab
+functions so it can be documented automatically by sphinx.
+
+```matlab
+function y = my_function(arg1, arg2)
+    %
+    % Describe what the function does here.
+    %
+    %  y = my_function_napoleon(arg1, arg2)
+    %
+    % :param arg1: The first input value
+    % :param arg2: The second input value
+    % :returns: The input value multiplied by two
+
+    y = arg1 + arg2
+```
+
+"Napoleon" way more similar to Numpy:
+
+```matlab
+function y = my_function_napoleon(arg1, arg2)
+    %
+    % Describe what the function does here.
+    %
+    %  y = my_function_napoleon(arg1, arg2)
+    %
+    % Parameters:
+    %    x: The first input value
+    %
+    %    y: The second input value
+    %
+    % Returns:
+    %    The input value multiplied by two
+
+    y = x * 2;
+```
+
+You then just need to insert this in your `.rst` file for the documentation to
+be done automatically.
+
+```rst
+
+.. automodule:: src .. <-- This is necessary for autodocumenting the rest
+
+.. autofunction:: my_function
+
+.. autofunction:: my_function_napoleon
+```
+
+## Build the documentation locally
+
+From the `docs` directory:
+
+```bash
+sphinx-build -b html source build
+```
+
+This will build an html version of the doc in the `build` folder.
+
+## Buid the documentation with Read the Docs
+
+Add a [`.readthedocs.yml`](../.readthedocs.yml) file in the root of your repo.
+
+See [HERE](https://docs.readthedocs.io/en/stable/config-file/v2.html) for
+details.
+
+You can then trigger the build of the doc by going to the [read the docs]
+website: https://readthedocs.org.
+
+You might need to be added as a maintainer of the doc.
+
+The doc can be built from any branch of a repo.
+
+<!-- TODO -->
+
+## Other matlab projects that use...
+
+### Sphinx
+
+Some are listed
+https://github.com/sphinx-contrib/matlabdomain#users
+
+### Read the docs
+
+- [qMRLab](https://github.com/qMRLab/qMRLab/wiki/Guideline:-Generating-Documentation)

docs/.readthedocs.yml1

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 7b5b1a5e051521c21de157c4bf2ecab6
+config: 10fab318711bbc6c9d19f0bcaabfa2e5
 tags: 645f666f9bcd5a90fca523b33c5a78b7