tutorials/begin.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Mydocstring tutorial\n",
    "Welcome to the mydocstring tutorial. This tutorial will show you how to parse a function that contains a docstring that has been documented using the Google-style docstring format.\n",
    "\n",
    "Before we begin you should know that mydocstring is not a complete documentation system. Instead, it contains a few core components that are designed to help you build you a documentation system just the way you want it. In essence, mydocstring parses docstrings and packs documentation for sections, arguments, and so forth into dictoinary. At the end of you day, you have control of the data that makes up a docstring, and you can do whatever you want with it.\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Extracting info from functions and class methods\n",
    "\n",
    "\n",
    "### Functions\n",
    "To get started, we need to have some data to work with. Consider the following string that contains source code for a function for adding two numbers. You can modify it if you like."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "source = (\"\"\"def add(a: float, b: float) -> float:\n",
    "                \\\"\"\"\n",
    "                Add two floating-point numbers together.\n",
    "    \n",
    "                Args:\n",
    "                    a : First float to add.\n",
    "                    b : Second float to add.\n",
    "                        \n",
    "                Returns:\n",
    "                    The result of the operation.\n",
    "                \\\"\"\"\n",
    "                return a + b\n",
    "                \"\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that in the example above, the docstring of the function is encapulsated in \"\"\" quotes. This is necessary for the detection of the docstring to work correctly for python source code. An exception is auto-generated docstrings from pybind, which we will explore later. Also, the signature is annotated with argument types, and a return type. That said, annotations are optional."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now, let's extract information from this function. It is important to pick the right extraction tool for the job. In this case, since we are working with usual python source code, we want to use `PyExtract` (use `PyBindExtract` for pybind docstrings). "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [],
   "source": [
    "import mydocstring as mydoc"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "extract = mydoc.extract.PyExtract(source)\n",
    "add = extract.extract('add')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The return value `add` is a dictionary that contains the function signature, docstring, and so forth. The reason why we need to specify what function to extract is because the source code can contain multiple functions, and maybe only some of them are of interest to us."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is the docstring"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "\n",
      "Add two floating-point numbers together.\n",
      "\n",
      "Args:\n",
      "    a : First float to add.\n",
      "    b : Second float to add.\n",
      "        \n",
      "Returns:\n",
      "    The result of the operation.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(add['docstring'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here are the arguments, their annotations, as well as the return type. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'args': {'a': 'float', 'b': 'float'}, 'return_annotation': 'float'}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "add['parsed_signature']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If you ever need to parse a signature on its own you can do so as follows."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'args': {'a': 'int', 'b': 'int', 'default': 'bool=True'},\n",
       " 'return_annotation': 'int'}"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "mydoc.parse.parse_signature('(a: int, b: int, default: bool=True) -> int)')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Class methods\n",
    "Now, let's look at a class method and how to extract one of those. \n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [],
   "source": [
    "source = (\"\"\"\n",
    "            class Math(object):\n",
    "                \\\"\"\"\n",
    "                Class that contains mathematical operations.\n",
    "                \\\"\"\"\n",
    "                def add(self, a: float, b: float) -> float:\n",
    "                    \\\"\"\"\n",
    "                    Add two floating-point numbers together.\n",
    "    \n",
    "                    Args:\n",
    "                        a : First float to add.\n",
    "                        b : Second float to add.\n",
    "                        \n",
    "                    Returns:\n",
    "                        The result of the operation.\n",
    "                    \\\"\"\"\n",
    "                    return a + b\n",
    "            \"\"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This code snippet contains the `add` function from before, and also a class that contains method with the same name as the `add` function. To signal to the extract function what we want to extract, we use the class name to distinguish between a function and a method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "extract = mydoc.extract.PyExtract(source)\n",
    "math = extract.extract('Math')\n",
    "math_add = extract.extract('Math.add') "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'(self, a: float, b: float) -> float'"
      ]
     },
     "execution_count": 9,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "math_add['signature']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Pybind\n",
    "Docstrings generated by pybind look slightly different from the ones in the Python source code. The key difference is that both the function name and the documentation is contained in the same string. To parse these strings, we need to use `PyBindExtract`, like this."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [],
   "source": [
    "source = \"\"\"add(a: float, b: float) -> float\n",
    "            Add two floating-point numbers together.\n",
    "    \n",
    "            Args:\n",
    "                a : First float to add.\n",
    "                b : Second float to add.\n",
    "                        \n",
    "            Returns:\n",
    "                The result of the operation.\n",
    "        \"\"\"\n",
    "add = mydoc.extract.PyBindExtract(source).extract('add')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Besides the slightly different syntax in the string itself, and the need to use `PyBindExtract` everything else works exactly the same as before. For example, to inspect the parsed signature, we use"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'args': {'a': 'float', 'b': 'float'}, 'return_annotation': 'float'}"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "add['parsed_signature']"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Parsing docstrings\n",
    "Let's see how to parse a docstring stored in the google docstring format. We import the `GoogleDocString` parser tool and call its `parse` function. It is a good idea to pass the parsed signature as well because then the docstring parser can warn about any undocumented arguments."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [],
   "source": [
    "source = (\"\"\"def add(a: float, b: float) -> float:\n",
    "                \\\"\"\"\n",
    "                Add two floating-point numbers together.\n",
    "    \n",
    "                Args:\n",
    "                    a : First float to add.\n",
    "                    b : Second float to add.\n",
    "                        \n",
    "                Returns:\n",
    "                    The result of the operation.\n",
    "                \\\"\"\"\n",
    "                return a + b\n",
    "                \"\"\")\n",
    "add = mydoc.extract.PyExtract(source).extract('add')\n",
    "add_doc = mydoc.parse.GoogleDocString(add['docstring'], signature=add['parsed_signature']).parse()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The parser works by splitting a docstring section by section. The example above contains three sections, the first one starting with *Add two...*, then there is section *Args..*, and finally a section *Returns*. Each section starts with an optional header (such as *Args*) and can contain an argument or text."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "\n",
      "Add two floating-point numbers together.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print(add_doc[0]['text'])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is the argument list found in the second section."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "a(float): First float to add.\n",
      "b(float): Second float to add.\n",
      "    \n"
     ]
    }
   ],
   "source": [
    "args = add_doc[1]['args']\n",
    "for arg in args:\n",
    "    print('%s(%s): %s'% (arg['field'], arg['signature'], arg['description']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that the type has been automatically inferred. This was possible because we passed `add['parsed_signature']` during initialization."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here is the header and text in the last section."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Returns: The result of the operation.\n",
      "\n"
     ]
    }
   ],
   "source": [
    "print('%s: %s' %(add_doc[2]['header'], add_doc[2]['text']))"
   ]
  }
 ],
 "metadata": {
  "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.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}