🚧 📝 Document 1.7 → 1.8 pipeline config key mappings

Author: shnizzedy

.circleci/config.yml

@@ -24,6 +24,11 @@ commands:
             source ~/simple/bin/activate
             pip install cpac
             deactivate
+  link-references:
+    steps:
+      - run:
+          name: 🖇️ Linking references
+          command: ln $(python -c "import os, CPAC; print(os.path.abspath(os.path.dirname(CPAC.__file__)))")/resources/configs/1.7-1.8-nesting-mappings.yml docs/_sources/references/1.7-1.8-nesting-mappings.yml
   run-cpac-commands:
     steps:
       - setup_remote_docker

docs/_sources/user/1.7-1.8-nesting-mappings.rst

@@ -0,0 +1,26 @@
+.. title:: C-PAC 1.7 → 1.8 pipeline configuration mappings
+
+The following YAML is formatted such that the keys are the pipeline configuration keys in C-PAC ≤ 1.7 and the values are a list of successively deeper keys in a C-PAC 1.8 pipeline configuration. For example,
+    .. code-block:: YAML
+
+       pipelineName:
+         - pipeline_setup
+         - pipeline_name
+    
+    indicates the change, from 1.7
+
+    .. code-block:: YAML
+
+       pipelineName: pipline-name_value
+    
+    to 1.8
+
+    .. code-block:: YAML
+
+       pipeline_setup:
+          pipeline_name: pipeline-name_value
+
+The full list of mappings is as follows:
+
+.. literalinclude:: /references/1.7-1.8-nesting-mappings.yml
+   :language: YAML

docs/_sources/user/design_a_pipeline.rst

@@ -1,6 +1,22 @@
 Design A Pipeline
 -----------------
 
+.. warning::
+
+    The C-PAC pipeline configuration was changed to a nested format with import capabilities in v1.8.0.
+    
+    With this change, the following configuration keys are deprecated:
+
+    * ``TR``
+    * ``fdCalc``
+    * ``reGenerateOutputs``
+    * ``runMedianAngleCorrection``
+    * ``slice_timing_pattern``
+    * ``targetAngleDeg``
+    * ``runSymbolicLinks``
+
+    Mappings for all other C-PAC 1.7 keys can be found :doc:`here </user/1.7-1.8-nesting-mappings>`.
+
 C-PAC offers a graphical interface you can use to quickly and easily modify the default pipeline or create your own from scratch:
 
 `https://fcp-indi.github.io/C-PAC_GUI/versions/latest/browser/#/ <https://fcp-indi.github.io/C-PAC_GUI/versions/latest/browser/#/>`_