如何在VSCode中优雅渲染NumPy风格的文档字符串？

问题背景 #

我正在开发一个解析MESA模拟输出的Python工具库，为了方便自己和Python经验不足的同行使用，采用NumPy风格文档字符串编写函数说明，但在VSCode中悬停查看函数文档时，显示效果杂乱。希望在不使用Sphinx等大型文档生成器、保留标准NumPy风格的前提下，让VSCode能美观清晰地展示这些文档字符串。

解决方案 #

1. 开启VSCode Python插件的NumPy风格支持 #

VSCode的Python插件默认可能未正确识别NumPy格式的文档字符串，需手动配置开启：

• 打开VSCode设置（快捷键Ctrl+,）
• 搜索Python > Docstring Format，选择numpy选项
• 也可直接在settings.json中添加配置：

  "python.analysis.docstringFormat": "numpy"
  

2. 修正文档字符串中的参数名匹配错误 #

你的代码存在参数名不匹配的问题：函数定义的参数是data_start，但文档中误写为data_headers_start，这会导致VSCode解析混乱，需统一参数名称。

3. 规范文档字符串的缩进与换行 #

确保每个参数的描述保持一致的缩进（建议4个空格），删除多余换行或空格，让结构更规整。

修改后的示例代码 #

"""Utilities for reading and processing MESA output files."""

__all__ = [
    "PathLike",
    "read_history",
]

import os

import pandas as pd
import astropy.units as u
from astropy.table import QTable

PathLike = os.PathLike | str | bytes


def read_history(
    path: PathLike = "history.data",
    units: dict[str, u.Unit] | None = None,
    descriptions: dict[str, str] | None = None,
    *,
    meta_start: int = 1,
    data_start: int = 4,
) -> QTable:
    """Read a MESA history file and return it as an astropy `QTable`.

    Parameters
    ----------
    path
        Path to the history file (defaults to "history.data").
    units
        Optional dictionary with units to apply to columns. For example,
        if the history file has columns named "star_age" and "star_mass", and you want
        to assign them units of years and solar masses, respectively, you can pass
        `units={"star_age": u.yr, "star_mass": u.Msun}`. The returned table
        will have the corresponding units applied to the columns.
    descriptions
        Optional dictionary with descriptions to apply to columns.
    meta_start
        Indicates the line number where the metadata of the history file starts.
        Only non-blank and non-comment lines are considered. Starts from zero.
        Defaults to 1 as that is usually where the metadata is located in MESA
        history files (Usually the first line, line 0, is column numbers and then the
        second line, line 1, is column names).
    data_start
        Indicates the line number where the data of the history file starts.
        Only non-blank and non-comment lines are considered. Starts from zero.
        Defaults to 4 as that is usually where the data is located in MESA
        history files (Usually the first 3 lines are lines 0 to 2 for metadata.
        The 4th line is blank so it doesn't count, and the 5th line (line 3) contains
        column numbers, so the data starts at the 6th line which is line 4).

    Returns
    -------
    QTable
        An astropy `QTable` with the data from the history file. The history's metadata
        is stored in the `meta` attribute of the table under the key "history_meta"
        (The `meta` attribute can contain more information, including user custom
        information).
    """
    ...

内容的提问来源于stack exchange，提问作者Shai Avr