Opened 2 years ago

Closed 2 years ago

Last modified 2 years ago

#20786 closed Uncategorized (fixed)

Importing exceptions: documentation should be more explicit and clearer

Reported by: EvilDMP Owned by: dominicrodger
Component: Documentation Version: master
Severity: Normal Keywords:
Cc: internet@… Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: yes UI/UX: no

Description

At https://docs.djangoproject.com/en/dev/ref/exceptions, for some of the listed exceptions information is provided on how to import it.

For example: "The UnreadablePostError is raised when a user cancels an upload. It is available from django.http."

For others though (e.g. https://docs.djangoproject.com/en/dev/ref/exceptions/#noreversematch) there isn't clear explicit information about where to get them from.

Also, when the information is provided, it's not always provided consistently.

My suggestion is that each section (Database Exceptions, Http Exceptions and so on) there should begin with a paragraph on its own: Core exceptions are provided in django.core.exceptions, Database exceptions are provided in django.db and so on.

FInally, Django-specific Exceptions seems a bit of a misnomer, since others not in that section are also Django-specific. Calling them Core exceptions would seem to make more sense.

Change History (6)

comment:1 Changed 2 years ago by bmispelon

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

comment:2 Changed 2 years ago by dominicrodger

  • Cc internet@… added
  • Owner changed from nobody to dominicrodger
  • Status changed from new to assigned

This has bugged me in the past too - I'll take a look at fixing it.

comment:3 Changed 2 years ago by dominicrodger

  • Has patch set
  • Version changed from 1.5 to master

Pull request created at https://github.com/django/django/pull/1425.

There are a couple of extra commits in the pull request that tidy up two other things on this page (one typo, and the section on DoesNotExist). I'll happily separate those out into a separate pull request if that'd be easier.

Do let me know if there's anything else I can do to make getting this merged easier, this is my first (non-single-line!) submission to Django.

comment:4 Changed 2 years ago by EvilDMP

I'm taking a look at your pull request now. Eventually, your commits should be collapsed into one, which will require a git rebase. There's no reason to make multiple pull requests.

Anyway, it looks fundamentally good; I'll send you a pull request myself if I think any minor tweaks to your improvements are required.

comment:5 Changed 2 years ago by Tim Graham <timograham@…>

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

In 920b242e307297778c6e5010f23502c4f41f299c:

Fixed #20786 -- Cleaned up docs/ref/exceptions.txt

Thanks Daniele Procida for the suggestion and edits.

comment:6 Changed 2 years ago by Tim Graham <timograham@…>

In e710f6dc56731b52f84864e7cb199dc4a8f881e7:

[1.6.x] Fixed #20786 -- Cleaned up docs/ref/exceptions.txt

Thanks Daniele Procida for the suggestion and edits.

Backport of 920b242e30 from master

Note: See TracTickets for help on using tickets.
Back to Top