Add documentation (#8)

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -28,7 +28,7 @@ body:
         For information on how to contribute, please refer to our [contributing guidelines](https://www.nipreps.org/community/CONTRIBUTING/).
       options:
         - "Yes"
-        - Yes, but I would need guidance
+        - "Yes, but I would need guidance"
         - "No"
     validations:
       required: true

.github/config.yml

@@ -0,0 +1,25 @@
+# Configuration for new-pr-welcome - https://github.com/behaviorbot/new-pr-welcome
+
+# Comment to be posted to on PRs from first time contributors in your repository
+newPRWelcomeComment: >
+    Welcome, new contributor!
+
+    We ask you to read through the Contributing Guide:
+    https://github.com/nipreps/fmripost-template/blob/main/CONTRIBUTING.md
+
+    These are guidelines intended to make communication easier by describing a consistent process, but
+    don't worry if you don't get it everything exactly "right" on the first try.
+
+    To boil it down, here are some highlights:
+
+    1) Consider starting a conversation in the issues list before submitting a pull request. The discussion might save you a
+    lot of time coding.
+    2) Please use a descriptive title for your pull request.
+    Please remember to set your pull request as a "draft" if it is not ready for review.
+    3) Any code you submit will be licensed under the same terms (Apache License 2.0) as the rest of fMRIPost-template.
+    4) We invite every contributor to add themselves to the `.zenodo.json` file
+    (https://github.com/nipreps/fmripost-template/blob/main/.zenodo.json), which will result in your being listed as an author
+    at the next release. Please add yourself as the next-to-last entry, just above Russ.
+
+    A pull request is a conversation. We may ask you to make some changes before accepting your PR,
+    and likewise, you should feel free to ask us any questions you have.

.github/pull_request_template.md

@@ -1,15 +1,11 @@
-<!--
-Text in these brackets are comments, and won't be visible when you submit your pull request.
-If this is your first contribution, please take the time to read these, in particular the comment
-beginning "Welcome, new contributors!".
--->
+Closes .
 
 ## Changes proposed in this pull request
 
 <!--
 Please describe here the main features / changes proposed for review and integration in fMRIPost-template
 If this PR addresses some existing problem, please use GitHub's citing tools
-(eg. ref #, closes # or fixes #).
+(e.g., ref #, closes # or fixes #).
 If there is not an existing issue open describing the problem, please consider opening a new
 issue first and then link it from here (so the *fMRIPost-template* community has a better understanding
 of ongoing development efforts and possible overlaps between contributions).
@@ -20,30 +16,3 @@ of ongoing development efforts and possible overlaps between contributions).
 <!--
 Please summarize here the main changes to the documentation that the reviewers should be aware of.
 -->
-
-
-
-<!--
-Welcome, new contributors!
-
-We ask you to read through the Contributing Guide:
-https://github.com/nipreps/fmripost-template/blob/main/CONTRIBUTING.md
-
-These are guidelines intended to make communication easier by describing a consistent process, but
-don't worry if you don't get it everything exactly "right" on the first try.
-
-To boil it down, here are some highlights:
-
-1) Consider starting a conversation in the issues list before submitting a pull request. The discussion might save you a
-   lot of time coding.
-2) Please use descriptive prefixes in your pull request title, such as "ENH:" for an enhancement or "FIX:" for a bug fix.
-   (See the Contributing guide for the full set.) And consider adding a "WIP" tag for works-in-progress.
-3) Any code you submit will be licensed under the same terms (Apache License 2.0) as the rest of fMRIPost-template.
-4) We invite every contributor to add themselves to the `.zenodo.json` file
-   (https://github.com/nipreps/fmripost-template/blob/main/.zenodo.json), which will result in your being listed as an author
-   at the next release. Please add yourself as the next-to-last entry, just above Russ.
-
-A pull request is a conversation. We may ask you to make some changes before accepting your PR,
-and likewise, you should feel free to ask us any questions you have.
-
--->

.mailmap

@@ -1,3 +1,6 @@
 Christopher J. Markiewicz <[email protected]>
 Christopher J. Markiewicz <[email protected]> <[email protected]>
 Christopher J. Markiewicz <[email protected]> <[email protected]>
+Taylor Salo <[email protected]>
+Taylor Salo <[email protected]> <[email protected]>
+Taylor Salo <[email protected]> <[email protected]>

.zenodo.json

@@ -6,18 +6,6 @@
       "affiliation": "Lausanne University Hospital and University of Lausanne, Lausanne, Switzerland",
       "name": "Esteban, Oscar",
       "orcid": "0000-0001-8435-6191"
-    },
-    {
-      "name": "Ferrer, Vicente"
-    },
-    {
-      "name": "Uruñuela, Eneko"
-    },
-    {
-      "name": "Pedregosa, Fabian"
-    },
-    {
-      "name": "Caballero Gaudes, Cesar"
     }
   ],
   "creators": [
@@ -36,7 +24,7 @@
     "neuroimaging",
     "workflow",
     "pipeline",
-    "preprocessing",
+    "postprocessing",
     "fMRI",
     "BIDS"
   ],

