Contents Menu Expand Light mode Dark mode Auto light/dark, in light mode Auto light/dark, in dark mode Skip to content
Ginger - DJ 5.5.3 documentation
Ginger - DJ 5.5.3 documentation
  • Ginger documentation
  • Getting started
    • Ginger at a glance
    • Quick install guide
    • Writing your first Ginger app, part 1
    • Writing your first Ginger app, part 2
    • Writing your first Ginger app, part 3
    • Writing your first Ginger app, part 4
    • Writing your first Ginger app, part 5
    • Writing your first Ginger app, part 6
    • Writing your first Ginger app, part 7
    • Writing your first Ginger app, part 8
    • Advanced tutorial: How to write reusable apps
    • What to read next
    • Writing your first patch for Ginger
  • Using Ginger
    • How to install Ginger
    • Models and databases
      • Models
      • Making queries
      • Aggregation
      • Search
      • Managers
      • Performing raw SQL queries
      • Database transactions
      • Multiple databases
      • Tablespaces
      • Database access optimization
      • Database instrumentation
      • Fixtures
      • Examples of model relationship API usage
        • Many-to-many relationships
        • Many-to-one relationships
        • One-to-one relationships
    • Handling HTTP requests
      • URL dispatcher
      • Writing views
      • View decorators
      • File Uploads
      • Ginger shortcut functions
      • Generic views
      • Middleware
      • How to use sessions
    • Working with forms
      • Formsets
      • Creating forms from models
      • Form Assets (the Media class)
    • Templates
    • Class-based views
      • Introduction to class-based views
      • Built-in class-based generic views
      • Form handling with class-based views
      • Using mixins with class-based views
    • Migrations
    • Managing files
    • Testing in Ginger
      • Writing and running tests
      • Testing tools
      • Advanced testing topics
    • Ginger’s cache framework
    • Conditional View Processing
    • Cryptographic signing
    • Sending email
    • Internationalization and localization
      • Translation
      • Format localization
      • Time zones
    • Logging
    • Pagination
    • Security in Ginger
    • Performance and optimization
    • Serializing Ginger objects
    • Ginger settings
    • Signals
    • System check framework
    • External packages
    • Asynchronous support
  • “How-to” guides
    • How to use Ginger’s CSRF protection
    • How to create custom ginger-admin commands
    • How to create custom model fields
    • How to write custom lookups
    • How to implement a custom template backend
    • How to create custom template tags and filters
    • How to write a custom storage class
    • How to deploy Ginger
      • How to deploy with WSGI
        • How to use Ginger with Gunicorn
        • How to use Ginger with uWSGI
        • How to use Ginger with Apache and mod_wsgi
      • How to deploy with ASGI
        • How to use Ginger with Daphne
        • How to use Ginger with Hypercorn
        • How to use Ginger with Uvicorn
      • Deployment checklist
    • How to upgrade Ginger to a newer version
    • How to manage error reporting
    • How to provide initial data for models
    • How to integrate Ginger with a legacy database
    • How to configure and use logging
    • How to create CSV output
    • How to create PDF files
    • How to override templates
    • How to manage static files (e.g. images, JavaScript, CSS)
    • How to deploy static files
    • How to install Ginger on Windows
    • How to create database migrations
    • How to delete a Ginger application
  • Ginger FAQ
    • FAQ: General
    • FAQ: Installation
    • FAQ: Using Ginger
    • FAQ: Getting Help
    • FAQ: Databases and models
    • FAQ: The admin
    • FAQ: Contributing code
    • Troubleshooting
  • API Reference
    • Applications
    • System check framework
    • Built-in class-based views API
      • Base views
      • Generic display views
      • Generic editing views
      • Generic date views
      • Class-based views mixins
        • Simple mixins
        • Single object mixins
        • Multiple object mixins
        • Editing mixins
        • Date-based mixins
      • Class-based generic views - flattened index
    • Clickjacking Protection
    • contrib packages
      • The Ginger admin site
        • Admin actions
        • ModelAdmin List Filters
        • The Ginger admin documentation generator
        • JavaScript customizations in the admin
      • The flatpages app
      • GeoGinger
        • GeoGinger Tutorial
        • GeoGinger Installation
          • Installing Geospatial libraries
          • Installing PostGIS
          • Installing SpatiaLite
        • GeoGinger Model API
        • GeoGinger Database API
        • GeoGinger Forms API
        • GIS QuerySet API Reference
        • Geographic Database Functions
        • Measurement Objects
        • GEOS API
        • GDAL API
        • Geolocation with GeoIP2
        • GeoGinger Utilities
          • LayerMapping data import utility
          • OGR Inspection
          • GeoJSON Serializer
        • GeoGinger Management Commands
        • GeoGinger’s admin site
        • Geographic Feeds
        • Geographic Sitemaps
        • Testing GeoGinger apps
        • Deploying GeoGinger
      • ginger.contrib.humanize
      • The messages framework
      • ginger.contrib.postgres
        • PostgreSQL specific aggregation functions
        • PostgreSQL specific database constraints
        • PostgreSQL specific query expressions
        • PostgreSQL specific model fields
        • PostgreSQL specific form fields and widgets
        • PostgreSQL specific database functions
        • PostgreSQL specific model indexes
        • PostgreSQL specific lookups
        • Database migration operations
        • Full text search
        • Validators
      • The redirects app
      • The sitemap framework
      • The “sites” framework
      • The staticfiles app
      • The syndication feed framework
    • Cross Site Request Forgery protection
    • Databases
    • ginger-admin and manage.py
    • Running management commands from your code
    • Ginger Exceptions
    • File handling
      • The File object
      • File storage API
      • Uploaded Files and Upload Handlers
    • Forms
      • The Forms API
      • Form fields
      • Model Form Functions
      • Formset Functions
      • The form rendering API
      • Widgets
      • Form and field validation
    • Logging
    • Middleware
    • Migration Operations
    • Models
      • Model field reference
      • Field attribute reference
      • Model index reference
      • Constraints reference
      • Model _meta API
      • Related objects reference
      • Model class reference
      • Model Meta options
      • Model instance reference
      • QuerySet API reference
      • Lookup API reference
      • Query Expressions
      • Conditional Expressions
      • Database Functions
    • Paginator
    • Request and response objects
    • SchemaEditor
    • Settings
    • Signals
    • Templates
      • The Ginger template language
      • Built-in template tags and filters
      • The Ginger template language: for Python programmers
    • TemplateResponse and SimpleTemplateResponse
    • Unicode data
    • ginger.urls utility functions
    • ginger.urls functions for use in URLconfs
    • ginger.conf.urls functions for use in URLconfs
    • Ginger Utils
    • Validators
    • Built-in Views
  • Meta-documentation and miscellany
    • API stability
    • Design philosophies
    • Third-party distributions of Ginger
  • Glossary
  • Ginger internals
    • Contributing to Ginger
      • An overview of the contributing process and what's involved.
      • Contributing code
        • Writing your first patch for Ginger
        • How to submit a patch to Ginger for new and/or fixed behavior
        • How to write and run tests
        • How to run Ginger's unit tests
        • How to work with Git and GitHub
        • Coding style
        • JavaScript code
        • Committing code
      • Writing documentation
      • Localizing Ginger
      • Reporting bugs and requesting features
      • Triaging tickets
    • Mailing lists and Forum
    • Organization of the Ginger Project
    • Ginger’s security policies
    • Ginger’s release process
    • The Ginger source code repository
