CODEWITHSUNDEEP
python-sphinx
Matthew Murdoch
Matthew Murdoch

Reputation: 31453

How can I generate useful documentation of Python object constants with Sphinx?

I have some 'constants' in a Python module (vengeance.directions) for which I am trying to generate sensible documentation using Sphinx. The values of these 'constants' are objects (of type: Direction) rather than literal values and don't generate particularly useful documentation:

#: 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

The .rst file contains this:

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

And the generated output looks (more or less) like this:

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

East (opposite: WEST).

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

North (opposite: SOUTH).

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

South (opposite: NORTH).

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

West (opposite: EAST).

Literal values produce much more helpful documentation, for example:

vengeance.directions.EAST = 2

I'd like to be able to produce something similar, removing the <vengeance.game.Direction object at ...> and perhaps replacing it with the value of the Direction.__str__() method. This would also prevent having to add additional documentation. In other words I'd like to be able to simply write:

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

to generate:

vengeance.directions.EAST = East (opposite: WEST)

vengeance.directions.NORTH = North (opposite: SOUTH)

vengeance.directions.SOUTH = South (opposite: NORTH)

vengeance.directions.WEST = West (opposite: EAST)

How can I achieve this?

Upvotes: 2

Views: 1548

Answers (1)

mzjn
mzjn

Reputation: 50947

In Sphinx 1.2 (released Dec 10, 2013), there is a new annotation option for autoattribute and autodata (but not automodule and autoclass) that might help:

Autodoc directives for module data and attributes now support an annotation option, so that the default display of the data/attribute value can be overridden.

This does not make things as simple as envisioned in the question, but it is an improvement.

See also this SO answer.

Upvotes: 1

Related Questions