resultado - parametros por omision python

¿Cómo hago referencia a un parámetro documentado de la función Python utilizando el marcado Sphinx?

Question

Me gustaría hacer referencia a un parámetro de función previamente documentado en otro lugar en una docstring de Python. Considere el siguiente ejemplo (ciertamente completamente artificial):

def foo(bar):
"""Perform foo action
:param bar: The bar parameter
"""
def nested():
"""Some nested function that depends on enclosing scope''s bar parameter.
I''d like to reference function foo''s bar parameter here
with a link, is that possible?"""
return bar * bar
# ...
return nested()

¿Hay una manera simple de insertar una referencia de parámetro usando el marcado de Sphinx, o esto sucederá automágicamente?

(Soy un novato completo de Sphinx. He estado escaneando los documentos de Sphinx y no he encontrado una respuesta a esta pregunta, o un ejemplo que demuestre el marcado adecuado).

Answer 1

Acabo de construir una extensión para realizar esta tarea. Hasta ahora, parece estar funcionando con la creación de HTML independiente y, además, con readthedocs (después de algunos ajustes más).

la extensión está disponible en: https://pypi.python.org/pypi/sphinx-paramlinks/ .

Lo estoy implementando ahora mismo para los proyectos de Alembic y SQLAlchemy. ( sample )

Tomo desacuerdo con la sugerencia de que vincular a params significa que los documentos son demasiado extensos. La biblioteca estándar de Python es un ejemplo pobre aquí ya que las funciones stdlib son necesariamente granulares y simples. El software que está llevando a cabo una tarea de grano más grueso, donde una única función se monta sobre un problema complejo a resolver, a menudo tendrá parámetros que requieren mucha más explicación; esta explicación a menudo es bastante valiosa ya que la solución a un problema particular en otro lugar, y por lo tanto poder vincularse a ella es muy importante.

Answer 2

No hay una forma simple de obtener una referencia directa a un parámetro de una función con sphinx y no conozco una extensión para este problema.

La documentación del dominio python explica a qué objetos se puede hacer referencia cruzada.

Una posible forma de darle al usuario una referencia a la bar de parámetros de la función foo sería

See parameter ``bar`` in :func:`foo`.

Tal vez sería posible una referencia directa escribiendo una extensión.

Answer 3

Para aquellos que quieran usar sphinx-paramlinks con sphinx.ext.napoleon aquí hay un parche. Simple encuentra el fragmento correcto en el código fuente de sphinx-paramlinks (sphinx_paramlinks / sphinx_paramlinks.py, en algún lugar alrededor de la línea 50) y reemplázalo con esto:

def cvt(m):
directive, modifier, objname, paramname = (
m.group(1), m.group(2) or '''', name, m.group(3))
if directive == ''param'':
refname = _refname_from_paramname(paramname, strip_markup=True)
item = (''single'', ''%s (%s parameter)'' % (refname, objname),
''%s.params.%s'' % (objname, refname), '''')
if LooseVersion(__version__) >= LooseVersion(''1.4.0''):
item += (None,)
doc_idx.append(item)
return ":%s %s_sphinx_paramlinks_%s.%s:" % (
directive, modifier, objname, paramname)
return re.sub(r''^:(param|type) ([^:]+? )?([^:]+?):'', cvt, line)

Nota: recuerda sobre la sangría correcta.

No soy un especialista de Sphinx, pero parece que hace el trabajo bien.

Answer 4

Si está buscando una forma de vincular directamente con la definición de bar de foo , su documentación es demasiado extensa o le está pidiendo a su lector que ignore el bosque por un árbol o alguna combinación de ambos.

Tomando un ejemplo de defaultdict Ejemplos :

Setting the :attr:`default_factory` to :class:`int` makes the
:class:`defaultdict` useful for counting (like a bag or multiset in other
languages):

si no puedo molestarme en leer cinco oraciones en collections.defaultdict para encontrar el significado de default_factory , probablemente no merezco ser conducido allí.

Tenga en cuenta que la sintaxis de referencia del atributo es la misma que en la sección anterior:

The first argument provides the initial value for the :attr:`default_factory`
attribute; it defaults to ``None``.

pero parece que Sphinx no sale del alcance de la sección actual y, por lo tanto, representa la referencia posterior como texto con estilo en lugar de como un ancla. No me sorprendería si esto fuera intencional.