1

我使用组织模式编写软件文档,其中API函数,变量等文档自动从其中提取代码的文档字符串(恰好在Common Lisp中)。然后将该文档导出为HTML(我碰巧通过reStructuredText通过ox-rstSphinx执行此操作)。它的工作原理很像使用Sphinx直接与Python一起使用,但具有组织模式的所有特性,如可执行代码块。组织模式代码块结果中的内部链接和目标链接,例如链接到其他代码块的结果

为了简要说明原理,我演示了使用Emacs Lisp进行简化的方法。我有一个代码块提取函数的文档(与Common Lisp中的格式和使用:结果输出的原始我避免周围的结果双引号,但为了简单起见,我离开他们在下面的简短演示) 。

#+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...)" 

我可以使用组织模式在我的文档串格式,这种格式的预期输出。

现在来问我。我想用链接到API的条目(例如,函数的文档)等功能,变量等两个文档串内并从主文本中(即,不自动插入的文本)。自动插入目标名称的功能很容易,我只需要扩展我的代码块function-doc相应地。但是,这些目标在出口过程中没有找到。即使我的目标是MY-FUNCTION的文档自动添加上面的代码块function-doc,当我将组织模式链接[[MY-FUNCTION]]添加到该功能时,org -mode中断导出并出现以下错误。

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

有没有办法解决这个限制?在导出过程中,组织模式代码块的结果中的目标是否可以通过组织模式“看到”?

我已经尝试了各种解决方法,但迄今为止没有成功。例如,我尝试使用组织模式宏而不是代码块,但是具有多行宏结果非常棘手(在Define org mode macro with line breaks处报告的技巧对我来说不够用)。我正在寻找一种方法将有关未解析链接的错误消息转变为警告,但我发现的所有选项都是标记损坏的链接,如下所示。任何方式出口,只是忽略(看似)断开的链接?

#+OPTIONS: broken-links:mark 

我也认为首先自动我的组织文件导出到一个组织的所有代码块的结果已经插入,使组织模式能看到的所有目标的联系,但显然导出一个组织文件org模式也不可能与(看似)断开的链接。

任何帮助?非常感谢!

回答

1

当只使用reStructuredText导出为狮身人面像,然后我可以使用像下面的内联rST链接。这里额外的好处是,与组织模式链接不同,rST链接不区分大小写。

See also @@rst:`my-function`[email protected]@. 

如果我要导出为多种格式,那么我可以定义生成以上所述RST链路,以及为其它导出格式链路的org-模式宏。