Sphinx documenting dictionary content (a module constant)

Question

This is somewhat related to How to document a module constant in Python? but not same.

I have a constant in the module (its a dict):

possiblestringencodings = dict(
    StringsAsBytes=1,
    ascii=1,
    utf8=1, utf_8=1, U8=1,
    utf16=2, utf_16=2, U16=2, utf_16_be=2, utf_16_le=2,
    utf32=4, utf_32=4, U32=4, utf_32_be=4, utf_32_le=4,
)

The readthedocs page has (see autodata docs):

.. autodata:: construct.possiblestringencodings

However, this produces the docstring from dict docstring (its ctor). How can I document the content of that dictionary, ONLY its items using Sphinx?

If someone would like to test patching it up, just fork the repo and run "make html" inside docs/ folder. https://github.com/construct/construct/blob/1b53d9122a2c652db64c6558d101caee5bbbab3a/construct/core.py#L1280 https://github.com/construct/construct/blob/1b53d9122a2c652db64c6558d101caee5bbbab3a/docs/api/strings.rst

score 2 · Answer 1 · edited Feb 04 '18 at 18:11

The dictionary data member does not have a docstring so you get the one from the dict class.

Add an empty "documentation comment" immediately before the definition (or a docstring immediately after), and you will only get the dictionary items in the output.

#:
possiblestringencodings = dict(
    StringsAsBytes=1,
    ascii=1,
    utf8=1, utf_8=1, U8=1,
    utf16=2, utf_16=2, U16=2, utf_16_be=2, utf_16_le=2,
    utf32=4, utf_32=4, U32=4, utf_32_be=4, utf_32_le=4,
)

You also need to fully qualify the "core" module:

.. autodata:: construct.core.possiblestringencodings

Sphinx documenting dictionary content (a module constant)

1 Answers1