如何使用Sphinx生成有用的Python对象常量文档？ [英] How can I generate useful documentation of Python object constants with Sphinx?

问题描述

我在一个Python模块(vengeance.directions)中有一些‘常量’，我试图使用Sphinx为其生成合理的文档。这些‘常量’的值是对象(类型：Direction)，而不是文字值，并且不会生成特别有用的文档：

#: North (opposite: SOUTH).
NORTH = _NORTH_SOUTH.direction

#: South (opposite: NORTH).
SOUTH = _NORTH_SOUTH.opposite

#: East (opposite: WEST).
EAST = _EAST_WEST.direction

#: West (opposite: EAST).
WEST = _EAST_WEST.opposite

.rst文件包含以下内容：

.. automodule:: vengeance.directions
    :members:
    :undoc-members:
    :show-inheritance:

生成的输出(或多或少)如下所示：

复仇.方向.EAST=<vengeance.game.Direction object at 0x1046fd690>

东(相对：西)。

复仇.方向.NORTH=<vengeance.game.Direction object at 0x1046fd750>

北(相对：南)。

复仇.方向.SOUTH=<vengeance.game.Direction object at 0x1046fd790>

南(相对：北)。

Revgeance.Directions.WEST=<vengeance.game.Direction object at 0x1046fd6d0>

西方(相对：东方)。

文字值可以生成更有用的文档，例如：

复仇。方向.EAST=2

我希望能够产生类似的结果，删除<vengeance.game.Direction object at ...>，也许用Direction.__str__()方法的值替换它。这也将避免必须添加额外的文档。换句话说，我希望能够简单地写下：

NORTH = _NORTH_SOUTH.direction
SOUTH = _NORTH_SOUTH.opposite
EAST = _EAST_WEST.direction
WEST = _EAST_WEST.opposite

生成：

复仇.方向.EAST=东(相反：西)

复仇方向.NORTH=北(相对：南)

复仇。方向.SOUTH=南(相反：北)

Revgeance.Directions.WEST=West(相反：East)

如何实现此目标？

推荐答案

在Sphinx 1.2(2013年12月10日发布)中，有一个新的annotation选项可用于autoattribute和autodata(但不包括automodule和autoclass)：

模块数据和属性的AutoDoc指令现在支持annotation选项，因此可以覆盖数据/属性值的默认显示。

这并没有使事情像问题中设想的那样简单，但这是一种改进。

另请参阅this SO answer。

这篇关于如何使用Sphinx生成有用的Python对象常量文档？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！