more restructuring of new docs

Author: tclose

new-docs/source/examples/real-example.ipynb renamed to new-docs/source/examples/t1w-preprocess.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Real-world example"
+    "# T1w MRI preprocessing"
    ]
   },
   {

new-docs/source/explanation/environments.rst

@@ -0,0 +1,4 @@
+Containers and environments
+===========================
+
+Work in progress...

new-docs/source/explanation/provenance.rst

@@ -9,37 +9,46 @@ implement scientific workflows that use a mix of shell commands and Python funct
 Pydra is developed as an open-source project in the neuroimaging community,
 but it is designed as a general-purpose dataflow engine to support any scientific domain.
 
-See the :ref:`Design philosophy` for more an explanation of the design
-philosophy and goals of Pydra.
+See :ref:`Design philosophy` for more an explanation of the design of Pydra.
 
 Installation
 ------------
 
 Pydra itself is a pure-Python package, which has only a handful of dependencies,
-therefore, it is straightforward to install via pip
+therefore, it is straightforward to install via pip for Python >= 3.11
 
 .. code-block:: bash
 
     $ pip install pydra
 
-Of course, if you use Pydra to execute shell-commands tools, you will need to either have
-those commands installed on the execution machine, or use software containers
-(e.g., Docker or Singularity) to run them.
+Pre-designed tasks are available under the `pydra.tasks.*` package namespace. These tasks
+are implemented within separate packages that are typically specific to a given shell-command toolkit such as FSL_, AFNI_ or ANTs_,
+or a collection of related tasks/workflows (e.g. `niworkflows`_). Pip can be used to
+install these packages as well:
+
+
+.. code-block:: bash
+
+    $ pip install pydra-fsl pydra-ants
+
+Of course, if you use Pydra to execute commands within toolkits, you will need to
+either have those commands installed on the execution machine, or use containers
+environments (see [Environments](../explanation/environments.html)) to run them.
 
 
 Tutorials
 ---------
 
 * :ref:`Getting started`
-* :ref:`Execution options`
+* :ref:`Advanced execution`
 * :ref:`Python-tasks`
 * :ref:`Shell-tasks`
 * :ref:`Workflows`
 
 Examples
 --------
 
-* :ref:`Real-world example`
+* :ref:`T1w MRI preprocessing`
 
 How-to Guides
 -------------
@@ -55,6 +64,7 @@ Indices and tables
 
 .. toctree::
     :maxdepth: 2
+    :caption: Execution
     :hidden:
 
     tutorial/getting-started
@@ -75,7 +85,7 @@ Indices and tables
    :caption: Examples
    :hidden:
 
-   examples/real-example
+   examples/t1w-preprocess
 
 .. toctree::
    :maxdepth: 2
@@ -92,10 +102,10 @@ Indices and tables
 
    explanation/design-approach
    explanation/splitting-combining
+   explanation/conditional-lazy
    explanation/typing
    explanation/hashing-caching
-   explanation/conditional-lazy
-   explanation/provenance
+   explanation/environments
 
 
 .. toctree::
@@ -104,3 +114,8 @@ Indices and tables
    :hidden:
 
    reference/api
+
+.. _FSL: https://fsl.fmrib.ox.ac.uk/fsl/fslwiki/FSL
+.. _ANTs: http://stnava.github.io/ANTs/
+.. _AFNI: https://afni.nimh.nih.gov/
+.. _niworkflows: https://niworkflows.readthedocs.io/en/latest/

new-docs/source/index.rst

@@ -4,28 +4,39 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Execution options"
+    "# Advanced execution"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Execution plugins"
+    "## Plugins"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Cache locations"
+    "## Caching results\n",
+    "\n",
+    "See [Caching and hashing](../explanation/hashing-caching.html) for more details."
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Environments"
+    "## Environments (containers)\n",
+    "\n",
+    "See [Containers and Environments](../explanation/environments.rst) for more details."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Provenance"
    ]
   },
   {