如何使用Sphinx生成Python对象常量的有用文档？

Question

我在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:

生成的输出看起来（或多或少）像这样：

  

vengeance.directions.EAST = <vengeance.game.Direction object at 0x1046fd690>

     

    东（对面：WEST）。

  

     

vengeance.directions.NORTH = <vengeance.game.Direction object at 0x1046fd750>

     

    北方（对面：南方）。

  

     

vengeance.directions.SOUTH = <vengeance.game.Direction object at 0x1046fd790>

     

    南方（对面：北方）。

  

     

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

     

    西部（对面：EAST）。

  

文字值会产生更多有用的文档，例如：

  

vengeance.directions.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

生成：

  

vengeance.directions.EAST = East（对面：WEST）

     

vengeance.directions.NORTH = North（对面：南方）

     

vengeance.directions.SOUTH = South（对面：NORTH）

     

vengeance.directions.WEST = West（对面：EAST）

我怎样才能做到这一点？

Answer 1

在Sphinx 1.2（2013年12月10日发布）中，autoattribute和autodata有一个新的annotation选项（但不是automodule和{{ 1}}）可能会有所帮助：

  

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

这并不会使问题中的设想变得如此简单，但这是一种改进。

另见this SO answer。