使用MKDocs构建Markdown格式API文档(macOS)

1. MkDocs是什么?

   MKDocs就是一个能快速，简单，优雅的生成静态文档站点的项目。文档用Markdown书写，目录用YAML配置，弄好之后你可以把它放到Github的Pages 上，或者自己服务器上就可以了。并且也有好几套UI供你选择MkDocs UI，特别适合那些做开源项目的童鞋，生成说明文档使用。总的来说，就是省时省力，效果还不错

2. 安装

   我的机子装了brew，所以可以直接命令行安装软件。

   1. 安装Python

      在终端输入下面指令：brew install python

      查看版本：

      python --versionPython 2.7.10

   2. 安装mkdocs

      在终端输入下面指令：pip install mkdocs

      查看版本：

      mkdocs --versionmkdocs, version 0.15.3

3. 实战一下

   1. 在终端输入下面指令：mkdocs new project。创建一个名为project的mkdocs的项目。

   2. 运行项目：

      cd projectmkdocs serve

   3. 显示如下：

      Running at: http://127.0.0.1:8000/

   4. 在浏览器中访问上面的链接即可。

4. 解释一下

   1. 在project文件下，会有一个doc目录和一个mkdocs.yml文件，.yml就是配置文件。修改里面的内容就可以修改样式以及需要添加的展示内容。

   2. 给出几个样式：

      theme: readthedocstheme: bootstraptheme: ameliatheme: cosmotheme: slatetheme: yetitheme: unitedtheme: journal

5. 其他指令

   $mkdocs build /*生成网站的site目录，里面有一些静态资源*/$mkdocs build --clean$mkdocs --help

6. 说明

   系统：macOS

   其他详细的说明，可以去官网查看MKDocs。

---

参考资料：
MKDocs官网文档
备注：
转载请注明出处：http://blog.csdn.net/wsyw126/article/details/51997395
作者：WSYW126