发现问题
今天在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是一门解释执行的语言，因此库代码一定是以源码的形式保存在某个目录下。
- 解决了问题就值得夸奖
时间： 2024-10-09 14:29:05