¿Hay alguna manera en Sphinx/Pygments de enfatizar una o más líneas de código en includes literal?

En algunos documentos esfinge estoy escribiendo, estoy incluyendo ejemplos de código de un archivo auxiliar, así:¿Hay alguna manera en Sphinx/Pygments de enfatizar una o más líneas de código en includes literal?

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

Este documento en particular es un tutorial, donde las clases son construir paso a paso. Lo que me gustaría hacer es incluir toda la clase o un solo método, y enfatizar solo las líneas de interés de esa sección. De esta manera, el contexto se conserva, pero las partes interesantes son obvias de un vistazo. En este momento, he recurrido a solo referirme a los números de línea en el texto, lo cual está bien, pero está lejos de ser ideal.

Mirando los documentos y el código para esfinge y pygments no encuentro una manera obvia de hacerlo. No estoy en contra de parchearlos o hacer algo complicado en conf.py, pero me preguntaba si alguien había resuelto esto.

Fuente

2010-03-18 Casey Duncan

"De esa manera el contexto se conserva, pero las partes interesantes son evidentes a simple vista" Me acuerdo con esta afirmación, yo mismo. No estoy seguro de lo que estás haciendo realmente vale mucho esfuerzo. Quizás podría probar otras presentaciones usando ': lines:' para seleccionar líneas individuales del archivo. –

Ciertamente hago eso. Pero hay casos en que es inadecuado. En particular, cuando intento construir sobre cosas creadas anteriormente en el tutorial. Un nuevo concepto puede requerir agregar nuevas líneas a un constructor de clase creado anteriormente. Me gustaría mostrar el constructor en su totalidad para el contexto, pero enfatizar las líneas que se agregaron, algo así como un diff. El lector ya estaría familiarizado con el código existente, por lo que no necesita explicación, pero el contexto donde se agregan las nuevas líneas es importante para la comprensión del panorama general. –

Esto sería muy útil. – codeape

Se puede parchear Directiva LiteralInclude de la Esfinge en Sphinx/directivas/code.py

Hay que tendría que hacer algo de tal manera que cuando se incluye código que puede especificar una línea de inicio/fin de destacar en este fragmento .
El segundo paso requeriría crear algunas formas de resaltar las cosas de manera diferente. El enfoque más simple es que la parte sin énfasis no se resalta y la parte con énfasis se resalta. Eso evitaría hacer piratería más compleja de los estilos y resaltar.

Esto da, por ejemplo, una nueva opción de líneas énfasis en la directiva literalinclude que se puede utilizar de esta manera:

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

donde la línea-énfasis es una línea de salida, línea de fondo en relación con el código incluido , primera línea es 1.

Usando 0.6.5 esfinge en pypi.python.org/pypi/Sphinx/0.6.5 como base un code.py quicky patched está ahí: http://paste.pocoo.org/show/194456/

cuenta que la siguiente sería equi valente:

El uso de la esfinge estándar (más o menos lo que sugiere 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-

... y el uso de la esfinge parcheado:

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

Por lo tanto, no puede ser exactamente lo Estás buscando. El parche crea un nuevo nodo para cada una de las secciones resaltadas o no resaltadas del código. Cada uno de estos será renderizado por Sphinx como una sección separada de < div> y <. Para ir más allá, es posible que desee crear una hoja de estilo que mejor extraiga las líneas con énfasis. Es posible que otros hacks tengan que profundizar en las entrañas de Sphinx y Pygments para tener un estilo enfatizado perfectamente generado directamente allí: no trivial.

/HTH

Fuente

2010-03-27 14:29:30

Esfinge tiene ahora una directiva para emphasize-lines literal incluye:

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

Fuente

2012-04-17 20:26:44

Solo para referencia, este trabajo en directivas '.. code-block ::' también. Sé que de eso no se trata la pregunta, sino en caso de que alguien más esté buscándola. – brianmearns

¿Hay alguna manera en Sphinx/Pygments de enfatizar una o más líneas de código en includes literal?

Respuesta

Cuestiones relacionadas