我可以抑制Sphinx文档中的变量扩展吗？ [英] Can I suppress variable expansion in Sphinx documentation?

问题描述

在我的代码中，我有

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']

及以后

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

所以在我的Sphinx文档中，使用（例如，使用）。 。自动功能:: 等）我得到了$ code> some_function的签名中扩展的整个长而笨重的价值 X_DEFAULT ：

so that in my Sphinx documentation, using (e.g., using .. autofunction::, etc.) I get the entire long and unwieldy value of X_DEFAULT expanded in the signature for some_function:

some_function （ ...，x =一个''''''''''''''''''''，
'is'，'really'，'丑'，'到'，'看' ，'和'，'over'，'again'，
'every'，'ti我'''''''''''''''''''''''，
'documentation']，... ）

有没有办法在生成的文档中抑制这种替换，理想情况下是回到 X_DEFAULT

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

some_function （ ...，x = X_DEFAULT ，... ）

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

---

我知道我可以手动覆盖我明确列出为Sphinx文档指令的参数的每个函数和方法的签名，但这不是我的目标。我也知道我可以使用 autodoc_docstring_signature 和docstring的第一行，但会产生不良的docstrings，真正用于内省失败的情况（如C）。我怀疑在 autodoc-process-signature 可能是足够的（但不完美），虽然我不确定如何继续。

---

I'm aware that I can manually override the signature for each function and method that I explicitly list as arguments to Sphinx documentation directives, but that's not my goal here. I'm also aware that I could use autodoc_docstring_signature and the first line of the docstring, but that would produce bad docstrings, really intended for cases where introspection fails (like C). I suspect that there's something I could do in autodoc-process-signature that might be adequate (but not perfect), though I'm unsure how to proceed.

推荐答案

一种方法，例如，将在模块级定义的所有值的还原替换为公共常量（由全名无名称识别下划线），在其中定义的模块中可以找到一个唯一的名称：

One approach, that will, for example, "revert" substitution of all values that have been defined at the module level as "public constants" (recognized by all-caps names with no leading underscore) for which a unique name can be found in the module in which it was defined:

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：

---

An alternative is to simply take the docstring directly from the source:

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

这篇关于我可以抑制Sphinx文档中的变量扩展吗？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！