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

时间:2010-03-18 20:41:07

标签: python documentation-generation python-sphinx pygments

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

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

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

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

2 个答案:

答案 0 :(得分:5)

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

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

答案 1 :(得分:2)

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

  • 在那里你需要做一些事情,当你包含代码时,你可以指定一个开始/结束行来强调这个片段。
  • 第二步需要创建一些方法来突出显示不同的东西。最简单的方法是不强调没有强调的部分,突出强调部分。这样可以避免对样式进行更复杂的黑客攻击和突出显示。

这为literalinclude指令提供了一个新的行重点选项,您可以这样使用:

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

其中,行重点是起始行,相对于包含的代码的结束行,第一行是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>和<前>部分。要超越这个范围,您可能需要创建一个样式表,以便更好地摘录这些行。进一步的黑客攻击可能需要深入了解Sphinx和Pygments的内容,以便在那里直接生成无缝强调的风格:并非无足轻重。

/ HTH