在 GitHub上的 C++ 項目，應該用什麼文檔工具寫使用手冊和 API 手冊？

01-05

最近把rapidjson搬到Github，想重新編寫一些文檔。有人介紹用Read the Docs去自動生成文檔，它可以continuous integration(CI)，更新文件後自動通知它生成HTML及PDF，好像不錯。但是它不能處理doxygen的API標記。之後找到了breathe，可以用doxygen生成XML然後再轉換成RST，但沒有TOC，而且生成全部文檔的時候private及undoc的東西都顯示出來，如TinyXML Test Suite，似乎沒法使用。
希望能有CI，不用人手生成上傳。沒有建議呢？

首先多謝各位提供的答案，之後考慮了這些答案以及其他網友的意見，最後得出一個方案。

分享一下我現時的方案。效果：RapidJSON: Main Page

這個方案沿於發現較新版本的 Doxygen 支持了 Markdown，可以 Markdown 作為輸入，然後生成HTML。

然後在 Travis CI 寫腳本運行 Doxygen，當每次有新 commit，就會自動生成文檔及上載至 GitHub Pages。(.travis.yml, travis-doxygen.sh)

更改 doxygen 的 header/footer HTML及CSS文件，讓 Markdown 的效果接近 GitHub，而 navigation 風格則是接近Read the Docs。

現在還未細調 API reference 的 CSS，但整體效果我覺得可以了。而且在 Markdown 裡，代碼中的類、方法還可以直接鏈接至API reference。

唯一有些問題是由GitHub渲染的Markdown中鏈接會出現錯誤，但不影響閱讀。

另外，那些圖是用Graphviz繪畫的。

Getting started guide 用 markdown，讓 github 去渲染。

API reference manual 用代碼 header 中的注釋充當，不用單獨生成一套 html 文檔。function/class 前面的注釋的格式首先照顧 IDE 的智能提示（如果有），然後照顧 doxygen。

好多年不做CPP項目了，如果是希望類似python docstring 那樣可以代碼跟文檔一起寫，確實不知道有什麼比較好的工具。

挺好的工具

maven