Какое чтение для остальных ¶
Итак, вы прочитали всю вводную документацию и решили продолжить использование Django. В этом вступлении мы коснулись только поверхности (даже прочитав каждое слово вступления, вы просмотрели только около 5% всей документации).
Как продолжить?
Мы всегда верили в обучение на практике. На этом этапе вы должны знать достаточно, чтобы начать свой собственный проект по изучению технологий. Как только вы почувствуете необходимость изучить новые концепции, вернитесь к документации.
Мы приложили много усилий, чтобы сделать документацию Django полезной, понятной и максимально полной. Остальная часть этого документа объясняет немного больше о том, как эта документация структурирована, чтобы вы могли извлечь из нее максимальную пользу.
(Да, это документация по документации. Будьте уверены, что мы не планируем писать документ о том, как читать документ о документации.)
Поиск в документации ¶
У Django много документации - почти 450000 слов и их количество - поэтому найти то, что вам нужно, иногда бывает непросто. Хорошее место для начала - Index . Мы также рекомендуем использовать встроенную функцию поиска.
Или вы можете просто просмотреть содержимое.
Организация документации ¶
Основная документация Django разбита на разделы, предназначенные для различных нужд:
Вводное содержание предназначено для начинающих с Django, или с общей веб - разработкой. Он не охватывает все подробно, а скорее дает общий обзор общего подхода к разработке в Django.
Тематические руководства , с другой стороны, подробно освещают определенные области Django. Есть полные инструкции к системе шаблонов , шаблоны Engine , Forms Architecture и многое другое.
Вероятно, это то место, где вы проведете больше всего времени; Если вы попытаетесь изучить эти различные руководства, вы будете знать почти все, что нужно знать о 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 channel #django ).
В текстовом режиме ¶
Для чтения в автономном режиме или просто по желанию можно прочитать документацию Django в текстовом режиме.
Если вы используете официальную версию Django, пакет сжатого кода содержит каталог со docs/ всей документацией для этой версии.
Если вы используете разрабатываемую версию Django (т. Е. Основную ветку), каталог docs/ содержит всю документацию. Вы можете обновить свою кассу Git, чтобы получить последние изменения.
Полезный совет для ознакомления с необработанной документацией Django - использовать утилиту Unix «grep» для поиска содержимого по всей документации. Например, это расскажет вам обо всех упоминаниях выражения «max_length» в документации:
$ 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 установить 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/ взята из основной ветки
master. Эта документация является последней официальной версией Django, а также любыми функциями, добавленными или измененными с момента последнего выпуска. - По мере добавления дополнительных функций в разрабатываемую версию DJango мы обновляем документацию в той же транзакции Git по мере изменения кода.
- Чтобы выделить изменения или дополнения к функциям в документации, мы используем фразу «Новое в версии для разработки Django», если соответствующая версия Django еще не была официально выпущена, или «Новое в версии XY» для опубликованные версии.
- Исправления и улучшения документации могут быть перенесены в ветвь стабильной версии по усмотрению лица, выполняющего коммит. Однако, как только версия Django больше не поддерживается , эта версия документации больше не обновляется.
- Основной веб - страница документации содержит ссылки на документацию для предыдущих выпусков. Обязательно используйте версию документации, которая соответствует используемой вами версии Django!