我在Sphinx中记录了一个python模块。我有一个完整的模块使用示例的源代码文件。我想引用这个文件。内联作为连续代码太长了。有没有办法创建一个完整源文件的链接，格式化为代码友好的方式（即文字或行号）？
谢谢。
Python 3就是这样做的。例如，the argparse docs链接到源代码（靠近页面顶部，其中显示“源代码”）。您可以通过查看source for the docs（从第一个链接链接，在左下方有列）来查看它们是如何做到的。
我假设他们正在使用标准的Sphinx，但我很难在他们的文档中找到:source: ...
更新：:source:角色定义为here。
如果我的问题正确，您需要从文档到原始源文件的链接。您可以通过将sphinx.ext.viewcode扩展名添加到conf文件（在扩展条目下）来完成此操作。这将为类，方法，函数等的每个标题创建“源”链接。单击该链接将打开突出显示所单击项目的原始文件。更多解释here
.. literalinclude:: filename
来自Sphinx (v1.5.1) documentation：
通过将示例文本存储在仅包含纯文本的外部文件中，可以包括更长的逐字文本显示。可以使用literalinclude指令包含该文件。
例如，要包含Python源文件example.py，请使用：
.. literalinclude:: example.py
文件名通常相对于当前文件的路径。但是，如果它是绝对的（以/开头），则它相对于顶级源目录。
如果为tab-width选项提供所需的选项卡宽度，则会扩展输入中的选项卡。
与代码块一样，该指令支持使用linenos标志选项来切换行号，使用lineno-start选项来选择第一行号，使用强调行选项来强调特定行，使用语言选项来选择与当前文件的标准语言。选项示例：
.. literalinclude:: example.rb
:language: ruby
:emphasize-lines: 12,15-18
:linenos:
假设包含文件在source_encoding中编码。如果文件具有不同的编码，则可以使用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
这显示了带有统一diff格式的example.py和example.py.orig之间的差异。