最近在给一个app做后台开发，许多api需要写文档说明，找了一下写文档的工具，发现还是有很多非常高效的工具值得好好学习。其中，也找到了Slate这个很不错的API 文档编写工具。

Write In reStructuredText

使用Sphinx进行编写

Sphinx 是一种文档工具，它可以令人轻松的撰写出清晰且优美的文档, 由 Georg Brandl 在BSD 许可证下开发. 新版的Python文档 就是由Sphinx生成的， 并且它已成为Python项目首选的文档工具,同时它对 C/C++ 项目也有很好的支持; 并计划对其它开发语言添加特殊支持.

pip install sphinx sphinx-autobuild
cd /path/to/project
mkdir docs
cd docs
sphinx-quickstart

然后按提示进行操作，生成一个 index.rst，conf.py

make html

这里可以使用 Read the documents 的主题，参考https://github.com/snide/sphinx_rtd_theme

[/bash]
pip install sphinx_rtd_theme
[/bash]

在conf.py文件中，

import sphinx_rtd_theme
html_theme = "sphinx_rtd_theme"
html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]

Sphinx 官方网站：http://sphinx-doc.org/

中文手册：http://zh-sphinx-doc.readthedocs.org/en/latest/

Write In Markdown

使用Mkdocs进行编写

pip install mkdocs
cd /path/to/project
mkdocs new docs

mkdocs build

参考：http://docs.readthedocs.org/en/latest/getting_started.html#write-your-docs

Read the Docs

官方网站：https://readthedocs.org/ 

Read the Docs 托管文档， 让文档可以被搜索和更易查找。您可以导入您使用版本控制系统托管的文档，包括 Mercurial, Git, Subversion, 和 Bazaar。我们支持 webhooks 因此可以在您提交代码时自动构建文档。并且同样也支持版本功能，因此您可以构建来自您代码仓库中某个标签或分支的文档。

根据官方的介绍，它可以直接从你的github项目生成文档，托管你的文档，实时更新……

Write the Docs

官方网站：http://conf.writethedocs.org/

Write the Docs is a series of conferences and local meetups focused on documentation systems, tech writing theory, and information delivery.

We consider everyone who cares about communication and documentation and their users to be a member of our community. This can be programmers, tech writers, customer support, marketers, and anyone else who wants people to have great experiences with software.

Our conferences create a time and a place for the global community of documentarians to share information, discuss ideas, and work together to improve the art and science of documentation.

We invite all those who write the docs to spread the word: Docs or it didn’t happen!

手册：http://docs.writethedocs.org/en/latest/

Middleman

官方网站：http://middlemanapp.com/

Middleman is a static site generator using all the shortcuts and tools in modern web development.

middleman用于快速开发静态网站，具体参考：http://middlemanapp.com/basics/getting-started/

Slate

基于middleman实现的一个api文档编写工具（markdown）：https://github.com/tripit/slate，简单快速高效，需要依赖Ruby，Bundle.

Getting Set Up

1. Fork this repository on Github.
2. Clone your forked repository (not our original one) to your hard drive with git clone https://github.com/YOURUSERNAME/slate.git
3. cd slate
4. Install all dependencies: bundle install
5. Start the test server: bundle exec middleman server

You can now see the docs at http://localhost:4567. And as you edit source/index.md, your server should automatically update! Whoa! That was fast!

最后发布：bundle exec middleman build