Revert make; exclude workflow notebook from execution

Signed-off-by: Shah, Karan <[email protected]>

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?= -D autodoc_default_options.imported-members=True -D nb_execution_mode=force
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/conf.py

@@ -113,6 +113,10 @@
 nb_merge_streams = True
 nb_execution_show_tb = True
 nb_execution_timeout = 600  # secs
+nb_execution_excludepatterns = [
+    # TODO(MasterSkepticista) this requires fx experimental enabled, conflicts with taskrunner CLI
+    "tutorials/workflow.ipynb",
+]
 
 # Tell sphinx autodoc how to render type aliases.
 autodoc_typehints = "description"

docs/tutorials/taskrunner.ipynb

@@ -22,25 +22,33 @@
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
+   "cell_type": "markdown",
    "metadata": {},
-   "outputs": [],
    "source": [
-    "!fx workspace create --prefix ./mnist_example --template keras_cnn_mnist"
+    "### Create a workspace\n",
+    "\n",
+    "For brevity, we will reuse an existing workspace."
    ]
   },
   {
    "cell_type": "code",
    "execution_count": null,
-   "metadata": {
-    "vscode": {
-     "languageId": "shellscript"
-    }
-   },
+   "metadata": {},
    "outputs": [],
    "source": [
-    "%cd ./mnist_example"
+    "!mkdir -p /tmp/mnist_example\n",
+    "!fx workspace create --prefix /tmp/mnist_example --template keras_cnn_mnist\n",
+    "%cd /tmp/mnist_example"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Initialize a Plan\n",
+    "\n",
+    "This step builds an entire FL experiment plan, along with the initial set of parameters that will be used in the experiment.\n",
+    "We supply `localhost` as the aggregator address, for simulation purposes."
    ]
   },
   {
@@ -56,6 +64,15 @@
     "!fx plan initialize -a localhost"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Create a certificate authority (CA)\n",
+    "\n",
+    "OpenFL supports mTLS, which ensures secure communication between the collaborators and the aggregator. This step generates a certificate authority (CA) that will be used to sign the certificates of the collaborators. The CA is generated only once and can be reused for multiple experiments."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -69,6 +86,13 @@
     "!fx workspace certify"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Create an aggregator, and its key-pair"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -83,6 +107,15 @@
     "!fx aggregator certify --fqdn localhost --silent"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Create collaborators, and their key-pairs\n",
+    "\n",
+    "We will name our collaborators `bob` and `charlie`."
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -94,20 +127,19 @@
    "outputs": [],
    "source": [
     "!fx collaborator create -d 0 -n bob --silent\n",
-    "!fx collaborator generate-cert-request -n bob --silent"
+    "!fx collaborator create -d 1 -n charlie --silent\n",
+    "\n",
+    "!fx collaborator generate-cert-request -n bob --silent\n",
+    "!fx collaborator generate-cert-request -n charlie --silent"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "vscode": {
-     "languageId": "shellscript"
-    }
-   },
-   "outputs": [],
+   "cell_type": "markdown",
+   "metadata": {},
    "source": [
-    "!ls -l"
+    "### Certify the collaborator with the CA.\n",
+    "\n",
+    "> Note: This is a command that runs on the `aggregator` side. The collaborator's certificate signing request (CSR) is sent to the aggregator, which then signs the certificate with the CA. The signed certificate then has to be sent back to the collaborator."
    ]
   },
   {
@@ -120,20 +152,17 @@
    },
    "outputs": [],
    "source": [
-    "!fx collaborator certify --request-pkg col_bob_to_agg_cert_request.zip --silent"
+    "!fx collaborator certify --request-pkg col_bob_to_agg_cert_request.zip --silent\n",
+    "!fx collaborator certify --request-pkg col_charlie_to_agg_cert_request.zip --silent"
    ]
   },
   {
-   "cell_type": "code",
-   "execution_count": null,
-   "metadata": {
-    "vscode": {
-     "languageId": "shellscript"
-    }
-   },
-   "outputs": [],
+   "cell_type": "markdown",
+   "metadata": {},
    "source": [
-    "!fx collaborator certify --import agg_to_col_bob_signed_cert.zip"
+    "### Import CA signed certificates\n",
+    "\n",
+    "This step imports the signed certificates of the collaborator and the aggregator into the workspace."
    ]
   },
   {
@@ -146,7 +175,17 @@
    },
    "outputs": [],
    "source": [
-    "!fx aggregator start & fx collaborator start -n bob"
+    "!fx collaborator certify --import agg_to_col_bob_signed_cert.zip\n",
+    "!fx collaborator certify --import agg_to_col_charlie_signed_cert.zip"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Start the simulation\n",
+    "\n",
+    "This step starts the simulation of the FL experiment. The aggregator will orchestrate the training process between the collaborators."
    ]
   },
   {
@@ -158,7 +197,9 @@
     }
    },
    "outputs": [],
-   "source": []
+   "source": [
+    "!fx aggregator start & fx collaborator start -n bob & fx collaborator start -n charlie"
+   ]
   }
  ],
  "metadata": {