{
 "cells": [
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": [
     "remove-input",
     "active-ipynb",
     "remove-output"
    ]
   },
   "outputs": [],
   "source": [
    "try:\n",
    "    from openmdao.utils.notebook_utils import notebook_mode\n",
    "except ImportError:\n",
    "    !python -m pip install openmdao[notebooks]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Sphinx and Decorated Methods\n",
    "",
    "\n",
    "Sphinx does not correctly handle decorated methods. To ensure a method's\n",
    "call signature appears correctly in the docs, put the call signature of the method\n",
    "into the first line of the docstring.\n",
    "\n",
    "For example, if you have decorator that looks like this:\n",
    "\n",
    "```\n",
    "    from functools import wraps\n",
    "\n",
    "    def mydecorator(f):\n",
    "        @wraps(f)\n",
    "        def wrapped(*args, **kwargs):\n",
    "            print \"Before decorated function\"\n",
    "            r = f(*args, **kwargs)\n",
    "            print \"After decorated function\"\n",
    "            return r\n",
    "        return wrapped\n",
    "```\n",
    "\n",
    "and a method that looks like this and has the decorator applied to it:\n",
    "\n",
    "```\n",
    "    @mydecorator\n",
    "    def compute_partials(self, inputs, partials):\n",
    "        \"\"\"\n",
    "        Compute sub-jacobian parts / factorization.\n",
    "\n",
    "        Parameters\n",
    "        ----------\n",
    "        inputs : Vector\n",
    "            unscaled, dimensional input variables read via inputs[key]\n",
    "        partials : Jacobian\n",
    "            sub-jac components written to partials[output_name, input_name]\n",
    "        \"\"\"\n",
    "\n",
    "        pass\n",
    "```\n",
    "\n",
    "The docs will look like this:\n",
    "\n",
    "![The Sphinx generated documentation for a method that is decorated but nothing fixing\n",
    "        the problem in the docstring](images/decorated_method_incorrect_docs.png)\n",
    "\n",
    "But if we add the call signature of the method to the docstring as the first line like this:\n",
    "\n",
    "```\n",
    "    @mydecorator\n",
    "    def compute_partials(self, inputs, partials):\n",
    "        \"\"\"\n",
    "        Compute sub-jacobian parts / factorization.\n",
    "\n",
    "        Parameters\n",
    "        ----------\n",
    "        inputs : Vector\n",
    "            unscaled, dimensional input variables read via inputs[key]\n",
    "        partials : Jacobian\n",
    "            sub-jac components written to partials[output_name, input_name]\n",
    "        \"\"\"\n",
    "\n",
    "        pass\n",
    "\n",
    "```\n",
    "\n",
    "The documentation that results shows the correct call signature:\n",
    "\n",
    "![The Sphinx generated documentation for a method that is decorated and has the correct c\n",
    "         all string in the docstring](images/decorated_method_correct_docs.png)\n"
   ]
  }
 ],
 "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.8.1"
  },
  "orphan": true
 },
 "nbformat": 4,
 "nbformat_minor": 4
}
