Что читать дальше ¶
Итак, вы прочитали весь вводный материал и решили, что хотите продолжать использовать Django. Мы только коснулись поверхности этого вступления (на самом деле, если вы прочитали каждое слово, вы прочитали около 5% всей документации).
Ну и что дальше?
Что ж, мы всегда были большими поклонниками обучения на практике. На этом этапе вы должны знать достаточно, чтобы начать собственный проект и начать дурачиться. Если вам нужно изучить новые приемы, вернитесь к документации.
Мы приложили много усилий, чтобы документация Django была полезной, понятной и максимально полной. Остальная часть этого документа объясняет больше о том, как работает документация, чтобы вы могли извлечь из нее максимальную пользу.
(Да, это документация о документации. Будьте уверены, что мы не планируем писать документ о том, как читать документ о документации.)
Поиск документации ¶
У Django много документации - почти 450000 слов и их количество, поэтому найти то, что вам нужно, иногда бывает непросто. Хорошее место для начала - Index . Мы также рекомендуем использовать встроенную функцию поиска.
Или вы можете просто просмотреть!
Как организована документация ¶
Основная документация Django разбита на «блоки», предназначенные для различных нужд:
Вводный материал предназначен для людей , новых Джанго - или веб - разработки в целом. Он не раскрывает ничего подробно, но вместо этого дает общий обзор того, как «ощущается» разработка в Django.
В разделе руководства , с другой стороны, погружение вглубь отдельные части Джанго. Есть полные руководства по модельной системе Django , шаблонизатору , фреймворку форм и многому другому.
Вероятно, именно здесь вы захотите проводить большую часть своего времени; Если вы проработаете эти руководства, вы должны знать почти все, что нужно знать о Django.
Веб-разработка часто бывает широкой, а не глубокой - проблемы охватывают многие области. Мы написали набор практических руководств , в которых есть ответы на распространенные вопросы: «Как мне…?» вопросов. Здесь вы найдете информацию о создании PDF-файлов с помощью Django , написании пользовательских тегов шаблонов и многом другом.
Ответы на действительно распространенные вопросы также можно найти в FAQ .
Руководства и инструкции не охватывают каждый отдельный класс, функцию и метод, доступный в Django - это было бы ошеломляющим, когда вы пытаетесь учиться. Вместо этого в справочнике хранятся сведения об отдельных классах, функциях, методах и модулях . Здесь вы найдете подробную информацию о конкретной функции или о том, что вам нужно.
Если вы заинтересованы в развертывании проекта для публичного использования, в нашей документации есть несколько руководств по различным настройкам развертывания, а также контрольный список развертывания для некоторых вещей, о которых вам нужно подумать.
Наконец, есть некоторая «специализированная» документация, обычно не имеющая отношения к большинству разработчиков. Сюда входят примечания к выпуску и внутренняя документация для тех, кто хочет добавить код в сам Django, а также несколько других вещей, которые не подходят для других мест .
Как обновляется документация ¶
Так же, как база кода Django ежедневно развивается и улучшается, наша документация постоянно совершенствуется. Мы улучшаем документацию по нескольким причинам:
- Для исправления содержимого, например исправления грамматики / опечаток.
- Чтобы добавить информацию и / или примеры к существующим разделам, которые необходимо расширить.
- Чтобы задокументировать функции Django, которые еще не задокументированы. (Список таких функций сокращается, но, тем не менее, существует.)
- Чтобы добавить документацию по новым функциям по мере добавления новых функций или изменения API Django или поведения.
Документация Django хранится в той же системе управления версиями, что и его код. Он находится в каталоге документации нашего репозитория Git. Каждый онлайн-документ представляет собой отдельный текстовый файл в репозитории.
Где взять ¶
Вы можете прочитать документацию Django несколькими способами. Они в порядке предпочтения:
В Интернете ¶
Самая последняя версия документации Django находится по адресу https://docs.djangoproject.com/en/dev/ . Эти HTML-страницы создаются автоматически из текстовых файлов в системе управления версиями. Это означает, что они отражают «самое последнее и лучшее» в Django - они включают самые последние исправления и дополнения, а также обсуждают последние функции Django, которые могут быть доступны только пользователям версии для разработки Django. (См. Раздел « Различия между версиями» ниже.)
Мы рекомендуем вам помочь улучшить документацию, отправив изменения, исправления и предложения в систему тикетов . Разработчики Django активно следят за системой тикетов и используют ваши отзывы, чтобы улучшить документацию для всех.
Обратите внимание, однако, что билеты должны явно относиться к документации, а не задавать общие вопросы технической поддержки. Если вам нужна помощь с конкретной настройкой Django, попробуйте вместо этого использовать список рассылки django-users или канал IRC #django .
Обычным текстом ¶
Для чтения в автономном режиме или просто для удобства вы можете прочитать документацию Django в виде обычного текста.
Если вы используете официальный выпуск Django, заархивированный пакет (tarball) кода включает docs/
каталог, содержащий всю документацию для этого выпуска.
Если вы используете разрабатываемую версию Django (также известную как основная ветвь),
docs/
каталог содержит всю документацию. Вы можете обновить свою кассу Git, чтобы получить последние изменения.
Один из простых способов воспользоваться преимуществами текстовой документации - это использовать grep
утилиту Unix для поиска фразы во всей документации. Например, это покажет вам каждое упоминание фразы «max_length» в любом документе Django:
$ grep -r max_length /path/to/django/docs/
... \> grep -r max_length \ путь \ к \ 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 . По этой причине стоит указать на нашу политику, чтобы выделять последние изменения и дополнения в Django.
Мы следуем этой политике:
- Документация по разработке на https://docs.djangoproject.com/en/dev/ взята из основной ветки. Эти документы соответствуют последнему выпуску функций, а также всем функциям, которые были добавлены / изменены с тех пор во фреймворке.
- По мере добавления функций в разрабатываемую версию Django мы обновляем документацию в той же транзакции фиксации Git.
- Чтобы различать изменения / дополнения функций в документации, мы используем фразу: «Новое в версии для разработки Django» для версии Django, которая еще не была выпущена, или «Новое в версии XY» для выпущенных версий.
- Исправления и улучшения документации могут быть перенесены в ветку последней версии по усмотрению коммиттера, однако, как только версия Django больше не поддерживается , эта версия документации больше не получит обновлений.
- На главной веб-странице документации есть ссылки на документацию по предыдущим версиям. Убедитесь, что вы используете версию документации, соответствующую используемой вами версии Django!