请稍侯

文档生成器doxygen在github中的设置

26 March 2014
更多

Doxygen是一个编写软件参考文档的工具。该文档是直接写在代码中,因此比较容易保持更新。 Doxygen可以交叉引用文档和代码,使文件的读者可以很容易地引用实际的代码。

如果你的代码托管在Github中,则可以通过gh-pages生成文档,保持你的代码和文档的持续演进。

这里是我在github中使用doxygen的demo:

https://github.com/rookiecalf/doxygenDemo

doxygen生成文档效果:

http://softci.com/doxygenDemo/index.html

此处假定你的个人电脑上已经安装了doxygen和git,并且拥有github账号。下面主要介绍配置过程。

首先创建git本地仓库,并push到github:

# Make your gitHub project. 
mkdir doxygenDemo
cd doxygenDemo/
git init
echo "# doxygenDemo README file" > README.md
git add .
git commit -m "doxygenDemo README added"
git remote add origin git@github.com:rookiecalf/doxygenDemo.git
git push origin master

当然你也可以在github中创建仓库,然后使用git将clone到本地。

接下来需要创建html子目录,并在git中ignore此目录:

# Make a new html directory, and tell git to ignore it. 
mkdir html
echo "html/" > .gitignore
git add .
git commit -m ".gitignore html/ folder (contains gh-pages branch)"
git push origin master

创建本项目的gh-pages:

在settings选项内,点击automatic page genorator ,点击load README.md,点击 continue to layouts,最后点击publish。在代码库中生成gh-pages分支。

clone仓库到html子目录:

cd html/
git clone git@github.com:rookiecalf/doxygenDemo.git .
git checkout origin/gh-pages -b gh-pages

使用命令git branch可以看到gh-pages和master两个分支,删除master分支:

git branch -d master

删除有github生成的html文件:

rm -r *.*
rm -rf images/ javascripts/ stylesheets/

添加README.md文件并push到gh-pages分支:

echo "# html README file" > README.textile
git add . 
git commit -m "html README added"
git push origin gh-pages

到这里,将在doxygenDemo得到master分支,html目录下得到gh-pages分支。

在doxygenDemo目录下建立docs目录,并生成doxygen配置文件:

mkdir docs
cd docs
doxygen -s -g

配置Doxyfile,将INPUT设定为你需要生成文档的目录或文件,在doxygenDemo目录中运行doxygen生成文档(更直观的方式为使用doxygen图形化工具来生成,生成目录设定为html):

doxygen ./docs/Doxyfile

将修改push到master分支:

git push origin master

最后将生成的html文件push到gh-pages分支:

cd html
git add .
git commit -m "add doxygen html files to doxygenDemo"
git push origin gh-pages

如此,可以看到如此效果的doxygen:

http://softci.com/doxygenDemo

可以参考的文章和文件:

1、http://rickfoosusa.blogspot.com/2011/10/howto-use-doxygen-with-github.html

2、http://www.admb-project.org/developers/workshop/reykjavik-2013/doxygen-github.pdf/at_download/file