寫(xiě)文檔很重要嗎簿煌？
當(dāng)你寫(xiě)了上萬(wàn)行代碼，幾十幾百個(gè)函數(shù)和類(lèi)褒侧，然后面對(duì)源文件一臉懵逼的時(shí)候你就不會(huì)有這個(gè)疑問(wèn)了良风。如果規(guī)模較小，那么文檔系統(tǒng)可能對(duì)自己沒(méi)有太大幫助闷供。但是寫(xiě)文檔總可以幫助自己總結(jié)和記錄工作烟央。對(duì)其他人而言，要知道你的軟件和代碼如何使用歪脏，首先就是看你的說(shuō)明文檔疑俭，就和產(chǎn)品說(shuō)明書(shū)一樣，所以寫(xiě)文檔是非常重要的婿失。文檔系統(tǒng)是什么呢钞艇？隨著軟件系統(tǒng)的復(fù)雜度日益增大，人們迫切需要一種規(guī)范的軟件文檔使維護(hù)和使用他人軟件代碼更加方便和標(biāo)準(zhǔn)化豪硅。這就催生了文檔系統(tǒng)香璃，例如Javadoc。通過(guò)在源代碼中特殊的注釋方式舟误，就可以通過(guò)Javadoc生成非常標(biāo)準(zhǔn)化的注釋文檔，并且文檔系統(tǒng)會(huì)分析類(lèi)之間的繼承關(guān)系姻乓，區(qū)分類(lèi)型嵌溢，形成查詢(xún)索引，大大減輕了人工創(chuàng)建和維護(hù)文檔的負(fù)擔(dān)蹋岩。更方便地是赖草，它可以直接生成在線(xiàn)的網(wǎng)頁(yè)使得文檔的查閱變得很方便。
文檔系統(tǒng)是什么呢剪个？
隨著軟件系統(tǒng)的復(fù)雜度日益增大秧骑，人們迫切需要一種規(guī)范的軟件文檔使維護(hù)和使用他人軟件代碼更加方便和標(biāo)準(zhǔn)化。這就催生了文檔系統(tǒng)，例如Javadoc乎折。通過(guò)在源代碼中特殊的注釋方式绒疗，就可以通過(guò)Javadoc生成非常標(biāo)準(zhǔn)化的注釋文檔，并且文檔系統(tǒng)會(huì)分析類(lèi)之間的繼承關(guān)系骂澄，區(qū)分類(lèi)型吓蘑，形成查詢(xún)索引，大大減輕了人工創(chuàng)建和維護(hù)文檔的負(fù)擔(dān)坟冲。更方便地是磨镶，它可以直接生成在線(xiàn)的網(wǎng)頁(yè)使得文檔的查閱變得很方便。
為什么使用Sphinx
C++標(biāo)準(zhǔn)的文檔系統(tǒng)是Doxygen健提，而且Doxygen也可以支持很多其他語(yǔ)言琳猫。而Sphinx主要是寫(xiě)python文檔用的。那么為什么還要使用Sphinx呢私痹？原因有：
-
Doxygen生成的文檔很丑脐嫂。這讓你的工程看起來(lái)活在90年代。而Sphinx的文檔主題（readthedoc主題）看起來(lái)很現(xiàn)代侄榴。
Eigen的Doxygen文檔
Tornado的Sphinx文檔 Sphinx可以在Readthedoc網(wǎng)站上在線(xiàn)編譯并托管發(fā)布雹锣，不需要建立自己的網(wǎng)站就可以在線(xiàn)發(fā)布文檔了。
那么問(wèn)題來(lái)了癞蚕，Sphinx是python的文檔系統(tǒng)蕊爵，一個(gè)Python的文檔系統(tǒng)，怎么就跑去生成C++文檔了呢桦山，主要還是這個(gè)顏值和Sphinx的強(qiáng)大功能攒射。接下來(lái)就簡(jiǎn)單說(shuō)下怎么做。
Doxygen+breathe+Sphinx
由于C++文檔需要Doxygen去生成恒水，因此有人發(fā)明了breathe去橋接Sphinx和Doxygen兩個(gè)文檔系統(tǒng)会放。可以把Doxygen的輸出作為輸入給Sphinx钉凌。后來(lái)又有人做了簡(jiǎn)化的工具exhale咧最，只需要如下命令：
pip install exhale
就可以集成到Sphinx里去了（不過(guò)Doxygen還得另外下載安裝）。具體參見(jiàn)文檔御雕。
根據(jù)網(wǎng)站介紹矢沿，你的c++工程需要這樣的結(jié)構(gòu)。
其中include和src是你的c++工程酸纲，和文檔系統(tǒng)其實(shí)沒(méi)有關(guān)系捣鲸，只是文檔系統(tǒng)需要分析的對(duì)象。只有docs文件夾里的內(nèi)容才是文檔系統(tǒng)的主體闽坡。其中又可以看到index.rst栽惶，這個(gè)文件是Sphinx文檔的主頁(yè)愁溜，規(guī)定要顯示的頁(yè)面內(nèi)容。conf.py是Sphinx的配置文件外厂，里面需要包括插件配置以及其他參數(shù)的設(shè)置冕象。需要注意的是，實(shí)際上我們首先應(yīng)該做的是在doc文件夾下運(yùn)行sphinx-quickstart生成文檔編譯所需的各項(xiàng)文件酣衷，再去修改這些配置交惯。然后在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í)最重要的一個(gè)參數(shù)就是 exhaleDoxygenStdin 中的INPUT參數(shù)。它指向你想生成文檔的頭文件啊片。這時(shí)只锻，文檔系統(tǒng)以及可以調(diào)用doxygen并生成文檔了，但是還需要讓他在頁(yè)面上顯示出來(lái)紫谷。這就需要在index.rst中添加exhale_args對(duì)象中定義的rootFileName齐饮。如下圖中的api/library_root：
需要注意的是這些文件必須放在toctree指令下面，并且不能和上面冒號(hào)所表示的選項(xiàng)相連笤昨，要空一行祖驱。另外，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)頁(yè)版的documentation。效果非常贊拔稳！需要注意的是默認(rèn)doxygen是不會(huì)輸出類(lèi)的private成員的葛峻，需要修改doxygen的配置或參數(shù)。
在文檔系統(tǒng)中巴比，我們不僅僅可以寫(xiě)代碼注釋說(shuō)明术奖，還可以加入公式甚至圖片，相比另外寫(xiě)一個(gè)單獨(dú)的說(shuō)明文檔轻绞，不知道高到哪里去了腰耙！在別人在代碼和word之間來(lái)回穿梭時(shí)你只需要好好寫(xiě)注釋?zhuān)缓髆ake一下，然后就可以和小姐姐談笑風(fēng)生去了铲球，回來(lái)就可以看到最新且完美的文檔網(wǎng)頁(yè)！并且所有類(lèi)型的鏈接都自動(dòng)關(guān)聯(lián)好了晰赞，非常好查詢(xún)稼病。比如下圖中我們可以顯示LaTeX选侨，并注釋函數(shù)參數(shù)。具體如何去寫(xiě)這種文檔注釋?zhuān)泻芏囡L(fēng)格然走，請(qǐng)參考Doxygen的官方文檔援制。
還有很多其他功能和配置芍瑞，就不在這里一一展示了晨仑。
總結(jié)
Sphinx文檔系統(tǒng)非常好用，而且網(wǎng)頁(yè)很漂亮拆檬，讀起來(lái)非常愉悅洪己。利用exhale構(gòu)建文檔系統(tǒng)的方法也很簡(jiǎn)單，只需要做三件小事（不談安裝）：1.sphinx-quickstart竟贯；2.修改index和conf.py答捕；3.make！真的非常方便了屑那。那么拱镐，大家一起努力來(lái)寫(xiě)出精美漂亮的工程文檔吧!
作者：高壓電力電容器
https://www.bilibili.com/read/cv3247399
略有修改
