Django 笔记-3-文档阅读-关于 Django 文档

请注意：本文编写于 2024-02-16，其中某些信息可能已经失去时效性。

Django 笔记系列

前言

最近春节假期在家闲着无聊，就顺着之前阅读 Django Url 模块的劲头开始读起了 Django 的源码和文档。在阅读 Django 文档的过程中，我第一次发现 Django 文档实际的组织方式，于是便有了这篇文章。

脉络梳理

我们打开 Django 文档时一般看到的都是根目录，在根目录下 Django 很贴心地使用副标题分割出了 16 个话题，并在相应的话题下面对话题所包含的内容进行展开和索引。这很好，当我对 Django 中某个部分（模块）产生疑惑的时候我都能够通过这个页面快速定位到对应的页面。我一度认为 Django 的文档就是通过话题进行组织的，但在我上次想要通读 Django 文档时，我从页面右侧我老早就发现但是从未点击的目录按钮进入到了 Django 文档真实的组织架构页面：目录页。

根据目录页可以看出 Django 文档实际被分为了 9 部分（忽略索引和词汇表），分别是：

开始 | intro：通过一个简单的教程帮助初学者快速掌握 Django 开发的能力。
使用 Django | topics：重点，将 Django 中较为关键部分的概念以主题的形式进行介绍。
操作指南 | howto：一些常用流程的整理，个人觉得没啥用，这些大都能通过搜索引擎找到更加细致的回答。
Django FAQ | faq：一些常见问题的解答，其中关于如何寻求帮助和如何贡献代码的部分可以根据需要阅读一下。
API 参考 | ref：重点，将 Django 中较为关键部分的接口设计以主题的形式进行介绍。
元文件和杂记 | misc：不要被标题迷惑，里面存放的是 Django 的设计理念，内容不多可以读一下。
术语 | glossary：没啥用，总结的并不全面。
发行说明 | releases：重点，Django 的发版日志，用于了解不同 Django 版本之间的区别。
Django 内部 | internals：重点，如果你是期望更加深入的了解、讨论或参与 Django，这里里面的章节就都适合读一读。

竖线前是章节的中文翻译，竖线后是对应的 url path。

根目录实际上是将目录页中的大部分内容通过话题的形式进行重新组合的产物。

阅读方式

首次使用

适合场景：第一次了解 Django，想要快速掌握 Django 的使用方法。

这时候可以阅读开始部分，里面的教程几乎是每个 Django 入门者的必经之路。

搜索阅读

适合场景：遇到一些比较生僻的概念，直接丢到搜索引擎没办法快速理解。

这时候就可以尝试将这个概念丢到 Django 文档右上角的搜索框中，它会为你列出在文档中所有出现过这个概念的地方。

有两个需要注意的点：

只建议搜索概念性的问题，搜索词尽可能是一个单词；
建议先使用英语搜索，找到搜索结果后再切换到中文（如果没有英文阅读方法）。

概念阅读

适合场景：希望能够准确掌握 Django 中某个概念 50% 以上的内容。

这时候可以通过根目录配合目录页的使用 Django 和 API 参考阅读相关的内容。

这样做能够使你快速从零开始了解一个 Django 概念，并掌握其 50% 以上的内容（如何使用），剩下的部分（具体代码实现）则需要阅读 Django 源码来补齐。

通读

适用场景：希望对 Django 有一个全面了解，进一步掌握 Django。

这时候可以以根目录中模型层以下的主题为索引，从目录页的使用 Django 和 API 参考找到相应的章节，先读使用 Django 中的概念讲解，再读 API 参考中的接口设计。

关于翻译

Django 文档虽然有较为全面的中文翻译，但是从我阅读的体验来看绝大多数应该是机翻，而且因为文档中有大量的引用格式，导致在汉化的过程中会存在解析失败的情况，所以有能力的最好还是直接阅读英文版。实在不行我也建议中英文混合阅读，可以中文英文各开一个页面，也可以使用能够保留英文原文的翻译插件。

Django 社区

在 Django 内部 | internals 中有对 Django 社区的全面介绍，这里只简单介绍几个常用的：

Github 源码：没有 Issue；
Django 论坛：可以提问或者宣传自己的 Django 项目；
Django 邮件列表：Django 有几个官方的邮件列表，感兴趣的话可以去文档里翻找一下；
Django Issues：Django 独立的 issue 提交平台，可以在这里提交或搜索你遇到的 bug；

注：上面的几个社区平台基本全是英文的，所以需要一定的英语阅读方法；

参考

Django 文档-4.2-中文