Что читать дальше¶
Итак, вы прочитали все introductory material и решили, что хотите продолжать использовать Django. Мы только поцарапали поверхность этим введением (на самом деле, если вы прочитали все до единого слова, вы прочитали около 5% всей документации).
И что дальше?
Мы всегда были большими поклонниками обучения на практике. На данный момент вы должны знать достаточно, чтобы начать собственный проект и начать дурачиться. Когда вам понадобится изучить новые приемы, возвращайтесь к документации.
Мы приложили много усилий, чтобы сделать документацию Django полезной, понятной и максимально полной. Остальная часть этого документа объясняет, как работает документация, чтобы вы могли извлечь из нее максимум пользы.
(Да, это документация о документации. Будьте уверены, мы не планируем писать документ о том, как читать документ о документации.)
Поиск документации¶
Django имеет много документации - почти 450 000 слов и не меньше - поэтому найти то, что вам нужно, иногда бывает непросто. Хорошее место для начала - Алфавитный указатель. Мы также рекомендуем использовать встроенную функцию поиска.
Или вы можете просто побродить вокруг!
Как организована документация¶
Основная документация Django разбита на «куски», предназначенные для удовлетворения различных потребностей:
introductory material предназначен для новичков в Django - или в веб-разработке в целом. В ней не рассматривается ничего глубокого, а вместо этого дается высокоуровневый обзор того, как «чувствует» себя разработка на Django.
тематические руководства, с другой стороны, глубоко погружаются в отдельные части Django. Существуют полные руководства по системе моделей, движку шаблонов, инфраструктуре форм и многое другое.
T
W
Ответы на действительно распространенные вопросы также можно найти в FAQ.
В руководствах не рассматриваются все классы, функции и методы, доступные в Django - это было бы слишком сложно, когда вы пытаетесь учиться. Вместо этого, подробности об отдельных классах, функциях, методах и модулях хранятся в разделе reference. Именно сюда вы обратитесь, чтобы найти подробности о конкретной функции или о том, что вам нужно.
Если вы заинтересованы в развертывании проекта для публичного использования, в нашей документации есть several guides для различных настроек развертывания, а также deployment checklist для некоторых вещей, о которых вам нужно будет подумать.
Наконец, есть некоторая «специализированная» документация, обычно не имеющая отношения к большинству разработчиков. Сюда входят release notes и internals documentation для тех, кто хочет добавить код в сам Django, а также few other things that don’t fit elsewhere
Как обновляется документация¶
Так же, как кодовая база Django развивается и улучшается ежедневно, наша документация постоянно совершенствуется. Мы улучшаем документацию по нескольким причинам:
- Вносить исправления в содержание, например, грамматические и типовые исправления.
- Добавление информации и/или примеров в существующие разделы, которые необходимо расширить.
- Документировать возможности Django, которые еще не документированы. (Список таких возможностей сокращается, но тем не менее существует).
- Добавление документации по новым возможностям по мере добавления новых возможностей или изменения API Django или поведения.
Документация Django хранится в той же системе контроля исходных текстов, что и код. Она находится в директории docs нашего Git-репозитория. Каждый документ в сети - это отдельный текстовый файл в репозитории.
Где купить¶
Вы можете читать документацию Django несколькими способами. Вот они, в порядке предпочтения:
В Интернете¶
Самая последняя версия документации Django находится по адресу https://docs.djangoproject.com/en/dev/. Эти HTML-страницы генерируются автоматически из текстовых файлов в системе управления исходными текстами. Это означает, что они отражают «последнее и самое лучшее» в Django - они включают самые последние исправления и дополнения, а также обсуждают последние возможности Django, которые могут быть доступны только пользователям версии разработки Django. (См. Различия между версиями ниже.)
Мы призываем вас помочь улучшить документацию, внося изменения, исправления и предложения в тикет ticket system. Разработчики Django активно следят за системой тикетов и используют ваши отзывы для улучшения документации для всех.
Обратите внимание, однако, что заявки должны явно относиться к документации, а не задавать общие вопросы технической поддержки. Если вам нужна помощь с вашей конкретной установкой Django, попробуйте обратиться в список рассылки django-users или #django IRC channel.
Обычным текстом¶
Для автономного чтения или просто для удобства вы можете читать документацию Django в виде обычного текста.
Если вы используете официальный релиз Django, застегнутый пакет (tarball) кода включает каталог docs/, который содержит всю документацию для этого релиза.
Если вы используете версию Django для разработки (она же основная ветвь), каталог docs/ содержит всю документацию. Вы можете обновить свой Git checkout, чтобы получить последние изменения.
Одним из низкотехнологичных способов использования преимуществ текстовой документации является использование утилиты Unix grep для поиска фразы во всей документации. Например, это покажет вам каждое упоминание фразы «max_length» в любом документе Django:
$ grep -r max_length /path/to/django/docs/
...\> grep -r max_length \path\to\django\docs\
Как HTML, локально¶
Вы можете получить локальную копию документации HTML, выполнив несколько шагов:
Документация Django использует систему под названием Sphinx для преобразования обычного текста в HTML. Вам нужно установить Sphinx, скачав и установив пакет с сайта Sphinx, или с помощью
pip:$ python -m pip install Sphinx...\> py -m 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 feature release. По этой причине стоит обратить внимание на нашу политику освещения последних изменений и дополнений Django.
Мы следуем этой политике:
- Документация по разработке на сайте https://docs.djangoproject.com/en/dev/ взята из основной ветки. Эти документы соответствуют последнему релизу функциональности, плюс все возможности, которые были добавлены/изменены во фреймворке с тех пор.
- По мере добавления функций в версию разработки Django, мы обновляем документацию в той же транзакции Git commit.
- Чтобы различать изменения/дополнения в документации, мы используем фразу: «Новое в версии Django Development» для еще не выпущенной версии Django, или «Новое в версии X.Y» для выпущенных версий.
- Documentation fixes and improvements may be backported to the last release branch, at the discretion of the merger, however, once a version of Django is no longer supported, that version of the docs won’t get any further updates.
- В main documentation web page содержатся ссылки на документацию для предыдущих версий. Убедитесь, что вы используете версию документации, соответствующую версии Django, которую вы используете!