Reference Section to Python Google Docstring

Question

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

Answer 1

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: