Итак, вы прочитали весь вводный материал и решили, что хотите продолжать использовать Django. Мы коснулись только поверхности документации по 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”.
The topic guides, on the other hand, dive deep into individual parts of Django. There are complete guides to Django’s model system, template engine, forms framework, and much more.
На эти вещи вы, наверное, захотите потратить большую часть своего времени, если вы начали работать с этим руководством, не зная практически ничего о 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 разработчики активно наблюдают за системой тикетов и используют обратную связь от вас для улучшения документации для каждого.
Однако следует отметить, что тикеты должны быть заведены по существу, а не обсуждать вопросы по технической поддержке широкого характера. Если Вам нужна помощь с вашей индивидуальной установкой Django, воспользуйтесь рассылкой django-users или #django IRC channel
Для чтения в автономном режиме, или просто для удобства, вы можете читать Django документацию в текстовом формате.
Если вы используете официальный релиз Django, обратите внимание, что zip-архив кода включает в себя каталог docs/, который содержит всю документацию для этого релиза.
Если вы используете разрабатываемую версию Django (ака “trunk”), обратите внимание, что каталог docs/ содержит всю документацию. Вы можете выполнить git checkout, чтобы получить последнюю версию.
При помощи утилиты grep можно сделать поиск заданной фразы по всей документации. Например, эта команда выдаст каждое упоминание фразы “max_length” во всей документации Django:
$ grep -r max_length /path/to/django/docs/
Вы можете получить локальную копию HTML документации, выполнив несколько простых шагов:
Документация Django использует систему под названием Sphinx для преобразования обычного текста в HTML. Вам нужно установить Sphinx веб-сайта Сфинкс или при помощи pip:
$ pip install Sphinx
Затем, используйте Makefile для включения документов в HTML:
$ cd path/to/django/docs
$ make html
Вам понадобится GNU Make, установленный для этого.
Если вы используете Windows, также можно использовать включенный batch файл:
cd path\to\django\docs
make.bat html
HTML документация будет размещена в docs/_build/html.
Примечание
Генерация Django документации способна работать со Sphinx версии 0.6 или выше, но мы рекомендуем использовать сразу Sphinx 1.0.2 или выше.
Как упоминалось ранее, текст документации нашего Git репозитория содержит “новейшие и самые лучшие” изменения и дополнения. Эти изменения часто включают в себя документацию c новыми особенностями, добавленными в текущей разрабатываемой версии Django, которая находится в Git (“trunk”) версии Django. По этой причине, стоит рассказать о нашей политике по поддержанию документации для различных версий системы.
Мы следуем следующей политике:
Первичная документация по djangoproject.com это HTML версия последних документов в Git. Эти документы всегда соответствуют последнему официальному релизу Django, а также содержат те особенности, которые мы добавили/изменили во фреймворке после последнего релиза.
При добавлении новых функции к разрабатываемой версии Django, мы стараемся обновлять документацию в той же транзакции Git.
Чтобы выделить особенности изменений/дополнений в документах, мы используем фразу: “Новое в версии X.Y”, где X.Y - версия релиза (а, значит, находящаяся в разработке).
Изменения в документации добавляются ко всем версиям. Но если версия Django больше не поддерживается, изменения в документацию этой версии больше не будут вносится.
main documentation Web page включает в себя ссылки на документацию для всех предыдущих версий. Удостоверьтесь, что вы читаете версию соответствующую используемой версии Django!
Mar 31, 2016