23 Document: Be Obssessed

23 文档：鬼迷心窍

Given a choice between ice cream and writing great documentation, most Python developers would probably choose to write the documentation. That being said, writing documentation while eating ice cream is even better.

如果要在冰淇淋和编写优秀文档之间进行选择，大多数 Python 开发人员可能会选择去编写文档。话虽如此, 如果能吃着冰淇淋写文档那就更好了。

When you have great documentation tools like reStructuredText and Sphinx, you actually can't help but want to add docs to your projects.

当你有像 reStructuredText 和 Sphinx 这么好的文档工具时，你真的止不住为你的项目添加文档。

PACKAGE TIP: Install Sphinx SystemWide

We've found that simply installing sphinx fetches for us all the pieces you need to doucment our Django(or Python) project. We recommend pip installing Sphinx systemwide, as you'll want to have it handy for every Django project.

PACKAGE TIP：在全局安装 Sphinx

我们发现可以简单的安装 Sphinx 来记录所有我们的 Django（或 Python ）项目需要的文档。我们建议使用 pip 全局安装 Sphinx，因为你会希望在每个Django 项目方便地使用它。

23.1 Use reStructuredText for python Docs

23.1 使用 reStructuredText 来记录 Python 文档

you'll want to learn and follow the standard Python best practices for documentation. These days, reStructuredText(RST) is the most common markup language used for documenting Python projects.

你将需要学习并遵循标准的 Python 文档最佳实践。现在，reStructuredText(RST) 是 Python 项目中最常见的标记语言。

What follows are links to the formal reStructedText specification and a couple sample projects which benefit from using it:

下面是 reStructedText 正式规范的链接和一些从中受益的项目：

While it's possible to study the formal documentaion for reStructuredText and learn at least the basics, here is a quick primer of some very useful commands you should learn.

尽管学习 reStructuredText 的官方文档并且至少掌握些基础是最好的，这里有一些你应该学习的非常有用的命令快速入门。

EXAMPLE 23.1
Section Header
==============

**emphasis (bold/strong)**

*italics*

Simple link: http://django.2scoops.org
Fancier Link: 'Two Scoops of Django'_

.. _Two Scoops of Django: https://django.2scoops.org

Subsection Header
_________________

#) An enumerated list item

#) Second item

* First bullet

* Second bullet
    * Indented Bullet
    * Note carriage return and indents

Literal code block::

    def like():
        print("I like Ice Cream")

    for i in range(10):
        like()

Python colored code block (requires pygments):

code-block:: python

    # You need to "pip install pygments" to make this work

    for in in range(10):
        like()

JavaScript colored code block:

code-block:: javascript

    console.log("Don't use alert()")

23.2 Use Sphinx to Generate Documentation From reStructuredGText

23.2 使用 Sphinx 来从 reStructuredGText 生成文档

Sphinx is a tool for generate nice-looking docs from your .rst files. Output formats include HTML, LaTex, manual pages and plain text.

Sphinx 是一个根据你的 .rst 文件来生产好看文档的工具。它的输出形式包括 HTML, Latex， 手册页和纯文本。

Follow the instructions to generate Sphinx docs: http://sphinx-doc.org/.

按照这个说明来生成 Sphinx 文档： http://sphinx-doc.org/。

TIP: Build Your Sphinx Documentation at least Weekly

You never know when bad cross-references or invalid formatting can break the Sphinx Build. Rather than discover the documentation is unbuildable at an awkward moment, just make a habit of ceating it on a regular basis.

TIP: 每周至少都要构建一次你的 Sphinx 文档

你永远不知道有问题的相互引用或无效的格式可以打破 Sphinx 的构建。 与其在一个尴尬的时刻发现文档是不可构建的，只是保持一个定期创建它的习惯。

23.3 What Docs Should Django Projects Conatin?

23.3 Django 项目汇总应该包含什么文档

Developer-facing documentation refers to notes and guides that developers need in order to set up and maintain a project. This includes notes on installation, deployment, architecture, how to tests or submit pull requests, and more. We've found that it really helps to place this documentation in all our projects, private or public. Here we provide a table that describes what we consider the absolute minimum documentation:

