Skip to main content
 首页 » 编程设计

python之在 Sphinx 中记录带有长描述的参数

2025年05月04日1598°冷暖

我正在使用 Sphinx 记录我的 Python 类,有时我想给我的参数提供很长的描述以详细解释某些内容。不幸的是,Sphinx 为我生成了丑陋的输出,这浪费了大量空间并破坏了整个页面的外观:

可以看出,Sphinx 创建了一个表,然后将“Parameters”标题放在左侧单元格中,将实际的参数列表放在右侧单元格中。但是应该有办法避免完全创建这个表。在玩完页面 DOM 树之后,我终于可以证明我想要实现:

是否有内置方法可以执行此操作,或者我必须为 Sphinx 主题或 Sphinx 本身创建 PR?

请您参考如下方法:

发布后an issue到 Sphinx bug-tracker 并且没有回应,我决定推出我自己的解决方案(更好地说,hack)。为了实现我想要的外观,我编写了一个简单的 Sphinx 扩展,它对生成的 HTML 代码进行后处理。它可以在 PyPI 上找到:

这似乎不是解决问题的最佳方法,但我想要更改的行为在 docutils 中进行了深度硬编码,而不是 Sphinx。