Django 2.0.1 官方文档翻译:接下来读什么（page 14）

接下来读什么（page 14）

现在你应该已经阅读了所有的（page1-13 ）介绍材料，决定继续使用Django。我们仅仅做了简要的介绍（事实上，如果你阅读了前面所有的内容，也只是全部文档的5%。）

那下一步怎么做呢？

好吧，我们都是通过实践来学习的狂热爱好者。在这一点上，你应该已经了解了足够的知识去启动你的项目，并开始四处闲逛。当你需要去学习一些新的技巧时，请回来继续学习文档。

我们花费了大量精力，使用django的文档使用、易读并尽可能的完整。本节文档下面的内容更多的是关于文档是如何工作的，以便让你可以充分利用它。

（是的，本节文档是介绍如何使用文档的，放心，我们并没有计划去写一份如何阅读文档的文档）

查找文档

django有很多文档 —— 大概有450,000单词 —— 所以查找你需要的内容有时会变得困难。一些好的地方是你可以使用Search Page 和 Index 页（这两个功能在官方文档中有，这里就不提供了）。

文档是如何组织的

django的主要文档被分成几个“chunks”（块），以满足不同的需求：

• 入门教程（page 3）是专门为djang新手设计的 —— 或一般的web开发者。它并不包含所有有深度的内容，而是给出了一个如何使用django开发的高级概述的感觉
• 主题指南（page 16），在另一方面，深入讲解django的各个部分。对Django的model system（少链接）, template engine（少链接）, forms framework（少链接） 和更多其他内容有完整的介绍。
  
  这可能是你想花掉大部分时间的地方；如果你以自己的方式学完了这些教程，那么你应该知道了所有关于django的知识。
• web发开通常是涉及范围广，但不深 —— 问题跨多个领域。我们已经编写了一套How-to教程来回答常见的“我应该如何……”的问题。这里你会看到关于generating PDFs with Django（少链接）, writing custom template tags（少链接），等更多其他的内容。
  
  常见问题的答案也可以在FAQ（少链接）中找到。
• 本指南和How-to文档不会覆盖到你可以在django中获取到的每一个类、函数和方法 —— 那这样的话，在你尝试去学习的时候会给你带来很多压力。相反，关于单个的类、函数、方法和模块的详细内容都可以在 reference（少链接）中找到。这里就是你要找到一个特定功能细节或者任何你需要的内容的地方。
• 如果你有兴趣开发一个公用的项目，我们的有一些用于多种部署的教程，例如一些需要考虑的内容的部署清单（少链接）。
• 最后，有一些和大多数开发者无关的特殊文档。包括release notes 和 internals documentation，他们是写给那些想为django共享代码的人的，还包括一些不好分类的其他文档。

如何更新文档

就像django每天都在被开发和改进一样，我们的文档也一直在改进。我们改进文档有以下结果原因：

• 内容更正，比如语法/拼写的更正
• 向现有的需要扩展的部分添加信息或示例
• 记录还没有被记录的django特性。（这些特性的列表正在缩小，但仍然存在）
• 随着特性的添加 或django的APIs或行为的改变 时，添加新特性的文档内容，

django的文档和它的代码一样，同样使用版本控制系统。它存放在我们的git仓库的docs目录。仓库中的每篇文档都是苏丽的文本文件。

从哪里获取它

你有几种方式可以阅读django文档，下面它们以有限顺序排列：

在网络上

最新版本的django文档存放在https://docs.djangoproject.com/en/dev/。这些HTML页面由版本控制（系统）中的文本文件自动生成。这意味着它们反映了django中“最新且最好”的内容 —— 它们报错最新的更正和增补内容；它们详述最新的django特性，这些特性可能只对使用django开发版本的用户有效。（“版本之间的差异”，下面会做讲解）

我们鼓励你在ticket system中提交变更、更正和建议来帮助改善文档。django开发者会积极的观察ticket system，并使用你的反馈为每个人改善文档。

注意，不管怎样，ticket都应该是明确的和文档有关系的，而不是询问一些宽泛的技术支持问题。如果你在django设置上需要帮助，请尝试 django-users邮件列表(此列表不再做翻译)或者 #django IRC channel .

纯文本

为了离线阅读，或者是为了方便阅读，你可以阅读纯文本的django文档。

如果你使用一个django官方发行版，注意，代码中docs/目录下的zip包（tar包），它包含对应发行版本的所有文档。

如果你使用开发版的django（又称“Trunk”），注意docs/目录下包含对应的所有文档。你可以使用 git checkout 更新，以获取最新的变更。

一种利用文本文档的低技术含量的方法是在所有的文档中使用 Unix下的 grep工具去搜索关键字。例如，下面会显示所有文档中每一个提及“max_length”关键字的内容。

$ grep -r max_length /path/to/django/docs/

本地的HTML文件

你可以通过下面几个简单步骤获取一份HTML文档的本地副本。

• django的文档使用一个叫Sphinx的系统把纯文本转换成HTML。你需要从Sphinx官网或者pip下载安装sphinx：

  $ pip install Sphinx
  

• 然后，使用文档目录中的Makefile把文档转换成HTML：

  $ cd path/to/django/docs
  $ make html
  

• 为此你需要安装GNU Make
  
  如果你使用windows，你可以选择使用文档目录中的批处理文件：

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

• 生成的HTML文件会存放在docs/_build/html。

不同版本之间的区别

如前所述，我们git仓库中的文本文档包含“最新最好”的变更和额外内容。这些变更通常包含已添加到django开发版本中的新特性的稳定 —— django的git（主干）版本。由于这个原因，值得指出的是，我们的策略是为多个版本的框架保留文档。

我们遵循下面的策略：

• 放在djangoproject.com上的主要文档是Git中最新文档HTML版本。这些文档总是对应最新的django发布版本，还有在最新的发布的框架中已经添加/更改的特性。
• 在我们为django的开发版添加新特性时，我们尽力在相同的Git事务提交动作中更新文档。
• 为了区分文档中更改/添加的特性，我们使用短语：“New in version X.Y”，X.Y是下一个发布版本（因此它是正在开发的版本）。
• 在提交者的谨慎操作下，文档修复和改进可能会回迁到最后一个发布分支，然而，一旦一个版本的django的不在被支持，这个版本对应的文档将不会再做更新。
• main documentation Web page 包含指向以前所有版本文档的链接。确保你正在阅读的文档的版本和你正在使用的django的版本相符。