literalinclude

Question

我正在Sphinx中记录一个python模块。我有一个完整的模块使用示例的源代码文件。我想引用这个文件。内联作为连续代码太长了。有没有办法创建一个完整的源文件的链接，格式化为代码友好的方式（即文字或行号）？

感谢。

Answer 1

如果我的问题正确，您需要从文档到原始源文件的链接。您可以通过在conf文件中添加sphinx.ext.viewcode扩展名（在扩展条目下）来执行此操作。这将创建一个＆＃34;来源＆＃34;类，方法，函数等的每个标题的链接。单击该链接将打开突出显示所单击项目的原始文件。更多解释here

Answer 2

literalinclude

.. literalinclude:: filename

来自Sphinx (v1.5.1) documentation：

通过将示例文本存储在仅包含纯文本的外部文件中，可以包括更长的逐字文本显示。可以使用literalinclude指令包含该文件。

例如，要包含Python源文件example.py，请使用：

.. literalinclude:: example.py

文件名通常相对于当前文件的路径。但是，如果它是绝对的（以/开头），则它相对于顶级源目录。

如果您提供带有所需标签宽度的标签宽度选项，则会展开输入中的标签。

与代码块一样，该指令支持使用linenos标志选项来切换行号，使用lineno-start选项来选择第一行号，使用强调行选项来强调特定行，使用语言选项来选择语言与当前文件的标准语言不同。选项示例：

.. literalinclude:: example.rb
   :language: ruby
   :emphasize-lines: 12,15-18
   :linenos:

假设包含文件在source_encoding中编码。如果文件具有不同的编码，则可以使用编码选项指定它：

.. literalinclude:: example.py
   :encoding: latin-1

该指令还支持仅包含部分文件。如果它是Python模块，您可以使用pyobject选项选择要包含的类，函数或方法：

.. literalinclude:: example.py
   :pyobject: Timer.start

这只包括属于文件中Timer类的start（）方法的代码行。

或者，您可以通过给出一个行选项来准确指定要包含的行：

.. literalinclude:: example.py
   :lines: 1,3,5-10,20-

这包括第1,3,5至10行和第20行至最后一行。

控制文件的哪个部分的另一种方法是使用start-after和end-before选项（或只使用其中一个）。如果start-after作为字符串选项给出，则仅包含在包含该字符串的第一行之后的行。如果end-before作为字符串选项给出，则仅包含在包含该字符串的第一行之前的行。

指定要显示的文件的特定部分时，准确显示正在显示的行是很有用的。这可以使用lineno-match选项完成。

您可以分别使用prepend和append选项为所包含的代码添加和/或附加一行。这很有用，例如用于突出显示不包含标记的PHP代码。

如果要显示代码的差异，可以通过给出diff选项来指定旧文件：

.. literalinclude:: example.py
   :diff: example.py.orig

这显示了带有统一差异格式的example.py和example.py.orig之间的差异。

Answer 3

Python 3就是这样做的。例如，the argparse docs链接到源代码（靠近页面顶部，其中显示“源代码”）。您可以通过查看source for the docs（从第一个链接链接，左下方有列）来了解他们是如何做到的。

我认为他们使用的是标准的Sphinx，但我很难在他们的文档中找到:source: ...

更新：:source:角色定义为here。

链接到sphinx中的源代码文件

3 个答案:

literalinclude