下一步看什么

如果你已经读完了 介绍文档，且对继续使用 Django 感兴趣。不过，你读的是整体文档的精简版（实际上，如果你逐字阅读了此文档，你已经阅读了整体文档的 5%）。

那么下一步做什么？

不错，我们已经通过边学边做成为了 Django 的死忠粉了。此时，你应该已经知道如何开始你自己的工程，且会到处搜索其它文档了。想知道更多技巧的话，请回到文档页。

为了使 Django 的文档达到更易使用，更清晰，更加全面的目的，我们付出了巨大的努力。本文档的剩余部分将更详细地介绍此文档的工作方式，以便你可以充分利用它。

（是的，这就是传说中的说明文档的说明文档。请放心，我们不打算写一篇关于如何阅读此文档的文档。）

查找文档

Django 有 许多 文档——差不多由 450,000 字（英文单词）——所以查找你需要的文档可能需要点技巧。有一个好的起点 索引。我们还建议使用内置搜索功能。

或者你可以只是四处看看！

文档是如何组成

Django的主要文档以“块”的形式划分，用于满足不同的需求：

  • The introductory material is designed for people new to Django — or to web development in general. It doesn’t cover anything in depth, but instead gives a high-level overview of how developing in Django “feels”.

  • 另一方面，The 主题指南 则深入介绍 Django 的各个部分。那里有更多完整的关于 Django的 模板系统, 模板引擎, 表单框架 和其它东西的信息。

    这可能是你会花费你大部分时间的地方。如果你详细阅读了这些指南，你就能了解几乎所有关于 Django 的知识。

  • Web 开发通常是广而不深的——问题通常跨越多个领域。我们已经写了一系列的文档 how-to 指引 用于回答常见的“为什么我会……？”系列问题。在这里，你可以找到关于 通过 Django 生成 PDF，定义自定义模板标签 的文档，当然，还有其它的文档。

    关于常见问题的回答可参见 FAQ。

  • 这个引导和怎么做的文档不会覆盖 Django 中每个可用的类，函数和方法——在你想学的时候，你会发现实在是太多了。作为替代，每个类，函数，方法和模块的细节在 参考 中介绍。那是你未来查找某个函数的细节或其它你需要的东西的地方。

  • 如果你对部署一个公用的工程感兴趣，我们有介绍各种部署设置的文档 几个指引 和介绍你几个你需要了解的东西的文档 部署清单。

  • 最后，这里有一些与大部分开发者无关的“专业”文档。包含 发布说明 和 内部文档 ，用于向那些想向 Django 提交代码的专业人士。还有一份文档 不适合放到其它地方的一点内容 。

这个文档是如何更新的

就像 Django 的源码每天都被更新和提升一样，我们的文档也会持续优化。我们因为以下几个原因优化文档：

  • 更正内容，如更正语法/拼写错误。
  • 向已有的需要被扩展的某个章节添加介绍信息或例子。
  • 记录尚未记录的 Django 功能。 （这些功能的列表正在缩小，但仍然存在。）
  • 在新特性被添加时，或 Django 的 API 或行为有变化时，会添加新文档。

Django 的文档以和它的代码一样，以代码版本管理系统方式进行管理。它被保存在 git 仓库的 docs 目录内。每份在线文档都是仓库内的一份独立文本文件。

从哪里获取这个

你可以以好几种形式阅读 Django 的文档。他们按照优先顺序排列：

On the web

Django 最新的在线版文档位于 https://docs.djangoproject.com/en/dev/。这些网页由 Django 的源码控制系统中的纯文本文件自动生成。这意味着它们展示了 Django “最新最好” 的修改——它们包含最新的更正和补充，并讨论了最新的Django功能，这些功能只可供Django开发版的用户使用。（参见以下关于“不同版本之间的差异”的介绍。）

为提高文档质量，你可以选择在 工单系统 中提交变更，修正以及建议，为此我们将十分欣喜。 Django 的开发者们会积极的监控工单系统，并使用你的反馈为大家改善文档。

值得一提的是，工单(ticket)应该明确地关联到文档，而不是询问笼统的技术支持问题。 如果你需要针对你的 Django 配置寻求帮助，尝试联系 django-users 邮件组 或者 #django IRC channel 。

纯文本形式

离线阅读，或仅仅是为了方便，你可以阅读 Djano 文档的纯文本形式。

如果你正在使用的是 Django 的某个正式发布版，注意有一个代码压缩包，包含了 docs/ 目录，内含这个版本的完整文档。

如果你使用的是 Django 的开发版（也就是 main 分支），docs/ 目录下包含了所有的文档。你可以更新你的 Git checkout 来获取最新的变化。

一种没啥技术含量的利用纯文本文档的方式是使用 Unix 的 grep 工具在文档中全局中搜索一个短语。举个例子，接下来会向你展示 Django 文档中所有提到这个特定短语 “max_length” 的地方：

Linux/macOS   Windows

  1. $ grep -r max_length /path/to/django/docs/
  1. ...\> grep -r max_length \path\to\django\docs\

以本地网页形式阅读

经过几步操作，你可以获得一份网页文档的副本：

  • Django 文档使用了一个叫做 Sphinx 的系统将纯文本转换为网页。你可以通过 Sphinx 的官方网站或 pip 来下载和安装它：

    Linux/macOS   Windows

    1. $ python -m pip install Sphinx
    1. ...\> py -m pip install Sphinx

  • 接着，使用其中的 Makefile 工具将文档转换为网页：

    1. $ cd path/to/django/docs
    2. $ make html

    你需要为此安装 GNU Make 工具。

    如果你是 Windows 系统，你应该使用其中的批处理文件：

    1. cd path\to\django\docs
    2. make.bat html

  • 这个 HTML 文档将会被放置在 docs/_build/html。

版本之间的差异

Git 仓库主分支中的文本文档包含了 “最新和最大” 的变更和新增。这些变化包括针对 Django 下一个 特性版本 的新特性文档。因此，值得指出的是，我们的政策是突出 Django 的最新变化和新增功能。

我们遵循以下原则：

  • https://docs.djangoproject.com/en/dev/ 上的开发文档来自 main 分支。这些文档对应于最新的功能发布，加上之后框架中增加／修改的任何功能。
  • 当我们为 Django 的开发版本添加功能时，我们会在相同的 Git commit 事务中更新文档。
  • 为区分文档中修改或新增的内容，我们使用短语 : “New in Django Development version” 来表示其属于还未发布的开发版，使用 “New in version X.Y” 来表示其属于已经发布的某个版本。
  • 文档的修复和提升可能只会提交到最新的一个发布版本，这取决于提交者，然而，一旦一个 Django 的版本处于 不在维护列表 中，这个版本对应的文档将不再更新。
  • The main documentation web page includes links to documentation for previous versions. Be sure you are using the version of the docs corresponding to the version of Django you are using!