项目文档

作者:王蒙 标签:文档，python 开发，编码规范，持续集成 简介:没有文档介绍的项目，别人没法使用。所以文档对于项目至关重要。

Contents

• 项目文档
  • 目标读者
  • 预备知识
  • 问题
  • 解决办法
    • 技术文档写作7个规则
    • 通常项目要写哪些文档
    • A reStructuredText Primer
    • 文档构建和项目集成
  • 参考文献

目标读者

Python 开发

预备知识

问题

• 技术文档写作规则
• 项目通常包含哪些文档
• Python 推荐的文档格式
• 持续集成和文档托管

解决办法

技术文档写作7个规则

1. 开始写的时候，专注于内容；然后整个检查一遍，整理格式。
2. 每个文档针对明确的读者。
3. 文档应该写的尽可能简单。比如一句话不要太长，一个段落不要太长等等。
4. 分主题组织文档，给每篇文档写合适的题目。选择标题时，可以想，如果读者对文档内容感兴趣，他会在 Google 中输入什么。
5. 使用统一的格式，使用模板。
6. 不要写过多的文档，特别不要在文档中写废话，开玩笑等等。
7. 示例代码，选择真实的，拿来就能运行的代码片段。

通常项目要写哪些文档

• Design

• Usage

  • Recipe
  • Tutorial
  • Module Helper

• Operations

  • Installation and deployment documents
  • Administration documents
  • FAQ
  • Documents that explain how people can contribute, ask for help, or provide feedback

A reStructuredText Primer

Python 文档推荐使用 reStructuredText 格式写。

• reStructuredText Premier

• Sphinx 是比 Docutils 要强大的工具。

  • Sphinx 编译出的文档支持检索。
  • Sphinx 编译出的文档有多种主题可选，更美观。
  • Sphinx 支持 toctree 命令，能生成 index 页。
  • Sphinx 能根据 Python 源码的 docstring 生成 API 文档。

• Sphinx 提供的重要的 directives:

  module mod toxtree index

文档构建和项目集成

一般会把编译生成文档，把文档挂到文档托管平台（比如对于开源项目可以使用 readthedocs 服务）的流程放进持续集成配置中。 这样做之后，文档每次更新都能及时反映给文档的读者。 开源项目可以免费使用 Travis 提供的持续集成服务。

参考文献

• Sphinx: http://www.sphinx-doc.org/en/master/
• Sphinx 文档模板：http://graceful.readthedocs.io/en/latest/
• recipe 模板： http://code.activestate.com/recipes/langs/python/
• reStructuredText premier: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
• reStructuredText 幻灯片: http://docutils-zh-cn.readthedocs.io/zh_CN/latest/user/slide-shows.html#features-2-handouts
• readthedocs 文档托管平台： https://readthedocs.org/
• Travis: https://www.travis-ci.org/getting_started