added lesson 7 documentation with sphinx

lesson 7/documentation-with-sphinx.ipynb

@@ -0,0 +1,187 @@
+{
+ "metadata": {
+  "name": "",
+  "signature": "sha256:f9840f8981b95ed90c130bab6534919d94748a9ced8719853feb7da6b3bf8fe7"
+ },
+ "nbformat": 3,
+ "nbformat_minor": 0,
+ "worksheets": [
+  {
+   "cells": [
+    {
+     "cell_type": "heading",
+     "level": 1,
+     "metadata": {},
+     "source": [
+      "Generating Documentation with Sphinx"
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "With Sphinx you can:\n",
+      "\n",
+      "* Generate nicely formatted documentation in HTML and PDF\n",
+      "* Docstrings are usefull twice: when reading the code and when consulting the manual\n",
+      "* re-structured text (reST)\n",
+      "* Include LaTeX formula's\n",
+      "* Doc-string tests\n",
+      "* Used exstensively by other (scientific) Python modules"
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "See Sphinx in action:\n",
+      "* http://sphinx-doc.org/examples.html\n",
+      "\n",
+      "Examples:\n",
+      "* http://matplotlib.org/sampledoc/\n",
+      "* http://pythonhosted.org/an_example_pypi_project/index.html\n",
+      "\n",
+      "Documentation:\n",
+      "* http://sphinx-doc.org/contents.html\n",
+      "\n",
+      "First steps with Sphinx:\n",
+      "* http://sphinx-doc.org/tutorial.html\n",
+      "\n",
+      "Python PEP-257: doc string conventions:\n",
+      "* http://legacy.python.org/dev/peps/pep-0257/"
+     ]
+    },
+    {
+     "cell_type": "heading",
+     "level": 2,
+     "metadata": {},
+     "source": [
+      "ReST"
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "* http://docutils.sourceforge.net/docs/user/rst/quickref.html\n",
+      "* http://sphinx-doc.org/rest.html"
+     ]
+    },
+    {
+     "cell_type": "heading",
+     "level": 2,
+     "metadata": {},
+     "source": [
+      "Extensions for Sphinx"
+     ]
+    },
+    {
+     "cell_type": "heading",
+     "level": 3,
+     "metadata": {},
+     "source": [
+      "NumPy doc strings: numpydoc"
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "* https://github.com/numpy/numpydoc\n",
+      "* https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt"
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "* While a rich set of markup is available, we limit ourselves to a very basic subset, in order to provide docstrings that are easy to read on text-only terminals\n",
+      "* The length of docstring lines should be kept to 75 characters to facilitate reading the docstrings in text terminals."
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "NumPy documentation conventions:\n",
+      "\n",
+      "* Parameters (optional keyword arguments), Returns, Raises, Attributes (for classes), ...\n",
+      "* Including LaTeX formatted formula's\n",
+      "* Including examples\n",
+      "* example: https://github.com/numpy/numpy/blob/master/doc/example.py\n",
+      "* example: http://sphinx-doc.org/latest/ext/example_numpy.html"
+     ]
+    },
+    {
+     "cell_type": "heading",
+     "level": 3,
+     "metadata": {},
+     "source": [
+      "HTML slides with Hieroglyph"
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "Hieroglyph is an extension for Sphinx which builds HTML slides from ReStructured Text documents.\n",
+      "* https://github.com/nyergler/hieroglyph\n",
+      "* http://docs.hieroglyph.io"
+     ]
+    },
+    {
+     "cell_type": "heading",
+     "level": 3,
+     "metadata": {},
+     "source": [
+      "Generate Sphinx documentation based on IPython notebooks"
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "http://sphinx-ipynb.readthedocs.org/en/latest/index.html"
+     ]
+    },
+    {
+     "cell_type": "heading",
+     "level": 1,
+     "metadata": {},
+     "source": [
+      "Publish documentation"
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "You can use either [Github's pages](https://pages.github.com/) mechanism or [Read the Docs](https://readthedocs.org/)."
+     ]
+    },
+    {
+     "cell_type": "markdown",
+     "metadata": {},
+     "source": [
+      "* Read the Docs: http://dont-be-afraid-to-commit.readthedocs.org/en/latest/documentation.html\n",
+      "* Github gh-pages: http://raxcloud.blogspot.dk/2013/02/documenting-python-code-using-sphinx.html"
+     ]
+    },
+    {
+     "cell_type": "code",
+     "collapsed": false,
+     "input": [],
+     "language": "python",
+     "metadata": {
+      "run_control": {
+       "breakpoint": false,
+       "state": "n"
+      }
+     },
+     "outputs": []
+    }
+   ],
+   "metadata": {}
+  }
+ ]
+}