Merge pull request #191 from HChughtai/review-docs-notes

Review docs notes - Added some clarifications including where to go to install Sphinx from, as well as updated a broken link to sphinx-quickstart documentation

Author: HChughtai

ch04packaging/04documentation.ipynb

@@ -90,14 +90,14 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We're going to document our \"greeter\" example using docstrings with Sphinx.\n",
+    "We're going to document our \"greeter\" example from the previous section using docstrings with Sphinx.\n",
     "\n",
-    "There are various conventions for how to write docstrings, but the native sphinx one doesn't look nice when used with\n",
+    "There are various conventions for how to write docstrings, but the native Sphinx one doesn't look nice when used with\n",
     "the built in `help` system.\n",
     "\n",
     "In writing Greeter, we used the docstring conventions from NumPy.\n",
     "So we use the [numpydoc](https://numpydoc.readthedocs.io/en/latest/) sphinx extension to \n",
-    "support these."
+    "support these (Note: you will need to install this extension for the later examples to work)."
    ]
   },
   {
@@ -134,17 +134,25 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Set up sphinx"
+    "### Set up Sphinx"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Install Sphinx using the [appropiate instructions](https://www.sphinx-doc.org/en/master/usage/installation.html) for your system following the documentation online.\n",
+    "(Note that your output and the linked documentation may differ slightly depending on when you installed Sphinx and what version you're using.)"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "\n",
-    "Invoke the [sphinx-quickstart](https://www.sphinx-doc.org/en/latest/usage/quickstart.html) command to build Sphinx's\n",
+    "Invoke the [sphinx-quickstart](https://www.sphinx-doc.org/en/master/usage/quickstart.html) command to build Sphinx's\n",
     "configuration file automatically based on questions\n",
-    "at the command line:\n"
+    "at the command line:"
    ]
   },
   {
@@ -168,13 +176,17 @@
    "metadata": {},
    "source": [
     "```\n",
-    "Welcome to the Sphinx 1.8.0 quickstart utility.\n",
+    "Welcome to the Sphinx 3.3.0 quickstart utility.\n",
     "\n",
-    "Please enter avalues for the following settings (just press Enter to\n",
+    "Please enter values for the following settings (just press Enter to\n",
     "accept a default value, if one is given in brackets).\n",
     "\n",
-    "Enter the root path for documentation.\n",
-    "> Root path for the documentation [.]:\n",
+    "Selected root path: .\n",
+    "\n",
+    "You have two options for placing the build directory for Sphinx output.\n",
+    "Either, you use a directory \"_build\" within the root path, or you separate\n",
+    "\"source\" and \"build\" directories within the root path.\n",
+    "> Separate source and build directories (y/n) [n]:\n",
     "```"
    ]
   },
@@ -215,7 +227,10 @@
    "cell_type": "code",
    "execution_count": 1,
    "metadata": {
-    "collapsed": false
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
    },
    "outputs": [
     {
@@ -295,7 +310,10 @@
    "cell_type": "code",
    "execution_count": 2,
    "metadata": {
-    "collapsed": false
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
    },
    "outputs": [
     {
@@ -335,7 +353,10 @@
    "cell_type": "code",
    "execution_count": 3,
    "metadata": {
-    "collapsed": false
+    "collapsed": false,
+    "jupyter": {
+     "outputs_hidden": false
+    }
    },
    "outputs": [
     {
@@ -348,8 +369,7 @@
     {
      "name": "stderr",
      "output_type": "stream",
-     "text": [
-     ]
+     "text": []
     }
    ],
    "source": [
@@ -513,9 +533,9 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.7.3"
+   "version": "3.8.5"
   }
  },
  "nbformat": 4,
- "nbformat_minor": 0
+ "nbformat_minor": 4
 }