Code

Opened 3 years ago

Closed 3 years ago

Last modified 3 years ago

#14905 closed (fixed)

models.FileField links to url attribute, which is undocumented.

Reported by: Keryn Knight <keryn@…> Owned by: nobody
Component: Documentation Version: master
Severity: Keywords: filefield url easy-pickings
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:

Description

As part of the documentation callout on FileField.storage found in the Model Field Types documentation here, reference is made to the FileField.url attribute, which links to the documentation on the File class itself, where it is decidedly absent.

Following the rabbit hole from the original note on the modelfields through the Managing Files documentation, and on to the how-to on writing a custom storage backend (where a note is made that any custom solution must implement the url() method) we finally end up at the Storage API which does discuss the method.

It's a convoluted process, and I think the ref documentation on File should either document the attribute, or the model FileField reference should link to the documentation for the Storage API itself.

I can attempt to work up a documentation patch if the ticket has merit.

Attachments (1)

django-documentation-14990.diff (1.2 KB) - added by Keryn Knight <keryn@…> 3 years ago.
documentation changes, svn diff against revision 14990

Download all attachments as: .zip

Change History (6)

comment:1 Changed 3 years ago by gabrielhurley

  • milestone set to 1.3
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Accepted

The answer is much simpler here: all three of those attributes are mis-linked. They should reference django.core.files.storage.Storage instead of django.core.files.File.

There was recently a ticket that pointed out that url wasn't an attribute on django.core.files.File at all, and the docs were subsequently reworked to remove the reference from the File API page.

What surprises me is that the crossref link to that anchor on the page still resolved itself somehow. Whoever commits a fix for this, please build the docs locally to make sure links to django.core.files.File.url no longer resolve. I'm hoping it was just a bit of bad caching that kept the link there this time.

Changed 3 years ago by Keryn Knight <keryn@…>

documentation changes, svn diff against revision 14990

comment:2 Changed 3 years ago by Keryn Knight <keryn@…>

  • Has patch set
  • Keywords easy-pickings added

I've attempted a documentation patch, although I'm still not sure it's correct — all three cannot be mis-linked, as far as I can tell, because there's no documentation on the name attribute on Storage implementations. For better or worse then, I've left the name attribute pointing at django.core.files.File , and updated the others, adding the caveat that it's up to the Storage class in use to implement them.

I'm adding it as easy-pickings, because even if the current patch isn't workable, it shouldn't be hard for someone perhaps wiser in the file/storage internals to improve.

comment:3 Changed 3 years ago by gabrielhurley

  • Resolution set to fixed
  • Status changed from new to closed

(In [15088]) Fixed #14905 -- Corrected some misleading linking and language in the FileField docs. Thanks to Keryn Knight for the report and draft patch.

comment:4 Changed 3 years ago by gabrielhurley

(In [15089]) [1.2.X] Fixed #14905 -- Corrected some misleading linking and language in the FileField docs. Thanks to Keryn Knight for the report and draft patch.

Backport of [15088] from trunk.

comment:5 Changed 3 years ago by jacob

  • milestone 1.3 deleted

Milestone 1.3 deleted

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.