编译OpenCV文档

概述

使用OpenCV的过程中经常查看文档，每次都去官网查看，不过国内访问速度很慢，有一份本地的文档就好了。本文列出了在Linux(Fedora)系统上从OpenCV源码编译出documentation的步骤。在Windows系统上也可以编译出文档，只需在cmake-gui界面中勾选build-doc并根据提示信息安装相应依赖程序，generate后用visual studio编译安装文档。

你也可以直接下载我编译生成好的文档：
OpenCV-3.0.0文档：百度云盘 我的github项目。
OpenCV-3.1.0文档：百度云盘

如果你觉得pdf格式的文档看起来就够了，可以到这里和这里下载。本文讲的是html格式的文档，以网站形式展示的，可以部署在本机或(局域网)服务器上的。
以下是在Fedora系统上编译的具体步骤，Ubuntu下的操作基本一致。

改CMakeLists.txt

首先，干掉CMakeLists.txt中的IPP和CUDA，CUDA是GPU相关的暂时用不到；IPP这东西似乎是有License的问题，不在opencv下载的包中，它会去自动下载，但是下载速度太慢（原因我并不懂。。），当然你也可以到CMakeLists.txt相关文件中去找下它的下载地址。

yum install cmake #先确保装了cmake，否则无法编译
cd opencv-2.4.11
vim CMakeLists.txt

找到如下两行，在行首添加#来注释掉：

#OCV_OPTION(ITH_CUDA           "Include NVidia Cuda Runtime support" 

#OCV_OPTION(WITH_IPP            "Include Intel IPP support"                   OFF  IF (MSVC OR X86 OR X86_64) )

生成文档

接下来，执行cmake：

#先确保你在opencv-2.4.11目录
mkdir build
cd build
cmake ..

然后要执行make html_docs，需要先安装python-sphinx，texlive和doxygen最好也安装下。
怎样看出要安装这些软件？执行cmake ..后有个汇总，看Documentation部分的说明就知道了。比如：

--   Documentation:
--     Build Documentation:         YES
--     Sphinx:                      /usr/bin/sphinx-build (ver 1.2.3)
--     PdfLaTeX compiler:           /usr/bin/pdflatex
--     Doxygen:                     YES (/usr/bin/doxygen)

那么这段说明是怎么生成的？是根据CMakeLists.txt生成的。所以要安装什么具体的软件，也可以先去CMakeLists.txt中去看个究竟:

# ========================== documentation ==========================
if(BUILD_DOCS)                                                                                                                              
  status("")
  status("  Documentation:")
  if(HAVE_SPHINX)
    status("    Build Documentation:" PDFLATEX_COMPILER      THEN YES ELSE "YES (only HTML and without math expressions)")
  else()
    status("    Build Documentation:" NO)
  endif()
  status("    Sphinx:"              HAVE_SPHINX              THEN "${SPHINX_BUILD} (ver ${SPHINX_VERSION})" ELSE NO)
  status("    PdfLaTeX compiler:"   PDFLATEX_COMPILER        THEN "${PDFLATEX_COMPILER}" ELSE NO)
  status("    Doxygen:"             HAVE_DOXYGEN             THEN "YES (${DOXYGEN_BUILD})" ELSE NO)
endif()

ok，这里看到sphinx、pdflatex_compiler、doxygen，其实很蛋疼的一点是名字并不总能和rpm仓库中的包名字对应，我用yum search pdflatex执行查找，在fedora22上找不就叫pdflatex的软件。不过google后发现，安装texlive后就可以了，它会把pdflatex装好的。

接下来就去生成html文档：

make html_docs  #这个是sphinx风格的文档
make doxygen   #这个是doxygen风格的文档
#两者各有千秋

P.S 如果是opencv-3.0.0，执行cmake后发现make没有html_docs的选项，目测是官方把sphinx格式的文档抛弃了。毕竟有了doxygen了，是用markdown格式写的，还是比较赞的。

编译报错的处理

上面是正常的步骤，但是很可能报错。我遇到的主要是texlive的问题。当然，如果先前不把pdflatex装上去，可能没有这么麻烦。。。
首先是报错说"bbm.sty找不到"。然后fedora22的dnf(yum)中，找不到bbm的包。手动安装：

wget http://mirror.hmc.edu/ctan/macros/latex/contrib/bbm.zip
unzip bbm.zip
sudo mv bbm /usr/share/texlive/texmf-dist/tex/latex  #如果是centos7，那么是/usr/share/texlive/texmf/tex/latex目录
cd $_
latex bbm.ins   #执行安装
sudo texhash   #更新数据库

还没完，还需要安装这些：

sudo yum install dvipng   #当然，如果是centos7，默认好像是装好的

尝试再次make html_docs，发现卡在75%的地方，报错说：

writing output... [ 75%] modules/ml/doc/expectation_maximization                
Exception occurred:
  File "/usr/lib/python2.7/site-packages/docutils/nodes.py", line 344, in __new__
    return reprunicode.__new__(cls, data)
UnicodeDecodeError: 'ascii' codec can't decode byte 0xe6 in position 723: ordinal not in range(128)
The full traceback has been saved in /tmp/sphinx-err-qQfbOj.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.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!
make[3]: *** [doc/CMakeFiles/html_docs] 错误 1
make[2]: *** [doc/CMakeFiles/html_docs.dir/all] 错误 2
make[1]: *** [doc/CMakeFiles/html_docs.dir/rule] 错误 2
make: *** [html_docs] 错误 2

这时候把$LANG变量从zh_CN.UTF-8换调，再编译：

sudo export LANG=en_US.UTF-8
make html_docs

这样可能还会出现问题吧，不过确实是能生成documentation了，latex公式也都基本转换为图片显示了，所以就不再细究了。
这个过程很繁琐，我上传了一份到百度云，可下载之。

另外推荐一个chrome插件：gooreplacer，谷歌的各种css和js直接从科大API获取，stackoverflow什么的网站都能加速了！

======
以下是原文

写程序文档必不可少。基本用法都在文档上。

OpenCV的HTML文档

opencv的windows版本解压后有doc目录，里面是pdf格式的文档。查询某个函数用法时不是很方便。
opencv官网英文文档是web形式的，http://www.docs.opencv.org/，有查询框，可以查询指定的函数，使用方便。
但是opencv官网访问速度还是有点慢，我们自行创建opencv的html格式文档，部署在本地。

首先下载opencv源代码，解压并执行cmake生成makefile。发现很多没有用的选项比如ipp，cuda，对于生成文档没有帮助，在CMakeLists.txt中去掉。
然后执行make html_docs生成文档。
用python建立简单的http服务器并部署文档站点：python -m SimpleHTTPServer 8080
访问站点，发现奇卡无比。因为使用了google的一些js脚本，谷歌无法正常访问导致的。
到最外层doc目录修改sphinx的模板。html_docs中的html是用rst文档生成的，通过sphinx生成的。

修改后重新cmake，make html_docs，部署，访问，速度正常。enjoy it！

下载：http://pan.baidu.com/s/1dD91nrz

numpy的HTML文档

numpy官方文档下载：http://docs.scipy.org/doc/numpy/numpy-html-1.9.1.zip
谷歌访问不了，导致一些js文件、字体无法正常显示，并影响文档显示速度。
本文档为删除了谷歌相关的js文件、字体样式的文档，访问速度迅速。

下载：http://pan.baidu.com/s/1ntA6XBz