Skip to content

Commit cc29251

Browse files
eurunuelaeurunuela
authored
Merge pull request #121 from eurunuela/docs_example
Improvements to the docs
2 parents 6095d4c + fd6c8dd commit cc29251

File tree

10 files changed

+151
-141
lines changed

10 files changed

+151
-141
lines changed

‎docs/_static/theme_overrides.css

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,28 @@
11
/* override table width restrictions */
22
@media screen and (min-width: 767px) {
3-
4-
.wy-table-responsive table td {
5-
/* !important prevents the common CSS stylesheets from overriding
3+
.wy-table-responsive table td {
4+
/* !important prevents the common CSS stylesheets from overriding
65
this as on RTD they are loaded after this stylesheet */
7-
white-space: normal !important;
8-
}
6+
white-space: normal !important;
7+
}
98

10-
.wy-table-responsive {
11-
overflow: visible !important;
12-
}
9+
.wy-table-responsive {
10+
overflow: visible !important;
11+
}
1312
}
1413

1514
div.admonition.caution {
16-
background: #FFC3C3
15+
background: #ffc3c3;
1716
}
1817
.rst-content .caution .admonition-title {
19-
background: #FF6F6F
18+
background: #ff6f6f;
19+
}
20+
21+
:root {
22+
--pst-color-primary: #b672da !important;
23+
--pst-color-link: #b672da !important;
24+
--pst-color-link-hover: #8c41af !important;
25+
--bs-link-color: #b672da !important;
26+
--bs-link-hover-color: #8c41af !important;
27+
--pst-color-inline-code-links: #46594f !important;
2028
}

‎docs/api.md

Lines changed: 11 additions & 105 deletions
Original file line numberDiff line numberDiff line change
@@ -1,108 +1,14 @@
11
(api-ref)=
22