Dockerfile

@@ -2,7 +2,7 @@
 #
 # MIT License
 #
-# Copyright (c) The NiPreps Developers
+# Copyright (c) 2024 The NiPreps Developers
 #
 # Permission is hereby granted, free of charge, to any person obtaining a copy
 # of this software and associated documentation files (the "Software"), to deal

NOTICE

@@ -1 +1 @@
-src/fmripost_aroma/data/NOTICE
+src/fmripost_template/data/NOTICE

README.rst

@@ -0,0 +1,42 @@
+#################
+fMRIPost-template
+#################
+
+A generic fMRIPost workflow.
+
+********
+Overview
+********
+
+fMRIPost-template is a template repository that can be used to create new fMRIPost workflows.
+
+The workflows and functions in this repository are designed to implement the majority of
+general-purpose steps in an fMRIPost pipeline.
+Here are a few of the key features:
+
+1.  Configuration files to define expected BIDS derivatives from the preprocessing pipeline.
+2.  Functions to collect and organize data from the BIDS derivatives.
+3.  The ability to work with the following preprocessing configurations:
+
+    -   fMRIPrep with ``--level full`` and the required output space for the fMRIPost workflow.
+        For example, fMRIPost-AROMA requires outputs in ``MNI152NLin6Asym`` space with
+        2x2x2 mm voxels.
+    -   fMRIPrep with ``--level full`` and boldref-space outputs,
+        along with transforms to the required output space for the fMRIPost workflow.
+    -   fMRIPrep with ``--level full`` and boldref-space outputs,
+        along with transforms to spaces that can be combined with existing transforms to
+        required spaces.
+        For example, users may apply fMRIPost-AROMA to boldref derivatives with transforms to
+        MNI152NLin2009cAsym space.
+        In this case, the fMRIPost-AROMA workflow will pull a transform from MNI152NLin2009cAsym
+        to MNI152NLin6Asym from TemplateFlow and apply it,
+        along with the boldref-to-MNI152NLin2009cAsym transform, to the boldref-space derivatives.
+
+    .. warning::
+
+        Currently, minimal- and resampling-level fMRIPrep derivatives are not supported,
+        as fMRIPost workflows typically require confounds that are only generated with
+        ``--level full``.
+
+4.  General NiPreps infrastructure for running a BIDS App, such as a config file,
+    a command-line interface, and tools to generate HTML reports.

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_static/theme_overrides.css

@@ -0,0 +1,21 @@
+/* override table width restrictions */
+@media screen and (min-width: 767px) {
+
+   .wy-table-responsive table td {
+      /* !important prevents the common CSS stylesheets from overriding
+         this as on RTD they are loaded after this stylesheet */
+      white-space: normal !important;
+   }
+
+   .wy-table-responsive {
+      overflow: visible !important;
+   }
+}
+
+
+/* Fix parameter type style */
+.function .classifier {
+   margin: 0 0 0 5px;
+   padding: 3px;
+   background: rgba(0, 0, 0, .1);
+}

docs/api.rst

@@ -0,0 +1,39 @@
+.. include:: links.rst
+
+================
+Developers - API
+================
+
+The *NiPreps* community and contributing guidelines
+---------------------------------------------------
+
+*fMRIPost-template* is a *NiPreps* application, and abides by the
+`NiPreps Community guidelines <https://www.nipreps.org/community/>`__.
+Please, make sure you have read and understood all the documentation
+provided in the `NiPreps portal <https://www.nipreps.org>`__ before
+you get started.
+
+Setting up your development environment
+---------------------------------------
+
+We believe that *fMRIPost-template* must be free to use, inspect, and critique.
+Correspondingly, you should be free to modify our software to improve it
+or adapt it to new use cases and we especially welcome contributions to
+improve it or its documentation.
+
+We actively direct efforts into making the scrutiny and improvement processes
+as easy as possible.
+As part of such efforts, we maintain some
+`tips and guidelines for developers <https://www.nipreps.org/devs/devenv/>`__
+to help minimize your burden if you want to modify the software.
+
+Internal configuration system
+-----------------------------
+
+.. automodule:: fmripost_template.config
+   :members: from_dict, load, get, dumps, to_filename, init_spaces
+
+Workflows
+---------
+
+.. automodule:: fmripost_template.workflows.base

docs/changes.rst

@@ -0,0 +1,7 @@
+.. include:: links.rst
+
+----------
+What's new
+----------
+
+.. include:: ../CHANGES.rst