web-dev-qa-db-fra.com

Comment référencer un paramètre de fonction documenté Python à l'aide du balisage Sphinx?

Je voudrais référencer un paramètre de fonction précédemment documenté ailleurs dans une docstring Python. Considérez l'exemple suivant (certes complètement artificiel):

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()

Existe-t-il un moyen simple d'incorporer une référence de paramètre à l'aide du balisage Sphinx, ou cela se produira-t-il automatiquement?

(Je suis un débutant complet sur Sphinx. J'ai numérisé les documents Sphinx et je n'ai pas trouvé de réponse à cette question, ou un exemple démontrant un balisage approprié.)

pythondocumentationpython-sphinxdocstring
41
Inactivist

Je viens de créer une extension pour accomplir cette tâche. Jusqu'à présent, il semble fonctionner avec une version HTML autonome et en plus avec readthedocs (après quelques ajustements supplémentaires).

l'extension est disponible sur: https://pypi.python.org/pypi/sphinx-paramlinks/ .

Je le déploie en ce moment pour les projets Alembic et SQLAlchemy. ( exemple ).

Je suis en désaccord avec la suggestion selon laquelle la liaison avec les paramètres signifie que les documents sont trop longs. La bibliothèque standard Python est un mauvais exemple ici car les fonctions stdlib sont nécessairement granulaires et simples. Un logiciel qui accomplit une tâche plus grossière, où une fonction unique surmonte un problème complexe pour être résolu, aura souvent des paramètres qui nécessitent beaucoup plus d'explications; cette explication est souvent très utile comme solution à un problème particulier ailleurs, et donc être capable de s'y connecter est très important.

25
zzzeek

Il n'y a pas de moyen simple d'obtenir une référence directe à un paramètre d'une fonction avec sphinx et je ne connais pas d'extension pour ce problème.

Le documentation du domaine python explique quels objets peuvent être croisés.

Une façon possible de donner à l'utilisateur une référence au paramètre bar de la fonction foo serait

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

Peut-être qu'une référence directe serait possible en écrivant une extension.

30
bmu

Pour ceux qui souhaitent utiliser sphinx-paramlinks avec sphinx.ext.napoleon voici un patch. Trouvez simplement le bon fragment dans le sphinx-paramlinks code source (sphinx_paramlinks\sphinx_paramlinks.py, quelque part autour de la ligne 50) et remplacez-le par ceci:

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)

Remarque: n'oubliez pas le tiret droit.

Je ne suis pas un spécialiste du Sphinx, mais cela semble faire le travail.

2
Tomasz Kurgan

Si vous cherchez un moyen de lier directement à la définition bar de foo, votre documentation est trop longue ou vous demandez à votre lecteur d'ignorer la forêt pour un arbre ou une combinaison des deux.

Prenant un exemple de Defaultdict Examples :

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

si je ne peux pas prendre la peine de lire cinq phrases dans collections.defaultdict pour trouver la signification de default_factory Je ne mérite probablement pas d'être là-bas.

Notez que la syntaxe de référence d'attribut est la même que dans la section ci-dessus:

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

mais il semble que Sphinx n'atteigne pas la portée de la section actuelle et rend donc la référence ultérieure sous la forme d'un texte stylisé plutôt que comme une ancre. Cela ne me surprendrait pas si c'était intentionnel.

0
msw