# Functions

GS Quant uses Sphinx to generate python API documentation automatically from the source code.

## Type Hinting

Since Python 3.5, functions can use type hinting to document both parameter and return types:

import pandas as pd

def abs(x: pd.Series) -> pd.Series:
"""Docstring"""

# function code

Each variable can be typed through the syntax param: type. The abs function above has a parameter x which is documented as type pd.Series, which is a pandas Series object. The -> syntax is used to declare the return type of the function. The abs function above also returns a pandas Series object.

## Docstring

Functions should use Docstrings per PEP 257 standard to document usage. Python function documentation should have the following components:

• Function title
• Parameters and return type
• Usage info
• Examples

Here's an example of a doc string:

def my_func(x: int) -> str:
"""
Title / one line description

:param x: description of parameter x
:return: description of return value

**Usage**

Describe how to use the function should be used

**Examples**

Provide one or more examples:

result = my_func(1)

:func:his_func :func:her_func
"""
# function code

## Mathematical Formulas

The GS Quant documentation supports inline LaTex within python docstrings in order to render mathematical formulae. This can be declared using the :math: declaration. For example:

import pandas as pd

def abs(x: pd.Series) -> pd.Series:
"""Absolute value

:math:R_t = |X_t|
"""
# function code

Everything inside the math block quote marks will be rendered as LaTeX-formatted math.

## Full Example

See below for an example of a fully documented function:

def abs(x: pd.Series) -> pd.Series:
"""
Absolute value of each element in series

:param x: date-based time series of prices
:return: date-based time series of absolute value

**Usage**

Return the absolute value of :math:X. For each value in time series :math:X_t, return :math:X_t if :math:X_t
is greater than or equal to 0; otherwise return :math:-X_t:

:math:R_t = |X_t|

Equivalent to :math:R_t = \sqrt{X_t^2}

**Examples**

Generate price series and take absolute value of :math:X_t-100

>>> prices = generate_series(100) - 100
>>> abs_(prices)

:func:exp :func:sqrt
return abs(x)