feat: use notebook for testing examples

docs/examples/1-single-function.ipynb

@@ -0,0 +1,169 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "source": [
+    "# Single function\n",
+    "\n",
+    "in a file named `single_function.py`\n",
+    "\n",
+    "```python\n",
+    "--8<-- \"single_function.py\"\n",
+    "```\n"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "usage: pytest [-h] [-k KW1] [-w] param1 param2\r\n",
+      "\r\n",
+      "Example function with types documented in the docstring.\r\n",
+      "\r\n",
+      "positional arguments:\r\n",
+      "  param1             The first parameter.\r\n",
+      "  param2             The second parameter.\r\n",
+      "\r\n",
+      "optional arguments:\r\n",
+      "  -h, --help         show this help message and exit\r\n",
+      "  -k KW1, --kw1 KW1\r\n",
+      "  -w, --kw2\r\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Run help\n",
+    "!python single_function.py -h"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "kw1 (<class 'NoneType'>): None\r\n",
+      "kw2 (<class 'bool'>): False\r\n",
+      "param1 (<class 'int'>): 10\r\n",
+      "param2 (<class 'str'>): p2\r\n"
+     ]
+    }
+   ],
+   "source": [
+    "# ran with both positional arguments\n",
+    "!python single_function.py 10 p2"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "usage: pytest [-h] [-k KW1] [-w] param1 param2\r\n",
+      "pytest: error: the following arguments are required: param1, param2\r\n"
+     ]
+    }
+   ],
+   "source": [
+    "#  ran empty\n",
+    "!python single_function.py"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "usage: pytest [-h] [-k KW1] [-w] param1 param2\r\n",
+      "pytest: error: the following arguments are required: param1, param2\r\n"
+     ]
+    }
+   ],
+   "source": [
+    "# ran with invalid option\n",
+    "!python single_function.py --invalid"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "usage: pytest [-h] [-k KW1] [-w] param1 param2\r\n",
+      "pytest: error: argument param1: invalid int value: 'p1'\r\n"
+     ]
+    }
+   ],
+   "source": [
+    "# ran with invalid type\n",
+    "!python single_function.py p1 p2"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   }
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "name": "python3",
+   "language": "python",
+   "display_name": "Python 3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}