restructuring new docs

nipype · Dec 28, 2024 · 6f1c8e3 · 6f1c8e3
1 parent 8e88ed2
commit 6f1c8e3
Show file tree

Hide file tree

Showing 11 changed files with 100 additions and 45 deletions.
diff --git a/new-docs/source/howto/real-example.ipynb → new-docs/source/examples/real-example.ipynb b/new-docs/source/howto/real-example.ipynb → new-docs/source/examples/real-example.ipynb
diff --git a/new-docs/source/explanation/conditional-lazy.rst b/new-docs/source/explanation/conditional-lazy.rst
@@ -1,4 +1,4 @@
-Conditional construction
-========================
+Conditionals and lazy fields
+============================
 
 Work in progress...
diff --git a/new-docs/source/explanation/hashing-caching.rst b/new-docs/source/explanation/hashing-caching.rst
@@ -1,4 +1,4 @@
-Caching
-=======
+Caching and hashing
+===================
 
 Work in progress....
diff --git a/new-docs/source/howto/create-task-package.ipynb b/new-docs/source/howto/create-task-package.ipynb
@@ -4,7 +4,7 @@
             "cell_type": "markdown",
             "metadata": {},
             "source": [
-                "# Creating a task package"
+                "# Create a task package"
             ]
         },
         {

diff --git a/new-docs/source/index.rst b/new-docs/source/index.rst
@@ -27,35 +27,67 @@ those commands installed on the execution machine, or use software containers
 (e.g., Docker or Singularity) to run them.
 
 
+Tutorials
+---------
+
+* :ref:`Getting started`
+* :ref:`Execution options`
+* :ref:`Python-tasks`
+* :ref:`Shell-tasks`
+* :ref:`Workflows`
+
+Examples
+--------
+
+* :ref:`Real-world example`
+
+How-to Guides
+-------------
+
+* :ref:`Create a task package`
+* :ref:`Port interfaces from Nipype`
+
 Indices and tables
 ------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
 
+.. toctree::
+    :maxdepth: 2
+    :hidden:
+
+    tutorial/getting-started
+    tutorial/advanced-execution
 
 .. toctree::
     :maxdepth: 2
-    :caption: Tutorials
+    :caption: Design
     :hidden:
 
-    tutorial/execution
     tutorial/python
     tutorial/shell
     tutorial/workflow
 
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Examples
+   :hidden:
+
+   examples/real-example
+
 .. toctree::
    :maxdepth: 2
-   :caption: How-to Guides
+   :caption: How-to
    :hidden:
 
-   howto/real-example
    howto/create-task-package
    howto/port-from-nipype
 
 .. toctree::
    :maxdepth: 2
-   :caption: Explanation
+   :caption: In-depth
    :hidden:
 
    explanation/design-approach

diff --git a/new-docs/source/tutorial/advanced-execution.ipynb b/new-docs/source/tutorial/advanced-execution.ipynb
@@ -0,0 +1,44 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Execution options"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Execution plugins"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Cache locations"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Environments"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": []
+  }
+ ],
+ "metadata": {
+  "language_info": {
+   "name": "python"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/new-docs/source/tutorial/execution.ipynb → ...ocs/source/tutorial/getting-started.ipynb b/new-docs/source/tutorial/execution.ipynb → ...ocs/source/tutorial/getting-started.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Running tasks\n",
+    "# Getting started\n",
     "\n",
     "A *Task* is the basic runnable component in Pydra, and can execute either a Python function,\n",
     "shell command or workflows consisting of combinations of all three types."

diff --git a/new-docs/source/tutorial/python.ipynb b/new-docs/source/tutorial/python.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Python-task design"
+    "# Python-tasks"
    ]
   },
   {

diff --git a/new-docs/source/tutorial/shell.ipynb b/new-docs/source/tutorial/shell.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Shell-task design"
+    "# Shell-tasks"
    ]
   },
   {

diff --git a/new-docs/source/tutorial/tst.py b/new-docs/source/tutorial/tst.py
diff --git a/new-docs/source/tutorial/workflow.ipynb b/new-docs/source/tutorial/workflow.ipynb
@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Workflow design\n",
+    "# Workflows\n",
     "\n",
     "In Pydra, workflows are DAG of component tasks to be executed on specified inputs.\n",
     "Workflow specifications are dataclasses, which interchangeable with Python and shell tasks\n",
@@ -208,7 +208,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "\n",
     "from pydra.engine.specs import WorkflowSpec, WorkflowOutputs\n",
     "\n",
     "def a_converter(value):\n",
@@ -376,14 +375,14 @@
    "metadata": {},
    "source": [
     "For more detailed discussion of the construction of conditional workflows and \"lazy field\"\n",
-    "placeholders see [Conditional construction](../explanation/conditional-lazy.html)"
+    "placeholders see [Conditionals and lazy fields](../explanation/conditional-lazy.html)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Typing\n",
+    "## Type-checking between nodes\n",
     "\n",
     "Pydra utilizes Python type annotations to implement strong type-checking, which is performed\n",
     "when values or upstream outputs are assigned to task specification inputs.\n",
@@ -430,7 +429,7 @@
     "            \"ffmpeg -i <in_video> -i <watermark:image/png> \"\n",
     "            \"-filter_complex <filter> <out|out_video:video/mp4>\"\n",
     "        )(\n",
-    "            in_video=input_video,\n",
+    "            in_video=input_video,  # This is OK because in_video is typed Any\n",
     "            watermark=watermark,  # Type is OK because generic.File is superclass of image.Png\n",
     "            filter=\"overlay={}:{}\".format(*watermark_dims),\n",
     "        ),\n",
@@ -449,6 +448,13 @@
     "    return handbrake.output_video"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "For more detailed discussion on Pydra's type-checking see [Type Checking](../explanation/typing.html)."
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},