3-
```{eval-rst}
4-
.. currentmodule:: pySPFM
5-
```
6-
7-
# API
8-
9-
(api-pyspfm-ref)=
10-
11-
## {mod}`pySPFM.workflows`: The main pySPFM workflow
12-
13-
```{eval-rst}
14-
.. automodule:: pySPFM.workflows
15-
:no-members:
16-
:no-inherited-members:
17-
```
18-
19-
```{eval-rst}
20-
.. currentmodule:: pySPFM.workflows
21-
```
22-
23-
```{eval-rst}
24-
.. autosummary::
25-
:toctree: generated/
26-
:template: module.rst
27-
28-
pySPFM.workflows.pySPFM
29-
pySPFM.workflows.auc_to_estimates
30-
```
31-
32-
(api-deconvolution-ref)=
33-
34-
## {mod}`pySPFM.deconvolution`: Deconvolution methods
35-
36-
```{eval-rst}
37-
.. automodule:: pySPFM.deconvolution
38-
:no-members:
39-
:no-inherited-members:
40-
```
41-
42-
```{eval-rst}
43-
.. currentmodule:: pySPFM.deconvolution
44-
```
45-
46-
```{eval-rst}
47-
.. autosummary::
48-
:toctree: generated/
49-
:template: function.rst
50-
51-
pySPFM.deconvolution.debiasing
52-
pySPFM.deconvolution.fista
53-
pySPFM.deconvolution.hrf_generator
54-
pySPFM.deconvolution.lars
55-
pySPFM.deconvolution.select_lambda
56-
pySPFM.deconvolution.spatial_regularization
57-
pySPFM.deconvolution.stability_selection
58-
59-
```
60-
61-
(api-io-ref)=
62-
63-
## {mod}`pySPFM.io`: Input/Output methods
64-
65-
```{eval-rst}
66-
.. automodule:: pySPFM.io
67-
:no-members:
68-
:no-inherited-members:
69-
```
70-
71-
```{eval-rst}
72-
.. currentmodule:: pySPFM.io
73-
```
74-
75-
```{eval-rst}
76-
.. autosummary::
77-
:toctree: generated/
78-
:template: function.rst
79-
80-
pySPFM.io.read_data
81-
pySPFM.io.update_header
82-
pySPFM.io.write_data
83-
pySPFM.io.write_json
84-
85-
```
86-
87-
(api-utils-ref)=
88-
89-
## {mod}`pySPFM.utils`: Miscellaneous utility methods
90-
91-
```{eval-rst}
92-
.. automodule:: pySPFM.utils
93-
:no-members:
94-
:no-inherited-members:
95-
```
96-
97-
```{eval-rst}
98-
.. currentmodule:: pySPFM.utils
99-
```
100-
101-
```{eval-rst}
102-
.. autosummary::
103-
:toctree: generated/
104-
:template: module.rst
105-
106-
pySPFM.utils.setup_loggers
107-
pySPFM.utils.teardown_loggers
3+
# API Reference
4+
5+
```{toctree}
6+
---
7+
maxdepth: 2
8+
caption: API Documentation
9+
---
10+
api/workflows
11+
api/deconvolution
12+
api/io
13+
api/utils
10814
```

‎docs/api/deconvolution.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
2+
# Deconvolution
3+
4+
```{eval-rst}
5+
.. currentmodule:: pySPFM.deconvolution
6+
7+
.. autosummary::
8+
:toctree: ../generated/
9+
:template: module.rst
10+
11+
debiasing
12+
fista
13+
hrf_generator
14+
lars
15+
select_lambda
16+
spatial_regularization
17+
stability_selection
18+
```

‎docs/api/io.md

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Input/Output
2+
3+
```{eval-rst}
4+
.. currentmodule:: pySPFM.io
5+
6+
.. autosummary::
7+
:toctree: ../generated/
8+
:template: module.rst
9+
10+
read_data
11+
update_header
12+
write_data
13+
write_json
14+
```

‎docs/api/utils.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Utilities
2+
3+
```{eval-rst}
4+
.. currentmodule:: pySPFM.utils
5+
6+
.. autosummary::
7+
:toctree: ../generated/
8+
:template: module.rst
9+
10+
setup_loggers
11+
teardown_loggers
12+
```

‎docs/api/workflows.md

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Workflows
2+
3+
```{eval-rst}
4+
.. currentmodule:: pySPFM.workflows
5+
6+
.. autosummary::
7+
:toctree: ../generated/
8+
:template: module.rst
9+
10+
pySPFM
11+
auc_to_estimates
12+
```

‎docs/conf.py

Lines changed: 40 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
4040
# ones.
4141
extensions = [
42-
"ipykernel",
42+
# "ipykernel",
4343
"matplotlib.sphinxext.plot_directive",
4444
# "myst_parser",
4545
"myst_nb",
@@ -51,12 +51,33 @@
5151
"sphinx.ext.ifconfig",
5252
"sphinx.ext.intersphinx",
5353
"sphinx.ext.linkcode",
54-
# "sphinx.ext.mathjax",
54+
"sphinx.ext.mathjax",
5555
"sphinx.ext.napoleon",
5656
"sphinx.ext.todo",
57+
# "sphinx_gallery",
5758
"sphinx_gallery.load_style",
5859
]
5960

61+
myst_enable_extensions = [
62+
"colon_fence",
63+
"dollarmath",
64+
]
65+
66+
67+
# Update mime priority configuration with integer priorities
68+
nb_mime_priority_overrides = [
69+
("html", "application/vnd.plotly.v1+json", 10), # Format: (format, mimetype, priority)
70+
("html", "text/html", 5),
71+
("html", "image/svg+xml", 4),
72+
("html", "image/png", 3),
73+
("html", "image/jpeg", 2),
74+
("html", "text/plain", 1),
75+
]
76+
77+
# Keep plotly plugin configuration
78+
# nb_render_plugin = "plotly"
79+
80+
6081
from distutils.version import LooseVersion
6182

6283
import sphinx
@@ -137,18 +158,31 @@
137158

138159
html_theme = "sphinx_book_theme"
139160

161+
# Configure TOC settings
162+
toc_object_entries_show_parents = "hide"
163+
164+
# Add autosummary settings to control display names
165+
autosummary_member_order = "groupwise"
166+
add_module_names = False # Don't prefix module names
167+
modindex_common_prefix = ["pySPFM."] # Remove common prefix from module index
168+
140169
# Theme options are theme-specific and customize the look and feel of a theme
141170
# further. For a list of options available for each theme, see the
142171
# documentation.
143172

173+
144174
html_theme_options = {
145-
"includehidden": False,
175+
"show_nav_level": 2,
176+
"collapse_navigation": True,
177+
"navigation_depth": 4,
178+
"show_toc_level": 2,
146179
}
147180

148181
# Add any paths that contain custom static files (such as style sheets) here,
149182
# relative to this directory. They are copied after the builtin static files,
150183
# so a file named "default.css" will overwrite the builtin "default.css".
151184
html_static_path = ["_static"]
185+
html_css_files = ["theme_overrides.css"]
152186

153187

154188
def setup(app):
@@ -178,5 +212,7 @@ def setup(app):
178212
"matplotlib": ("https://matplotlib.org/", None),
179213
"nibabel": ("https://nipy.org/nibabel/", None),
180214
"pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
181-
"nilearn": ("http://nilearn.github.io/", None),
215+
"nilearn": ("http://nilearn.github.io/stable/", None),
182216
}
217+
218+
html_js_files = ["https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"]

‎docs/examples.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
# Examples
22

3-
```{nbgallery}
4-
notebooks/examples.ipynb
3+
This is an example.
54

