链接到sphinx中的源代码文件

Question

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

谢谢.

Answer 1

如果我的问题正确,您需要从文档到原始源文件的链接.您可以通过将sphinx.ext.viewcode扩展名添加到conf文件(在扩展条目下)来完成此操作.这将为类,方法,函数等的每个标题创建"源"链接.单击该链接将打开突出显示所单击项目的原始文件.这里有更多解释

Answer 2

文字包括

.. literalinclude:: filename

从Sphinx（v1.5.1）文档中：

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

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

.. literalinclude:: example.py

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

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

与代码块一样，该指令支持linenos标志选项以打开行号，lineno-start选项以选择第一个行号，强调行选项以强调特定行以及language选项以选择与当前文件的标准语言。带有选项的示例：

.. 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（）方法的代码行。

或者，您可以通过指定lines选项来确切指定要包括的行：

.. 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代码很有用。

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

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

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

Answer 3

Python 3 就是这样做的。例如，argparse 文档链接到源代码（在页面顶部附近，上面写着“源代码”）。您可以通过查看文档的来源（从第一个链接开始，在左列底部向下链接）来了解他们是如何做到的。

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

更新：:source:角色在此处定义。