1

我正在使用 org-mode 编写软件文档，其中函数、变量等的 API 文档是从代码的文档字符串中自动提取的（恰好在 Common Lisp 中）。然后将此文档导出为 HTML（我碰巧通过带有ox-rst和Sphinx的 reStructuredText 执行此操作）。它的工作方式与直接在 Python 中使用 Sphinx 非常相似，但具有 org-mode 的所有功能，例如可执行代码块。

只是为了简要说明原理，我将使用 Emacs Lisp 演示以下方法进行了一些简化。我有一个提取函数文档的代码块（使用 Common Lisp 的格式并使用:results output raw我避免在结果中包含双引号，但为简单起见，我将它们留在下面的简短演示中）。

#+name: function-doc
#+begin_src emacs-lisp :results output raw :exports results :var name='list
  (print (documentation name))
#+end_src

然后，我使用我想要记录的函数调用该代码块，并在导出过程中将该调用替换为生成的文档。

#+CALL function-doc(name:'map)

自动插入到导出文件中的地图生成文档恰好如下。

"Map a FUNCTION across one or more SEQUENCEs, returning a sequence.
TYPE is the sequence type to return.

(fn TYPE FUNCTION SEQUENCE...)"

我可以在我的文档字符串中使用 org-mode 格式，并且这种格式会按预期导出。

现在是我的问题。我想在其他函数、变量等的文档字符串和主文本（即，未自动插入的文本）中使用指向 API 条目（例如，函数的文档）的链接。使用函数名称自动插入目标很容易，我只需要相应地扩展上面的代码块function-doc。但是，在导出过程中找不到这些目标。即使我将目标文件自动添加到上面的代码块function-doc中，当我将 org-mode 链接[[ MY -FUNCTION]]插入该函数时，org-mode 会中断导出以下错误。

user-error: Unable to resolve link: "MY-FUNCTION"

有没有办法绕过这个限制？在导出过程中，org-mode 是否可以“看到”org-mode 代码块结果中的目标？

我已经尝试了各种解决方法，但到目前为止都没有成功。例如，我尝试使用 org-mode 宏而不是代码块，但是产生多行宏结果非常棘手（Define org-mode macro with line breaks where 对我来说不够用）。我正在寻找一种方法将有关未解决链接的错误消息转换为警告，但我发现的只是标记损坏链接的选项，如下所示。有什么方法可以导出并忽略（看似）断开的链接？

#+OPTIONS: broken-links:mark

我还考虑过首先将我的 org 文件自动导出到已插入所有代码块结果的 org，以便 org-mode 可以看到链接的所有目标，但显然也无法将 org 文件导出到 org 模式（看似）断开的链接。

有什么帮助吗？非常感谢！

4

1 回答 1

1

当仅对 Sphinx 使用 reStructuredText 导出时，我可以使用如下内联 rST 链接。这里的另一个好处是 rST 链接不区分大小写，这与 org-mode 链接不同。

See also @@rst:`my-function`_@@.

如果我想导出为多种格式，那么我可以定义一个 org-mode 宏来生成上面的 rST 链接，以及其他导出格式的链接。

于 2017-09-21T23:58:05.277 回答