Куда двигаться далее¶
Итак, вы прочитали весь вводный материал и решили, что хотите продолжать использовать Django. Мы коснулись только поверхности документации по Django (на самом деле, если вы прочитали каждое слово, вы пока освоили менее 5% от общего объема документации).
Итак, что дальше?
Мы всегда были большими поклонниками обучения на практике. На данный момент вы должны знать достаточно, чтобы создать собственный проект и начать с ним разбираться. Как только вам понадобится научиться новым хитростям, возвращайтесь к документации.
Мы приложили немало усилий, чтобы сделать документацию по Django полезной, легко читаемой и как можно более полной. Остальная часть этого документа объясняет больше то, как работает документация, так что вы можете получить максимальную отдачу от нее.
(Да, это документация о документации. Будьте уверены, мы не планируем писать документ о том, как прочитать документ о документации.)
Поиск документации¶
Документация Django очень большая – почти 450,000 слов – поэтому найти необходимое может оказаться трудной задачей. В этом случае вам поможет Поиск и Алфавитный указатель.
Или вы можете просто полистать!
Как организована документация¶
Основная документация Django разбита на «блоки», предназначенные для удовлетворения различных потребностей:
Вводный материал предназначен для новичков в Django или веб-разработке в целом. Он не охватывает все темы, но вместо этого дает общий обзор того, какова на вкус разработка на Django.
Путеводитель по темам, с другой стороны, дает возможность погрузиться в отдельные части Django. Есть полные справочники по ORM Django, механизме шаблонов, doc:формах </topics/forms/index> и многому другому.
На эти вещи вы, наверное, захотите потратить большую часть своего времени, если вы начали работать с этим руководством, не зная практически ничего о Django.
Веб-разработка часто широко, но не глубоко, затрагивает проблемы из многих областей. Мы написали множество практических руководств, которые отвечают на вопросы вида «Как мне …?». Здесь вы найдете сведения о создании PDF-файлов с Django, написании шаблонных тегов и многом другом.
Ответы на часто задаваемые вопросы можно найти в FAQ.
Руководства и how-to не покрывают каждый класс, функцию и метод, доступные в Django - это негативно сказалось бы на изучении. Вместо этого, информация об отдельных классах, функциях, методах и модулях хранится в Справочнике API. В нем вы можете найти детали той или иной функции или то, что Вам нужно.
Если вы хотите развернуть проект на севере, документация содержит несколько гайдов для различных вариантов установки, также deployment checklist содержит некоторую полезную информацию.
Наконец, есть некоторая «специализированная» документация, которая обычно не нужна большинству разработчиков. Это release notes и внутренняя документация для тех, кто хочет добавить код в Django сам, и некоторые другие вещи, которые просто не вписались в других местах.
Как обновляется документация¶
Подобно тому, как базовый код Django ежедневно развивается и совершенствуется, наша документация постоянно улучшается. Мы улучшаем документацию по нескольким причинам:
Для исправления грамматических ошибок и опечаток.
Чтобы добавить информацию и/или примеры в существующие разделы, которые требуют расширения.
Для документирования особенностей Django, которые до сих пор не документированы. (Перечень таких особенностей сокращается, но тем не менее, существует.)
Чтобы добавить документацию для новых функций или Django API после их добавления или изменения.
Документация Django хранится в системе управления исходным кодом. Он находится в каталоге `docs`_ Git репозитория. Каждый онлайн документ соответствует отдельному текстовому файлу в репозитории.
Где взять документацию¶
Вы можете читать Django документацию несколькими путями. В порядке предпочтения:
В интернете¶
Самая последняя версия документации Django живет по адресу http://docs.djangoproject.com/en/dev/. Эти HTML-страницы генерируются автоматически из текстовых файлов в системе управления версиями. Они отражают «новейшее и самое лучшее» в Django - включают в себя самые последние исправления и дополнения, и рассказывают о последних возможностях Django, которые могут быть доступны только для пользователей версии разработки Django. (См. «Различия между версиями» ниже).
Мы поощряем улучшение документации через внесение изменений, исправлений и предложений в ticket system. Django разработчики активно наблюдают за системой тикетов и используют обратную связь от вас для улучшения документации для каждого.
Note, however, that tickets should explicitly relate to the documentation, rather than asking broad tech-support questions. If you need help with your particular Django setup, try the django-users mailing list or the #django IRC channel instead.
В текстовом формате¶
Для чтения в автономном режиме, или просто для удобства, вы можете читать Django документацию в текстовом формате.
Если вы используете официальный релиз Django, обратите внимание, что zip-архив кода включает в себя каталог docs/, который содержит всю документацию для этого релиза.
Если вы используете разрабатываемую версию Django (ака «trunk»), обратите внимание, что каталог docs/ содержит всю документацию. Вы можете выполнить git checkout, чтобы получить последнюю версию.
При помощи утилиты 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 веб-сайта Сфинкс или при помощи
pip:$ python -m pip install Sphinx
...\> py -m pip install SphinxЗатем, используйте
Makefileдля включения документов в HTML:$ cd path/to/django/docs $ make html
Вам понадобится GNU Make, установленный для этого.
Если вы используете Windows, также можно использовать включенный batch файл:
cd path\to\django\docs make.bat htmlHTML документация будет размещена в
docs/_build/html.
Различия между версиями¶
Текстовая документация в главной ветке в Git репозитории содержит «последние и лучшие» изменения и дополнения. Эти изменения содержат документация новых возможностях, запланированных для следующей версии Django feature release. По этой причине стоит обратить внимание на нашу политику освещения последних изменений и дополнений.
Мы следуем следующей политике:
Документация по разработке, расположенная на сайте https://docs.djangoproject.com/en/dev/ из главной ветки. Эта документация описывает последний релиз, и возможности, добавленные/измененные во фреймворке с момента релиза.
При добавлении новых функции к разрабатываемой версии Django, мы стараемся обновлять документацию в той же транзакции Git.
Чтобы выделить особенности изменений/дополнений в документах, мы используем фразу: «Новое в версии X.Y», где X.Y - версия релиза (а, значит, находящаяся в разработке).
Documentation fixes and improvements may be backported to the last release branch, at the discretion of the committer, 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!