ModelForm documentation horribly unclear for foreign key models

[ColinAlston]

The only way I found this out was by swearing profusely in #django. *Please* document it.

The current documentation rather tenuously approaches the subject with the whole Author thing which is just too simplistic to demonstrate the usage.

# -- Model --
class Colour(models.Model):
    colour_name = models.CharField(max_length=200)

class Fruit(models.Model):
    fruit_name = models.CharField(max_length=200)
    fruit_colour = models.ForeignKey(Colour, blank=True, null=True)

# -- View -- 
class AddFruitForm(forms.ModelForm):
    class Meta: 
        model = Fruit

    fruit_colour = forms.ModelChoiceField(queryset=Colour.objects.order_by('colour_name'))

[James Bennett]

This ticket doesn't actually explain any problem with the documentation, or what the solution to the problem was; it's just a code sample. Please provide an explanation of:

1. What problem you ran into.
2. How the documentation didn't help you solve it.
3. How you did actually solve it, so we can look into documenting it if it turns out to be a common problem.

[(none)]

Milestone post-1.0 deleted

[anonymous]

And even four years later, no development in the documents regarding this issue! Just wasted an enormous amount of time!