04-Documentation.ipynb

{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<link href='http://fonts.googleapis.com/css?family=Open+Sans:100,300,400,500,700,800,900,100italic,300italic,400italic,500italic,700italic,800italic,900italic' rel='stylesheet' type='text/css'>\n",
       "<link href='http://fonts.googleapis.com/css?family=Merriweather:400,700,400italic' rel='stylesheet' type='text/css'>\n",
       "<link href='http://fonts.googleapis.com/css?family=Inconsolata' rel='stylesheet' type='text/css'>\n",
       "<style>\n",
       "\n",
       "@font-face {\n",
       "    font-family: \"Computer Modern\";\n",
       "    src: url('http://mirrors.ctan.org/fonts/cm-unicode/fonts/otf/cmunss.otf');\n",
       "}\n",
       "\n",
       "#notebook_panel { /* main background */\n",
       "    background: rgb(245,245,245);\n",
       "}\n",
       "\n",
       "div.cell { /* set cell width */\n",
       "    width: 75em;\n",
       "}\n",
       "\n",
       "div #notebook { /* centre the content */\n",
       "    background: #fff; /* white background for content */\n",
       "    width: 80em;\n",
       "    margin: auto;\n",
       "    padding-left: 0em;\n",
       "}\n",
       "\n",
       "#notebook li { /* More space between bullet points */\n",
       "margin-top:0.8em;\n",
       "}\n",
       "\n",
       "/* draw border around running cells */\n",
       "div.cell.border-box-sizing.code_cell.running {\n",
       "    border: 1px solid #111;\n",
       "}\n",
       "\n",
       "/* Put a solid color box around each cell and its output, visually linking them*/\n",
       "div.cell.code_cell {\n",
       "    /*font-family: 'Inconsolata', monospace;*/\n",
       "    background-color: rgb(256,256,256);\n",
       "    border-radius: 0px;\n",
       "    padding: 0.5em;\n",
       "    margin-left:1em;\n",
       "    margin-right:1em;\n",
       "    margin-top: 1em;\n",
       "}\n",
       "\n",
       "div.text_cell_render{\n",
       "    font-family: 'Open Sans', sans-serif;\n",
       "    line-height: 140%;\n",
       "    font-size: 110%;\n",
       "    font-weight: 400;\n",
       "    padding: 0.5em;\n",
       "    margin-left:1em;\n",
       "    margin-right:1em;\n",
       "}\n",
       "\n",
       ".text_cell_render pre {\n",
       "    white-space: pre;\n",
       "    white-space: pre-wrap;\n",
       "    white-space: -moz-pre-wrap;\n",
       "    white-space: -o-pre-wrap;\n",
       "    background-color: #f5f5f5;\n",
       "    padding: 0.5em;\n",
       "}\n",
       "\n",
       ".text_cell_render code {\n",
       "    font-size: 95%;\n",
       "    white-space: pre;\n",
       "    white-space: pre-wrap;\n",
       "    white-space: -moz-pre-wrap;\n",
       "    white-space: -o-pre-wrap;\n",
       "    background-color: #f5f5f5;\n",
       "}\n",
       "\n",
       "/* Formatting for header cells */\n",
       ".text_cell_render h1 {\n",
       "    font-family: 'Merriweather', serif;\n",
       "    font-style: regular;\n",
       "    font-weight: 400;\n",
       "    font-size: 3em;\n",
       "    line-height: 100%;\n",
       "    color: rgb(36,67,87);\n",
       "    margin-bottom: 0.5em;\n",
       "    margin-top: 0.5em;\n",
       "    display: block;\n",
       "}\n",
       ".text_cell_render h2 {\n",
       "    font-family: 'Merriweather', serif;\n",
       "    font-weight: 400;\n",
       "    font-size: 2.2em;\n",
       "    line-height: 100%;\n",
       "    color: rgb(36,67,87);\n",
       "    margin-bottom: 0.3em;\n",
       "    margin-top: 0.3em;\n",
       "    display: block;\n",
       "}\n",
       "\n",
       ".text_cell_render h3 {\n",
       "    font-family: 'Merriweather', serif;\n",
       "    margin-top:1em;\n",
       "\tfont-size: 1.6em;\n",
       "    font-weight: 400;\n",
       "    margin-bottom: 0.3em;\n",
       "    font-style: regular;\n",
       "    color: rgb(85, 111, 127);\n",
       "}\n",
       "\n",
       ".text_cell_render h4 {\n",
       "    font-family: 'Inconsolata', monospace;\n",
       "    /*font-family: 'Merriweather', serif;*/\n",
       "    font-size: 1.3em;\n",
       "    margin-top: 0.3em;\n",
       "    margin-bottom: 0.5em;\n",
       "    font-style: regular;\n",
       "    color: rgb(85, 111, 127);\n",
       "}\n",
       "\n",
       ".text_cell_render h5 {  /*Captions*/\n",
       "    font-family: 'Merriweather', serif;\n",
       "    font-weight: 400;\n",
       "    font-size: 1em;\n",
       "    color: rgb(85, 111, 127);\n",
       "    font-style: regular;\n",
       "    margin-bottom: .1em;\n",
       "    margin-top: 0.8em;\n",
       "    display: block;\n",
       "    text-align: center;\n",
       "}\n",
       "\n",
       ".text_cell_render h6 { /*use this for copyright note*/\n",
       "    font-family: 'Inconsolata', sans-serif;\n",
       "    font-weight: 300;\n",
       "    font-size: 9pt;\n",
       "    line-height: 100%;\n",
       "    color: grey;\n",
       "    margin-bottom: 1px;\n",
       "    margin-top: 1px;\n",
       "}\n",
       "\n",
       "img {\n",
       "    margin-left: auto;\n",
       "    margin-right: auto;\n",
       "}\n",
       "\n",
       "/*.CodeMirror{\n",
       "        font-size: 120%;\n",
       "}*/\n",
       "\n",
       "</style>\n",
       "<script>\n",
       "    MathJax.Hub.Config({\n",
       "                        TeX: {\n",
       "                           extensions: [\"AMSmath.js\"],\n",
       "                           equationNumbers: { autoNumber: \"AMS\", useLabelIds: true}\n",
       "                           },\n",
       "                tex2jax: {\n",
       "                    inlineMath: [ ['$','$'], [\"\\\\(\",\"\\\\)\"] ],\n",
       "                    displayMath: [ ['$$','$$'], [\"\\\\[\",\"\\\\]\"] ]\n",
       "                },\n",
       "                displayAlign: 'center', // Change this to 'center' to center equations.\n",
       "                \"HTML-CSS\": {\n",
       "                    styles: {'.MathJax_Display': {\"margin\": 4}}\n",
       "                }\n",
       "        });\n",
       "</script>\n"
      ],
      "text/plain": [
       "<IPython.core.display.HTML object>"
      ]
     },
     "execution_count": 1,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from IPython.core.display import HTML\n",
    "css_file = \"./notebook_style.css\"\n",
    "HTML(open(css_file, 'r').read())"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# 4. Documentation\n",
    "\n",
    "- [Why should I document my code?](#Why-should-I-document-my-code?)\n",
    "- [How?](#How?)\n",
    "- [Automating documentation](#Automating-documentation)\n",
    "    * [Sphinx](#Sphinx)\n",
    "- [Read more](#Read-more)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Why should I document my code?\n",
    "\n",
    "Documentation is a part of software development that is often overlooked. In the rush to produce results, it can seem like a waste of time writing documentation when you could instead be fixing bugs or adding new features. However, good documentation is vital for good code: why should someone trust your code is producing the correct results if they have no idea how it works? \n",
    "\n",
    "In experimental science, experiments must be reproducible. The apparatus and experimental setup must be described in enough detail that an independent group can replicate any results. Detailed descriptions of testing are given to demonstrate that the apparatus are performing as designed and so any new results can be trusted. \n",
    "\n",
    "In computational science, we should aim for similar standards. The algorithm and its implementation should ideally be described in enough detail for someone who does not have access to the original source code to implement it themselves and reproduce your results. Tests should be described to demonstrate the functionality of the code and show it is performing as described. \n",
    "\n",
    "Documentation also helps other users of the code. It's likely that at some point you will want to show or give your code to someone else. If it's well documented, this will allow other people to read and understand what your code is doing without you having to sit down with them and explain everything in person. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "![Documentation](http://www.phdcomics.com/comics/archive/phd031214s.gif)\n",
    "##### Good documentation is important - [PHD Comics](http://www.phdcomics.com/comics/archive/phd031214s.gif)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "Finally, documentation will help you be a more effective software developer. If you are working on the same code for any length of time, it is very easy to forget how parts of it you wrote weeks/months/years ago work. By taking the time to comment your code, briefly explaining how it works and why you made certain choices (e.g. of algorithm, data structure), it will save you a lot of time down the line."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "![Comments](images/commenting.jpg)\n",
    "##### [Geek and Poke](http://geekandpoke.typepad.com/geekandpoke/2011/06/code-commenting-made-easy.html)\n",
    "\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## How?\n",
    "\n",
    "Bad documentation is almost as useless as no documentation at all: to be useful, documentation must be easy to navigate, clear and concise yet informative. Ideally, it should answer any potential questions a new user (with some assumed level of background knowledge) might have about your code. \n",
    "\n",
    "Starting to write documentation can be a daunting task, especially if your code is already quite well developed. It's therefore a good idea to begin writing documentation as soon as possible. No matter how small a project may seem at the start, there is always the potential that it will turn into something bigger or be incorporated into another project at a later date.\n",
    "\n",
    "It is useful for your code to be to some extent 'self-documenting' - e.g. classes, functions and variables are given sensible, descriptive names that make it clear what they are doing. To see this, contrast the following two implementations of the same function:\n",
    "\n",
    "```python\n",
    "def f(x, y):\n",
    "    for z in y:\n",
    "        if x in z:\n",
    "            print(z)\n",
    "            \n",
    "def find_substring(substring, string_list):\n",
    "    for line in string_list:\n",
    "        if substring in line:\n",
    "            print(line)\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Different programming languages have different documentation conventions and standards. The most important thing is to be consistant with your style across your project. \n",
    "\n",
    "For python, a good standard to follow is that used by the [`numpy` and `scipy` documentation](https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt) (or alternatively follow the [Google python style guide](http://google.github.io/styleguide/pyguide.html)). This helps produce documentation that is clear and concise, and they can be used in combination with `Sphinx` (provided the [`napoleon` extension](http://www.sphinx-doc.org/en/stable/ext/napoleon.html) is used). Docstrings can be written in [reStructuredText](http://docutils.sourceforge.net/docs/user/rst/quickref.html), enabling the use of e.g. lists, tables, hyperlinks and laTeX maths expressions. An example of a python file documented using the NumPy style is:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### docs_example.py"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": [
    "\"\"\"Brief description of module\n",
    "\n",
    "A more in depth description of the module goes here.\n",
    "\"\"\"\n",
    "import numpy\n",
    "\n",
    "def example_function(param1, param2):\n",
    "    \"\"\"Brief function description.\n",
    "    \n",
    "    A more in depth description of the function. Sphinx will support any reStructuredText\n",
    "    formatting and even LaTeX math expressions (if the mathjax extension is included), e.g.\n",
    "        indented sections like this\n",
    "    \n",
    "    and::\n",
    "        \n",
    "        literal blocks like this \n",
    "        \n",
    "    or even :math:`\\latex` like this.\n",
    "    \n",
    "    Parameters\n",
    "    ----------\n",
    "    param1 : float \n",
    "        Brief description of the first parameter.\n",
    "    param2 : float\n",
    "        Brief description of the second parameter.\n",
    "        \n",
    "    Returns\n",
    "    -------\n",
    "    float\n",
    "        Brief description of what the function returns.\n",
    "    \"\"\"\n",
    "    return numpy.sqrt(param1 * param2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Automating documentation\n",
    "\n",
    "Fortunately, there are tools out there that can take a lot of the work out of documenting your code. They can take information from the source code itself, including comments within the code, and turn this into clear, well-structured documentation. Two commonly used tools are [`sphinx`](http://www.sphinx-doc.org/en/stable/) and [`doxygen`](http://www.stack.nl/~dimitri/doxygen/). Sphinx is good for python projects, doxygen for C++ projects. \n",
    "\n",
    "These tools can then be linked to a [`Read The Docs`](https://readthedocs.org/) account. This will host the repository's documentation and, much like the continuous integration tools of the previous section, can be configured to rebuild the documentation every time changes are pushed so that it is kept up to date with the latest versions of your code. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Sphinx\n",
    "\n",
    "Getting started with Sphinx is simple: navigate to the directory where you'd like to build your documentation and execute\n",
    "\n",
    "    sphinx-quickstart\n",
    "    \n",
    "This will produce a series of prompts, asking questions about your project. At the end, it will then automatically generate some skeleton documentation: a `docs` directory containing a Makefile, a configuration file `conf.py` and a master document `index.rst`. The Makefile is what you will use to build your documentation - you'll probably want to leave this alone. The configuration file contains information about the sphinx setup including the values you gave when quickstart-ing your project - for now you will probably want to leave this alone as well, but there are a lot of parameters in there that can be customised if you so wish. The master document is the index file for your documentation. It normally contains a brief introduction to the project and a table of contents linking to the other pages of the documentation. Let's look at the index file that quickstart generated for us:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### index.rst\n",
    "\n",
    "```rst\n",
    "Welcome to My Project's documentation!\n",
    "======================================\n",
    "\n",
    "Contents:\n",
    "\n",
    ".. toctree::\n",
    "   :maxdepth: 2\n",
    "   \n",
    "Indices and tables\n",
    "==================\n",
    "\n",
    "* :ref:`genindex`\n",
    "* :ref:`modindex`\n",
    "* :ref:`search`\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The index file currently contains a `toctree` (a **T**able **O**f **C**ontents **tree**). The `maxdepth` option here says that the table of contents will list headings and subheadings but not subsubheadings. At the bottom, Sphinx has put links to some pages it has generated for us automatically by looking at the source files in the original project folder: an index of functions, classes, member variables etc., an index of modules and a search page. \n",
    "\n",
    "Let's add another page to our documentation by creating the file `example.rst`:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### example.rst\n",
    "```rst\n",
    "Example Title\n",
    "=============\n",
    "\n",
    "This is some example text about an example project.\n",
    "\n",
    "Example subtitle\n",
    "----------------\n",
    "This is some more example text\n",
    "\n",
    "    * with an\n",
    "    * example list\n",
    "    \n",
    "and some ``example code``.\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We now include this file in our documentation by amending the `toctree`:\n",
    "\n",
    "```rst\n",
    "Contents:\n",
    "\n",
    ".. toctree::\n",
    "   :maxdepth: 2\n",
    "   \n",
    "   example\n",
    "```\n",
    "\n",
    "The spacing here is very important: there must be a blank line after the `maxdepth` option, and three spaces between the file name and the left margin. We can now build our documentation by executing \n",
    "\n",
    "    make html\n",
    "    \n",
    "This will build a set of HTML pages in the directory `docs/_build/html`. If you open the `index.html` file in a browser, this should give you a look at the documentation it built. \n",
    "\n",
    "The default Sphinx formatting is perhaps not the prettiest, but fortunately at this point we can now link our project to Read the Docs. Once you've made an account and linked it to your github/bitbucket account, Read the Docs will then scan for repositories connected to your account(s). You can also create a project manually by providing the repository URL. It will then use Sphinx to build documentation for your project, hosting it online at `myproject.readthedocs.io` (or a custom domain). This documentation will be rebuilt every time you push changes to your code to the remote repository, automatically keeping your documentation up to date with minimal effort on your part!"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above example shows how to build documentation from reStructured Text files, however it's also possible to use Sphinx to generate documentation from jupyter notebooks using the [nbsphinx extension](https://nbsphinx.readthedocs.io/en/0.2.13/index.html). To do this, go to the configuration file `conf.py` and find where it defines the variable `extensions`. Change this to be\n",
    "\n",
    "```python\n",
    "extensions = [\n",
    "    'nbsphinx',\n",
    "    'sphinx.ext.mathjax', 'sphinx.ext.autodoc',\n",
    "    'IPython.sphinxext.ipython_console_highlighting',\n",
    "]\n",
    "```\n",
    "\n",
    "You will now be able to list the names of your `.ipynb` files in the `toctree` just as you did with the `.rst` file.\n",
    "\n",
    "To get this working in Read the Docs, you'll need to create a requirements file:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### requirements.txt\n",
    "\n",
    "    sphinx>=1.4\n",
    "    ipykernel\n",
    "    nbsphinx"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "On `readthedocs.org`, go to Admin >> Advanced Settings for your project and give the location of your requirements file. "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "## Read more\n",
    "- [markdown reference](https://learnxinyminutes.com/docs/markdown/)\n",
    "- [reStructuredText reference](http://docutils.sourceforge.net/docs/user/rst/quickref.html) \n",
    "- [Quick introduction to Sphinx](https://www.ibm.com/developerworks/library/os-sphinx-documentation/)\n",
    "- [A more detailed guide to Sphinx](https://pythonhosted.org/an_example_pypi_project/sphinx.html)\n",
    "- [Full Sphinx documentation](http://www.sphinx-doc.org/en/stable/contents.html)\n",
    "- [Doxygen manual](http://www.stack.nl/~dimitri/doxygen/manual/index.html)\n",
    "- [Breathe documentation](https://breathe.readthedocs.io/en/latest/) - Breathe provides a bridge between doxygen and Sphinx, which is useful for generating Sphinx-like / Read the Docs documentation for projects written in languages not currently supported by Sphinx (e.g. fortran) "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "collapsed": true
   },
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [default]",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.5.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}