在Sphinx/Pygments中是否有一种方法可以强调文字包含中的一行或多行代码？

Question

在我写的一些sphinx文档中,我包含来自辅助文件的代码示例,如下所示:

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

这个特定的文档是一个教程,其中的类是逐步构建的.我想要做的是包括整个班级或单一方法,并只强调该部分感兴趣的行.这样就保留了上下文,但有趣的部分一目了然.现在我只是提到文本中的行号,这是好的,但远非理想.

看看sphinx和pygments的文档和代码,我找不到一个明显的方法来做到这一点.我并不反对修补它们或做一些棘手的事情conf.py,但我想知道是否有人解决了这个问题.

Answer 1

Sphinx现在有一个emphasize-lines文字指令包括:

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

Answer 2

您可以在 sphinx/directives/code.py 中修补 sphinx 的 LiteralIninclude 指令

• 在那里，您需要做一些事情，以便在包含代码时可以指定要在此片段中强调的开始/结束行。
• 第二步需要创建一些方法来以不同的方式突出显示事物。最简单的做法是，不强调的部分不突出显示，而强调的部分突出显示。这将避免对样式和突出显示进行更复杂的修改。

例如，这在literalinclude指令中提供了一个新的lines-emphasis选项，您可以这样使用：

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

其中 line-emphasis 是相对于包含的代码的起始行、结束行，第一行是 1。

使用 pypi.python.org/pypi/Sphinx/0.6.5 上的 sphinx 0.6.5 作为基础，快速修补的 code.py 就在那里： http: //paste.pocoo.org/show/194456/

请注意，以下内容是等效的：

使用标准狮身人面像（与 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-

...并使用修补后的狮身人面像：

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

因此，它可能不完全是您正在寻找的东西。该补丁为代码的每个突出显示或未突出显示的部分创建一个新节点。其中每一个都将由 Sphinx 呈现为单独的 <div> 和 <pre> 部分。为了超越这一点，您可能需要创建一个样式表，以更好地重点摘录这些行。进一步的黑客可能需要深入 Sphinx 和 Pygments 的内部，才能直接在那里生成无缝的强调风格：这不是微不足道的。

/HTH