组织模式代码块结果中的内部链接和目标链接，例如，到其他代码块的结果答案

【问题标题】：Internal links and targets in results of org-mode code blocks linking, e.g., to the results of other code blocks组织模式代码块结果中的内部链接和目标链接，例如，到其他代码块的结果
【发布时间】：2017-09-21 22:21:55
【问题描述】：

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

只是为了简要说明原理，我将使用 Emacs Lisp 演示以下稍微简化的方法。我有一个提取函数文档的代码块（使用 Common Lisp 的 format 并使用 :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 结果文档恰好如下。

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

(fn TYPE FUNCTION SEQUENCE...)"

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

现在是我的问题。我想在其他函数的文档字符串中使用 links 到 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 报告的技巧对我来说还不够）。我正在寻找一种方法将有关未解决链接的错误消息转换为警告，但我发现的只是标记损坏链接的选项，如下所示。有什么方法可以导出并忽略（看似）损坏的链接？

#+OPTIONS: broken-links:mark

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

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

【问题讨论】：

标签： python-sphinx org-mode documentation-generation org-babel

【解决方案1】：

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

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

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

【讨论】：