======================
GingerDJ documentation
======================

.. rubric:: Everything you need to know about GingerDJ.

.. _index-first-steps:

First steps
===========

Are you new to GingerDJ or to programming? This is the place to start!

* **From scratch:**
  :doc:`Overview <intro/overview>` |
  :doc:`Installation <intro/install>`

* **Tutorial:**
  :doc:`Part 1: Requests and responses <intro/tutorial01>` |
  :doc:`Part 2: Models and the admin site <intro/tutorial02>` |
  :doc:`Part 3: Views and templates <intro/tutorial03>` |
  :doc:`Part 4: Forms and generic views <intro/tutorial04>` |
  :doc:`Part 5: Testing <intro/tutorial05>` |
  :doc:`Part 6: Static files <intro/tutorial06>` |
  :doc:`Part 7: Customizing the admin site <intro/tutorial07>` |
  :doc:`Part 8: Adding third-party packages <intro/tutorial08>`

* **Advanced Tutorials:**
  :doc:`How to write reusable apps <intro/reusable-apps>` |

How the documentation is organized
==================================

GingerDJ has a lot of documentation. A high-level overview of how it's organized
will help you know where to look for certain things:

* :doc:`Tutorials </intro/index>` take you by the hand through a series of
  steps to create a web application. Start here if you're new to GingerDJ or web
  application development. Also look at the ":ref:`index-first-steps`".

* :doc:`Topic guides </topics/index>` discuss key topics and concepts at a
  fairly high level and provide useful background information and explanation.

* :doc:`Reference guides </ref/index>` contain technical reference for APIs and
  other aspects of GingerDJ's machinery. They describe how it works and how to
  use it but assume that you have a basic understanding of key concepts.

* :doc:`How-to guides </howto/index>` are recipes. They guide you through the
  steps involved in addressing key problems and use-cases. They are more
  advanced than tutorials and assume some knowledge of how GingerDJ works.

The model layer
===============

GingerDJ provides an abstraction layer (the "models") for structuring and
manipulating the data of your web application. Learn more about it below:

* **Models:**
  :doc:`Introduction to models <topics/db/models>` |
  :doc:`Field types <ref/models/fields>` |
  :doc:`Indexes <ref/models/indexes>` |
  :doc:`Meta options <ref/models/options>` |
  :doc:`Model class <ref/models/class>`

* **QuerySets:**
  :doc:`Making queries <topics/db/queries>` |
  :doc:`QuerySet method reference <ref/models/querysets>` |
  :doc:`Lookup expressions <ref/models/lookups>`

* **Model instances:**
  :doc:`Instance methods <ref/models/instances>` |
  :doc:`Accessing related objects <ref/models/relations>`

* **Migrations:**
  :doc:`Introduction to Migrations<topics/migrations>` |
  :doc:`Operations reference <ref/migration-operations>` |
  :doc:`SchemaEditor <ref/schema-editor>` |
  :doc:`Writing migrations <howto/writing-migrations>`

* **Advanced:**
  :doc:`Managers <topics/db/managers>` |
  :doc:`Raw SQL <topics/db/sql>` |
  :doc:`Transactions <topics/db/transactions>` |
  :doc:`Aggregation <topics/db/aggregation>` |
  :doc:`Search <topics/db/search>` |
  :doc:`Custom fields <howto/custom-model-fields>` |
  :doc:`Multiple databases <topics/db/multi-db>` |
  :doc:`Custom lookups <howto/custom-lookups>` |
  :doc:`Query Expressions <ref/models/expressions>` |
  :doc:`Conditional Expressions <ref/models/conditional-expressions>` |
  :doc:`Database Functions <ref/models/database-functions>`

* **Other:**
  :doc:`Supported databases <ref/databases>` |
  :doc:`Legacy databases <howto/legacy-databases>` |
  :doc:`Providing initial data <howto/initial-data>` |
  :doc:`Optimize database access <topics/db/optimization>` |
  :doc:`PostgreSQL specific features <ref/contrib/postgres/index>`

The view layer
==============

GingerDJ has the concept of "views" to encapsulate the logic responsible for
processing a user's request and for returning the response. Find all you need
to know about views via the links below:

* **The basics:**
  :doc:`URLconfs <topics/http/urls>` |
  :doc:`View functions <topics/http/views>` |
  :doc:`Shortcuts <topics/http/shortcuts>` |
  :doc:`Decorators <topics/http/decorators>` |
  :doc:`Asynchronous Support <topics/async>`

* **Reference:**
  :doc:`Built-in Views <ref/views>` |
  :doc:`Request/response objects <ref/request-response>` |
  :doc:`TemplateResponse objects <ref/template-response>`

* **File uploads:**
  :doc:`Overview <topics/http/file-uploads>` |
  :doc:`File objects <ref/files/file>` |
  :doc:`Storage API <ref/files/storage>` |
  :doc:`Managing files <topics/files>` |
  :doc:`Custom storage <howto/custom-file-storage>`

* **Class-based views:**
  :doc:`Overview <topics/class-based-views/index>` |
  :doc:`Built-in display views <topics/class-based-views/generic-display>` |
  :doc:`Built-in editing views <topics/class-based-views/generic-editing>` |
  :doc:`Using mixins <topics/class-based-views/mixins>` |
  :doc:`API reference <ref/class-based-views/index>` |
  :doc:`Flattened index<ref/class-based-views/flattened-index>`

* **Advanced:**
  :doc:`Generating CSV <howto/outputting-csv>` |
  :doc:`Generating PDF <howto/outputting-pdf>`

* **Middleware:**
  :doc:`Overview <topics/http/middleware>` |
  :doc:`Built-in middleware classes <ref/middleware>`

