Add FAQ page (#388)

* Add FAQ page.

* Update docs.

* Fix docs.

* Add more info to FAQ.

.gitignore

@@ -1,3 +1,4 @@
+docs/generated/
 cubids/_version.py
 *.DS_Store
 

cubids/metadata_merge.py

@@ -304,6 +304,7 @@ def group_by_acquisition_sets(files_tsv, output_prefix, acq_group_level, is_long
     """Find unique sets of Key/Param groups across subjects.
 
     This writes out the following files:
+
     - <output_prefix>_AcqGrouping.tsv: A tsv with the mapping of subject/session to
       acquisition group.
     - <output_prefix>_AcqGrouping.json: A data dictionary for the AcqGrouping.tsv.

docs/api.rst

@@ -25,17 +25,17 @@ API
    :toctree: generated/
    :template: function.rst
 
-   cubids.workflows.validate
-   cubids.workflows.bids_sidecar_merge
-   cubids.workflows.group
-   cubids.workflows.apply
-   cubids.workflows.datalad_save
-   cubids.workflows.undo
-   cubids.workflows.copy_exemplars
-   cubids.workflows.add_nifti_info
-   cubids.workflows.purge
-   cubids.workflows.remove_metadata_fields
-   cubids.workflows.print_metadata_fields
+   workflows.validate
+   workflows.bids_sidecar_merge
+   workflows.group
+   workflows.apply
+   workflows.datalad_save
+   workflows.undo
+   workflows.copy_exemplars
+   workflows.add_nifti_info
+   workflows.purge
+   workflows.remove_metadata_fields
+   workflows.print_metadata_fields
 
 
 **********************************************
@@ -48,11 +48,11 @@ API
    :toctree: generated/
    :template: function.rst
 
-   cubids.metadata_merge.check_merging_operations
-   cubids.metadata_merge.merge_without_overwrite
-   cubids.metadata_merge.merge_json_into_json
-   cubids.metadata_merge.get_acq_dictionary
-   cubids.metadata_merge.group_by_acquisition_sets
+   metadata_merge.check_merging_operations
+   metadata_merge.merge_without_overwrite
+   metadata_merge.merge_json_into_json
+   metadata_merge.get_acq_dictionary
+   metadata_merge.group_by_acquisition_sets
 
 
 ***********************************
@@ -65,8 +65,8 @@ API
    :toctree: generated/
    :template: function.rst
 
-   cubids.validator.build_validator_call
-   cubids.validator.build_subject_paths
-   cubids.validator.run_validator
-   cubids.validator.parse_validator_output
-   cubids.validator.get_val_dictionary
+   validator.build_validator_call
+   validator.build_subject_paths
+   validator.run_validator
+   validator.parse_validator_output
+   validator.get_val_dictionary

docs/conf.py

@@ -73,7 +73,7 @@
 # You can specify multiple suffix as a list of string:
 #
 # source_suffix = ['.rst', '.md']
-source_suffix = ".rst"
+source_suffix = {".rst": "restructuredtext"}
 
 # The master toctree document.
 master_doc = "index"
@@ -171,13 +171,10 @@
 _python_doc_base = "https://docs.python.org/" + _python_version_str
 intersphinx_mapping = {
     "python": (_python_doc_base, None),
-    "numpy": ("https://numpy.org/doc/stable/", (None, "./_intersphinx/numpy-objects.inv")),
-    "scipy": (
-        "https://docs.scipy.org/doc/scipy/reference",
-        (None, "./_intersphinx/scipy-objects.inv"),
-    ),
-    "sklearn": ("https://scikit-learn.org/stable", (None, "./_intersphinx/sklearn-objects.inv")),
-    "matplotlib": ("https://matplotlib.org/", (None, "https://matplotlib.org/objects.inv")),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/reference/", None),
+    "sklearn": ("https://scikit-learn.org/stable", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
     "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
     "pybids": ("https://bids-standard.github.io/pybids/", None),
     "nibabel": ("https://nipy.org/nibabel/", None),

docs/contributing.rst

@@ -0,0 +1 @@
+.. include:: ../CONTRIBUTING.rst

docs/faq.rst

@@ -0,0 +1,29 @@
+==========================
+Frequently Asked Questions
+==========================
+
+
+--------------------------------------
+Does CuBIDS work on all BIDS datasets?
+--------------------------------------
+
+CuBIDS relies on many hardcoded rules and data types,
+so it may not work on all BIDS datasets.
+Some datatypes, such as EEG or iEEG, are not yet supported,
+nor are some configurations of supported datatypes, such as multi-echo fMRI.
+
+If you encounter an issue, please open an issue on the CuBIDS GitHub repository.
+
+
+-----------------------------------------------------
+How do the developers determine what features to add?
+-----------------------------------------------------
+
+CuBIDS is primarily developed to curate large-scale datasets in order to be used by the PennLINC team.
+This means that we will naturally prioritize features that are useful to us.
+However, we are always open to suggestions and contributions from the community,
+and will of course consider features that do not directly benefit us.
+
+If you want to request support for a new modality or niche data feature,
+please open an issue on the CuBIDS GitHub repository.
+We are more likely to add support for a new feature if you can point us toward a dataset that we can use to test it.

docs/index.rst

@@ -13,8 +13,7 @@ Contents
    usage
    cli
    example
-   ../CONTRIBUTING
-   ../AUTHORS
-   ../HISTORY
+   contributing
+   faq
    glossary
    api

docs/usage.rst

@@ -110,7 +110,7 @@ but it keeps track of every file's assignment to Entity and Parameter Groups.
 .. _acqgrouptsv:
 
 Modifying Entity and Parameter Group Assignments
----------------------------------------------
+------------------------------------------------
 
 Sometimes we see that there are important differences in acquisition parameters within a Entity Set.
 If these differences impact how a pipeline will process the data,