sphinx.ext.autodoc: Keeping names of constants in signature

Question

I'm using Sphinx's autodoc feature to document my API.

Example:

DEFAULT_OPTION = 'default'
def do_something(msg, option=DEFAULT_OPTION):
    print msg

The generated documentation now shows the following signature:

do_something(msg, option='default')

How can I tell Sphinx to keep the name of the constant value i.e.

do_something(msg, option=DEFAULT_OPTION)

?

Is there an option I have overlooked? If at all possible, I'd like NOT to write all signature by hand again.

Answer 1

Since version 4.0 of Sphinx there is a new configuration option (autodoc_preserve_defaults). Setting

autodoc_preserve_defaults = True

in your conf.py will preserve the default values as they are in the source code.

Answer 2

You probably have to override the signature by hand in the reST file.

It's hard to come up with a better answer. Autodoc imports the modules it documents, so all module-level code (including default function arguments) is executed.

See also these similar questions: here and here.

---

Update:

I just realized that there is another option. You can override the signature by including it as the very first line of the docstring. See the documentation of the autodoc_docstring_signature configuration variable, and this answer.