文档管理

项目文档用来说明和记录项目的信息，有助于开发人员、管理人员、使用者的交流和沟通。 在 Python 项目中 一般通过 Mkdocs 和 sphinx 来构建项目文档。 两者都支持 markdown 标记的文件，但后者也支持 reStructuredText 标记文件。

Readme

**Readme**与文档管理中的文档是不同的，各自有各自的作用。

• Readme：这应该是每个项目都应该有的一个文件，目的是能简要描述该项目的信息，让读者快速了解这个项目。Readme负责简单介绍项目背景、软件功能、简单的使用说明、常见问题等等信息。
• 文档（docs）：文档负责记录整个项目的具体信息，包括项目结构、模块功能实现、开发日志、版本控制等等。

MkDocs

MkDocs是一个快速、简单、华丽的静态网站生成器，适用于构建项目文档。文档源文件以Markdown编写，并使用一个YAML文件来进行配置。 MkDocs生成完全静态的HTML网站，你可以将其部署到GitHub pages、Amzzon S3或你自己选择的其它任意地方。 MkDocs有一堆很好看的主题。 官方内置了两个主题： mkdocs 和 readthedocs， 也可以从MkDocs wiki中选择第三方主题， 或者自定义主题。你还可以使用第三方库mkdocs-material来使用更多更好看的主题库以及更强大的插件。

• MkDocs官网
• MkDocs官方中文文档
• MkDocs-Material

特点：

• YAML 单文件配置
• 生成静态站点
• 支持 markdown
• 支持自定义主题
• 支持 markdown 扩展标记
• 支持插件

注： 本网站也是使用通过编写MarkDown文件，然后使用MkDocs与mkdocs-material生成的静态网站。

Sphinx

Sphinx 是一个 文档生成器 ，您也可以把它看成一种工具，它可以将一组纯文本源文件转换成各种输出格式，并且自动生成交叉引用、索引等。 也就是说，如果您的目录包含一堆 reStructuredText 或 Markdown 文档，那么 Sphinx 就能生成一系列HTML文件，PDF文件（通过LaTeX），手册页等。

Sphinx 专注于文档，尤其是 handwritten documentation ，然而，Sphinx 也可以用来生成博客、主页甚至书籍。 Sphinx 的大部分功能来自于 reStructuredText ，它是一种纯文本标记格式，有着丰富的功能和 显著的扩展能力 。 例如Google Python风格指南中文版就是使用 Sphinx 与 reStructuredText 文档生成的网站。

• Sphinx官网
• Sphinx官方中文文档

特点：

• 单个 Python 文件配置
• 生成 HTML 、 ePub 等多种格式
• 支持 markdown 和 reStructuredText
• 支持自定义主题
• 支持扩展