{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "# An introduction to Sphinx\n",
    "\n",
    "**Credit:** this notebook draws heavily on [Carol Willing's Practical Sphinx tutorial](https://github.com/willingc/2017_09_28_sdpug_sphinx), originally MIT licensed. All modifications made here are also MIT licensed."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Sphinx?\n",
    "\n",
    "The [Python documentation generator](http://www.sphinx-doc.org/en/stable).\n",
    "\n",
    "By default, Sphinx assumes input files are created using the [reStructuredText format](http://docutils.sourceforge.net/rst.html) (this [quick reference](http://docutils.sourceforge.net/docs/user/rst/quickref.html) can be handy).  But Sphinx is an *extensible system*, and with a couple of custom extensions, we can:\n",
    "\n",
    "* Use Markdown, thanks to [recommonmark](https://github.com/rtfd/recommonmark).\n",
    "* Use Jupyter Notebooks, thanks to [nbsphinx](https://nbsphinx.readthedocs.io).\n",
    "\n",
    "**This is what the class website uses!**"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## The Jupyter Docs\n",
    "\n",
    "Available at [jupyter.readthedocs.io](http://jupyter.readthedocs.io):\n",
    "\n",
    "* Complex set of docs that span multiple projects\n",
    "* Include sources in reST, Markdown and Jupyter Notebooks.\n",
    "* [Detailed explanations with figures](http://jupyter.readthedocs.io/en/latest/architecture/how_jupyter_ipython_work.html)\n",
    "* [Reference documentation for the software](http://ipython.readthedocs.io/en/stable/api/generated/IPython.display.html)\n",
    "* [Notebooks rendered as part of the documentation](http://jupyter-notebook.readthedocs.io/en/latest/examples/Notebook/Running%20Code.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Getting Started\n",
    "\n",
    "If you didn't already, in your class environment, run:\n",
    "\n",
    "```bash\n",
    "conda install sphinx\n",
    "conda install -c conda-forge nbsphinx recommonmark ghp-import \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Create project folder\n",
    "\n",
    "```\n",
    "mkdir my-doc-project\n",
    "cd my-doc-project\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Run sphinx's quickstart\n",
    "\n",
    "We can leave most items as default:\n",
    "\n",
    "```\n",
    "sphinx-quickstart\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Build docs from your docs root directory\n",
    "\n",
    "Type `make` for help on all the possible targets. Typical workflow:\n",
    "\n",
    "\n",
    "```\n",
    "make clean\n",
    "make html\n",
    "make linkcheck\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## To view the docs\n",
    "\n",
    "```\n",
    "open _build/html/index.html\n",
    "```\n",
    "\n",
    "## Or start a webserver and view\n",
    "\n",
    "```\n",
    "python -m http.server\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Configuration"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## `conf.py`\n",
    "\n",
    "- Use for configuration settings.\n",
    "- This is a Python file.\n",
    "- You can execute Python code for custom builds."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## `conf.py`\n",
    "\n",
    "- themes\n",
    "- source files\n",
    "- extensions"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Themes in `conf.py`\n",
    "\n",
    "**Easiest** Use the default.\n",
    "\n",
    "**Easy** Use another standard theme.\n",
    "\n",
    "**Customize** `css`, `js` and override `templates` (`jinja2`)\n",
    "\n",
    "**Create your own theme** Only do if the above doesn't meet your needs."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Source files\n",
    "#### More than `.rst`\n",
    "\n",
    "- reStructuredText `.rst` and sometimes `.txt`\n",
    "- markdown `.md`\n",
    "- Jupyter notebooks `.ipynb`"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## `conf.py`\n",
    "\n",
    "#### reStructuredText `.rst`\n",
    "\n",
    "No changes needed in `conf.py`."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## `conf.py` (cont.)\n",
    "\n",
    "#### Markdown `.md` using `recommonmark`.\n",
    "\n",
    "```python\n",
    "# For conversion from markdown to html\n",
    "import recommonmark.Parser\n",
    "\n",
    "# Add a source file parser for markdown\n",
    "source_parsers = {\n",
    "    '.md': 'recommonmark.parser.CommonMarkParser',\n",
    "}\n",
    "\n",
    "# Add type of source files\n",
    "source_suffix = ['.rst', '.md']\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## `conf.py` (cont.)\n",
    "\n",
    "#### Jupyter notebooks  `.ipynb` using `nbsphinx` extension.\n",
    "\n",
    "```python\n",
    "extensions = [\n",
    "    'sphinx.ext.mathjax',\n",
    "    'nbsphinx',  # This lets us use notebooks\n",
    "]\n",
    "\n",
    "# I execute the notebooks manually in advance. If notebooks test the code,\n",
    "# they should be run at build time.\n",
    "nbsphinx_execute = 'never'\n",
    "nbsphinx_allow_errors = True\n",
    "\n",
    "# Add type of source files\n",
    "source_suffix = ['.rst', '.md', '.ipynb']\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## `index.rst`\n",
    "\n",
    "Table of Contents using each source file type\n",
    "\n",
    "```\n",
    ".. toctree::\n",
    "   :maxdepth: 2\n",
    "   :caption: Sphinx Tips\n",
    "   \n",
    "   installation\n",
    "   configuration.md\n",
    "   content.ipynb\n",
    "   deploy-on-rtd\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Github Pages\n",
    "\n",
    "- Host static websites (HTML+JS) directly from a Github Repo!\n",
    "- https://pages.github.com\n",
    "- All we need to have is a branch called `gh-pages` that has an HTML build (with an `index.html` file at the start). Github does the rest!\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Using Github Pages to post a sphinx site easily\n",
    "\n",
    "Make sure you answer `yes` to the question about Github Pages in the quickstart! If you didn't, add to your extensions list:\n",
    "\n",
    "```python\n",
    "'sphinx.ext.githubpages'\n",
    "```\n",
    "\n",
    "Add this target to the `Makefile`. It automates pushing to GitHub Pages:\n",
    "\n",
    "```makefile\n",
    "\n",
    ".PHONY: github\n",
    "\n",
    "github: html\n",
    "\tghp-import $(BUILDDIR)/html/\n",
    "\tgit push -u origin gh-pages\n",
    "\t@echo\n",
    "\t@echo \"Published to Github\"\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Let's post our site\n",
    "\n",
    "* Turn our little test into a git repo (`git init, etc...`)\n",
    "* Go to GitHub and create a GH repo for it\n",
    "* Type:\n",
    "\n",
    "```\n",
    "ghp-import _build/html/\n",
    "git push -u origin gh-pages\n",
    "```\n",
    "* Go to **Settings** page and see that Github Pages is enabled.\n",
    "\n",
    "Once we verify the above works, we can just use, thanks to our above target:\n",
    "\n",
    "```\n",
    "make github\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true,
    "slideshow": {
     "slide_type": "slide"
    }
   },
   "source": [
    "## Love your docs!\n",
    "\n",
    "- Many documentation examples esp. Django, Jupyter, Python\n",
    "- Check out Carol's documentation examples on GitHub: `https://github.com/willingc`\n",
    "- A minimal documentation example repo https://github.com/willingc/doc-basics\n",
    "- Anne Gentle's https://justwriteclick.com/ and https://www.docslikecode.com/articles/ \n",
    "- Eric Holscher  http://www.writethedocs.org/ and https://readthedocs.io"
   ]
  }
 ],
 "metadata": {
  "celltoolbar": "Slideshow",
  "kernelspec": {
   "display_name": "Python 3",
   "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.6.3"
  },
  "livereveal": {
   "autolaunch": true,
   "scroll": true
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}