面向开发者的文档指的是开发人员为了设置和维护项目而需要的注释和指南。这包括有关安装，部署，架构，如何测试和提交 pull 请求等等。我们发现，将这个文档放置在我们的所有项目（无论是私人或公共）中真的很有帮助。这里我们提供了一张表描述了我们认为一个项目中至少应该有的文档：

Filename or directory reason notes
README.rst Every python project you begin should have a README.rst file in the repository root. Provide at least a short paragraph describing what the project does. Also, link to the installation instructions in the docs/directory.
docs/ Your project documentation should go in one, consistent location. This is the Python ciommunity standard. A simple directory.
Docs/deployment.rst This file lets you take a day off. A point-by-point set of instructions on how to install/update the project into production, even if it's done via something powered by Ruby, Chef, Fabric, or a Makefile
docs/installtion.rst this is really nice for new people coming into a project or you get a new laptop and need to set up the project. A point-by-point set of instructions on how to onboard yourself or another developer with the sofware setup for a projec
docs/architecture.rst A guide for understanding what things evloved from as a project ages and grows in scope. This is how you imagine a project to be in simple text and it can be as long or short as you want. Good for keeping focuned at the beginng of an effort.

​ Table 23.1 Documentation Django Projects Should Contain

文件名或目录 原因 说明
README.rst 每一个你开始的 Python 项目根目录中都应该有一个 README.rst 文件。 至少应该提供一段描述说明这个项目是做什么的。另外，提供在 docs/ 目录中安装指示的链接
docs/ 你的项目文档应该放在一个统一的地方，这是 Python 社区的标准。 只是一个文件夹。
docs/deployment.rst 这个文件可以让你休一天的假。 有关如何将项目安装/更新到生产环境的逐步指令，无论部署是通过Ruby，Chef，Fabric或Makefile 完成的。
docs/installation.rst 当一个新人加入项目或者你拥有一台新电脑需要启动这个项目的时候是非常好的。 一个让你自己或其他开发人员完成安装一个项目软件相关配置的逐步指令。
docs/architecture.rst 一份关于项目在规模上逐步演化的指南。 这是描述你认为这个项目应该变的怎么样的简单文本，长度可以根据你所想的调整。在项目开始时就保持关注是良好的习惯。

23.4 Additional Documentation Resources

23.4 额外的文档资源

23.5 The Markdown Alternative

23.5

Markdown ia a text formatting syntax not too dissimilar to reStructuredText. While it doesn't have build-in features of reStructuredText, it does have the advantage of being easier to learn. While used infrequently in the Python and Django communities, it's popular in tangential places including the JavaScript and technical book-writing community.

When using Markdown instead of reStructuredText for open source projects, keep the folling in mind:

  • PyPI will not format the log_description if it's written in anything except reStruectedText.
  • Many Python and Django developers will search reStructedText-powered documentation sources before Markdown-powered ones.

23.5.1 README.md to README.rst: Using Pandoc for Packages Uploaded to PyPI

Pandoc is a command-line tool that allow us to convert files from one markup format into another. We can write a README in one format, and for uploading to PyPI, display it in another. Here's how some people use pandoc in their setup.py module:

EXAMPLE 23.2

# setup.py
import subprocess
import sys

if sys.argv[-1] == 'md2rst':
    subprocess.call('pandoc README.md -o README.rst', shell=True)
...

To convert a README.md to README.rst, just run python setup.py md2rst. Then we upload the package to PyPI as per the normal process.

23.5.2 Markdown Resource

23.6 Wikis and Other Documentation Methods

For whatever reason, if you can't place developer-facing documentation in the project itself, you should have other options. While wikis, online document stores, and word processing documents don't have the feature of being placed in version control, they are better than no documentation.

Please consider creating documents whithin these other modules with the same names as the one we suggested in the table on the previous page.

23.7 Summary

In the chapter we went over the following:

  • The use of reStruectedText to write documentation in plaintext format.
  • The use Sphinx to render your documentation in HTML and EPUB formats. If you know how to install LaTeX you can even render it as PDF. For reference, install LaTeX is easy to do on linux and Windows and a bit harder on Mac OS X.
  • Advice on the documentation requirements for any Django project.
  • Using Markdown for documentation, and convert README.md to README.rst

Next, we'll take a look at common bootlenecks in Django projects and ways to deal with them.

results matching ""

    No results matching ""