文章出處

概述

使用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


文章列表


不含病毒。www.avast.com
arrow
arrow
    全站熱搜
    創作者介紹
    創作者 大師兄 的頭像
    大師兄

    IT工程師數位筆記本

    大師兄 發表在 痞客邦 留言(0) 人氣()

    E-mail轉寄