Back to top
View this page

What to read next¶

So you’ve read all the introductory material and have decided you’d like to keep using Ginger. We’ve only just scratched the surface with this intro (in fact, if you’ve read every single word, you’ve read about 5% of the overall documentation).

So what’s next?

Well, we’ve always been big fans of learning by doing. At this point you should know enough to start a project of your own and start fooling around. As you need to learn new tricks, come back to the documentation.

We’ve put a lot of effort into making Ginger’s documentation useful, clear and as complete as possible. The rest of this document explains more about how the documentation works so that you can get the most out of it.

(Yes, this is documentation about documentation. Rest assured we have no plans to write a document about how to read the document about documentation.)

Finding documentation¶

Ginger’s got a lot of documentation – almost 450,000 words and counting – so finding what you need can sometimes be tricky. A good place to start is the Index. We also recommend using the builtin search feature.

Or you can just browse around!

How the documentation is organized¶

Ginger’s main documentation is broken up into “chunks” designed to fill different needs:

  • The introductory material is designed for people new to Ginger – or to web development in general. It doesn’t cover anything in depth, but instead gives a high-level overview of how developing in Ginger “feels”.

  • The topic guides, on the other hand, dive deep into individual parts of Ginger. There are complete guides to Ginger’s model system, template engine, forms framework, and much more.

    This is probably where you’ll want to spend most of your time; if you work your way through these guides you should come out knowing pretty much everything there is to know about Ginger.

  • Web development is often broad, not deep – problems span many domains. We’ve written a set of how-to guides that answer common “How do I …?” questions. Here you’ll find information about generating PDFs with Ginger, writing custom template tags, and more.

    Answers to really common questions can also be found in the FAQ.

  • The guides and how-to’s don’t cover every single class, function, and method available in Ginger – that would be overwhelming when you’re trying to learn. Instead, details about individual classes, functions, methods, and modules are kept in the reference. This is where you’ll turn to find the details of a particular function or whatever you need.

  • If you are interested in deploying a project for public use, our docs have several guides for various deployment setups as well as a deployment checklist for some things you’ll need to think about.

  • Finally, there’s some “specialized” documentation not usually relevant to most developers. This includes the internals documentation for those who want to add code to Ginger itself, and a few other things that don’t fit elsewhere.

