在Sphinx中链接回源代码文件

Question

我正在使用Sphinx记录一个Python模块。我有一个源代码文件，其中包含使用我的模块的示例。我想引用这个文件，但它太长了，不能作为连续代码嵌入。是否有一种方法可以创建链接到完整的源代码文件，并以友好的方式格式化代码（即：逐行显示或带有行号）？

- Eli S

---

将其作为文件读取..但我不确定你为什么要这样做，为什么不直接提供运行示例呢？ - aIKid

我已经提供了运行示例，但有些用户喜欢有一个单独的可编译文件来阅读。从某种意义上说，我只想“将其作为文件读取”，但如果该文件深埋在文件系统中（如site-packages通常所在的位置，特别是在带有虚拟.的Enthought发行版中）， - Eli S

在某些环境中，它被认为是可用性的影响。因此，我想要一个链接到该文件。 - Eli S

我曾经有同样的疑问，但在Sphinx文档中找到了一些东西。它由标准的Sphinx支持，并且实际上比我寻找的功能更多，例如diff。 已添加为答案在这里。 - Lucas Siqueira

Answer 1

如果我理解正确的话，您想在文档中添加指向原始源文件的链接。您可以通过将`sphinx.ext.viewcode`扩展添加到配置文件中（在扩展条目下）来实现此目的。这将为每个类、方法、函数等的头部创建一个“source”链接。点击该链接将打开原始文件并突出显示所单击的项目。更多解释请点击此处。

- A. B

---

请注意，在您的文档中添加“.. module:: example”以便视图代码扩展程序找到类、方法等的源代码，并随后在输出中添加链接。 - inkychris

请注意，现在有 spinx.ext.linkcode (link)，它链接到例如 GitHub，而不是生成语法突出显示的源代码页面。 - Tomas

Answer 2

literalinclude

.. literalinclude:: filename

来自Sphinx (v1.5.1)文档：

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

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

.. literalinclude:: example.py

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

如果您使用所需的制表符宽度选项，则输入中的制表符将被展开。

与code-block类似，该指令支持linenos标志选项以打开行号，lineno-start选项以选择第一个行号，emphasize-lines选项以强调特定行，并且语言选项以选择与当前文件的标准语言不同的语言。带有选项的示例：

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

假设包含文件已经使用源编码进行了编码。如果文件有不同的编码，您可以使用编码选项指定它:

.. 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代码非常有用。如果想要显示代码的差异，可以通过提供diff选项来指定旧文件：

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

这显示了使用统一的差异格式对example.py和example.py.orig之间的差异。

- Lucas Siqueira

---

有没有类似于pyobject的对象来显示JSON对象的一部分？ - Anuj TBE

这真的很好！我有兴趣显示C文件的一部分，比如一个函数或仅仅是头文件。 - Kiteloopdesign

如果您想包含来自在线源文件（例如GitHub存储库）的代码，可以使用remoteliteralinclude扩展https://github.com/wpilibsuite/sphinxext-remoteliteralinclude。 - Matt Pitkin

Answer 3

Python 3可以做到这一点。例如，argparse文档链接到源代码（页面顶部附近有“源代码”字样）。您可以通过查看文档的源代码（从第一个链接中链接，在左侧列的底部）来了解他们如何实现。

我假设他们使用标准的Sphinx，但我很难在他们的文档中找到:source:。 更新：定义:source:角色在这里。

- andrew cooke

---

请查看此答案 https://dev59.com/amIj5IYBdhLWcg3wn2Zn#21650878，因为那是流行的方法。 - jochem

“文档来源”链接已损坏（404） - tobi delbruck