mac系統下修復第三方Python包bug

發現問題

　　今天在github上fork了CI 3.x的中文手冊，按照README文檔一步步進行Sphinx和相關工具的安裝，最終build生成html版手冊。操做到第6步執行`make html`的時候，拋出Python異常：

#這裏省略了上面的輸出信息
Exception occurred:
  File "/Library/Python/2.7/site-packages/Sphinx-1.5-py2.7.egg/sphinx/environment/managers/toctree.py", line 273, in _entries_from_toctree
    title = clean_astext(self.titles[ref])
AttributeError: 'Toctree' object has no attribute 'titles'
The full traceback has been saved in /var/folders/2x/b7_jzxyd1dj5cq7q41yr18s00000gn/T/sphinx-err-BF9qkA.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 1

　　顯然問題出在sphinx庫。必需要找到解決方案才能完成第6步。

 

解決方案

　　經過提示信息訪問它的github issue頁面，用第四行的錯誤信息（AttributeError: 'Toctree' object has no attribute 'titles'）做爲關鍵詞搜索，搜到了一條反映這個問題的issue。這個問題在6天前被提出，而且在4天前被close，說明問題已經解決。

　　在評論列表中找到開發者的回覆，根據他給的連接找到fix bug的commit，查看所作的修改，發現是將toctree.py文件第273行的

 

title = clean_astext(self.titles[ref])

 

這句改成

title = clean_astext(self.env.titles[ref])

這個修改恰好對應到產生異常信息的那句代碼。因而根據異常信息找到toctree.py文件，將那行修改。

　　最後再次執行`make html`，執行成功。

 

總結反思

　　此次找解決方案的過程其實饒了不少彎路。作得比較差勁的地方有：

• 沒有注意到issue的狀態。出現了異常之後，根據異常信息很快就找到了關於這個bug的issue頁面。評論列表中開發者回覆說會在週末發佈一個新的release，因爲沒有留意issue已經被close了，因此最開始並不知道已經有新的提交修復了bug。
• 沒有注意到異常信息第二行已經給出了產生異常的文件，用搜索引擎和find命令找了很久。後來想到用easy_install命令從新安裝Sphinx可能會將安裝路徑輸出到終端，用這個方法果然找到了庫的目錄。（寫這篇隨筆的時候才發現錯誤信息裏面已經告訴我文件的位置了。。。）

　　固然也有值得自我誇獎的地方：

• 看到開發者修復bug的提交後當即想到，在release出來之前我能夠本身動手修復這個bug。由於Python是一門解釋執行的語言，所以庫代碼必定是以源碼的形式保存在某個目錄下。
• 解決了問題就值得誇獎