Can I suppress variable extension in Sphinx documentation?

Question

In my code I have

X_DEFAULT = ['a', 'long', 'list', 'of', 'values', 'that', 'is', 'really', 'ugly', 'to', 'see', 'over', 'and', 'over', 'again', 'every', 'time', 'it', 'is', 'referred', 'to', 'in', 'the', 'documentation']

and later

def some_function(..., x=X_DEFAULT, ...):

so in my Sphinx documentation, using (e.g. using .. autofunction::, etc.), I get all the long and cumbersome value X_DEFAULTextended in the signature for some_function:

some_function (..., x = ['a', 'long', 'list', 'of', 'values',' that ',' "is", "really", "ugly", "k", "see", "above", "and", "above", "again", "everyone", "time", "this", "is", "refer", "to", "to", "to ", 'documentation'], ...)

Is there a way to suppress this substitution in the generated documentation, ideally with reference to the definition X_DEFAULT:

some_function ( ..., x = X_DEFAULT , ... )

---

I know that I can manually override the signature for each function and method, which I explicitly list as arguments for the Sphinx documentation directives, but that is not my goal here. I also know that I could use the autodoc_docstring_signaturefirst docstring line too, but this would create bad docstrings really meant for cases where introspection fails (like C). I suspect that there is something that I could do in autodoc-process-signaturethat might be adequate (but not ideal), although I am not sure how to proceed.

Answer 1

, , , "" , " " ( - ), , :

def pretty_signature(app, what, name, obj, options, signature, return_annotation):
    if what not in ('function', 'method', 'class'):
        return

    if signature is None:
        return

    import inspect
    mod = inspect.getmodule(obj)

    new_sig = signature
    # Get all-caps names with no leading underscore
    global_names = [name for name in dir(mod) if name.isupper() if name[0] != '_']
    # Get only names of variables with distinct values
    names_to_replace = [name for name in global_names
                        if [mod.__dict__[n] for n in global_names].count(mod.__dict__[name]) == 1]
    # Substitute name for value in signature, including quotes in a string value
    for var_name in names_to_replace:
        var_value = mod.__dict__[var_name]
        value_string = str(var_value) if type(var_value) is not str else "'{0}'".format(var_value)
        new_sig = new_sig.replace(value_string, var_name)

    return new_sig, return_annotation

def setup(app):
    app.connect('autodoc-process-signature', pretty_signature)

---

docstring :

import inspect
import re

def pretty_signature(app, what, name, obj, options, signature, return_annotation):
    """Prevent substitution of values for names in signatures by preserving source text."""
    if what not in ('function', 'method', 'class') or signature is None:
        return

    new_sig = signature
    if inspect.isfunction(obj) or inspect.isclass(obj) or inspect.ismethod(obj):
        sig_obj = obj if not inspect.isclass(obj) else obj.__init__
        sig_re = '\((self|cls)?,?\s*(.*?)\)\:'
        new_sig = ' '.join(re.search(sig_re, inspect.getsource(sig_obj), re.S).group(2).replace('\n', '').split())
        new_sig = '(' + new_sig + ')'

    return new_sig, return_annotation