{
 "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  # noqa: F401\n",
    "except ImportError:\n",
    "    !python -m pip install openmdao[notebooks]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Sphinx and Decorated Methods\n",
    "\n",
    "\n",
    "Sphinx does not always correctly handle decorated methods. To ensure a method's\n",
    "call signature appears correctly in the docs, use `functools.wraps` in the definition\n",
    "of the decorator. This will ensure that metadata associated with the function or method,\n",
    "such as the docstring, are correctly applied to the decorated function.\n",
    "\n",
    "For example, if you have decorator that looks like this:\n",
    "\n",
    "```\n",
    "    import functools\n",
    "\n",
    "    def mydecorator(f):\n",
    "        @functools.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 generated documentation will correctly document the inputs and partials arguments.\n",
    "Without it, the documented arguments would be `*args` and `**kwargs`, the arguments of the decorator itself."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "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
}