6-
```
5+
<!-- ```{glue:} regularization_figure
6+
:doc: notebooks/examples.ipynb
7+
``` -->

‎docs/notebooks/examples.ipynb

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@
1010
},
1111
{
1212
"cell_type": "code",
13-
"execution_count": 103,
13+
"execution_count": null,
1414
"id": "f215440b-fc20-4d7d-b3ee-c55f9cba35a8",
1515
"metadata": {},
1616
"outputs": [],
@@ -21,7 +21,9 @@
2121
"\n",
2222
"from pySPFM.deconvolution.hrf_generator import HRFMatrix\n",
2323
"from pySPFM.deconvolution.lars import solve_regularization_path\n",
24-
"import matplotlib.pyplot as plt"
24+
"import matplotlib.pyplot as plt\n",
25+
"\n",
26+
"from myst_nb import glue"
2527
]
2628
},
2729
{
@@ -543,7 +545,7 @@
543545
},
544546
{
545547
"cell_type": "code",
546-
"execution_count": 127,
548+
"execution_count": null,
547549
"id": "6f58e999-d740-4b86-975b-6023f2ca81d4",
548550
"metadata": {},
549551
"outputs": [
@@ -1754835,7 +1754837,8 @@
17548351754837
" yaxis=dict(title='Amplitude'),\n",
17548361754838
")\n",
17548371754839
"\n",
1754838-
"fig.show()"
1754840+
"glue(\"regularization_figure\", fig, display=False)\n",
1754841+
"# fig.show()"
17548391754842
]
17548401754843
},
17548411754844
{

‎docs/usage.md

Lines changed: 15 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -10,26 +10,26 @@ The fixed $\lambda$ method is the simplest one. It consists in choosing one of t
1010
to automatically calculate the regularization parameter lambda:
1111

1212
- `universal threshold`:
13-
: $\lambda = \sigma * \sqrt{2 * \log(T)}$, where $\sigma$ is the median absolute
14-
deviation of the estimated level of noise and T is the number of TRs.
13+
$\lambda = \sigma * \sqrt{2 * \log(T)}$, where $\sigma$ is the median absolute
14+
deviation of the estimated level of noise and T is the number of TRs.
1515
- `lower universal threshold`:
16-
: $\lambda = \sigma * \sqrt{2 * \log(T) - \log(1 + 4 * \log(T))}$, where $\sigma$
17-
is the median absolute deviation of the estimated level of noise and T is the number of TRs.
16+
$\lambda = \sigma * \sqrt{2 * \log(T) - \log(1 + 4 * \log(T))}$, where $\sigma$
17+
is the median absolute deviation of the estimated level of noise and T is the number of TRs.
1818
- `median absolute deviation`:
19-
: Calculate lambda as the median absolute deviation of fine-scale wavelet coefficients
20-
(Daubechies, order 3). For more information, see [Karahanoglu et al. (2013)].
19+
Calculate lambda as the median absolute deviation of fine-scale wavelet coefficients
20+
(Daubechies, order 3). For more information, see [Karahanoglu et al. (2013)].
2121
- `updating median absolute deviation`:
22-
: Median absolute deviation of the estimated level of the noise that gets updated on each
23-
iteration (see [Karahanoglu et al. (2013)]):
24-
$\lambda_{n+1} = {\frac{N \sigma}{\frac{1}{2} \| \mathbf{y} - \mathbf{Hs} \|_2^2 \lambda_n}}$.
22+
Median absolute deviation of the estimated level of the noise that gets updated on each
23+
iteration (see [Karahanoglu et al. (2013)]):
24+
$\lambda_{n+1} = {\frac{N \sigma}{\frac{1}{2} \| \mathbf{y} - \mathbf{Hs} \|_2^2 \lambda_n}}$.
2525
- `percentage of maximum lambda`:
26-
: percentage of the maximum lambda possible to use as lambda.
27-
$\lambda = \textrm{pcg} * \lambda_{max}$,
28-
where $\lambda_{max}= \| \mathbf{H}^T \mathbf{y} \|$ and
29-
$0 \leq \textrm{pcg} \leq 1$
26+
percentage of the maximum lambda possible to use as lambda.
27+
$\lambda = \textrm{pcg} * \lambda_{max}$,
28+
where $\lambda_{max}= \| \mathbf{H}^T \mathbf{y} \|$ and
29+
$0 \leq \textrm{pcg} \leq 1$
3030
- `factor of median absolute deviation`:
31-
: factor of the estimate of the level of noise to use as lambda.
32-
$\lambda = \textrm{factor} * \sigma, with 0 \leq \textrm{factor} \leq 1$
31+
factor of the estimate of the level of noise to use as lambda.
32+
$\lambda = \textrm{factor} * \sigma, with 0 \leq \textrm{factor} \leq 1$
3333

3434
```bash
3535
pySPFM -i my_echo_1.nii.gz my_echo_3.nii.gz my_echo_3.nii.gz -m my_mask.nii.gz

0 commit comments

Comments
 (0)