Sphinx/Pygments中是否可以在插入的代码中强调一行或多行代码？

Question

在我写的一些 Sphinx 文档中，我想要从一个辅助文件中包含代码示例，像这样：

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

这个文档是一个教程，里面的类是一步一步构建起来的。我想做的是包含整个类或者某个方法，并且只突出显示对这一部分有用的行。这样可以保留上下文，同时让重要的部分一眼就能看出来。目前我只能在文本中提到行号，这样虽然可以，但远不是最理想的方式。

我查看了 Sphinx 和 Pygments 的文档和代码，但没有找到明显的方法来实现这个。我不介意对它们进行一些修改，或者在 conf.py 中做一些小技巧，但我想知道有没有人已经解决了这个问题。

Answer 1

你可以在sphinx的代码文件sphinx/directives/code.py中修改LiteralInclude指令。

• 在这里，你需要做一些调整，让你在包含代码时可以指定要强调的开始和结束行。
• 第二步是创建一些方法来以不同的方式高亮显示内容。最简单的办法是没有强调的部分不高亮，而有强调的部分高亮。这样就不需要复杂地修改样式和高亮了。

这样就可以在literalinclude指令中添加一个新的行强调选项，你可以这样使用：

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

这里的行强调是指相对于包含的代码的开始行和结束行，第一行是1。

使用sphinx 0.6.5作为基础，你可以在这里找到一个快速修改过的code.py： http://paste.pocoo.org/show/194456/

请注意，以下两种方式是等效的：

使用标准的sphinx（基本上是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-

... 以及使用修改过的sphinx：

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

所以这可能并不是你想要的完全效果。这个修改为代码的每个高亮和不高亮部分创建了一个新的节点。每个节点都会被Sphinx渲染成一个单独的< div >和< pre >部分。如果想要更进一步，你可能需要创建一个样式表，以更好地突出强调的行。进一步的修改可能需要深入到Sphinx和Pygments的内部，以便直接生成无缝的强调样式：这并不简单。

/希望这对你有帮助

Answer 2

Sphinx现在为literalinclude指令增加了一个emphasize-lines选项。

这个选项在“附加选项”中提到。具体的细节可以在code-block的文档中找到。