Sphinx Documentation with Numpydoc.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "toc": "true"
   },
   "source": [
    "# Table of Contents\n",
    " <p><div class=\"lev1\"><a href=\"#Description\"><span class=\"toc-item-num\">1&nbsp;&nbsp;</span>Description</a></div><div class=\"lev1\"><a href=\"#Generating-Documentation\"><span class=\"toc-item-num\">2&nbsp;&nbsp;</span>Generating Documentation</a></div><div class=\"lev2\"><a href=\"#Getting-Started\"><span class=\"toc-item-num\">2.1&nbsp;&nbsp;</span>Getting Started</a></div><div class=\"lev2\"><a href=\"#Running-Sphinx\"><span class=\"toc-item-num\">2.2&nbsp;&nbsp;</span>Running Sphinx</a></div><div class=\"lev2\"><a href=\"#Editing-Conf.py\"><span class=\"toc-item-num\">2.3&nbsp;&nbsp;</span>Editing Conf.py</a></div><div class=\"lev2\"><a href=\"#Finishing-Up\"><span class=\"toc-item-num\">2.4&nbsp;&nbsp;</span>Finishing Up</a></div>"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Description\n",
    "\n",
    "Every good project needs good documentation. [Sphinx](http://www.sphinx-doc.org/en/stable/) provides a really easy way of autogenerating docs. Sphinx is really extensive, however, so it can be a little tricky to find the most minimalistic way of getting up and running. This notebook is a quick walkthrough of the simplest way I've found. The only complication I'll add is the use of [numpydoc](https://pypi.python.org/pypi/numpydoc), because I vastly prefer their docstring style. [Here's](https://codeandchaos.wordpress.com/2012/08/09/sphinx-and-numpydoc/) a small snippet of normal rst:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "def public_fn_with_sphinxy_docstring(name, state=None):\n",
    "    \"\"\"This function does something.\n",
    " \n",
    "    :param name: The name to use.\n",
    "    :type name: str.\n",
    "    :param state: Current state to be in.\n",
    "    :type state: bool.\n",
    "    :returns:  int -- the return code.\n",
    "    :raises: AttributeError, KeyError\n",
    " \n",
    "    \"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "And numpy style:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {
    "collapsed": false
   },
   "outputs": [],
   "source": [
    "def foo(var1, var2, long_var_name='hi'):\n",
    "    \"\"\"This function does something.\n",
    " \n",
    "    Parameters\n",
    "    ----------\n",
    "    var1 : array_like\n",
    "        This is a type.\n",
    "    var2 : int\n",
    "        This is another var.\n",
    "    Long_variable_name : {'hi', 'ho'}, optional\n",
    "        Choices in brackets, default first when optional.\n",
    " \n",
    "    Returns\n",
    "    -------\n",
    "    describe : type\n",
    "        Explanation\n",
    "    \"\"\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Maybe you think the rst style is better. In that case, it's no problem to just skip over the numpydoc portions. \n",
    "\n",
    "I'm currently working on a small game for my summer class, so we'll work on the documentation for that project. Additionally, if you're a visual learner, there's a great [video tutorial](https://www.youtube.com/watch?v=LQ6pFgQXQ0Q), which more or less covers this same material.\n",
    "\n",
    "Finally, [sklearn](http://scikit-learn.org/stable/documentation.html) is a beautiful example of documentation using both Sphinx and numpydoc."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Generating Documentation\n",
    "\n",
    "## Getting Started\n",
    "\n",
    "As usual, I'm hoping people are working with the Anaconda distribution, which means that you already have Sphinx installed. If not `pip install sphinx`. You do have to download numpydoc though:\n",
    "\n",
    "```bash\n",
    "conda install numpydoc\n",
    "```\n",
    "\n",
    "If you haven't already, go to your project directory:\n",
    "\n",
    "```bash\n",
    "cd ~/Code/small_group/year2/asteroid/\n",
    "```\n",
    "\n",
    "## Running Sphinx\n",
    "\n",
    "Starting Sphinx is going to take you through a fairly extensive menu, but we'll leave most of the options as defaults:\n",
    "```bash\n",
    "sphinx quick-start\n",
    "```\n",
    "\n",
    "\t> Root path for the documentation [.]: docs\n",
    "\t> Separate source and build directories (y/n) [n]: \n",
    "\t> Name prefix for templates and static dir [_]: \n",
    "\t> Project name: Asteroid\n",
    "\t> Author name(s): Jessime\n",
    "\t> Project version: 1\n",
    "\t> Project release [1]: 1.1\n",
    "\t> Project language [en]: \n",
    "\t> Source file suffix [.rst]: \n",
    "\t> Name of your master document (without suffix) [index]: \n",
    "\t> Do you want to use the epub builder (y/n) [n]: \n",
    "\t> autodoc: automatically insert docstrings from modules (y/n) [n]: y\n",
    "\t> doctest: automatically test code snippets in doctest blocks (y/n) [n]: \n",
    "\t> intersphinx: link between Sphinx documentation of different projects (y/n) [n]: \n",
    "\t> todo: write \"todo\" entries that can be shown or hidden on build (y/n) [n]: \n",
    "\t> coverage: checks for documentation coverage (y/n) [n]: \n",
    "\t> pngmath: include math, rendered as PNG images (y/n) [n]: \n",
    "\t> mathjax: include math, rendered in the browser by MathJax (y/n) [n]: \n",
    "\t> ifconfig: conditional inclusion of content based on config values (y/n) [n]: \n",
    "\t> viewcode: include links to the source code of documented Python objects (y/n) [n]: \n",
    "\t> Create Makefile? (y/n) [y]: \n",
    "\t> Create Windows command file? (y/n) [y]:\n",
    "    \n",
    "## Editing Conf.py\n",
    "    \n",
    "If that went well, you can open up `docs/conf.py`. We'll make a few changes in here. First, we want to add the path to our modules. Change line 22 from:\n",
    "\n",
    "```python\n",
    "#sys.path.insert(0, os.path.abspath('.'))\n",
    "```\n",
    "to:\n",
    "```python\n",
    "sys.path.insert(0, os.path.abspath('../'))\n",
    "```\n",
    "Add the numpydoc extension to the extensions on lines 32-34:\n",
    "```python\n",
    "extensions = [\n",
    "    'sphinx.ext.autodoc', 'numpydoc'\n",
    "]\n",
    "```\n",
    "And finally, choose you favorite [theme from the list](http://www.sphinx-doc.org/en/stable/theming.html). Set it on line 113 from:\n",
    "\n",
    "```python\n",
    "html_theme = 'alabaster'\n",
    "```\n",
    "to\n",
    "```python\n",
    "html_theme = 'sphinx_rtd_theme'\n",
    "```\n",
    "Make sure to save the changes before moving on.\n",
    "\n",
    "## Finishing Up\n",
    "\n",
    "We've done all the hard work, we just have to pull together the actual module documentation now. Sphinx has a nice script to take care of pulling out all of the docstrings and building all of the files. We want to let it do all its work, so we'll use the `-F` flag, and continue to put everything in the docs folder with `-o`. After that, we just have to generate the html version.\n",
    "\n",
    "```bash\n",
    " sphinx-apidoc -o docs/ -F ./\n",
    " cd docs\n",
    " make html\n",
    "```\n",
    "\n",
    "This should produce warnings (presumably because of numpydoc), but build sucessfully.\n",
    "\n",
    "**Open \\_build/html/index.html in the browswer to see the results!**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 2",
   "language": "python",
   "name": "python2"
  },
  "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.11"
  },
  "toc": {
   "toc_cell": true,
   "toc_number_sections": true,
   "toc_threshold": 6,
   "toc_window_display": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 0
}