add geo support to admindocs

[andrepleblanc@…]

This patch adds support for the GIS Data Types to the admindocs app.

[andrepleblanc@…]

admindocs support

[Brett Hoerner]

I know this ticket / patch is GeoDjango specific, but in general DATA_TYPE_MAPPING should be made extensible outside of Django itself, right?

If you add your own field type the admindoc breaks (ie: UUIDField will always be a KeyError here, too).

[Brett Hoerner]

Er, well, I guess it is just a normal dict, and can be imported elsewhere and mutated. I just wonder how permanent that "API" will be.

[Malcolm Tredinnick]

I think Brett's broader point is valid here. This is a bit of an ugly patch, since it's so highly specific to one contrib app. Let's put on our brightly coloured thinking caps and do something better (dispatching to a "standard" function in each installed app in turn if there's a KeyError, for example).

It was probably either me or Jacob who had Eric move this to "d-d-n" during the Lawrence sprint last year. Moving to "Accepted" since, yes, we should do this. But not this way, preferably.

[anonymous]

If there's no "standard function" defined in the app, I'd still like to see it not throw an exception.

At minimum, DATA_TYPE_MAPPING should be a defaultdict that returns "Unknown field type" or "Field of type %s" % (field.class.name) if the type is not accounted for.

Better, the fields themselves carry information that can be used before falling back on the list (or after checking the list, or in place of the list). If checking on the field itself is the last thing done, fields can use the value on their superclasses by default, and then everything could fall back to a value on Field (which could be "Field of type %s" % field.class.name or "Unknown field type").

[Cliff Dyer]

Replying to anonymous:

Oops. I forgot to log in. Last comment was by me.

[Cliff Dyer]

Patch that allows fields to define type in docstrings

[Cliff Dyer]

A couple comments on my patch:

1. I'm not sure I like that I changed the docstring on OneToOneField to a comment. It was the only field/relationship that had a docstring at all. Alternatively, the patch could be modified so that get_readable_field_data_type() could just take the first line of the docstring, and strip off the rest. That might be unexpected behavior, though.

2. admindocs didn't have any associated unit tests that I could find, so I created some, but I only wrote tests for the function I modified. Some tests are better than none, right?

[Alex Gaynor]

I'm not sure I like using docstrings for this as the -OO flag omits all docstrings, which someone might want to use in production.

[Cliff Dyer]

Using docstrings is consistent with how admindocs extracts documentation from apps, though, so if you're using -OO, admindocs is useless anyway.

[Cliff Dyer]

In my mind, using -OO is an explicit declaration that you aren't interested in the documentation. So it doesn't seem unreasonable that it would affect the output of admindocs. Also, the problem is mitigated by having a sensible default to fall back on. Even in the absence of any docstrings whatsoever, my patch will produce decent output. It also seemed cleaner than creating a Field.doc attribute, which would (mostly) duplicate the functionality of a docstring.

That said, it should be easy enough to redo the patch using attributes instead of docstrings, if the consensus is that it would be better that way.

[Cliff Dyer]

I'm setting this to "Design Decision Needed," in order to get some feedback on whether to use the field type's docstrings (which mimics the behavior of the rest of admindocs, but has issues when running django with python -OO—as does the rest of admindocs), or to add a doc class attribute to each field type.

If we decide to go with docstrings, the patch is good to go.

[Cliff Dyer]

Here's a patch using class attributes. I went with field_description as the name.

Both patches apply cleanly, and the tests pass for both of them.

[Cliff Dyer]

Patch that allows fields to define type in class attribute

[Cliff Dyer]

Replying to jcd:

Here's a patch using class attributes. I went with field_description as the name.

Both patches apply cleanly, and the tests pass for both of them.

Correction: I went with description for the name

[Eric Holscher]

Applied this against trunk, and it worked as advertised. Beforehand it was giving me a KeyError on the Point field, afterwards it listed the point field.

A bit of whitespace in the admindocs/views.py didn't apply correctly, but otherwise it was fine.

[Cliff Dyer]

Added documentation, and revised to only use first line of long docstrings.

[Cliff Dyer]

Moves tests and related files into tests subdirectory

[Karen Tracey]

(In [11833]) Fixed #7977: Fixed admindocs to use docstrings instead of a static array to locate type information.
Thanks J. Clifford Dyer.

[Karen Tracey]

(In [11834]) [1.1.X] Fixed #7977: Fixed admindocs to use docstrings instead of a static array to locate type information. Thanks J. Clifford Dyer.

r11833 from trunk.

[Karen Tracey]

(In [11841]) Apply doc addition that somehow was left out of r11833. Refs #7977.

[Karen Tracey]

(In [11842]) [1.1.X] Apply doc addition that somehow was left out of r11834. Refs #7977.

r11841 from trunk.

[Jacob]

Milestone 1.2 deleted