Skip to content

Commit 513d789

Browse files
Remi-GauRemi-Gau
committed
set up doc
1 parent 74587cd commit 513d789

File tree

12 files changed

+124
-132
lines changed

12 files changed

+124
-132
lines changed

‎.readthedocs copy.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# .readthedocs.yml
2+
# Read the Docs configuration file
3+
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
4+
5+
# Required
6+
version: 2
7+
8+
# Build documentation in the docs/ directory with Sphinx
9+
sphinx:
10+
configuration: docs/source/conf.py
11+
builder: html
12+
fail_on_warning: true
13+
14+
# Build documentation with MkDocs
15+
#mkdocs:
16+
# configuration: mkdocs.yml
17+
18+
# Optionally build your docs in additional formats such as PDF
19+
formats:
20+
- pdf
21+
22+
# Optionally set the version of Python and requirements required to build your docs
23+
python:
24+
version: 3.7
25+
install:
26+
- requirements: requirements.txt

‎CITATION.cff‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
cff-version: 1.2.0
2+
3+
title: "CPP ROI"
4+
5+
version: v0.2.0dev
6+
7+
abstract: Set of Octave and Matlab functions, demos and scripts to help manage ROIs and to play nice with BIDS datasets.
8+
9+
message: "If you use this software, please cite it as below."
10+
11+
repository-code: "https://github.com/cpp-lln-lab/CPP_ROI"
12+
13+
contact:
14+
- affiliation: "Université catholique de Louvain"
15+
email: [email protected]
16+
family-names: Gau
17+
given-names: Rémi
18+
19+
authors:
20+
- family-names: "Gau"
21+
given-names: "Rémi"
22+
orcid: "https://orcid.org/0000-0002-1535-9767"
23+
affiliation: "Université catholique de Louvain"
24+
25+
- family-names: "Barilari"
26+
given-names: "Marco"
27+
orcid: "https://orcid.org/0000-0002-3313-3120"
28+
affiliation: "Université catholique de Louvain"
29+
30+
- family-names: "Battal"
31+
given-names: "Ceren"
32+
orcid: "https://orcid.org/0000-0002-9844-7630"
33+
affiliation: "Université catholique de Louvain"
34+
35+
- family-names: "Falagiarda"
36+
given-names: "Federica"
37+
orcid: "https://orcid.org/0000-0001-7844-1605"
38+
affiliation: "Université catholique de Louvain"
39+
40+
license: GPL-3.0
41+
42+
keywords:
43+
- BIDS
44+
- brain imaging data structure
45+
- neuroimaging
46+
- MRI
47+
- MATLAB
48+
- Octave
49+
- SPM
50+
- ROI
51+
- region of interest

‎Makefile‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,5 +2,12 @@
22

33
clean:
44
rm -rf coverage*
5+
rm version.txt
56
install_dev:
67
git clone https://github.com/bids-standard/bids-matlab.git --branch dev --depth 1 lib/bids-matlab
8+
9+
version.txt: CITATION.cff
10+
grep -w "^version" CITATION.cff | sed "s/version: /v/g" > version.txt
11+
12+
validate_cff: CITATION.cff
13+
cffconvert --validate

‎docs/README.md‎

