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-模式宏。