{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d3df99d5-0fd1-4912-aef2-26fc189917ec",
   "metadata": {},
   "source": [
    "<h1 align=\"center\">Markov Chain Monte Carlo for fun and profit</h1>\n",
    "<h1 align=\"center\"> 🎲 ⛓️ 👉 🧪 </h1>\n",
    "\n",
    "# Adding Documentation \n",
    "\n",
    "[Intro to basic Rst](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html)\n",
    "\n",
    "[Getting started with Sphinx](https://www.sphinx-doc.org/en/master/usage/quickstart.html)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2ecf10d-0025-4ce0-938a-807dbf0b6d1f",
   "metadata": {},
   "source": [
    "Make a folder called `docs/` inside `code/`, cd into it and run sphinx\n",
    "```sh\n",
    "% mkdir docs\n",
    "% cd docs\n",
    "% sphinx-quickstart #just go with the defaults\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7da17bd4-4072-4dd8-9680-dfd2a982de6f",
   "metadata": {},
   "source": [
    "To tell sphinx where to find our code we add some lines to conf.py:\n",
    "```python\n",
    "import os\n",
    "import sys\n",
    "sys.path.insert(0, os.path.abspath('../src'))\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "64d55530-c21a-4bd3-b25a-9c7109541038",
   "metadata": {},
   "source": [
    "We also add two extensions:\n",
    "```python\n",
    "extensions = [\n",
    "    'sphinx.ext.autodoc',\n",
    "    'sphinx.ext.napoleon',\n",
    "]\n",
    "```\n",
    "\n",
    "Autodoc allows us to generate documentation automatically from the docstrings in our source code, while [napoleon][napoleon] allows us to use [NUMPYDOC][numpydoc] and Google formats for the docstrings in addition to [reStructuredText][rst]\n",
    "\n",
    "[napoleon]: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html\n",
    "[NUMPYDOC]: https://numpydoc.readthedocs.io/en/latest/format.html\n",
    "[googledoc]: https://google.github.io/styleguide/pyguide.html\n",
    "[rst]: https://docutils.sourceforge.io/rst.html"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6d2d4a0f-adf2-4cc7-b220-8243635658d5",
   "metadata": {},
   "source": [
    "Numpy style docstrings look like this:\n",
    "```python\n",
    "def func(arg1, arg2):\n",
    "    \"\"\"Summary line.\n",
    "\n",
    "    Extended description of function.\n",
    "\n",
    "    Parameters\n",
    "    ----------\n",
    "    arg1 : int\n",
    "        Description of arg1\n",
    "    arg2 : str\n",
    "        Description of arg2\n",
    "\n",
    "    Returns\n",
    "    -------\n",
    "    bool\n",
    "        Description of return value\n",
    "\n",
    "    \"\"\"\n",
    "    return True\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "167d08ec-4c55-4050-929c-0ca5d4c03fd6",
   "metadata": {},
   "source": [
    "## Making the function declarations a bit nicer\n",
    "Longer function names in the generated documentation currently generate with no line break, I found a fix for that buried [inside a bug report on sphinx](https://github.com/sphinx-doc/sphinx/issues/1514#issuecomment-742703082) \n",
    "\n",
    "It involves adding some custom css and an extra line to `conf.py`:\n",
    "```python\n",
    "html_css_files = [\n",
    "    'custom.css',\n",
    "]\n",
    "```"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python [conda env:recode]",
   "language": "python",
   "name": "conda-env-recode-py"
  },
  "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.9.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}