Lines changed: 2 additions & 108 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,2 @@
1-
# Setting up sphinx to create a matlab doc
2-
3-
## Set up virtual environment
4-
5-
```bash
6-
virtualenv -p python3 cpp_spm
7-
source cpp_spm/bin/activate
8-
9-
pip install -r requirements.txt
10-
```
11-
12-
## Quick start on the doc
13-
14-
See the [sphinx doc](https://www.sphinx-doc.org/en/master/usage/quickstart.html)
15-
for more.
16-
17-
This
18-
[blog post](https://medium.com/@richdayandnight/a-simple-tutorial-on-how-to-document-your-python-project-using-sphinx-and-rinohtype-177c22a15b5b)
19-
is also useful.
20-
21-
```bash
22-
cd docs
23-
sphinx-quickstart # launch a basic interactive set up of sphinx
24-
```
25-
26-
Answer the questions on prompt.
27-
28-
## Setting up conf.py for matlab doc
29-
30-
Following the documentation from
31-
[matlabdomain for sphinx](https://github.com/sphinx-contrib/matlabdomain).
32-
33-
Specify the extensions you are using:
34-
35-
```python
36-
extensions = [
37-
'sphinxcontrib.matlab',
38-
'sphinx.ext.autodoc']
39-
```
40-
41-
`matlab_src_dir` in `docs/source/conf.py` should have the path (relative to
42-
`conf.py`) to the folder containing your matlab code:
43-
44-
```python
45-
matlab_src_dir = os.path.dirname(os.path.abspath('../../src'))
46-
```
47-
48-
## reStructured text markup
49-
50-
reStructured text mark up primers:
51-
52-
- on the [sphinx site](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)
53-
54-
- more
55-
[python oriented](https://pythonhosted.org/an_example_pypi_project/sphinx.html)
56-
57-
- typical doc strings templates
58-
- [google way](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html)
59-
- [numpy](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html#example-numpy)
60-
61-
## "Templates"
62-
63-
The templates to use for the doc are in the `src/templates` folder.
64-
65-
You then just need to insert this in your `.rst` file for the documentation to
66-
be done automatically.
67-
68-
```rst
69-
70-
.. automodule:: src.folder_name .. <-- This is necessary for auto-documenting the rest
71-
72-
.. autofunction:: function to document
73-
74-
```
75-
76-
To get the filenames of all the functions in a folder:
77-
78-
``` bash
79-
ls -l src/*.m | cut -c42- | rev | cut -c 3- | rev
80-
```
81-
82-
Increase the `42` to crop more characters at the beginning.
83-
84-
Change the `3` to crop more characters at the end.
85-
86-
## Build the documentation locally
87-
88-
From the `docs` directory:
89-
90-
```bash
91-
sphinx-build -b html source build
92-
```
93-
94-
This will build an html version of the doc in the `build` folder.
95-
96-
## Build the documentation with Read the Docs
97-
98-
Add a [`.readthedocs.yml`](../.readthedocs.yml) file in the root of your repo.
99-
100-
See [HERE](https://docs.readthedocs.io/en/stable/config-file/v2.html) for
101-
details.
102-
103-
You can then trigger the build of the doc by going to the
104-
[read the docs website](https://readthedocs.org).
105-
106-
You might need to be added as a maintainer of the doc.
107-
108-
The doc can be built from any branch of a repo.
1+
Information on how to write and build the documentation can be found in our
2+
[CONTRIBUTING guidelines](https://github.com/cpp-lln-lab/.github/blob/main/CONTRIBUTING.md).

‎docs/source/atlas.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
Atlas
2+
*****
3+
4+
.. automodule:: src.atlas
5+
6+
.. autofunction:: extractRoiFromAtlas
7+
.. autofunction:: extractRoiByLabel
8+
.. autofunction:: labelClusters

‎docs/source/conf.py‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,12 @@
3131
# Add any Sphinx extension module names here, as strings. They can be
3232
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3333
# ones.
34-
extensions = ["sphinxcontrib.matlab", "sphinx.ext.autodoc", "sphinx_copybutton"]
34+
extensions = [
35+
"sphinxcontrib.matlab",
36+
"sphinx.ext.autodoc",
37+
"sphinx_copybutton",
38+
"myst_parser",
39+
]
3540
matlab_src_dir = os.path.dirname(os.path.abspath("../../src"))
3641
primary_domain = "mat"
3742

‎docs/source/function_description.rst‎

Lines changed: 0 additions & 16 deletions
This file was deleted.

‎docs/source/index.rst‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,12 @@ Welcome to CPP_ROI documentation!
22
*********************************
33

44
.. toctree::
5-
:maxdepth: 2
5+
:maxdepth: 1
66
:caption: Content
77

8-
function_description
9-
8+
install
9+
roi
10+
atlas
1011

1112
Indices and tables
1213
==================

‎docs/source/install.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../README.md

‎docs/source/roi.rst‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
Region of interest
2+
******************
3+
4+
.. automodule:: src.roi
5+
6+
.. autofunction:: createRoi
7+
.. autofunction:: keepHemisphere
8+
.. autofunction:: thresholdToMask
9+
.. autofunction:: renameNeuroSynth
10+
.. autofunction:: resliceRoiImages

0 commit comments

Comments
 (0)