Dans Sphinx, puis-je enregistrer un tas de mots-clés qui devraient toujours être traduits en liens?

Question

Mes chaînes de document contiennent des références à d'autres classes python que j'ai définies. Chaque fois que Sphinx rencontre une de ces classes, je veux qu'il insère un lien vers la documentation de cette autre classe. Est-ce possible dans Sphinx?

Plus précisément, j'ai une doc string comme:

'''This class contains a bunch of Foo objects''' 

Je pourrais écrire:

'''This class contains a bunch of :class:`~foo.Foo` objects''' 

mais je préférerais que Sphinx trouve tout le texte correspondant Foo et fait paraître comme si je devais tapé : class: ~foo.Foo

Answer 1

Vous pouvez utiliser des macros.

Dans mon projet, j'ai un fichier d'en-tête qui contient toutes les classes "importantes" et les fonctions globales ainsi que leur abréviation. Deux lignes par exemple:

.. |PostItem| replace:: :class:`PostItem <hklib.PostItem>` 
.. |PostNotFoundError| replace:: :class:`PostNotFoundError <hklib.PostNotFoundError>` 

Dans mes rst fichiers, j'inclure ce fichier d'en-tête. Ensuite, je peux utiliser les macros dans un fichier rst:

.. include:: defs.hrst 

|PostItem| is a nice class. |PostNotFoundError|, on the other hand is not. 

(.. Vous pouvez inclure docstrings de fichiers source Python ainsi, en utilisant l'extension autogen macros dans ceux-ci seront remplacés ainsi)

A propos de votre exemple: J'ajouterais Foo au fichier d'en-tête et écrirais la docstring de cette manière:

'''This class contains a bunch of |Foo| objects''' 

Answer 2

Sphinx dispose d'un grand nombre de rôles de texte interprétés pour cela.

http://sphinx.pocoo.org/markup/inline.html#cross-referencing-python-objects

Je veux entrer Foo et ont Sphinx interpréter comme si je l'avais écrit: Classe: ~foo.Foo

Cela semble peu pratique. Il semble que cela paralyserait la RST en essayant d'analyser votre texte. La recherche de texte interprété et les quelques règles de cotation prises en charge par RST (*_|`) concernent la limite qui est pratique. Ce que vous demandez peut mener à la prise de RST toute la journée pour vérifier chaque instance Foo dans tous les contextes possibles et déterminer si vous voulez un lien ou non. Vous ne le souhaitez que dans les instances non-décorées de Foo; recherche triviale et remplacer ne fonctionnerait pas.

Vous pouvez modifier le pré-traitement de docstring.

http://sphinx.pocoo.org/ext/autodoc.html#docstring-preprocessing

Cela peut vous permettre d'essayer une stratégie globale de recherche et de remplacer le texte de votre docstring.