寫文檔很重要嗎？

當(dāng)你寫了上萬行代碼，幾十幾百個函數(shù)和類，然后面對源文件一臉懵逼的時候你就不會有這個疑問了。如果規(guī)模較小，那么文檔系統(tǒng)可能對自己沒有太大幫助。但是寫文檔總可以幫助自己總結(jié)和記錄工作。對其他人而言，要知道你的軟件和代碼如何使用，首先就是看你的說明文檔，就和產(chǎn)品說明書一樣，所以寫文檔是非常重要的。

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

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

為啥用Sphix

為什么使用Sphinx

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

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

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

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

Doxygen+breathe+Sphinx

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

pip install exhale

就可以集成到Sphinx里去了（不過Doxygen還得另外下載安裝）。具體參見?https://exhale.readthedocs.io/en/latest/。

根據(jù)網(wǎng)站介紹，你的c++工程需要這樣的結(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文件夾下運(yùn)行sphinx-quickstart生成文檔編譯所需的各項文件，再去修改這些配置。然后在conf.py中添加網(wǎng)站所述樣例代碼，就成功配置exhale的文檔插件了。

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

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

文檔生成

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

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

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

總結(jié)

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