Does anyone know of a good way to include references in a python docstring that follows the google formatting? I'm writing a series of fluid property generators. I wanted a way to easily document a reference to the correlation or equations I am using so someone could go read about them or see where they came from. I did the following but it is not properly formatted in VS Code. Does anyone know of any other methods?
def viscosity(self) -> float:
"""Live oil viscosity, cP
Return the live oil viscosity, cP.
Requires pressure and temperature condition to previously be set.
Args:
None
Returns:
uoil (float): live oil viscosity, cP
References:
Fundamental Principles of Reservoir Engineering, B.Towler (2002) Page 23
Correlations for Fluid Physical Property... Vasquez and Beggs (1980)
"""
pabs = self._pressa # absolute pressure
temp = self.temp # deg F
oil_api = self.oil_api
Most ways I've found to add a newline to the displayed code hint are quite clunky. For example:
Adding a \n
after the first reference results in a wider gap between the two references:
"""
...
References:
Fundamental Principles of Reservoir Engineering, B.Towler (2002) Page 23\n
Correlations for Fluid Physical Property... Vasquez and Beggs (1980)
...
"""
Adding a space before the second reference causes the first character of both lines to be unaligned:
"""
...
References:
Fundamental Principles of Reservoir Engineering, B.Towler (2002) Page 23
Correlations for Fluid Physical Property... Vasquez and Beggs (1980)
...
"""
You could instead use an unordered list to format your references:
def viscosity(self) -> float:
"""Live oil viscosity, cP
Return the live oil viscosity, cP.
Requires pressure and temperature condition to previously be set.
Args:
None
Returns:
uoil (float): live oil viscosity, cP
References:
- Fundamental Principles of Reservoir Engineering, B.Towler (2002) Page 23
- Correlations for Fluid Physical Property... Vasquez and Beggs (1980)
"""
pass
In the code hint, this unordered list appears like so: