Better usage instructions (#30)

docs/_toc.yml

@@ -6,4 +6,6 @@ root: intro
 chapters:
 - file: installation
 - file: usage
-# - file: markdown-notebooks
+- file: contributing
+- file: releasing
+

docs/contributing.md

@@ -0,0 +1,2 @@
+```{include} ../contributing.md
+```

docs/releasing.md

@@ -0,0 +1,2 @@
+```{include} ../releasing.md
+```

docs/usage.ipynb

@@ -53,28 +53,140 @@
     "\n",
     "from dj_notebook import activate\n",
     "\n",
+    "# Find this in tests/django_test_project/manage.py\n",
+    "# https://github.com/pydanny/dj-notebook/blob/main/tests/django_test_project/manage.py\n",
     "plus = activate(\"book_store.settings\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now you can use the ORM:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "<QuerySet [<User: Audrey>, <User: Daniel>]>"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "from django.contrib.auth import get_user_model\n",
+    "User = get_user_model()\n",
+    "\n",
+    "# Clean up the users\n",
+    "User.objects.all().delete()\n",
+    "\n",
+    "# Create some users\n",
+    "User.objects.create_user(\"Audrey\")\n",
+    "User.objects.create_user(\"Daniel\")\n",
+    "\n",
+    "# Query the users\n",
+    "User.objects.all()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Usage Plus\n",
+    "\n",
+    "But wait, it gets better!\n",
+    "\n",
+    "When you activated the Django environment, you instantiated a variable called 'plus'. The 'plus' variable is an object that contains everything loaded from django-extensions' shell_plus. Here's a demonstration, let try running this snippet:"
+   ]
+  },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": 10,
    "metadata": {},
    "outputs": [
     {
      "data": {
       "text/plain": [
-       "<QuerySet [<User: admin>, <User: user>]>"
+       "<QuerySet [<User: Audrey>, <User: Daniel>]>"
       ]
      },
-     "execution_count": 3,
+     "execution_count": 10,
      "metadata": {},
      "output_type": "execute_result"
     }
    ],
    "source": [
+    "\n",
     "plus.User.objects.all()"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Or this:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "admin | log entry | Can add log entry\n",
+      "admin | log entry | Can change log entry\n",
+      "admin | log entry | Can delete log entry\n",
+      "admin | log entry | Can view log entry\n",
+      "auth | group | Can add group\n"
+     ]
+    }
+   ],
+   "source": [
+    "for perm in plus.Permission.objects.all()[:5]:\n",
+    "    print(perm)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We're not done yet! \n",
+    "\n",
+    "We also provide a utility for introspection of classes, which can be useful in sophisticated project architectures. Let's see what happens when we use the `plus.diagram()` function:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/html": [
+       "<img src=\"https://mermaid.ink/img/Y2xhc3NEaWFncmFtCiAgY2xhc3MgZGphbmdvX2NvbnRyaWJfYXV0aF9tb2RlbHNfVXNlclsiZGphbmdvLmNvbnRyaWIuYXV0aC5tb2RlbHM6OlVzZXIiXQogIGRqYW5nb19kYl9tb2RlbHNfYmFzZV9Nb2RlbCA8fC0tIGRqYW5nb19jb250cmliX2F1dGhfYmFzZV91c2VyX0Fic3RyYWN0QmFzZVVzZXIKICBjbGFzcyBkamFuZ29fY29udHJpYl9hdXRoX21vZGVsc19QZXJtaXNzaW9uc01peGluWyJkamFuZ28uY29udHJpYi5hdXRoLm1vZGVsczo6UGVybWlzc2lvbnNNaXhpbiJdCiAgZGphbmdvX2NvbnRyaWJfYXV0aF9iYXNlX3VzZXJfQWJzdHJhY3RCYXNlVXNlciA8fC0tIGRqYW5nb19jb250cmliX2F1dGhfbW9kZWxzX0Fic3RyYWN0VXNlcgogIGRqYW5nb19kYl9tb2RlbHNfdXRpbHNfQWx0ZXJzRGF0YSA8fC0tIGRqYW5nb19kYl9tb2RlbHNfYmFzZV9Nb2RlbAogIGRqYW5nb19jb250cmliX2F1dGhfbW9kZWxzX0Fic3RyYWN0VXNlciA8fC0tIGRqYW5nb19jb250cmliX2F1dGhfbW9kZWxzX1VzZXIKICBjbGFzcyBkamFuZ29fZGJfbW9kZWxzX3V0aWxzX0FsdGVyc0RhdGFbImRqYW5nby5kYi5tb2RlbHMudXRpbHM6OkFsdGVyc0RhdGEiXQogIGRqYW5nb19kYl9tb2RlbHNfYmFzZV9Nb2RlbCA8fC0tIGRqYW5nb19jb250cmliX2F1dGhfbW9kZWxzX1Blcm1pc3Npb25zTWl4aW4KICBjbGFzcyBkamFuZ29fY29udHJpYl9hdXRoX2Jhc2VfdXNlcl9BYnN0cmFjdEJhc2VVc2VyWyJkamFuZ28uY29udHJpYi5hdXRoLmJhc2VfdXNlcjo6QWJzdHJhY3RCYXNlVXNlciJdCiAgY2xhc3MgZGphbmdvX2NvbnRyaWJfYXV0aF9tb2RlbHNfQWJzdHJhY3RVc2VyWyJkamFuZ28uY29udHJpYi5hdXRoLm1vZGVsczo6QWJzdHJhY3RVc2VyIl0KICBjbGFzcyBkamFuZ29fZGJfbW9kZWxzX2Jhc2VfTW9kZWxbImRqYW5nby5kYi5tb2RlbHMuYmFzZTo6TW9kZWwiXQogIGRqYW5nb19jb250cmliX2F1dGhfbW9kZWxzX1Blcm1pc3Npb25zTWl4aW4gPHwtLSBkamFuZ29fY29udHJpYl9hdXRoX21vZGVsc19BYnN0cmFjdFVzZXI=\"/>"
+      ],
+      "text/plain": [
+       "<IPython.core.display.Image object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "plus.diagram(plus.User)\n"
+   ]
   }
  ],
  "metadata": {