#15233: Docs misidentify modules for classes/functions
-----------------------------------------------------------------+----------
Reporter: Aryeh Leib Taurog <vim@…> |
Owner: nobody
Status: new |
Milestone:
Component: Documentation |
Version: SVN
Resolution: |
Keywords: module directives index
Triage Stage: Accepted | Has
patch: 1
Needs documentation: 0 | Needs
tests: 0
Patch needs improvement: 0 |
-----------------------------------------------------------------+----------
Comment (by gabrielhurley):
Hi Aryeh. Your script is an interesting little tool, but getting this
patch committed is going to require some more work. Let me try and explain
the main issues:
1. This patch is very broad (corrections in over a dozen unrelated
files) which makes it a significant job to try and verify that all the
changes are correct and don't cause unintended side-effects elsewhere.
2. The correct solution isn't always to simply prepend the "correct"
import path. In some cases what's really needed is a missing module
directive, or better indentation under a class directive. Adding that
module directive (as you did in some places) can also have unintended
consequences of nesting, etc. All this goes back to point 1, that this
patch is difficult to verify.
3. Some of the places where you've added the leading portions of the
import paths had them intentionally chopped off to improve readability, so
prepending with a "~" is necessary if adding the whole path is the right
solution.
My suggestion would be to break this ticket out into smaller tickets that
are easier to work with. For example, the changes you've got in there for
the File Upload documentation are very useful reST formatting corrections
which are excellent, but only marginally related to correct import paths.
Other people have had great luck getting tickets committed for similar
types of issues by working on one file or topic at a time. You can see an
example of how these kinds of tickets have been broken up successfully by
another contributor with
[http://code.djangoproject.com/query?resolution=fixed&description=~update&reporter=~adamv&or&resolution=fixed&description=~rest&reporter=~adamv&col=id&col=summary&col=status&col=milestone&col=component&col=version&order=priority
this query].
I really appreciate your thoroughness in working through all these, and I
want to see the work you've done get incorporated. You just have to make
it easy for everyone else, too. ;-)
--
Ticket URL: <http://code.djangoproject.com/ticket/15233#comment:2>
Django <http://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
