Tutorial notebook template in RTD

docs/TutorialNotebookExample.ipynb

@@ -0,0 +1,113 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "ff639336-c092-4882-b08e-78f8b82f741e",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "## Tutorial Notebook Example\n",
+    "\n",
+    "last updated: 2023-07-23\n",
+    "\n",
+    "This is a test notebook to show how we can include examples and tutorials as non-executed jupyter notebooks that get built during our documentation building on readthedocs. This way, we can still include code and code output to show the capabilities of TorchSig.\n",
+    "\n",
+    "This is just a template for how to do this and should be replaced :)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "d2d7597b-7f82-4493-b3b1-d4ef7b9c24b8",
+   "metadata": {},
+   "source": [
+    "### Generate Complex Sinusoid Example Data\n",
+    "\n",
+    "TODO: Explain steps in tutorial in more detail"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "7888b4a8-0b66-4d29-bf40-6bce2b83a288",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import matplotlib.pyplot as plt\n",
+    "import numpy as np\n",
+    "\n",
+    "num_samples = 4096\n",
+    "x = np.exp(2j * np.pi * 2.0 / num_samples * np.arange(num_samples))\n",
+    "\n",
+    "plt.figure()\n",
+    "plt.plot(x.real, c='b')\n",
+    "plt.plot(x.imag, c='r')\n",
+    "plt.title('Test plot')\n",
+    "plt.xlabel('samples')\n",
+    "plt.ylabel('amplitude')\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "2e3151e0-813b-4c07-bc86-72c72f92f6ee",
+   "metadata": {},
+   "source": [
+    "### Apply TorchSig Transform\n",
+    "\n",
+    "TODO: Explain steps in tutorial in more detail"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "462b7078-f064-4a2b-ba18-8c8b320e35ef",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from torchsig.transforms import AddNoise\n",
+    "\n",
+    "t = AddNoise(noise_power_db=-20)\n",
+    "\n",
+    "y = t(x)\n",
+    "\n",
+    "plt.figure()\n",
+    "plt.plot(y.real, c='b')\n",
+    "plt.plot(y.imag, c='r')\n",
+    "plt.title('Test plot')\n",
+    "plt.xlabel('samples')\n",
+    "plt.ylabel('amplitude')\n",
+    "plt.show()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "b2166e37-6a60-4088-9c60-d2bb62d7834b",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.13"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/conf.py

@@ -35,7 +35,8 @@
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.mathjax',
-    'sphinx.ext.viewcode'
+    'sphinx.ext.viewcode',
+    'nbsphinx',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -52,16 +53,16 @@
 
 # General information about the project.
 project = u'torchsig'
-copyright = u'2022, torchsig contributors'
+copyright = u'2020-2023, torchsig contributors'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
 # built documents.
 #
 # The short X.Y version.
-version = '0.1'
+version = '0.4'
 # The full version, including alpha/beta/rc tags.
-release = '0.1.0'
+release = '0.4.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -75,7 +76,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['_build', '**.ipynb_checkpoints']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 # default_role = None
@@ -273,3 +274,31 @@
     'numpy': ('https://docs.scipy.org/doc/numpy/', None),
     'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None)
 }
+
+
+# -- Pandoc for Jupyter NB integration ----------------------------------------
+
+from inspect import getsourcefile
+
+# Get path to directory containing this file, conf.py.
+DOCS_DIRECTORY = os.path.dirname(os.path.abspath(getsourcefile(lambda: 0)))
+
+def ensure_pandoc_installed(_):
+    import pypandoc
+
+    # Download pandoc if necessary. If pandoc is already installed and on
+    # the PATH, the installed version will be used. Otherwise, we will
+    # download a copy of pandoc into docs/bin/ and add that to our PATH.
+    pandoc_dir = os.path.join(DOCS_DIRECTORY, "bin")
+    # Add dir containing pandoc binary to the PATH environment variable
+    if pandoc_dir not in os.environ["PATH"].split(os.pathsep):
+        os.environ["PATH"] += os.pathsep + pandoc_dir
+    pypandoc.ensure_pandoc_installed(
+        # quiet=True,
+        targetfolder=pandoc_dir,
+        delete_installer=True,
+    )
+
+
+def setup(app):
+    app.connect("builder-inited", ensure_pandoc_installed)

docs/docs-requirements.txt

@@ -3,4 +3,7 @@ numba
 recommonmark>=0.7.1
 six
 sphinx-rtd-theme>=0.4.3
-Sphinx>=3.4.3
+Sphinx>=3.4.3
+nbsphinx
+ipykernel
+pypandoc

docs/index.rst

@@ -18,6 +18,7 @@ TorchSig
     transforms
     models
     utils
+    TutorialNotebookExample
 
 .. automodule:: torchsig
     :members:

pyproject.toml

@@ -38,7 +38,9 @@ dependencies = [
     "sympy",
     "numba",
     "torchmetrics",
-    "click"
+    "click",
+    "nbsphinx",
+    "pypandoc"
 ]
 dynamic = ["version"]