Why does this Python docstring not have newlines in the VS Code hover info?

Question

I have this docstring:

def get_crypto_price(crypto: str, currency: str, max_attempts: int = 3) -> float | None:
   """
   Retrieves the price of a cryptocurrency in a specified currency using the CoinGecko API.

   Args:
      crypto (str): The cryptocurrency to retrieve the price for (e.g., 'bitcoin').  
      currency (str): The currency to retrieve the price in (e.g., 'usd').  
      max_attempts (int): The maximum number of attempts to make before giving up (default: 3).

   Returns:
      float | None: The price of the cryptocurrency in the specified currency, or None if the price could not be retrieved.
   """

But it shows up like this in VS Code, with no newline between the currency and max_attempts lines:

How do I get the max_attempts line to be on a new line in the hover info?

Answer 1

Python docs generally use reStructuredText as their markup format. What you've written with your "Args" and "Returns" are definition lists, where paragraphs in the definition section are separated by empty lines, and two lines in the definition section with no empty line between them are treated as part of the same paragraph. So what I find actually surprising is the fact that VS Code puts a newline in the hover info between the first two lines of your "Args" definition section (and I don't know why it does that. Either it's a bug, or I'm missing something).

If you want to do things the way Python recommends for Sphinx usage, see https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists, https://devguide.python.org/documentation/markup/#quick-reference, https://devguide.python.org/documentation/markup/#directives, and https://devguide.python.org/documentation/markup/#information-units.

Which would look something like this:

"""
Retrieves the price of a cryptocurrency in a specified currency using the CoinGecko API.

:param crypto: The cryptocurrency to retrieve the price for (e.g., 'bitcoin').  
:param currency: The currency to retrieve the price in (e.g., 'usd').  
:param max_attempts: The maximum number of attempts to make before giving up (default: 3).
:return: The price of the cryptocurrency in the specified currency, or None if the price could not be retrieved.
"""

If you don't care about the Sphinx-friendly way of writing documentation, you can just turn your definition section into a bullet list. Ex.

Args:
    - crypto (str): The cryptocurrency to retrieve the price for (e.g., 'bitcoin').
    - currency (str): The currency to retrieve the price in (e.g., 'usd').
    - max_attempts (int): The maximum number of attempts to make before giving up (default: 3).