How documentation is updated¶

Just as the Ginger code base is developed and improved on a daily basis, our documentation is consistently improving. We improve documentation for several reasons:

  • To make content fixes, such as grammar/typo corrections.

  • To add information and/or examples to existing sections that need to be expanded.

  • To document Ginger features that aren’t yet documented. (The list of such features is shrinking but exists nonetheless.)

  • To add documentation for new features as new features get added, or as Ginger APIs or behaviors change.

Ginger’s documentation is kept in the same source control system as its code. It lives in the docs directory of our Git repository. Each document online is a separate text file in the repository.

Where to get it¶

You can read Ginger documentation in several ways. They are, in order of preference:

On the web¶

The most recent version of the Ginger documentation lives at https://docs.ginger.gloportal.dev/en/dev/. These HTML pages are generated automatically from the text files in source control. That means they reflect the “latest and greatest” in Ginger – they include the very latest corrections and additions, and they discuss the latest Ginger features, which may only be available to users of the Ginger development version. (See Differences between versions below.)

We encourage you to help improve the docs by submitting changes, corrections and suggestions in the ticket system. The Ginger developers actively monitor the ticket system and use your feedback to improve the documentation for everybody.

Note, however, that tickets should explicitly relate to the documentation, rather than asking broad tech-support questions. If you need help with your particular Ginger setup, try the ginger-users mailing list or the #ginger IRC channel instead.

In plain text¶

For offline reading, or just for convenience, you can read the Ginger documentation in plain text.

If you’re using an official release of Ginger, the zipped package (tarball) of the code includes a docs/ directory, which contains all the documentation for that release.

If you’re using the development version of Ginger (aka the main branch), the docs/ directory contains all of the documentation. You can update your Git checkout to get the latest changes.

One low-tech way of taking advantage of the text documentation is by using the Unix grep utility to search for a phrase in all of the documentation. For example, this will show you each mention of the phrase “max_length” in any Ginger document:

$ grep -r max_length /path/to/ginger/docs/
...\> grep -r max_length \path\to\ginger\docs\

As HTML, locally¶

You can get a local copy of the HTML documentation following a few steps:

  • Ginger’s documentation uses a system called Sphinx to convert from plain text to HTML. You’ll need to install Sphinx by either downloading and installing the package from the Sphinx website, or with pip:

    $ python -m pip install Sphinx
    
    ...\> py -m pip install Sphinx
    
  • Then, use the included Makefile to turn the documentation into HTML:

    $ cd path/to/ginger/docs
    $ make html
    

    You’ll need GNU Make installed for this.

    If you’re on Windows you can alternatively use the included batch file:

    cd path\to\ginger\docs
    make.bat html
    
  • The HTML documentation will be placed in docs/_build/html.

Differences between versions¶

The text documentation in the main branch of the Git repository contains the “latest and greatest” changes and additions. These changes include documentation of new features targeted for Ginger’s next feature release. For that reason, it’s worth pointing out our policy to highlight recent changes and additions to Ginger.

We follow this policy:

  • The development documentation at https://docs.ginger.gloportal.dev/en/dev/ is from the main branch. These docs correspond to the latest feature release, plus whatever features have been added/changed in the framework since then.

  • As we add features to Ginger’s development version, we update the documentation in the same Git commit transaction.

  • To distinguish feature changes/additions in the docs, we use the phrase: “New in Ginger Development version” for the version of Ginger that hasn’t been released yet, or “New in version X.Y” for released versions.

  • Documentation fixes and improvements may be backported to the last release branch, at the discretion of the merger, however, once a version of Ginger 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 Ginger you are using!

Next
Writing your first patch for Ginger
Previous
Advanced tutorial: How to write reusable apps
Copyright © Ginger Society and contributors
Made with Sphinx and @pradyunsg's Furo
Last updated on Oct 22, 2024
On this page
  • What to read next
    • Finding documentation
    • How the documentation is organized
    • How documentation is updated
    • Where to get it
      • On the web
      • In plain text
      • As HTML, locally
    • Differences between versions