下一步看什么

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

那么下一步做什么?

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

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

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

查找文档

Django有 许多 的文档——差不多有 450000 字(英文单词),所以查找你需要的文档可能需要点技巧。对此,有几个不错的去处,搜索页面索引

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

文档是如何组成

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

  • The 介绍文档 是专为 Django 初学者或 Web 初学者设计的。它不会做任何的深入,只是以高度概括的方式介绍了如果以 Django “风格”开发应用的方式。

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

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

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

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

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

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

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

这个文档是如何更新的

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

  • 更正内容,如更正语法/拼写错误。
  • 向已有的需要被扩展的某个章节添加介绍信息或例子。
  • 记录尚未记录的 Django 功能。 (这些功能的列表正在缩小,但仍然存在。)
  • 在新特性被添加时,或 Django 的 API 或行为有变化时,会添加新文档。Django 的文档以和它的代码一样,以代码版本管理系统方式进行管理。它被保存在 git 仓库的 docs 目录内。每份在线文档都是仓库内的一份独立文本文件。

从哪里获取这个

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

在网络上

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

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

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

纯文本形式

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

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

如果你正在使用开发版的 Django (又名“trunk”),注意目录 docs/ 包含所有的文档。你可以通过 git 获取最新的修改。

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

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

以本地网页形式阅读

经过几步简单的操作,你可以获得一份网页文档的备份:

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

/

  1. $ pip install Sphinx
  1. ...\> 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未来版本中的新特性的文档:术语叫:feature release。因此,为了方便看到最近的Django修改和扩展内容,非常需要表明我们的政策。

我们遵循以下原则:

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