reworking testing tasks

.github/workflows/docs.yml

@@ -0,0 +1,66 @@
+# This workflows will upload a Python Package using Twine when a release is created
+# For more information see: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+name: Build docs
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  # release:
+  #   types: [published]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+    - name: Install Pandoc
+      run: |
+        sudo apt-get update
+        sudo apt-get install -Y pandoc
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build twine
+
+    - name: Build docs
+      run: |
+        cd docs
+        make html
+        twine upload dist/*
+    - uses: actions/upload-artifact@v3
+      with:
+        name: built-docs
+        path: docs/build/html
+
+  deploy:
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+    - name: Download built docs
+      uses: actions/download-artifact@v3
+      with:
+        name: built-docs
+        path: docs-build
+    - name: Check for GHPAGES_DEPLOY_KEY token
+      id: deployable
+      if: github.event_name == 'release'
+      env:
+        GHPAGES_DEPLOY_KEY: "${{ secrets.GHPAGES_DEPLOY_KEY }}"
+      run: if [ -n "$GHPAGES_DEPLOY_KEY" ]; then echo "DEPLOY=true" >> $GITHUB_OUTPUT; fi
+    - name: Deploy Docs to GitHub Pages
+      if: steps.deployable.outputs.DEPLOY
+      uses: peaceiris/actions-gh-pages@v3
+      with:
+        github_token: ${{ secrets.GHPAGES_DEPLOY_KEY }}
+        publish_dir: docs-build

docs/source/tutorial/execution.ipynb

@@ -12,21 +12,15 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": 5,
    "metadata": {},
    "outputs": [
-    {
-     "name": "stderr",
-     "output_type": "stream",
-     "text": [
-      "A newer version (0.25) of nipype/pydra is available. You are using 0.25.dev71+g0dc7ec60.d20241216\n"
-     ]
-    },
     {
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "LoadJsonOutputs(out={'a': True, 'b': 'two', 'c': 3, 'd': [7, 0.5598136790149003, 6]})\n"
+      "Sample JSON file created at '0UAqFzWsDK4FrUMp48Y3tT3Q.json' with contents: {\"a\": true, \"b\": \"two\", \"c\": 3, \"d\": [7, 0.5598136790149003, 6]}\n",
+      "Loaded contents: {'a': True, 'b': 'two', 'c': 3, 'd': [7, 0.5598136790149003, 6]}\n"
      ]
     }
    ],
@@ -37,14 +31,17 @@
     "# Create a sample JSON file to test\n",
     "json_file = Json.sample()\n",
     "\n",
-    "# Parameterise the task to load the JSON file\n",
+    "# Print the path of the sample JSON file and its contents for reference\n",
+    "print(f\"Sample JSON file created at {json_file.name!r} with contents: {json_file.read_text()}\")\n",
+    "\n",
+    "# Parameterise the task specification to load the JSON file\n",
     "load_json = LoadJson(file=json_file)\n",
     "\n",
-    "# Run the task\n",
+    "# Run the task to load the JSON file\n",
     "result = load_json()\n",
     "\n",
     "# Print the output interface of the of the task (LoadJson.Outputs)\n",
-    "print(result.output)"
+    "print(f\"Loaded contents: {result.output.out}\")"
    ]
   },
   {

pydra/design/python.py

@@ -115,6 +115,11 @@ def define(
         The outputs of the function or class.
     auto_attribs : bool
         Whether to use auto_attribs mode when creating the class.
+
+    Returns
+    -------
+    PythonSpec
+        The task specification class for the Python function
     """
     from pydra.engine.task import PythonTask
     from pydra.engine.specs import PythonSpec, PythonOutputs