寫文檔很重要嗎？

當(dāng)你寫了上萬行代碼，幾十幾百個函數(shù)和類，然后面對源文件一臉懵逼的時候你就不會有這個疑問了。如果規(guī)模較小，那么文檔系統(tǒng)可能對自己沒有太大幫助。但是寫文檔總可以幫助自己總結(jié)和記錄工作。對其他人而言，要知道你的軟件和代碼如何使用，首先就是看你的說明文檔，就和產(chǎn)品說明書一樣，所以寫文檔是非常重要的。文檔系統(tǒng)是什么呢？隨著軟件系統(tǒng)的復(fù)雜度日益增大，人們迫切需要一種規(guī)范的軟件文檔使維護和使用他人軟件代碼更加方便和標(biāo)準(zhǔn)化。這就催生了文檔系統(tǒng)，例如Javadoc。通過在源代碼中特殊的注釋方式，就可以通過Javadoc生成非常標(biāo)準(zhǔn)化的注釋文檔，并且文檔系統(tǒng)會分析類之間的繼承關(guān)系，區(qū)分類型，形成查詢索引，大大減輕了人工創(chuàng)建和維護文檔的負擔(dān)。更方便地是，它可以直接生成在線的網(wǎng)頁使得文檔的查閱變得很方便。

文檔系統(tǒng)是什么呢？

隨著軟件系統(tǒng)的復(fù)雜度日益增大，人們迫切需要一種規(guī)范的軟件文檔使維護和使用他人軟件代碼更加方便和標(biāo)準(zhǔn)化。這就催生了文檔系統(tǒng)，例如Javadoc。通過在源代碼中特殊的注釋方式，就可以通過Javadoc生成非常標(biāo)準(zhǔn)化的注釋文檔，并且文檔系統(tǒng)會分析類之間的繼承關(guān)系，區(qū)分類型，形成查詢索引，大大減輕了人工創(chuàng)建和維護文檔的負擔(dān)。更方便地是，它可以直接生成在線的網(wǎng)頁使得文檔的查閱變得很方便。

Customnpc 的Javadoc截圖

為什么使用Sphinx

C++標(biāo)準(zhǔn)的文檔系統(tǒng)是Doxygen，而且Doxygen也可以支持很多其他語言。而Sphinx主要是寫python文檔用的。那么為什么還要使用Sphinx呢？原因有：

1. Doxygen生成的文檔很丑。這讓你的工程看起來活在90年代。而Sphinx的文檔主題（readthedoc主題）看起來很現(xiàn)代。

   
   
   Eigen的Doxygen文檔
   
   
   Tornado的Sphinx文檔

2. Sphinx可以在Readthedoc網(wǎng)站上在線編譯并托管發(fā)布，不需要建立自己的網(wǎng)站就可以在線發(fā)布文檔了。

那么問題來了，Sphinx是python的文檔系統(tǒng)，一個Python的文檔系統(tǒng)，怎么就跑去生成C++文檔了呢，主要還是這個顏值和Sphinx的強大功能。接下來就簡單說下怎么做。

Doxygen+breathe+Sphinx

由于C++文檔需要Doxygen去生成，因此有人發(fā)明了breathe去橋接Sphinx和Doxygen兩個文檔系統(tǒng)?？梢园袲oxygen的輸出作為輸入給Sphinx。后來又有人做了簡化的工具exhale，只需要如下命令：

pip install exhale

就可以集成到Sphinx里去了（不過Doxygen還得另外下載安裝）。具體參見文檔。

根據(jù)網(wǎng)站介紹，你的c++工程需要這樣的結(jié)構(gòu)。

工程結(jié)構(gòu)

其中include和src是你的c++工程，和文檔系統(tǒng)其實沒有關(guān)系，只是文檔系統(tǒng)需要分析的對象。只有docs文件夾里的內(nèi)容才是文檔系統(tǒng)的主體。其中又可以看到index.rst，這個文件是Sphinx文檔的主頁，規(guī)定要顯示的頁面內(nèi)容。conf.py是Sphinx的配置文件，里面需要包括插件配置以及其他參數(shù)的設(shè)置。需要注意的是，實際上我們首先應(yīng)該做的是在doc文件夾下運行sphinx-quickstart生成文檔編譯所需的各項文件，再去修改這些配置。然后在conf.py中添加網(wǎng)站所述樣例代碼，就成功配置exhale的文檔插件了。

