Added nb tutorial to docs

docs/README.md

@@ -7,10 +7,12 @@ controlled by the index.rst file.
 
 In order to compile the documentation locally, you need to install a new conda environment as: 
 
-    conda env create --file sphinx_env.yml
-    conda activate sphinx_rtd
-    make html
+```bash
+conda env create --file sphinx_env.yml
+conda activate sphinx_rtd
+make html
+```
 
 This creates the documentation inside the docs/build/html folder (just double click the index.html file to open it in a browser).
-Alternatively, the "make latex" command compiles a pdf file, which serves as the user-manual. Finally, you can use
-"make clean" to clear previous builds.
+Alternatively, the `make latex` command compiles a pdf file, which serves as the user-manual. Finally, you can use
+`make clean` to clear previous builds.

docs/source/conf.py

@@ -6,9 +6,7 @@
 os.system("sphinx-apidoc -fMT ../../arcjetCV -o api --templatedir=template -e")
 
 project = 'arcjetCV'
-copyright = '2024, arcjetCV Team'
 author = 'arcjetCV Team'
-release = 'v0.0.1'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -19,8 +17,13 @@
     'sphinx.ext.autosummary',
     'sphinx.ext.mathjax',
     'sphinx.ext.viewcode',
+    'nbsphinx',
+    'nbsphinx_link',
 ]
 
+# avoid running the notebook's cells
+nbsphinx_execute = 'never'
+
 myst_enable_extensions = [
     "dollarmath",
     "amsmath",

docs/source/index.md

@@ -12,41 +12,14 @@ placeholders/readme.md
 user_manual/user_manual.md
 ```
 
-## Python API
-
-```python
-# Simple example use of arcjetCV's API for batch processing 
-import arcjetCV as arcv
-import os
-
-path = "/path/to/video/"
-filename = "video"
-filepath = os.path.join(path, filename)
-
-video = arcv.Video(filepath + ".mp4")
-videometa = arcv.VideoMeta(video, filepath + ".meta")
-videometa["FLOW_DIRECTION"] = "right"
-videometa.set_frame_crop(250, 780, 490, 1020)
-
-processor = arcv.ArcjetProcessor(videometa)
-output = processor.process_all(
-    video, 
-    options={"SEGMENT_METHOD": "CNN"}, 
-    first_frame=videometa["FIRST_GOOD_FRAME"], 
-    last_frame=videometa["LAST_GOOD_FRAME"], 
-    frame_stride = 10,
-    write_json = True,
-    write_video = True
-)
-
-# output_data_path = output.path
-# video_output_path = video.output_path
-# videometa_filepath = videometa.path
+```{toctree} 
+:caption: Tutorial
+:maxdepth: 1
+tutorial.nblink
 ```
 
-### Functions and Classes
-
 ```{toctree} 
+:caption: Python API
 :maxdepth: 2
 placeholders/api.md
 ```

docs/source/tutorial.nblink

@@ -0,0 +1,3 @@
+{
+    "path": "../../tutorial.ipynb"
+}

docs/sphinx_env.yml

@@ -7,4 +7,8 @@ dependencies:
   - pip
   - sphinx
   - sphinx_rtd_theme
-  - myst-parser
+  - myst-parser
+  - nbsphinx
+  - nbsphinx-link
+  - pandoc
+  - ipython  # for colors in notebook

tutorial.ipynb

@@ -1,5 +1,12 @@
 {
  "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# arcjetCV Tutorial"
+   ]
+  },
   {
    "cell_type": "code",
    "execution_count": null,
@@ -8,8 +15,8 @@
    "source": [
     "!pip install git+https://github.com/magnus-haw/arcjetCV.git@develop -q\n",
     "!pip install segmentation-models-pytorch -q\n",
-    "!wget https://github.com/magnus-haw/arcjetCV/raw/main/tests/arcjet_test.mp4 -q\n",
-    "!pip install imageio[pyav] -q  # to load m4v"
+    "!pip install imageio[pyav] -q  # to load m4v\n",
+    "!wget https://github.com/magnus-haw/arcjetCV/raw/main/tests/arcjet_test.mp4 -q  # example video"
    ]
   },
   {
@@ -18,6 +25,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# functions to convert and display videos\n",
     "from moviepy.editor import ipython_display as display_video\n",
     "import imageio\n",
     "def convert_and_crop_video(video_path, output_path, fps=30, max_frames=None):\n",
@@ -38,6 +46,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# crop example video and display it\n",
     "convert_and_crop_video(\"arcjet_test.mp4\", \"arcjet_test.mp4\", max_frames=300)\n",
     "display_video(\"arcjet_test.mp4\")"
    ]
@@ -76,6 +85,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# convert annotated video from m4v to mp4 and display it\n",
     "convert_and_crop_video(\"video_out_arcjet_test.m4v\", \"video_out_arcjet_test.mp4\")\n",
     "display_video('video_out_arcjet_test.mp4')"
    ]