Existe-t-il un moyen dans Sphinx/Pygments de mettre en évidence une ou plusieurs lignes de code dans les inclusions littérales?

Question

Dans certains documents, je suis sphinx à écrire, je suis notamment des exemples de code à partir d'un fichier accessoire comme ceci:

.. literalinclude:: mymodule.py 
    :pyobject: MyClass 
    :linenos: 

Ce doc particulier est un tutoriel, où les classes sont construire étape par étape. Ce que je voudrais faire est d'inclure la classe entière ou une méthode unique, et souligner seulement les lignes d'intérêt pour cette section. De cette façon, le contexte est préservé, mais les parties intéressantes sont évidentes en un coup d'œil. À l'heure actuelle, je me suis contenté de faire référence aux numéros de ligne dans le texte, ce qui est acceptable, mais loin d'être idéal.

En regardant les docs et le code pour sphinx et pygments je ne trouve pas un moyen évident de le faire. Je ne suis pas opposé à les patcher ou à faire quelque chose de difficile dans conf.py, mais je me demandais si quelqu'un avait résolu cela.

Answer 1

Vous pouvez patcher la directive LiteralInclude de sphynx dans sphynx/directives/code.py

• Il vous aurait besoin de faire quelque chose de sorte que lorsque vous incluez le code, vous pouvez spécifier une ligne de début/fin de souligner dans cet extrait .
• La deuxième étape nécessiterait de créer des façons de mettre en évidence les choses différemment. L'approche la plus simple est que la partie sans accent n'est pas mise en évidence et la partie avec accentuation est mise en évidence. Cela éviterait de faire du piratage plus complexe des styles et de les mettre en évidence.

Cela donne par exemple une nouvelle option lignes accent dans la directive literalinclude que vous pouvez utiliser cette façon:

.. literalinclude:: ../sphinx/directives/code.py 
    :pyobject: Highlight 
    :lines-emphasis: 6,13 

où la ligne désaccentuation est une ligne de départ, ligne de fin par rapport au code inclus , première ligne est 1.

l'utilisation 0.6.5 à sphynx pypi.python.org/pypi/Sphinx/0.6.5 comme base un code.py patché Quicky est là: http://paste.pocoo.org/show/194456/

Notez que les éléments suivants serait equi valences:

Utilisation du sphynx standard (à peu près ce que suggère S. Lott):

.. literalinclude:: ../sphinx/directives/code.py 
    :language: none 
    :lines: 0-36 
.. literalinclude:: ../sphinx/directives/code.py 
    :lines: 36-46 
.. literalinclude:: ../sphinx/directives/code.py 
    :language: none 
    :lines: 37- 

... et en utilisant le sphynx patché:

.. literalinclude:: ../sphinx/directives/code.py 
    :lines-emphasis: 37,47 

Par conséquent, il peut pas être exactement ce que Tu recherches. Le correctif crée un nouveau nœud pour chacune des sections en surbrillance ou non mises en surbrillance du code. Chacun d'entre eux sera rendu par Sphinx comme une section distincte < div> et < pre>. Pour aller au-delà, vous voudrez peut-être créer une feuille de style qui ferait mieux d'extraire les lignes avec emphase. D'autres hacks pourraient avoir besoin d'aller au plus profond des entrailles de Sphinx et Pygments pour avoir un style souligné sans couture généré directement là: pas trivial.

/HTH

Answer 2

Sphinx dispose désormais d'une directive emphasize-lines pour littéral comprend:

http://sphinx-doc.org/markup/code.html#includes