# The `extensions` list should already be in here from `sphinx-quickstart`
extensions = [
    # there may be others here already, e.g. 'sphinx.ext.mathjax'
    'breathe',
    'exhale'
]

# Setup the breathe extension
breathe_projects = {
    "My Project": "./doxyoutput/xml"
}
breathe_default_project = "My Project"

# Setup the exhale extension
exhale_args = {
    # These arguments are required
    "containmentFolder":     "./api",
    "rootFileName":          "library_root.rst",
    "rootFileTitle":         "Library API",
    "doxygenStripFromPath":  "..",
    # Suggested optional arguments
    "createTreeView":        True,
    # TIP: if using the sphinx-bootstrap-theme, you need
    # "treeViewIsBootstrap": True,
    "exhaleExecutesDoxygen": True,
    "exhaleDoxygenStdin":    "INPUT = ../include"
}

# Tell sphinx what the primary language being documented is.
primary_domain = 'cpp'

# Tell sphinx what the pygments highlight language should be.
highlight_language = 'cpp'

在這里，其實最重要的一個參數(shù)就是 exhaleDoxygenStdin 中的INPUT參數(shù)。它指向你想生成文檔的頭文件。這時，文檔系統(tǒng)以及可以調(diào)用doxygen并生成文檔了，但是還需要讓他在頁面上顯示出來。這就需要在index.rst中添加exhale_args對象中定義的rootFileName。如下圖中的api/library_root：

添加根文件

需要注意的是這些文件必須放在toctree指令下面，并且不能和上面冒號所表示的選項相連，要空一行。另外，Sphinx也可以支持markdown和rst混合，但是這需要recommonmark插件支持。完成這一步，就以及可以生成文檔了！

Sphinx RTD Theme

為了擁有readthedoc那樣的漂亮主題，還需要pip install sphinx_rtd_theme并且在conf.py中添加相應(yīng)代碼：

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
import os 
# on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
on_rtd = os.environ.get('READTHEDOCS', None) == 'True'

if not on_rtd:  # only import and set the theme if we're building docs locally
    import sphinx_rtd_theme
    html_theme = 'sphinx_rtd_theme'
    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

文檔生成

在doc文件夾下執(zhí)行make html就可以得到html網(wǎng)頁版的documentation。效果非常贊！需要注意的是默認doxygen是不會輸出類的private成員的，需要修改doxygen的配置或參數(shù)。

image.png

在文檔系統(tǒng)中，我們不僅僅可以寫代碼注釋說明，還可以加入公式甚至圖片，相比另外寫一個單獨的說明文檔，不知道高到哪里去了！在別人在代碼和word之間來回穿梭時你只需要好好寫注釋，然后make一下，然后就可以和小姐姐談笑風(fēng)生去了，回來就可以看到最新且完美的文檔網(wǎng)頁！并且所有類型的鏈接都自動關(guān)聯(lián)好了，非常好查詢。比如下圖中我們可以顯示LaTeX，并注釋函數(shù)參數(shù)。具體如何去寫這種文檔注釋，有很多風(fēng)格，請參考Doxygen的官方文檔。

你們搞的這個文檔系統(tǒng)啊，Excited!

還有很多其他功能和配置，就不在這里一一展示了。

總結(jié)

Sphinx文檔系統(tǒng)非常好用，而且網(wǎng)頁很漂亮，讀起來非常愉悅。利用exhale構(gòu)建文檔系統(tǒng)的方法也很簡單，只需要做三件小事（不談安裝）：1.sphinx-quickstart；2.修改index和conf.py；3.make！真的非常方便了。那么，大家一起努力來寫出精美漂亮的工程文檔吧!

作者：高壓電力電容器
https://www.bilibili.com/read/cv3247399
略有修改