Что читать дальше¶
Итак, вы прочитали все introductory material и решили, что хотите продолжать использовать Django. Мы только поцарапали поверхность этим введением (на самом деле, если вы прочитали все до единого слова, вы прочитали около 5% всей документации).
И что дальше?
Мы всегда были большими поклонниками обучения на практике. На данный момент вы должны знать достаточно, чтобы начать собственный проект и начать дурачиться. Когда вам понадобится изучить новые приемы, возвращайтесь к документации.
Мы приложили много усилий, чтобы сделать документацию 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».
С другой стороны, topic guides глубоко погружаются в отдельные части Django. Есть полные руководства по model system, template engine, forms framework и многим другим частям Django.
Вероятно, именно здесь вы захотите провести большую часть своего времени; если вы пройдете свой путь через эти руководства, вы должны знать практически все, что нужно знать о Django.
Веб-разработка часто является широкой, а не глубокой - проблемы охватывают многие области. Мы написали набор how-to guides, которые отвечают на распространенные вопросы «Как мне …?». Здесь вы найдете информацию о generating PDFs with Django, writing custom template tags и многом другом.
Ответы на действительно распространенные вопросы также можно найти в 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 несколькими способами. Вот они, в порядке предпочтения:
On the web¶
Самая последняя версия документации Django находится по адресу https://docs.djangoproject.com/en/dev/. Эти HTML-страницы генерируются автоматически из текстовых файлов в системе управления исходными текстами. Это означает, что они отражают «последнее и самое лучшее» в Django - они включают самые последние исправления и дополнения, а также обсуждают последние возможности Django, которые могут быть доступны только пользователям версии разработки Django. (См. Различия между версиями ниже.)
Мы призываем вас помочь улучшить документацию, внося изменения, исправления и предложения в тикет ticket system. Разработчики Django активно следят за системой тикетов и используют ваши отзывы для улучшения документации для всех.
Обратите внимание, однако, что заявки должны явно относиться к документации, а не задавать общие вопросы технической поддержки. Если вам нужна помощь с вашей конкретной установкой Django, попробуйте обратиться в список рассылки django-users или #django IRC channel.
Обычным текстом¶
Для автономного чтения или просто для удобства вы можете читать документацию Django в виде обычного текста.
Если вы используете официальный релиз Django, застегнутый пакет (tarball) кода включает каталог docs/, который содержит всю документацию для этого релиза.
If you’re using the development version of Django (aka the main branch), the
docs/ directory contains all of the documentation. You can update your
Git checkout to get the latest changes.
Одним из низкотехнологичных способов использования преимуществ текстовой документации является использование утилиты 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.
Различия между версиями¶
The text documentation in the main branch of the Git repository contains the «latest and greatest» changes and additions. These changes include documentation of new features targeted for Django’s next feature release. For that reason, it’s worth pointing out our policy to highlight recent changes and additions to Django.
Мы следуем этой политике:
- The development documentation at https://docs.djangoproject.com/en/dev/ is from the main branch. These docs correspond to the latest feature release, plus whatever features have been added/changed in the framework since then.
- По мере добавления функций в версию разработки 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.
- 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!