Sphinx - autodata shows str.__doc__

Question

I'm trying to document my python code with Sphinx, but I found a problem documenting some data instantiated with exec; I have a table with names and values that I need to instantiate.

So in my code I wrote something like:

my_vars = [{'name': 'var1', 'value': 'first'},
           {'name': 'var2', 'value': 'second'}]

for var in my_vars:
    exec("{var[name]} = '{var[value]}'".format(var=var))

The problem is with Sphinx: since I'd like to maintain just the source code I used autodata, the corrisponding lines from my .rst file are:

.. autodata:: mymodule.var1

.. autodata:: mymodule.var2

that when built gave me this:

mymodule.var1 = 'first'
    str(string[, encoding[, errors]]) -> str

    Create a new string object from the given encoded string.
    encoding defaults to the current default string encoding.
    errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

mymodule.var2 = 'second'
    str(string[, encoding[, errors]]) -> str

    Create a new string object from the given encoded string.
    encoding defaults to the current default string encoding.
    errors can be ‘strict’, ‘replace’ or ‘ignore’ and defaults to ‘strict’.

I think autodata goes looking into var1.__doc__ for a doc string and there found str.__doc__ (that is the message shown before).

I really don't know what to do and I'm searching for a way of not showing that ugly doc string (but still maintaining mymodule.var1 = 'first').

Or maybe even better a way to show my own doc, like: var1 is this. (but I wouldn't know where to put it).

Answer 1

My suggestion is this: document the variables in the module docstring instead of trying to get something usable from autodata.

mymodule.py:

""" 
This module is...

Module variables:

* var1: var1 doc
* var2: var2 doc
"""

my_vars = [{'name': 'var1', 'value': 'first'},
           {'name': 'var2', 'value': 'second'}]

for var in my_vars:
    exec("{var[name]} = '{var[value]}'".format(var=var))

...
... 

You could also use info fields:

"""

:var var1: var1 doc
:var var2: var2 doc
"""

This works, sort of, but the output is not as nicely formatted as info fields used to document class variables or function parameters.

---

Update: following up on comments about str subclassing. Does this work for you?

from collections import UserString   

my_vars = [{'name': 'var1', 'value': 'first', "doc": "var1 docstring"},
           {'name': 'var2', 'value': 'second', "doc": "var2 docstring"}]

for var in my_vars:
    code = """\
{0} = UserString('{1}')
{0}.__doc__ = '{2}'""".format(var["name"], var["value"], var["doc"])
    exec(code)

Answer 2

I realized how can you fix it. Write smth like this:

x = 55
"""
x is varibble lala
"""

Use automodule directive and Sphinx will make docs for you.