跳到主要內容

Sphinx 的 autodoc 載入問題

為了使用 autodoc, 我在 conf.py 裡這樣寫:

sys.path.append('/usr/lib/python2.5/site-packages/Sphinx-1.0.7-py2.5.egg/sphinx/ext')
extensions = ['graphviz', 'autodoc']

結果跑出:

autodoc documenter <class 'autodoc.ModuleDocumenter'> must be a subclass of Documenter

正確的寫法是:

extensions = ['sphinx.ext.graphviz', 'sphinx.ext.autodoc']

開 pdb 追下去, 發現是 sphinx.application 和 sphinx.ext.autodoc 之間 circular import 造成的問題。

在 sphinx.application 裡:

def add_autodocumenter(self, cls):
    from sphinx.ext import autodoc
    autodoc.add_documenter(cls)
    self.add_directive('auto' + cls.objtype, autodoc.AutoDirective)

會載入 sphinx.ext.autodoc, 但我原本的寫法, 讓 sphinx 透過 __import__ 載入 autodoc, 結果產生兩個不同的物件, 但都是 autodoc, 結果剩下的一些程式操作, 就發生了悲劇。

在 autodoc 裡的這段程式就丟出 exception:

if not issubclass(cls, Documenter):
    raise ExtensionError('autodoc documenter %r must be a subclass '

cls (即 ModuleDocumenter) 真的不是 Documenter 的 subclass, 因為這個 ModuleDocumenter 是其中一個 autodoc 的, 而 Documenter 卻是另一個 autodoc 的。

若硬註解掉這兩行, 雖然 autodoc 的部份指令能用, 卻也會部份失效, 像 :members: 就會完全沒效果, 原因也是出在有兩個 autodoc 上, 結果找 members 的那個 autodoc 的 AutoDirective._registry 是空的, 造成它找不到能處理 members 的 Documenter。

備註: autodoc.AutoDirective 負責處理 directive auto*。AutoDirective 依指令名稱從 _registry 中找出適用的 class 來處理, 比方說 automodule 就會找 ModuleDocumenter 來處理。正常的程序下, autodoc.setup() 會填好 AutoDirective._registry, 但在上面說的錯誤設定下, 會變成 sphinx.ext.autodoc.AutoDirective._registry 有設好, 而 autodoc.AutoDirective._registry 是空的。

下面是用 pdb 看設錯情況發生的狀況, 滿有趣的:

> /usr/lib/python2.5/site-packages/Sphinx-1.0.7-py2.5.egg/sphinx/ext/autodoc.py(1177)run()
-> documenter.generate(more_content=self.content)
  /usr/lib/python2.5/site-packages/Sphinx-1.0.7-py2.5.egg/sphinx/ext/autodoc.py(715)generate()
-> self.document_members(all_members)
  /usr/lib/python2.5/site-packages/Sphinx-1.0.7-py2.5.egg/sphinx/ext/autodoc.py(981)document_members()
-> ModuleLevelDocumenter.document_members(self, all_members)
  /usr/lib/python2.5/site-packages/Sphinx-1.0.7-py2.5.egg/sphinx/ext/autodoc.py(609)document_members()
-> for (mname, member, isattr) in self.filter_members(members, want_all):
(Pdb) l
1172            # process the options with the selected documenter's option_spec
1173            self.genopt = Options(assemble_option_dict(
1174                self.options.items(), doc_class.option_spec))
1175            # generate the output
1176            documenter = doc_class(self, self.arguments[0])
1177 ->         documenter.generate(more_content=self.content)
1178            if not self.result:
1179                return self.warnings
1180
1181            # record all filenames as dependencies -- this will at least
1182            # partially make automatic invalidation possible
(Pdb) documenter.__module__
'autodoc'
(Pdb) id(AutoDirective)
21622640
(Pdb) down
> /usr/lib/python2.5/site-packages/Sphinx-1.0.7-py2.5.egg/sphinx/ext/autodoc.py(715)generate()
-> self.document_members(all_members)
(Pdb) id(AutoDirective)
20956032
(Pdb) import sys
(Pdb) id(sys.modules['autodoc'].AutoDirective)
20956032
(Pdb) id(sys.modules['sphinx.ext.autodoc'].AutoDirective)
21622640

表示一開始在 sphinx.ext.autodoc, 但 documenter 是從 autodoc 取來的, 結果就無聲無息的掛了。

留言

這個網誌中的熱門文章

(C/C++ ) 如何在 Linux 上使用自行編譯的第三方函式庫

以使用 LevelDB 為例。 抓好並編好相關檔案,編譯方式見第三方函式庫附的說明:$ ls include/ # header files leveldb/ $ ls out-shared/libleveldb.so* # shared library out-shared/libleveldb.so@ out-shared/libleveldb.so.1@ out-shared/libleveldb.so.1.20* 下面的例子用 clang++ 編譯,這裡用到的參數和 g++ 一樣。 問題一:找不到 header$ clang++ sample.cpp sample.cpp:5:10: fatal error: 'leveldb/db.h' file not found #include "leveldb/db.h" ^ 1 error generated. 解法:用 -I 指定 header 位置 問題二:找不到 shared library$ clang++ sample.cpp -I include/ /tmp/sample-2e7dd8.o: In function `main': sample.cpp:(.text+0x1e): undefined reference to `leveldb::Options::Options()' sample.cpp:(.text+0x6f): undefined reference to `leveldb::DB::Open(leveldb::Options const&, std::string const&, leveldb::DB**)' sample.cpp:(.text+0x10c): undefined reference to `leveldb::Status::ToString() const' sample.cpp:(.text+0x7d0): undefined reference to `leveldb::Status::ToString() const' clang: error: linker command failed with exit code 1 (u…

熟悉系統工具好處多多

記一下以前很困擾, 現在秒殺的小事。 更新這篇的時候, 忘了函式庫用的 man page 裝在那個 package。以前就會想辦法 google, 運氣好一下會找到, 運氣不好會多找一會兒。 這回我想到新作法:$ strace -e open man 3 printf > /dev/null # 發現是讀 /usr/share/man/man3/printf.3.gz $ dpkg --search /usr/share/man/man3/printf.3.gz # 找到套件名稱 manpages-dev $ aptitude show manpages-dev # 確認描述符合, 收工

virtualbox 使用 USB 裝置

2012-12-16 更新 現在 (4.x 版) 似乎無需做任何設定, 只要有裝 Oracle VM VirtualBox Extension Pack, 在 VirtualBox 視窗右下角按 USB 的圖示, 再點目標裝置, 即可加入或移除該裝置 同一時間只有 host 或 guest 可擁有該裝置, 所以從 guest OS 移除, 相當於接回 host OS 目前 VirtualBox 只支援 USB 2.0 的插槽, 若偵測不到時, 注意一下是否為這個問題 有時拔拔插插, VirtualBox 會進入奇怪的狀態, 接上去 guest OS 無法連接且跳出 device is busy 的錯誤訊息。試看看拔除該裝置, 重開 guest OS (續上則) 若重開 guest OS 無效, 並且 host OS 已移除該裝置, VirtualBox 的 USB 清單卻仍顯示 "captured", 試看看拔除該裝置, 重開 host OS原文網路上搜一下, 比較多是 Ubuntu 當 host 的解法, 我的情況是 Win7 當 host, Ubuntu 當 guest。 這兩篇說明很詳細《Learn How to Set Up USB and Networking Options in VirtualBox》《幻影千瞳的部落格: VirtualBox 使用筆記(二):使用 USB 裝置》 現在的版本圖形介面很好用了, 不用像第二篇說的那樣用指令操作。這裡記下我的操作步驟: 關掉 guest OS 在 VirtualBox 選單, 選擇 guest OS -> Settings -> USB -> Enable USB 2.0 會出現訊息框, 說明要安裝 Oracle VM VirtualBox Extension Pack。下載後安裝它 host OS 插入 USB 隨身碟 在 VirtualBox 選單, 選擇 guest OS -> Settings -> USB, 點右邊有綠色 "+" 的 USB 頭的圖示, 選擇該 USB 隨身碟, 加入它的 filter 從 host OS 移除 USB 隨身碟 開啟 guest OS 插入 USB 隨身碟, 於是 guest OS 會自動偵測…