Feature/sg 1147 notebooks in repo (#1493)

* Add CI config to run notebooks conversion

* Add CI config to run notebooks conversion

* Specify ipykernel

* Specify ipykernel

* Specify ipykernel

* Remove crashing notebook

* Added additional step to verify that all converted notebooks has a correct SG version installed and bumped up SG version in master to reflect that we already have 3.2.1

.circleci/config.yml

@@ -23,6 +23,10 @@ parameters:
     type: boolean
     description: If true will run sanity_test flow
     default: false
+  run_and_convert_notebooks_to_docs:
+    type: boolean
+    description: If true will run run_and_convert_notebooks_to_docs flow
+    default: false
   skip_md_files:
     type: boolean
     default: true
@@ -561,6 +565,50 @@ jobs:
           event: fail
           template: basic_fail_1 # see https://github.com/CircleCI-Public/slack-orb/wiki#templates.
 
+  run_and_convert_notebooks_to_docs:
+    docker:
+      - image: 307629990626.dkr.ecr.us-east-1.amazonaws.com/deci/infra/circleci/runner/sg-gpu:<< pipeline.parameters.sg_docker_version >>
+    resource_class: deci-ai/sg-gpu-on-premise
+    parameters:
+      sg_existing_env_path:
+        type: string
+        default: "/env/persistent_env"
+      sg_new_env_name:
+        type: string
+        default: "${CIRCLE_BUILD_NUM}"
+      sg_new_env_python_version:
+        type: string
+        default: "python3.8"
+    steps:
+      - checkout
+      - run:
+          name: install requirements and execute notebooks
+          command: |
+            << parameters.sg_new_env_python_version >> -m venv << parameters.sg_new_env_name >>
+            source << parameters.sg_new_env_name >>/bin/activate
+            python3.8 -m pip install --upgrade setuptools pip wheel
+            python3.8 -m pip install -r requirements.txt
+            python3.8 -m pip install -r requirements.dev.txt
+            python3.8 -m pip install .
+            python3.8 -m pip install torch torchvision torchaudio
+            python3.8 -m pip install pytorch-quantization==2.1.2 --extra-index-url https://pypi.ngc.nvidia.com
+            python3.8 -m pip install onnx_graphsurgeon==0.3.27   --extra-index-url https://pypi.ngc.nvidia.com
+            python3.8 -m ipykernel install --name << parameters.sg_new_env_name >> --user
+            make check_notebooks_version_match
+            make run_and_convert_notebooks_to_docs
+
+      - run:
+          name: Remove new environment when failed
+          command: "rm -r << parameters.sg_new_env_name >>"
+          when: on_fail
+
+      - slack/notify:
+          channel: "sg-integration-tests"
+          event: fail
+          template: basic_fail_1 # see https://github.com/CircleCI-Public/slack-orb/wiki#templates.
+
+
+
   recipe_sanity_tests_classification_pt1:
     docker:
       - image: 307629990626.dkr.ecr.us-east-1.amazonaws.com/deci/infra/circleci/runner/sg-gpu:<< pipeline.parameters.sg_docker_version >>
@@ -846,6 +894,16 @@ workflows:
       - recipe_accuracy_tests:
           context:
             - slack
+      - run_and_convert_notebooks_to_docs:
+          context:
+            - slack
+
+  run_and_convert_notebooks_to_docs:
+    when:  << pipeline.parameters.run_and_convert_notebooks_to_docs >>
+    jobs:
+      - run_and_convert_notebooks_to_docs:
+          context:
+            - slack
 
   release:
     unless:
@@ -896,6 +954,10 @@ workflows:
           context:
             - slack
           <<: *release_tag_filter
+      - run_and_convert_notebooks_to_docs:
+          context:
+            - slack
+          <<: *release_tag_filter
       - release_version:
           py_version: "3.8"
           requires:
@@ -907,6 +969,7 @@ workflows:
             - recipe_sanity_tests_segmentation
             - recipe_sanity_tests_detection
             - recipe_sanity_tests_pose_estimation
+            - run_and_convert_notebooks_to_docs
           <<: *release_tag_filter
       - deci-common/pip_upload_package_from_codeartifact_to_global_pypi:
           package_name: "super-gradients"

Makefile

@@ -30,6 +30,14 @@ sweeper_test:
 	  exit 1; \
 	fi
 
+# Here you define a list of notebooks we want to execute and convert to markdown files
+# NOTEBOOKS = hellomake.ipynb hellofunc.ipynb helloclass.ipynb
+NOTEBOOKS = src/super_gradients/examples/model_export/models_export.ipynb
 
-examples_to_docs:
-	jupyter nbconvert --to markdown --output-dir="documentation/source/" --execute src/super_gradients/examples/model_export/models_export.ipynb
+# This Makefile target runs notebooks listed below and converts them to markdown files in documentation/source/
+run_and_convert_notebooks_to_docs: $(NOTEBOOKS)
+	jupyter nbconvert --to markdown --output-dir="documentation/source/" --execute $@
+
+# This Makefile target runs notebooks listed below and converts them to markdown files in documentation/source/
+check_notebooks_version_match: $(NOTEBOOKS)
+	python tests/verify_notebook_version.py $@

requirements.dev.txt

@@ -2,3 +2,5 @@ flake8==5.0.4
 black==22.10.0
 pre-commit==2.20.0
 gitpython>=3.1.0
+ipykernel==6.25
+nbconvert==7.8.0

src/super_gradients/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "3.2.0"
+__version__ = "3.2.1"
 
 from super_gradients.common import init_trainer, is_distributed, object_names
 from super_gradients.training import losses, utils, datasets_utils, DataAugmentation, Trainer, KDTrainer, QATTrainer

src/super_gradients/examples/model_export/models_export.ipynb

@@ -44,6 +44,17 @@
     "collapsed": false
    }
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "outputs": [],
+   "source": [
+    "!pip install super_gradients==3.2.1"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
   {
    "cell_type": "markdown",
    "source": [

tests/verify_notebook_version.py

@@ -0,0 +1,54 @@
+import re
+import sys
+import super_gradients
+import nbformat
+
+
+def get_first_cell_content(notebook_path):
+    # Load the notebook
+    with open(notebook_path, "r", encoding="utf-8") as notebook_file:
+        notebook_content = nbformat.read(notebook_file, as_version=4)
+
+    # Get the content of the first cell (assuming it's a code cell)
+    code_cells = [cell for cell in notebook_content.cells if cell.cell_type == "code"]
+    first_cell_content = ""
+    if code_cells:
+        first_cell = code_cells[0]
+        first_cell_content = first_cell.source
+
+    return first_cell_content
+
+
+def main():
+    """
+    This script is used to verify that the version of the SG package matches the version of SG installed in the notebook.
+    The script assumes that the first cell of the notebook contains a `!pip install super_gradients=={version}` command.
+    :return: An exit code of 0 if the versions match, 1 otherwise.
+    """
+    notebook_path = sys.argv[1]
+    first_cell_content = get_first_cell_content(notebook_path)
+    print(first_cell_content)
+
+    # Check if the first cell contains "!pip install super_gradients=={version}" using regex and extract the version
+    pattern = re.compile(r"^!pip install super_gradients==([\d\.]+)")
+
+    for line in first_cell_content.splitlines():
+        match = re.search(pattern, line)
+        if match:
+            sg_version_in_notebook = match.group(1)
+            if sg_version_in_notebook == super_gradients.__version__:
+                return 0
+            else:
+                print(
+                    f"Version mismatch detected:\n"
+                    f"super_gradients.__version__ is {super_gradients.__version__}\n"
+                    f"Notebook uses super_gradients  {sg_version_in_notebook} (notebook_path)"
+                )
+                return 1
+
+    print("First code cell of the notebook does not contain a `!pip install super_gradients=={version} command`")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())