The template layer
==================

The template layer provides a designer-friendly syntax for rendering the
information to be presented to the user. Learn how this syntax can be used by
designers and how it can be extended by programmers:

* **The basics:**
  :doc:`Overview <topics/templates>`

* **For designers:**
  :doc:`Language overview <ref/templates/language>` |
  :doc:`Built-in tags and filters <ref/templates/builtins>` |
  :doc:`Humanization <ref/contrib/humanize>`

* **For programmers:**
  :doc:`Template API <ref/templates/api>` |
  :doc:`Custom tags and filters <howto/custom-template-tags>` |
  :doc:`Custom template backend <howto/custom-template-backend>`

Forms
=====

GingerDJ provides a rich framework to facilitate the creation of forms and the
manipulation of form data.

* **The basics:**
  :doc:`Overview <topics/forms/index>` |
  :doc:`Form API <ref/forms/api>` |
  :doc:`Built-in fields <ref/forms/fields>` |
  :doc:`Built-in widgets <ref/forms/widgets>`

* **Advanced:**
  :doc:`Forms for models <topics/forms/modelforms>` |
  :doc:`Integrating media <topics/forms/media>` |
  :doc:`Formsets <topics/forms/formsets>` |
  :doc:`Customizing validation <ref/forms/validation>`

The development process
=======================

Learn about the various components and tools to help you in the development and
testing of GingerDJ applications:

* **Settings:**
  :doc:`Overview <topics/settings>` |
  :doc:`Full list of settings <ref/settings>`

* **Applications:**
  :doc:`Overview <ref/applications>`

* **Exceptions:**
  :doc:`Overview <ref/exceptions>`

* **gingerdj-admin and manage.py:**
  :doc:`Overview <ref/gingerdj-admin>` |
  :doc:`Adding custom commands <howto/custom-management-commands>`

* **Testing:**
  :doc:`Introduction <topics/testing/index>` |
  :doc:`Writing and running tests <topics/testing/overview>` |
  :doc:`Included testing tools <topics/testing/tools>` |
  :doc:`Advanced topics <topics/testing/advanced>`

* **Deployment:**
  :doc:`Overview <howto/deployment/index>` |
  :doc:`WSGI servers <howto/deployment/wsgi/index>` |
  :doc:`ASGI servers <howto/deployment/asgi/index>` |
  :doc:`Deploying static files <howto/static-files/deployment>` |
  :doc:`Tracking code errors by email <howto/error-reporting>` |
  :doc:`Deployment checklist <howto/deployment/checklist>`

The admin
=========

Find all you need to know about the automated admin interface, one of GingerDJ's
most popular features:

* :doc:`Admin site <ref/contrib/admin/index>`
* :doc:`Admin actions <ref/contrib/admin/actions>`
* :doc:`Admin documentation generator<ref/contrib/admin/admindocs>`

Security
========

Security is a topic of paramount importance in the development of web
applications and GingerDJ provides multiple protection tools and mechanisms:

* :doc:`Security overview <topics/security>`
* :doc:`Clickjacking protection <ref/clickjacking>`
* :doc:`Cross Site Request Forgery protection <ref/csrf>`
* :doc:`Cryptographic signing <topics/signing>`
* :ref:`Security Middleware <security-middleware>`

Internationalization and localization
=====================================

GingerDJ offers a robust internationalization and localization framework to
assist you in the development of applications for multiple languages and world
regions:

* :doc:`Overview <topics/i18n/index>` |
  :doc:`Internationalization <topics/i18n/translation>` |
  :ref:`Localization <how-to-create-language-files>` |
  :doc:`Localized web UI formatting and form input <topics/i18n/formatting>`
* :doc:`Time zones </topics/i18n/timezones>`

Performance and optimization
============================

There are a variety of techniques and tools that can help get your code running
more efficiently - faster, and using fewer system resources.

* :doc:`Performance and optimization overview <topics/performance>`

Geographic framework
====================

:doc:`GeoGinger <ref/contrib/gis/index>` intends to be a world-class geographic
web framework. Its goal is to make it as easy as possible to build GIS web
applications and harness the power of spatially enabled data.

Common web application tools
============================

GingerDJ offers multiple tools commonly needed in the development of web
applications:

* **Authentication:**
* :doc:`Caching <topics/cache>`
* :doc:`Logging <topics/logging>`
* :doc:`Sending emails <topics/email>`
* :doc:`Syndication feeds (RSS/Atom) <ref/contrib/syndication>`
* :doc:`Pagination <topics/pagination>`
* :doc:`Messages framework <ref/contrib/messages>`
* :doc:`Serialization <topics/serialization>`
* :doc:`Sessions <topics/http/sessions>`
* :doc:`Sitemaps <ref/contrib/sitemaps>`
* :doc:`Static files management <ref/contrib/staticfiles>`
* :doc:`Data validation <ref/validators>`

Other core functionalities
==========================

Learn about some other core functionalities of the GingerDJ framework:

* :doc:`Conditional content processing <topics/conditional-view-processing>`
* :doc:`Flatpages <ref/contrib/flatpages>`
* :doc:`Redirects <ref/contrib/redirects>`
* :doc:`Signals <topics/signals>`
* :doc:`System check framework <topics/checks>`
* :doc:`The sites framework <ref/contrib/sites>`
* :doc:`Unicode in GingerDJ <ref/unicode>`

The GingerDJ open-source project
================================

Learn about the development process for the GingerDJ project itself.

* **Design philosophies:**
  :doc:`Overview <misc/design-philosophies>`

* **GingerDJ over time:**
  :doc:`API stability <misc/api-stability>` |