项目文档生成器

有了用Markdown格式写好的文档，如何展示给其他开发者或者同事呢？在Github上，当一个开发者上传了库项目后，通常会使用README文件的形式将项目说明写在里面，这样当其他开发者访问这个页面的时候，就可以在主页上看见该项目的README文件内容。那么，如果不是Github呢？还好现在已经有工具来帮助开发者展示项目文档了，这个工具就是MkDocs。

该工具的项目地址为http://www.mkdocs.org/，项目如1.63所示。

它的一个示例网站如图1.64所示。

可以看见该工具生成的界面，左边是项目的文档结构，这些都是通过Markdown生成的，而右边则是对应的文档说明，简洁明了，一目了然。

图1.63　MkDocs

图1.64　MkDocs示例

通过这个工具，可以清晰地展现项目文档，不管是开发者还是管理者，通过这个文档可以非常快地了解项目。而这个项目仅仅是通过Markdown文件就可以生成，同时还可以设置不同的主题和风格，适用于开发者进行文档管理。

类似的工具还有Raneto Docs。与MkDocs相似，它也是一个利用Markdown进行文档管理的系统，其官方地址为http://raneto.com/，示例界面如图1.65所示。

图1.65　Raneto

这些工具基本上都是一个原理，即通过Markdown管理API文档。Markdown的优势可见一斑。通过Markdown生成的文档，格式整齐、风格统一、简洁明了，对于程序API来说，这是一个非常好的展示文档。