From 8d7d9e70cfee612497add8195b8eb34c43766920 Mon Sep 17 00:00:00 2001 From: mathiasg Date: Mon, 17 Jun 2024 20:38:28 -0400 Subject: [PATCH 1/8] DOC: Move to shibuya theme, start porting over fMRIPrep documention --- docs/conf.py | 114 +++---- docs/index.md | 14 +- docs/installation.md | 32 +- docs/outputs.md | 689 ++++++++++++++++++++++--------------------- pyproject.toml | 6 +- 5 files changed, 446 insertions(+), 409 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index 7bfb2718..59f38770 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,51 +6,54 @@ import os import sys -from datetime import datetime -from sphinx import __version__ as sphinxversion +from datetime import datetime, timezone + +from github_link import make_linkcode_resolve # this is only available after sphinxext to PATH from packaging.version import Version, parse +from sphinx import __version__ as sphinxversion + +import nibabies # -- Path setup -------------------------------------------------------------- here = os.path.dirname(__file__) # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.append(os.path.join(here, "sphinxext")) -sys.path.insert(0, os.path.join(here, "..", "wrapper")) +sys.path.append(os.path.join(here, 'sphinxext')) +sys.path.insert(0, os.path.join(here, '..', 'wrapper')) -from github_link import make_linkcode_resolve # this is only available after sphinxext to PATH # -- General configuration --------------------------------------------------- # If your documentation needs a minimal Sphinx version, state it here. -needs_sphinx = "1.5.3" +needs_sphinx = '1.5.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.doctest", - "sphinx.ext.intersphinx", - "sphinx.ext.coverage", - "sphinx.ext.mathjax", - "sphinx.ext.linkcode", - "sphinx.ext.napoleon", - "sphinxarg.ext", # argparse extension - "nipype.sphinxext.plot_workflow", - "myst_nb", # stop segregating rst/md + 'sphinx.ext.autodoc', + 'sphinx.ext.doctest', + 'sphinx.ext.intersphinx', + 'sphinx.ext.coverage', + 'sphinx.ext.mathjax', + 'sphinx.ext.linkcode', + 'sphinx.ext.napoleon', + 'sphinxcontrib.bibtex', + 'sphinxarg.ext', # argparse extension + 'nipype.sphinxext.plot_workflow', + 'myst_parser', # allow markdown + 'sphinx-togglebutton', # collapse admonitions ] -autodoc_mock_imports = [ - "numpy", - "nibabel", - "nilearn" -] -if parse(sphinxversion) >= parse("1.7.0"): - autodoc_mock_imports += [ - "pandas", - "nilearn", - "seaborn", +bibtex_bibfiles = ['../nibabies/data/boilerplate.bib'] + +autodoc_mock_imports = ['numpy', 'nibabel', 'nilearn'] +if parse(sphinxversion) >= parse('1.7.0'): + autodoc_mock_imports = [ + 'pandas', + 'nilearn', + 'seaborn', ] # Add any paths that contain templates here, relative to this directory. @@ -62,14 +65,33 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] -source_suffix = [".rst", ".md"] +source_suffix = ['.rst', '.md'] # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' +html_theme = 'shibuya' + +# Options specific to theme +html_theme_options = { + 'color_mode': 'light', + 'dark_code': True, + 'github_url': 'https://github.com/nipreps/nibabies', + 'nav_links': [ + { + 'title': 'NiPreps Homepage', + 'url': 'https://nipreps.org', + 'external': True, + }, + { + 'title': 'Docker Hub', + 'url': 'https://hub.docker.com/r/nipreps/nibabies', + 'external': True, + }, + ], +} # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, @@ -83,40 +105,30 @@ # https://github.com/sphinx-contrib/napoleon/pull/10 is merged. napoleon_use_param = False napoleon_custom_sections = [ - ("Inputs", "Parameters"), - ("Outputs", "Parameters"), + ('Inputs', 'Parameters'), + ('Outputs', 'Parameters'), ] # -- MyST parameters --------------------------------------------------------- myst_heading_anchors = 3 myst_enable_extensions = [ - "colon_fence", - "substitution", + 'colon_fence', + 'substitution', ] -linkcode_resolve = make_linkcode_resolve("nibabies", - "https://github.com/nipreps/" - "nibabies/blob/{revision}/" - "{package}/{path}#L{lineno}") +linkcode_resolve = make_linkcode_resolve( + 'nibabies', + 'https://github.com/nipreps/' 'nibabies/blob/{revision}/' '{package}/{path}#L{lineno}', +) -project = "NiBabies" -author = "The NiPreps developers" -copyright = "2021-%s, %s" % (datetime.now().year, author) +project = 'NiBabies' +author = 'The NiPreps developers' -import nibabies +copyright = f'2021-{datetime.now(tz=timezone.utc)}, {author}' nibabies_ver = Version(nibabies.__version__) -release = "version" if nibabies_ver.is_prerelease else nibabies_ver.public - -myst_substitutions = { - "release": release, - "version": str(nibabies_ver), - "dockerbuild": "docker pull nipreps/nibabies:{{ release }}", - "singbuild": ( - "singularity build nibabies-{{ release }}.sif docker://nipreps/nibabies:{{ release }}" - ), -} +release = 'version' if nibabies_ver.is_prerelease else nibabies_ver.public # to avoid Python highlighting in literal text -highlight_language = "none" +highlight_language = 'none' diff --git a/docs/index.md b/docs/index.md index 14b59f40..c9251e11 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,4 @@ -```{include} ../README.md +``` :relative-docs: docs/ :relative-images: ``` @@ -6,11 +6,11 @@ ## Contents ```{toctree} -:maxdepth: 2 +:maxdepth: 3 -installation -usage -faqs -outputs -community +installation.md +usage.md +faqs.md +outputs.md +community.md ``` diff --git a/docs/installation.md b/docs/installation.md index b8be6e16..f511264d 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,37 +1,39 @@ # Installation -The latest release of *NiBabies* is {{ release }}. - -To view all available releases, refer to the [NiBabies PyPI page](https://pypi.org/project/nibabies/#history). +There are two ways to install *NiBabies*: + - using container technologies; or + - within a manually prepared environment, also known as *bare-metal*. ## Container Installation -Given its extensive dependencies, the easiest way to get up and running with *NiBabies* is by using a container service, such as [Docker](https://www.docker.com/get-started) or [Singularity](https://sylabs.io/singularity/). +Given its extensive dependencies, the easiest way to get up and running with *NiBabies* is by using a container service, such as [Docker](https://www.docker.com/get-started) or [Apptainer](https://apptainer.org/). ### Working with Docker Images are hosted on our [Docker Hub](https://hub.docker.com/r/nipreps/nibabies). To pull an image, the specific version tag must be specified in order to pull the images. +For example, to pull the first release in the 24.0.0 series, you can do: -:::{admonition} Example Docker build -:class: seealso - -$ {{ dockerbuild }} -::: +```shell +docker pull nipreps/nibabies:24.0.0 +``` There are also a few keyword tags, `latest` and `unstable`, that serve as special pointers. `latest` points to the latest release (excluding any betas or release candidates). `unstable` points to the most recent developmental change, and should only be used to test new features or fixes. -### Working with Singularity +:::{tip} -The easiest way to create a Singularity image is to build from the [Docker](#working-with-docker) images hosted online. +Using versioned releases (such as `24.0.0`) are preferred to using the `latest` tag, as they are more explicit. +::: -:::{admonition} Example Singularity build -:class: seealso +### Working with Apptainer (formerly Singularity) -$ {{ singbuild }} -::: +The easiest way to create an Apptainer image is to build from the [Docker](#working-with-docker) images hosted online. + +```bash +apptainer build nibabies-version.sif docker://nipreps/nibabies:version +``` ## Installing the nibabies-wrapper diff --git a/docs/outputs.md b/docs/outputs.md index 6c35605e..ff4caca9 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -1,57 +1,58 @@ -.. include:: links.rst +# Outputs of *NiBabies* -.. _outputs: - ---------------------- -Outputs of *NiBabies* ---------------------- *NiBabies* outputs conform to the :abbr:`BIDS (brain imaging data structure)` Derivatives specification (see `BIDS Derivatives`_, along with the upcoming `BEP 011`_ and `BEP 012`_). *NiBabies* generates three broad classes of outcomes: 1. **Visual QA (quality assessment) reports**: - one :abbr:`HTML (hypertext markup language)` per subject, + one {abbr}`HTML (hypertext markup language)` per subject, that allows the user a thorough visual assessment of the quality of processing and ensures the transparency of *NiBabies* operations. 2. **Derivatives (preprocessed data)** the input fMRI data ready for analysis, i.e., after the various preparation procedures have been applied. - For example, :abbr:`INU (intensity non-uniformity)`-corrected versions + For example, {abbr}`INU (intensity non-uniformity)`-corrected versions of the T1-weighted image (per subject), the brain mask, - or :abbr:`BOLD (blood-oxygen level dependent)` + or {abbr}`BOLD (blood-oxygen level dependent)` images after head-motion correction, slice-timing correction and aligned into - the same-subject's T1w space or in some standard space. + the same-subject's anatomical space or in some standard space. 3. **Confounds**: this is a special family of derivatives that can be utilized to inform subsequent denoising steps. - .. warning:: - These modules are still in alpha and require additional testing. +:::{warning} +Confounds, particularly a/t CompCor, are still in alpha and require additional testing. +::: - .. important:: - In order to remain agnostic to any possible subsequent analysis, - *NiBabies* does not perform any denoising (e.g., spatial smoothing) itself. - There are exceptions to this principle (described in its corresponding - section below): +:::{important} +In order to remain agnostic to any possible subsequent analysis, +*NiBabies* does not perform any denoising (e.g., spatial smoothing) itself. +There are exceptions to this principle (described in its corresponding +section below): - - CompCor regressors, which are calculated after temporal high-pass filtering. +- CompCor regressors, which are calculated after temporal high-pass filtering. +::: -Layout ------- -Assuming NiBabies is invoked with:: +## Layout - NiBabies / / participant [OPTIONS] +Assuming NiBabies is invoked with: -The outputs will be a `BIDS Derivatives`_ dataset of the form:: +``` +nibabies / / participant [OPTIONS] +``` - / - logs/ - sub-